16.2 Clinicaldata (Import and Retrieve Clinical Data)

The Clinicaldata endpoint allows you to import or retrieve clinical data in JSON or CDISC ODM XML format, including file attachments, using the OpenClinica API.

ℹ️ Prerequisites: 

• You must be authenticated before calling the service.
• Your ability to use the endpoint is determined by your role and permissions.

Importing Clinical Data:

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.

Example Import XML Template

To use the template:

1. Copy the text into a new .xml file.
2. Update the OIDs and values 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>

You can use the Clinical Data Import API to upload files into form items that support attachments.

To include attachments:

1. Create an XML import file that specifies the items.
2. Create a ZIP file of a folder containing all referenced attachments.
3. In the XML, set the item’s Value to the file name. The API will match it to the corresponding file in the ZIP.

ℹ️ File attachments can only be uploaded through the XML Import API; they are not supported using the Import screen in Study Runner or using the Tabular Import API.

ZIP file requirements

• Must contain all files referenced in the XML.
• All standard file formats are supported.
• Maximum size: ~2 GB by default.

⚠️ Note: OpenClinica does not validate that an uploaded file matches the item type (for example, an image for an Image item). Any file type can be uploaded, consistent with the UI behavior.

Audit logging

Each import is logged separately in the Audit Log, even if you re-import the same XML and ZIP.

Import Process

Import is a Two Step Process:

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

Create Import Job

Endpoint:

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

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

• {{serverName}} = your study URL (e.g. https://customerxyz.openclinica.io/OpenClinica).
• {{authentication token}} = your unique authentication token. For more information on how to get your authentication token, refer to How and When to Use APIs.
• {{fileName}} = full path of the XML file containing clinical data.
• {{zipFilePath}} = full path of the ZIP file containing file attachments.

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

Import Error Codes:

• errorCode.fileFormatNotSupported: File is not an XML file.
• errorCode.invalidXMLFile: CDISC ODM XML file is invalid or contains syntax issues.
• errorCode.missingStudyOID: No studyOID provided in the XML.
• errorCode.studyOIDNotFound: The specified Study OID was not found.
• errorCode.studyOIDNotAvailable: The specified Study OID is not in Available status.
• errorCode.noRoleSetup: The user has no role defined for the study or site
• errorCode.noSufficientPrivileges: The user does not have sufficient privileges to perform this operation.
• errorCode.missingItemFile.[filename]: There is a file name in the item value without a corresponding file in the ZIP file.
• errorCode.multipleFiles: Multiple ZIP files were submitted.

Downloading Import Logs

Endpoint:

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

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,

Retrieving Clinical Data

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.

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