The clinicaldata endpoint is used to:

  • Import clinical data to the study
  • Retrieve clinical data in JSON or CDISC XML format

The user must be authenticated prior to calling this service. The operation is allowed based on the user’s privileges.

Import clinical data to the study

POST {serverName}/pages/auth/api/clinicaldata

Where {serverName} is your study URL. For example: https: //studyxyz.eu.openclinica.io/OpenClinica

Sample cURL request:

curl -X POST 
  {{serverName}}/pages/auth/api/clinicaldata/ 
  -H 'Authorization: bearer {{authentication token}}' 
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' 
  -F 'file=@{{fileName}}'

Request Parameters:

  • content-type: text/xml
  • filename=”importFilename.xml”

“importFilename.xml” should be replaced with an XML file that contains the CRF data of the study participants.

Please refer to the Import Data documentation for the XML file structure and details.

Response Body on Success

{
"message": "SUCCESS",
"detailMessages": [
	"Audit Messages:success n n n",
	"Rule Action Messages:" ",
	"Skip CRF Messages:" "
	]
}

If the operation fails an appropriate errorCode is returned. The user should plan the approriate follow-up action based on the errorCode.

 

Sample Response Body on Failure:

{
"message": "VALIDATION FAILED",
"errors": [
	{
		"code": "errorCode.ValidationFailed",
		"message": "Missing studyEventRepeatKey for common event  StudyEventOID: SE_AEANDCONMEDS n"
	}]
}

 

Following is a list of the current error codes and desciptions:

  • errorCode.Exception: the XML file validation failed.
  • errorCode.studyNotExist: the Study OID specified in the request is not found.
  • errorCode.noRoleSetUp: the authenticated user has no role defined for the given Study/Site.
  • errorCode.noSufficientPrivileges: The user does not have sufficient privileges to perform this operation.
  • errorCode.participantNotExist: The Participant ID (SubjectKey) [participantID] specified in the request is not found under the given Study OID.
  • errorCode.eventNotExist: Study Event OID [SE_ECG(Occurrence_no)] for Participant OID [participantID] is not scheduled.
  • errorCode.invalidRepeatKey:Study Event OID [studyEventOID] is a non-repeating event. Repeat key value [x] is not valid.
  • errorCode.repeatKeyMissing: Study Event OID [studyEventOID] is a common event. Repeat key is required.
  • errorCode.repeatKeyOutofSequence: For Study Event OID [studyEventOID] repeat key value [x] is not valid. The next available sequential value is [y].
  • errorCode.sameRepeatKey: Study Event OID [studyEventOID] is a common event. Each form in this event must have a different repeat key.
  • errorCode.invalidFormOID: Form OID [formOID] specified in the request is not valid.
  • errorCode.invalidFormLayoutOID: For Form OID [formOID], Form Layout OID [formLayoutOID] is not valid.
  • errorCode.invalidItemGroupOID: Item Group OID [itemGroupOID] specified in the request is not valid.

 

Get clinical data in JSON or XML format

This endpoint retrieves participant clinical data in CDISC ODM XML file or in JSON file format from a given Study. Asterisks and wild cards can be used in place of OIDs and Participant ID in the request parameters. This endpoint can also be used to retrieve ONLY the study metadata and/or clinical data including audit logs, discrepancy notes (queries), and the clinical data in the archived forms.

The response from the endpoint will be as per the user’s access level. For example, a user with ONLY site A access will receive metadata and clinical data only for site A study, users, and participants.

Usage:

GET {serverName}/pages/auth/api/clinicaldata/{studyOID}/{studySubjectIdentifier}/{studyEventOID}/{formOID}

where {serverName} is your study URL. For example: https: //studyxyz.eu.openclinica.io/OpenClinica

Sample cURL request:

curl -X GET 
  '{{serverName}}/pages/auth/api/clinicaldata/{{studyOID}}/{{participantOID}}?clinicalData=y&includeMetadata=y&includeDN=n&includeAudits=n&showArchived=n' 
  -H 'Accept: application/xml' 
  -H 'Authorization: bearer {{authentication token}}'

Request Parameters:

  • studyOID: Required
    • Valid studyOID or siteOID.
  • studySubjectIdentifier: Required
    • Valid studySubjectOID
    • * (Asterisk) can be used to retrieve data for all Participants in the study.
  • studyEventOID: Required
    • Valid studyEventOID
    • * (Asterisk) can be used to retrieve data for all Event OIDs for the given Participant.
  • formOID: Required
    • Valid formOID
    • * (Asterisk) can be used to retrieve data for all Form OIDs for the given Study Event OID of the given participant.
  • includeMetadata: Optional
    • Whether or not to include the study metadata in the response. (For a large study, including metadata can slow down performance).
    • Possible values: ‘y’ or ‘n’
    • Default is ‘y’
  • includeAudits: Optional
    • Whether or not to include audit trail information in the response.
    • Possible values: ‘y’ or ‘n’
    • Default is ‘n’
  • includeDNs: Optional
    • Whether or not to include the discrepancy notes (Queries) in the response.
    • Possible values: ‘y’ or ‘n’
    • Default is ‘n’
  • showArchived: Optional
    • Whether or not to include the clinical data for the archived forms and form versions.
    • Possible values: ‘y’ or ‘n’
    • Default is ‘n’

Response Content type:

  • application/xml
  • application/json