17.1 Clinicaldata (Import and Retrieve clinical data)

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

This endpoint imports clinical data into the OpenClinica system using a CDISC ODM XML file format.  The structure of that XML file is a combination of CDISC ODM v1.3.2 and some OpenClinica specific tags. 

Below is the sample CDISC ODM XML import template for reference (to use this template, copy the following text, paste it into an XML file, and update the OIDs as needed):

<?xml version="1.0" encoding="UTF-8"?>
<ODM xmlns="http://www.cdisc.org/ns/odm/v1.3" xmlns:OpenClinica="http://www.openclinica.org/ns/odm_ext_v130/v3.1" ODMVersion="1.3" FileOID="1D20080412202420" FileType="Snapshot" Description="Demographics Import" CreationDateTime="2008-04-12T20:24:20" >

  <!-- StudyOID represents either the Study OID (if a study-level user is importing data) or the Site OID (if a site-level user is importing data). -->
  <ClinicalData StudyOID="S_OID" MetaDataVersionOID="null">
    <!--SubjectKey (optional) is the Participant OID. If not used, remove the entire text 'SubjectKey="SS_OID"'. 
        OpenClinica:StudySubjectID (required) represents the Participant ID. -->
    <SubjectData SubjectKey="SS_OID" OpenClinica:StudySubjectID="PID-001">
	<!--StudyEventOID (required): The OID for the event into which you are importing data.
           StudyEventRepeatKey (optional): The ordinal for a repeating event. 
	   If removed, a new study event ordinal is automatically generated.
	   For a visit-based event OpenClinica:StartDate is required.
	   If the StudyEventRepeatKey value is provided and the specified repeat is already in the database, 
then the system updates the form data for that study event repeat on import. OpenClinica:EndDate (optional): If the event has a scheduled end date, you can provide that here. Otherwise, delete it or leave it same as start date.--> <StudyEventData StudyEventOID="SE_OID" OpenClinica:StartDate="2017-09-29" OpenClinica:EndDate="2017-09-29" StudyEventRepeatKey="1"> <!--FormOID (required): The OID for the form into which you are importing data. OpenClinica:FormLayoutOID (optional): If no value is provided then the system assigns the default form version to the participant event form. OpenClinica:Status (optional): Possible values for OpenClinica:Status are: 'initial data entry' or 'complete'.
If no value is provided, then the system assigns the status 'initial data entry' to the participant event form on import. --> <FormData FormOID="F_OID" OpenClinica:FormLayoutOID="1.1" OpenClinica:Status="initial data entry"> <!--ItemGroupOID (required): The OID for the item group into which you are importing data. ItemGroupRepeatKey (optional): If not provided, a new repeat key is auto-generated on import.
If a value is provided and the provided repeat key already exists in the database,
then the associated item data is updated in that item group repeat upon import. --> <ItemGroupData ItemGroupOID="IG_OID" ItemGroupRepeatKey="1"> <!--ItemOID and Value (required): The OID of the item into which you are importing data and the data value to be imported into that item.
Any issues with the value of the item will be reported in the log file with an appropriate errorCode. --> <ItemData ItemOID="I_OID" Value="2017-09-13"/> <ItemData ItemOID="I_OID" Value="1"/> <ItemData ItemOID="I_OID" Value="Headache"/> </ItemGroupData> </FormData> </StudyEventData> <!--To import data for more than one Study event, repeat the StudyEventData tag and everything within the opening and closing tags. For a visit-based event with multiple forms, all forms belonging to one repeat of that event should be combined under the same StudyEventData tag. For commom events, each FORM should be provided with a SEPARATE pair of StudyEventData tags.--> </SubjectData> <!-- To import data for more than one Subject, copy and paste the opening and closing SubjectData tags, and everything between those tags. Then update OIDs and values as needed.--> </ClinicalData>

</ODM>

Please refer to the Import Data documentation for detailed information on rules and business logic pertaining to importing data.

Import is a two step process:

  • Create a job to import data using your CDISC ODM XML file
  • Once the job completes, download the log file to review the results

Below is the endpoint to create the import job using your CDISC ODM XML file:

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}}'

{{fileName}} references the full path of the ODM XML file that contains the clinical data to import.

Sample response body on Success

job uuid: 6c325687-c3c3-41f6-hj98-154ef3352cb1

Sample response body on Failure:

When there is a failure in starting the import job then an appropriate error code is returned. 

errorCode.noRoleSetUp 

Below is the list of all the error codes and their descriptions. You can also review the error code process in the create import job process workflow.

  • errorCode.fileFormatNotSupported: File is not an XML file.
  • errorCode.invalidXMLFile: XML file has syntax issues or is not a valid CDISC ODM XML.
  • errorCode.missingStudyOID: No studyOID provided in the XML.
  • errorCode.studyOIDNotFound: the Study OID specified in the request is not found.
  • errorCode.studyOIDNotAvailable: the Study OID specified in the request is in status other than Available.
  • 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.

Below is the endpoint to download the logfile once the job has completed:

Sample cURL request:

curl -X GET \
{{serverName}}/pages/auth/api/jobs/{{jobUuid}}/downloadFile \
  -H 'Authorization: bearer {{authentication token}}'

Sample XML import file content:

 

SubjectKey,ParticipantID,StudyEventOID,StudyEventRepeatKey,FormOID,ItemGroupOID,ItemGroupRepeatKey,ItemOID,Status,Timestamp,Message
SS_LA6,LA-6,SE_STUDYDISCONTINUATION,1,F_TERMINATION,IG_TERMI_GROUP1,1,I_TERMI_DSSTDAT,Inserted,2019-06-07T23:20:32.690Z,
SS_LA6,LA-6,SE_STUDYDISCONTINUATION,1,F_TERMINATION,IG_TERMI_GROUP1,1,I_TERMI_DSAENO,Inserted,2019-06-07T23:20:32.708Z,
SS_LA6,LA-6,SE_BASELINE,1,F_TERMINATION,,,,Failed,,errorCode.formOIDNotFound
SS_LA6,LA-6,SE_CONMEDS,1,F_CONMEDS,IG_CONME_GROUP1,1,I_CONME_MED,Inserted,2019-06-07T23:20:32.825Z,

If there is a failure in returning the job file, then an appropriate error code is returned. Below is the list of all the errorCodes with their descriptions:

  • errorCode.invalidUuid: The Job Uuid specified in the request is not found.
  • errorCode.jobInProgress: The Job represented by the specified job Uuid has not completed.

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.

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

Functional approval by rbhatnagar. Signed on 2019-08-01 11:34PM

Approved for publication by Benjamin Baumann (bbaumann), Principal. Signed on 2019-08-02 3:44PM

Not valid unless obtained from the OpenClinica document management system on the day of use.