API configuration

Accessing the API configuration feature

To access the API configuration feature and to manage API clients for a study in Viedoc Admin, you need to have the user role API Manager for the study.

The API client ID

An API client ID is needed when using the API to connect to and interact with any API endpoint related to your Viedoc study.

The client ID is used as follows:

For the Viedoc WCF API, the client ID is used together with the Viedoc user name and the password for authorizing the user.
For the Viedoc Web API, the client ID and the client secret are used for authorization. No user context is needed.

To ensure backward compatibility with previous Viedoc versions, you can select which data structure version should be used when creating an API client ID.

Adding a Viedoc WCF API client and obtaining the API client ID

To add an API client and to obtain a client ID:

1	On the Viedoc landing page, click on the Admin icon to open Viedoc Admin.
2	Open the study that you would like to work with and click the Edit button in the API configuration field to open the API configuration dialog. Note! You must have the API Manager user role to see the API configuration field.
3	On the tab WCF API client, click on Add a new API client.
4	Enter a name for the API client. Select whether the client should be linked to a production or demo study in the Status dropdown menu. Click Add.
5	A client ID is generated and appears in the list of WCF API clients (1).
6	Select which data structure version you want the data structure to be compatible with from the Data structure version dropdown menu (2). You can edit the status of a client at any time by selecting a new status (Production, Inactive, or Demo) from the Status dropdown menu. For more information about the versions, see About the data structure version of API client ID.
7	Note down the client ID to be used later.

Adding a Viedoc Web API client and obtaining the API client ID

To add a Viedoc Web API client and to obtain the API client ID:

1	On the Viedoc landing page, click on the Admin icon to open Viedoc Admin.
2	Open the study that you would like to work with and click the Edit button in the API configuration field to open the API configuration dialog. Note! You must have the API Manager user role to see the API configuration field.
3	On the tab Web API client, click on Add a new Web API client.
4	Enter a name for the API client.
5	Select which data structure version you want the data structure to be compatible with.
6	Select whether the client should be linked to a production or a demo study in the Status dropdown menu. You can edit the status of a client at any time by selecting a new status (Production, or Demo) from the Status dropdown menu. You can also select the Active/Inactive button to switch the study status. This is a fast way to inactivate the Web API Client. Using an inactive client in an API call will be rejected. Note! If you are configuring your API for a PMS study, you can select the Data controller dropdown to choose Sponsor side or Clinic side to narrow the scope.
7	Select the applicable scopes for a user. The available scopes are: Export Create/update site Get site information Invite Clinic user - requires the client Status to be Production Invite Admin user - requires the client Status to be Production Manage contract Get User information Note! See below for more information about how to define the Export scope.
8	Optionally, enter the IP addresses from which requests to the Web API endpoints are permitted. Note! You can add a semi-colon separated list of multiple IP addresses. If calls from any IP address are allowed, the IP address(es) field can be left blank.
9	The client secret expiry date is set to one year ahead by default. If needed, you can set another date, but it cannot be more than one year after the current date.
10	Click on Add API client.
11	When the API client has been added, the following fields are displayed: Client secret - Tip! Make sure you copy it, because it is shown only once. If needed, you can regenerate it. Client ID Token URL Grant type API URL
12	Note down the client ID to be used later.
13	If needed, you can change the settings for the scopes, the status, and the data structure version.
14	Click on Save changes.

About the data structure version of the API client ID

When creating an API client ID, you need to select which data structure version you would like to use. The Viedoc versions you can select are only those versions in which changes to the data structure were introduced.

This text is used in the lessons General study settings (Admin) and API configuration (Admin).

As of Viedoc release 4.79, the following output versions are available:

Output version	Changes in data structure
Latest Viedoc version	When choosing Latest Viedoc version, the exported data will automatically follow the structure of the latest Viedoc release in which changes to the data structure were introduced.
Viedoc 4.79	Introduction of a number of changes to the ODM data export. See the table below for details.
Viedoc 4.77	For studies where item-level SDV is enabled, when exporting review status, the SDV sheet in the CSV and Excel data exports will include only the items that require SDV and are visible to the user. On the Review status sheet, items that do not require SDV are indicated with N/A .
Viedoc 4.68	Introduction of pdf archive export system check which splits the archive into one pdf file per subject and stores resultant PDF in a zip file.
Viedoc 4.67	Introduction of two new columns for approving medical coding: "approved by" and "approved on date".
Viedoc 4.51	Introduction of three new form repeat keys and the table of contents in the PDF export, see the table below for details
Viedoc 4.39	Introduction of repeating forms and recurring events, see the table below for details.
Viedoc 4.38	Original output format (Viedoc versions 4.38 or older).

In Viedoc 4.79, the following changes to the export output were introduced:

File type	Changes in the export output format
ODM	Introduction of support for partial datetime, date, and time. This is now the default type when exporting designs and data in ODM format. Partial dates as per the ISO 6801 standard are written up to the most detailed value available. This makes the export compliant with CDISC ODM.
ODM	When exporting a design to ODM, multi-selection code lists are handled as follows: Checkbox item definitions are split by code list items. During metadata export, checkbox ItemDef is replaced with one for each code list item. For clinical data export, the comma-separated values are replaced for the checkbox with ItemData for each respective value. For example, when splitting a checkbox ItemDef with OID="CHK" and code list IDs "Yes" and "No", the split checkbox ItemDefs will have the OIDs "__CHK__Yes" and "__CHK__No", respectively. That is, the original OIDs and the code list IDs are prefixed with two underscore characters and separated by two underscore characters. In Viedoc Designer, checkbox items are exported as multiple ItemDefs - one for each selection value. In Viedoc Clinic and the Viedoc API: In the latest export version, checkboxes are exported as separate items for metadata and clinical data. In previous export versions, checkboxes are exported as one item. This has been introduced to be compliant with CDISC ODM.
ODM	Bug fix: In the ODM data export, the content of the Question element for study event items and booklet forms was not complete. According to the CDISC standard, the element should include one of the TranslatedText attributes. This is now solved, and the Question element is populated with a string related to the corresponding OID. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, the MeasuremetUnit.Name contained HTML code, making it non-compliant with the CDISC standard. This is now solved, and the HTML code is removed from the name. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, the translated text was missing for meta.Protocol.Description.TranslatedText. This is now solved, and the body is populated with the protocol name, as visible on the design overview page. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, the Length attribute was incorrect, making it non-compliant with the CDISC standard. This is now solved, and Length is populated as per the ItemDef data type. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, there was a mismatch between the item data type and the code list data type for checkboxes. This is now solved, and the checkbox data is split into different items, in the same way as for CSV and Excel exports. This is implemented in a new export version, version 4.79.
ODM	Bug fix: In the ODM data export, the study OID and ClinicalData didn't respect the Production/Demo mode for sites. This is now solved, and the study OID and ClinicalData are populated based on the Production/Demo mode of the exported study. This is applied without a new export version.
ODM	Bug fix: In the ODM data export, non-repeating forms included a repeat key, making the ODM data export non-compliant with the CDISC standard. This is now solved. This is implemented in a new export version, version 4.79.
ODM	Bug fix: In the ODM data export, the KeySet elements had an unregistered value for the ItemOID attribute, making the ODM data export non-compliant with the CDISC standard. This is now solved, and the KeySet elements reference items within the same MetaDataVersion. This is implemented in a new export version, version 4.79.
ODM	Bug fix: In the ODM data export, the attribute OrderNumber of the element StudyEventRef was not valid with respect to its type, integer. This is now solved, and StudyEventRef elements have unique and non-empty consecutive order numbers. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, there was a data type mismatch between CodeList and ItemDef, making the ODM data export non-compliant with the CDISC standard. This is now solved by always having a matching data type between ItemDef and CodeList. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, the element MeasurementUnitRef had an unregistered value for the MeasurementUnitOID attribute, making the ODM data export non-compliant with the CDISC standard. This is now solved, and measurement units not referenced in any MetaDataVersion are not included in the ODM data export. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, the Alias names were not correctly populated. This is now solved, and any code list item aliases with empty names are removed at import and export - and the Alias names are populated with the context values. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, the SAS field name and the SAS dataset name were not populated. This is now solved, and the SAS field name is populated based on the ItemDef OID, and the SAS dataset name is populated based on the FormDefOID, which means that the OIDs are SAS-compliant. There is an option for this in the data export. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, revisions linked to study events and revisions linked to forms requiring approval of the new design revision were not included. This is now solved. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, alerts had repeating order numbers. This is now solved, and the order numbers for all study settings alerts in Viedoc Designer are removed. This is applied to all export versions.
ODM	Bug fix: In the ODM data export, the item group containing the reference data items was not added to the MetaDataVersion. This is now solved. This is applied to all export versions.

In Viedoc 4.51, the following changes to the export output were introduced:

File type	Changes in the export output format
Excel	Addition of three columns for the new form sequence numbers introduced: `SubjectFormSeqNo` – Counter that uniquely identifies the instance of a specific form on a subject level, that is, it starts with 1 and is incremented each time a new instance of the form is created for that subject. `OriginSubjectFormSeqNo` – For a copied form instance, it identifies the form instance from which data was copied for the first time. For the first instance of the form (that is, not copied) it gets the value of the `SubjectFormSeqNo`. `SourceSubjectFormSeqNo` – For a copied form instance, a counter that identifies the source of a copied form instance (the form instance the data was copied from). It gets the value of the `SubjectFormSeqNo` from which the form instance was copied. For the first instance of the form (that is, not copied) it is empty.
ODM	Three new form sequence numbers were introduced, as Viedoc extensions: `v4:SubjectFormSeqNo`, `v4:OriginSubjectFormSeqNo` and `v4:SourceSubjectFormSeqNo`, within the `FormData`, right after the `FormRepeatKey`.
PDF	A table of contents was added to the PDF archive, starting on page 2 of the file.

In Viedoc 4.39, the following changes to the export output were introduced:

File type	Changes in the export output format
Excel	Addition of a column for Form sequence number (`FormSeq`) that contains the `FormRepeatKey`.
ODM	The `FormRepeatKey` now contains the activity ID as well, in the following format: `FormRepeatKey$ActivityId`. The ExportVersion attribute has been added to the ODM.
PDF	The summary formats are used to display the event and form names.

Defining the export scope for the Web API client

As an API Manager, in order to restrict what data is available to export through the Web API, when configuring a Web API Client you need to define the export scope. This is done by associating a role and site(s) to the Web API Client.
Only data that is available for the associated role under one of the associated sites will be included in the exported data.

The API export endpoint will then be accessible to a specific associated user role and site(s) only.

Note! You can select only one Associated role per Web API client.

To define the Export scope:

In the Add Web API client, in the Scopes field, select Export:

The Associated role and Associated site dropdown menus are displayed:

Select the Associated role and Associated site:

The associated roles available for selection are the Clinic user roles which have data export permission.

The available sites are the sites with an assigned study design together with their corresponding site groups.

Note! Web API requests will return an error code if a role and/or site is specified that does not comply with the configuration of the Web API client.

For example, if the configuration of the Web API Client is as follows:

If the Web API Client Role is configured for the associated role "Role 1", and the associated site(s) as All production sites, if the request specifies "Role 1" and the site is not specified, the data that is accessible (and thus returned) for the role and site is the data for "Role 1" and for all production sites.
If the Web API Client associated site is configured for a country and for the associated role "Role 1", a request for a specific site, but no associated role, will return data for "Role 1" and that site only - as long as the site is in the same country group.
If the Web API Client Role is configured for the associated role "Role 1", and the associated site as a specific site, If the request instead is for "Role 2" and the same site, this will result in an error code.
Requesting a different site to the configured associated site in the Web API Client results in an error code even if the associated role is requested is the same.
If the Web API Client site(s) is configured for a country and the Web API Client Role is configured for the associated role "Role 1", a request for a site in a different country with no associated role specified will result in an error code.
If the Web API Client site is configured for a country and the associated role "Role 1", if the request specifies "Role 1", and the request is for one site in the specified country and also another site not in the same country, this will result in an error code.

Notes!

If a study has an existing Web API client with the export scope, when the API Manager selects Edit, the Associated Role and Associated site dropdown menus are highlighted with a red border. The Web API client edits cannot be saved until a valid Associated role and Associated site are selected.
The role information (Name/ RoleID) and all changes to the Associated role of a Web API Client is included in the Admin Audit Trail Report.