Summary
This article provides an overview of the Rest API Developer Guide.
Table of Contents
- 1 Summary
- 2 Interface Details
- 3 CTMS API Call Examples
- Site Visit Manager Export
- Documents Manager Downloads
- Supported Filters
- documentType
- documentName
- personnel
- question
- uploadDateMin
- uploadDateMax
- expirationDateMin
- expirationDateMax
- study
- site
- studySite
- uploadedBy
- formType
- Example 1: Unstructured Document Download
- Example 2: Structured Document Download
- CTMS Import
- CTMS Get Import Status
- CTMS Get Import Log File Use this configuration to get the import file name with associated information.
- CTMS Report
- EDC API Calls
- 5 API Call Values
1 Summary
The purpose of this document is to provide information to external developers who wish to extract, import from/to CTMS and EDC. Fountayn has exposed several RESTful APIs to facilitate this functionality. This is intended to cover details for using APIs with the Fountayn platform, and is not meant to be an instructional guide to the general topic of APIs. Knowledge of APIs will be required to fully utilize this guide.
2 Interface Details
Message Format
All message requests are in JSON format, and reply payloads are in plain text as these are just status messages. If a file is requested, it will be returned as an attachment.
Authentication and Authorization
Authentication is done by the use of an “API Key”. This is a unique value per username, generated from the system. Every API call made will contain this key in the payload.
Authorization is done by specifying a toolId or a toolroleinstanceid in the payload.
Success and Error Codes
An HTTP 200 indicates success.
An HTTP 500 indicates an error occurred. The payload will contain the specific message.
An HTTP 403 indicates a request was made for which either the caller could not be authenticated, or they were authenticated but they do not have authorization for what was requested.
An HTTP 206 indicates a status request was made, and the answer is the operation is still in progress.
REST Verbs
All requests use the POST verb. This verb is then, sometimes, overridden with the X-DBP-Method-Override header. Specifics of this are detailed in the documentation for each API call.
3 CTMS API Call Examples
CTMS Export
Use this configuration for setting up a CTMS export of standard reports or managers. Note: Site Visit Manager and Documents Manager use separate configurations, noted in subsequent sections.
Request Headers:
POST /clickFind/rest/CtmsExport
Content-Type: application/json
Request Payload:
{ “apiKey”: “<the caller’s API key>”, “fileType”: “<the format of the export>”, “action”: “<the type of export (standard report) or exportManager,>”, “managerType”: “<used when action = exportManager, ignored otherwise>”, “studyId”: <the id of the study to be exported, only for CTMS standard reports that require study selection >, “toolId”: <the tool id> }
Reply Payload:
Unless an error has occurred, this will contain a zip file attachment with the export. The standard Content-Disposition header will contain the filename. For example:
Content-Disposition: inline; filename=”20170227124339451.zip”
Content-Type: application/zip
Content-Length: 3593
Site Visit Manager Export
Use this configuration for exporting CTMS Site Visit Manager data.
Supported Filters
study
Values for this parameter correspond to a unique internal study identifier within CTMS. See Section 5 for instructions on obtaining this value. When configured, only site visits with a matching study reference will be included in the downloaded archive.
The study key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
site
Values for this parameter correspond to a unique internal site identifier (global level) within CTMS. See Section 5 for instructions on obtaining this value. When configured, only site visits with a matching site reference will be included in the downloaded archive.
The site key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
studySite
Values for this parameter correspond to a unique internal study-level site identifier. See Section 5 for instructions on obtaining this value. When configured, only site visits with a matching study site reference will be included in the downloaded archive.
The studySite key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
visitType
Values for this parameter correspond to the value of the Visit Type selected on the site visit report and displayed in the Visit Type column of the Site Visit Manager. When configured, only site visits with a matching visit type reference will be included in the downloaded archive.
The visitType key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
reporters
Values for this parameter correspond to the value of the Reporters set in the Site Visit Table and displayed in the Reporters column of the Site Visit Manager. When configured, only site visits with a matching Reporters reference (“Last, First”) will be included in the downloaded archive.
The reporters key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
visitName
Values for this parameter correspond to the value of the Visit Name set in the Site Visit Table and displayed in the Visit Name column of the Site Visit Manager. When configured, only site visits with a matching Reporters reference (“Last, First”) will be included in the downloaded archive.
The visitName key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
status
Values for this parameter correspond to the value of the transition status the Site Visit Report. When configured, only site visits with a matching transition status will be included in the downloaded archive.
The status key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
templateName
Values for this parameter correspond to name of the Site Visit Report template used for the report. When configured, only site visits using the referenced template will be included in the downloaded archive.
The templateName key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
visitDateMin
Values for this parameter correspond to Visit Date for the report. When configured, only site visits with a visit date on or after the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Site Visit Manager.
visitDateMax
Values for this parameter correspond to Visit Date for the report. When configured, only site visits with a visit date on or before the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Site Visit Manager.
projectedDateMin
Values for this parameter correspond to Projected Date for the report. When configured, only site visits with a projected date on or after the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Site Visit Manager.
projectedDateMax
Values for this parameter correspond to Projected Date for the report. When configured, only site visits with a projected date on or before the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Site Visit Manager.
scheduledDateMin
Values for this parameter correspond to Scheduled Date for the report. When configured, only site visits with a scheduled date on or after the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Site Visit Manager.
scheduledDateMax
Values for this parameter correspond to Scheduled Date for the report. When configured, only site visits with a scheduled date on or before the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Site Visit Manager.
Example 1: Initiate Export
Request Headers:
POST /clickFind/rest/CtmsExport
Content-Type: application/json
Request Payload:
{ (The following are required parameters:) "apiKey": “<the caller’s API key>”, "toolId": <the tool id> "action": "exportpdfsitevisits", "filterName": 1253, “filterNameAcceptingMultipleValues”: [“value1”,”value2”] }
(Above bolded portion is the syntax for optional filter parameters, which may include any combination of parameters from the filters list.)
Reply Payload:
Unless an error has occurred, the reply payload will contain a JSON object with key taskId. This key/value pair can be used to check status of an export task and download exported file.
Example 2: Check Status
Request Headers:
POST /clickFind/rest/CtmsExport
Content-Type: application/json
X-DBP-Method-Override: HEAD
Request Payload:
{ (The following are required parameters:) "apiKey": "xA3B123xyz! ", "toolId": 23061, "action": "exportpdfsitevisits", "taskId": <taskId provided in initial reply payload> }
Reply Payload:
Unless an error has occurred, there will be no reply payload. An HTTP 200 return will indicate the export has completed. An HTTP 206 return will indicate the export is still in progress.
Example 3: Download PDF
Request Headers:
POST /clickFind/rest/CtmsExport
Content-Type: application/json
X-DBP-Method-Override: GET
Request Payload:
{ (The following are required parameters:) "apiKey": "xA3B123xyz! ", "toolId": 23061, "action": "exportpdfsitevisits", "taskId": <taskId provided in initial reply payload> }
Reply Payload:
Unless an error has occurred, there will contain a zip file attachment with the export. The standard Content-Disposition header will contain the filename. E.g.,
Content-Disposition: inline; filename=”20170227124339451.zip”
Content-Type: application/zip
Content-Length: 3593
Documents Manager Downloads
Use this configuration to download documents stored in the CTMS Documents Manager. Documents can be downloaded as an unstructured file (action = “documentsDownload”) or as a structured file (action = “documentsDownloadStructured”).
Supported Filters
These filters represent a number of optional parameters that can be added to a request.
documentType
Values for this parameter correspond to the value of the document type field associated with the file and as displayed in the Documents Manager (such as “1572” or “CV”). When configured, only files with a matching document type will be included in the downloaded archive.
The documentType key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
documentName
Values for this parameter correspond to the value of the file name as displayed in the Name column of the Documents Manager. When configured, only files with a matching file name will be included in the downloaded archive.
personnel
Values for this parameter correspond to the value of the Personnel record name for documents associated with a Personnel record. When configured, only documents with a matching Personnel reference (“Last, First”) will be included in the downloaded archive. Multiple personnel can be configured using syntax “Last1, First1|Last2, First2”
question
Values for this parameter correspond to the value of the question text for the question where the document was attached, and as displayed in the Question column of the Documents Manager. When configured, only files with a matching Question value will be included in the downloaded archive.
uploadDateMin
Values for this parameter correspond to the Upload Date of the document as displayed in the Document Manager. When configured, only documents with an upload date on or after the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Document Manager.
uploadDateMax
Values for this parameter correspond to the Upload Date of the document as displayed in the Document Manager. When configured, only documents with an upload date on or before the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Site Visit Manager.
expirationDateMin
Values for this parameter correspond to the Expiration Date of the document as displayed in the Document Manager. When configured, only documents with an expiration date on or after the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Document Manager.
expirationDateMax
Values for this parameter correspond to the Expiration Date of the document as displayed in the Document Manager. When configured, only documents with an expiration date on or before the specified date will be included in the downloaded archive. Dates should be configured using the same date format as displayed in the Document Manager.
study
Values for this parameter correspond to a unique internal study identifier within CTMS. See Section 5 for instructions on obtaining this value. When configured, only documents with a matching study reference will be included in the downloaded archive.
The study key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
site
Values for this parameter correspond to a unique internal site identifier (global level) within CTMS. See Section 5 for instructions on obtaining this value. When configured, only documents with a matching site reference will be included in the downloaded archive.
The site key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
studySite
Values for this parameter correspond to a unique internal study-level site identifier. See Section 5 for instructions on obtaining this value. When configured, only documents with a matching study site reference will be included in the downloaded archive.
The studySite key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
uploadedBy
Values for this parameter correspond to a unique internal login ID. See Section 5 for instructions on obtaining this value.. When configured, only documents with a matching Uploaded By reference will be included in the downloaded archive.
The uploadedBy key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
formType
Values for this parameter correspond to the value of the Form where the document was attached, and as displayed in the Form Type column of the Documents Manager. When configured, only files with a matching Form Type value will be included in the downloaded archive.
The formType key also supports an array of single values as parameter that will be handled with OR logic (multiple choice filter).
Example 1: Unstructured Document Download
Request Headers:
POST /clickFind/rest/CtmsExport
Content-Type: application/json
Request Payload:
{ "apiKey": “<the caller’s API key>”, "action": "documentsDownload", "toolId": <the tool id> "filterName": 1253, “filterNameAcceptingMultipleValues”: [“value1”,”value2”] }
(The above bolded portion is the syntax for optional filter parameters, which may include any combination of parameters from the filters list. Use “ “ when referencing an alphanumeric value:)
Example 2: Structured Document Download
Request Headers:
POST /clickFind/rest/CtmsExport
Content-Type: application/json
Request Payload:
{ (The following are required parameters:) "apiKey": “<the caller’s API key>”, "action": "documentsDownloadStructured", "toolId": <the tool id> (Below is the syntax for optional filter parameters, which may include any combination of parameters from Filters list above. Use “ “ when referencing an alphanumeric value:) "filterName": 1253, “filterNameAcceptingMultipleValues”: [“value1”,”value2”] }
CTMS Import
Use this configuration for setting up a CTMS import.
Request Headers:
POST /clickFind/rest/CtmsImport
Content-Type: multipart/form-data
Request Payload:
The payload has 2 parts –
- A part named “file” which is the file to be imported
- A part named “json” which is the json to be imported. This has 3 fields:
- apiKey – the caller’s API key
- importType – the type of data being imported
- toolId – the tool id
Examples:
Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW
——WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=”file”; filename=”myFile.xyz”
Content-Type:
——WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=”json”
{ “apiKey”: ” xA3B123xyz!”, “importType”: “StudyDeviation”, “toolId”: 23061 }
——WebKitFormBoundary7MA4YWxkTrZu0gW—
CTMS Get Import Status
Use this configuration to check if the status of your import is completed or still in progress.
Request Headers:
POST /clickFind/rest/CtmsImport
Content-Type: application/json
X-DBP-Method-Override: HEAD
Request Payload:
{ “apiKey”: “<the caller’s API key>”, “importType”: “<the type of data that was imported>”, “toolId”: <the tool id> }
Reply Payload:
Unless an error has occurred, there will be no reply payload. An HTTP 200 return will indicate the import has completed. An HTTP 206 return will indicate the import is still in progress.
CTMS Get Import Log File Use this configuration to get the import file name with associated information.
Request Headers:
POST /clickFind/rest/CtmsImport
Content-Type: application/json
X-DBP-Method-Override: GET
Request Payload:
{ “apiKey”: “<the caller’s API key>”, “importType”: “<the type of data that was imported>”, “toolId”: <the tool id>, “byUser”: <true or false, whether to return the latest import log for the caller, or the latest log period> }
Reply Payload:
Unless an error has occurred, this will contain the log file requested. The standard Content-Disposition header will contain the filename. E.g.,
Content-Disposition: inline; filename=”import.log”
Content-Type: text/plain
Content-Length: 386
CTMS Report
Use this configuration for setting up a CTMS export of ad hoc reports
Request Headers:
POST /clickFind/rest/CtmsReports
Content-Type: application/json
Request Payload:
{ “apiKey”: “<the caller’s API key>”, “reportId”: “<the id of the report >”, “toolId”: <the tool id> }
Reply Payload:
Unless an error has occurred, this will contain a zip file attachment with the export. The standard Content-Disposition header will contain the filename. E.g.,
Content-Disposition: inline; filename=”20170228182138519.zip”
Content-Type: application/zip
Content-Length: 341
EDC API Calls
EDC Request Export
Note:
- You now have the ability to use a primary and secondary Identifier when requesting exports.
Request Headers:
POST /clickFind/rest/EDCExport
Content-Type: application/json
Request Payload:
{ "apiKey": "<the caller’s API key>", "roleInstanceId": "<the role instance id>", "exportId": "<the id of the export>" }
Examples:
{ "apiKey": "xA3B123xyz! ", "roleInstanceId": "22552", "exportId": "export2", }
Subset Export Example:
{ "apiKey": "xA3B123xyz! ", "roleInstanceId": "22552", "exportId": "export2", "exportSelection": { "recordIdentifiers": [ { "primary": "DT305" }, { "primary": "DTS303", "secondary": "DEC" } ] } }
Reply Payload:
Unless an error has occurred, there will be no reply payload.
EDC Get Export Status
Use this configuration to check if the status of your export is completed or still in progress.
Request Headers:
POST /clickFind/rest/EDCExport
Content-Type: application/json
X-DBP-Method-Override: HEAD
Request Payload:
{ "apiKey": "<the caller’s API key>", "roleInstanceId": "<the role instance id>", "exportId": "<the id of the export>" }
Reply Payload:
Unless an error has occurred, there will be no reply payload. An HTTP 200 return will indicate the export has completed. An HTTP 206 return will indicate the export is still in progress. An HTTP 500 return will indicate the export has failed.
EDC Get Export File
Use this configuration to get the export file name with associated information.
Request Headers:
POST /clickFind/rest/EDCExport
Content-Type: application/json
X-DBP-Method-Override: GET
Request Payload:
{ "apiKey": "<the caller’s API key>", "roleInstanceId": "<the role instance id>", "exportId": "<the id of the export>" }
Reply Payload:
Unless an error has occurred, this will contain the export file requested. The standard Content-Disposition header will contain the filename. E.g.,
Content-Disposition: inline; filename=”20170301141448959.zip”
Content-Type: application/zip
Content-Length: 22727
EDC Import
Request Headers:
POST /clickFind/rest/EDCImport
Content-Type: multipart/form-data
Request Payload:
The payload has 2 parts –
- A part named “file” which is the file to be imported
- A part named “json” which is the json to be imported. This has 4 fields:
- apiKey – the caller’s API key
- roleInstanceId – the role instance id
- importId – the id of the import
Examples:
Content-Type: multipart/form-data; boundary=—-WebKitFormBoundary7MA4YWxkTrZu0gW
——WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=”file”; filename=”MyFile.xyz”
Content-Type:
——WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name=”json”
{ “apiKey”: ” xA3B123xyz!”, “roleInstanceId”: “22552″, “importId”: “import2″ }
——WebKitFormBoundary7MA4YWxkTrZu0gW–
Reply Payload:
Unless an error has occurred, there will be no reply payload.
EDC Get Import Status
Use this configuration to check if the status of your import is completed or still in progress.
Request Headers:
POST /clickFind/rest/EDCImport
Content-Type: application/json
X-DBP-Method-Override: HEAD
Request Payload:
{ “apiKey”: “<the caller’s API key>”, “roleInstanceId”: “<the role instance id>”, “importId”: “<the id of the import>” }
Reply Payload:
Unless an error has occurred, there will be no reply payload. An HTTP 200 return will indicate the import has completed. An HTTP 206 return will indicate the import is still in progress.
EDC Get Import Log File
Use this configuration to get the import file name with associated information.
Request Headers:
POST /clickFind/rest/EDCImport
Content-Type: application/json
X-DBP-Method-Override: GET
Request Payload:
{ “apiKey”: “<the caller’s API key>”, “roleInstanceId”: “<the role instance id>”, “importId”: “<the id of the import>” }
Reply Payload:
Unless an error has occurred, this will contain the log file requested. The standard Content-Disposition header will contain the filename. E.g.,
Content-Disposition: inline; filename=”20170301153905292.log”
Content-Type: text/plain;charset=UTF-8
Content-Length: 8144
EDC Ad Hoc Report
Use this configuration to retrieve EDC Ad Hoc Reports.
Request Headers:
POST /clickFind/rest/EDCReports
Content-Type: application/json
Request Payload:
{ “apiKey”: “<the caller’s API key>”, “reportId”: “<the id of the report >”, “roleInstanceId”: “<the role instance id>” }
Reply Payload:
Unless an error has occurred, this will contain a zip file attachment with the export. The standard Content-Disposition header will contain the filename. E.g.,
Content-Disposition: inline; filename=”20170228182138519.zip”
Content-Type: application/zip
Content-Length: 341
5 API Call Values
This section provides an alphabetical list and description of the call values used in the above examples. Additionally, where applicable, instructions for obtaining the value are provided. For each call value, the call examples requiring the value are listed.
Need more help?
Please visit the Fountayn Contact Information page.