API configuration

  • Published by Viedoc System 2023-10-09
  • Print

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 and 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, Inactive, or Demo) from the Status dropdown menu.

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
8

Optionally, enter the IP addresses from which requests to the Web API endpoints are permitted. You can add a semi-colon separated list of multiple IP addresses.
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.

Note that the text below is very similar to the single-source text under General.

As of Viedoc 4.77, the following data structure versions are available:

Data structure version Changes in data structure
Latest Viedoc version When selecting Latest Viedoc version, the data structure through which the Viedoc API communicates will automatically follow the structure of the latest Viedoc release in which changes to the data structure were introduced.
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 the 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.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:

  • SubjectFormatFormSeqNo - 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 format 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 nowcontains 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.