Bulk Create and Update Study Events - OpenClinica Reference Guide

16.7 Bulk Create and Update Study Events

The bulk study event endpoint is used to create or update multiple study events for a list of participant IDs.

The functionality, stipulations and access control for this endpoint is the same as per the single create and update study event endpoint.

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

URL:

POST {serverName}/pages/auth/api/clinicaldata/studies/{studyOID}/sites/{siteOID}/events/bulk

where {serverName} is your customer URL. For example: https: //customerxyz.openclinica.io/OpenClinica

Sample cURL Request:

curl -X POST 
  {{serverName}}/pages/auth/api/clinicaldata/studies/S_JUNO%28PROD%29/sites/S_BOSTON_3152%28PROD/events/bulk 
  -H 'Authorization: bearer {{authentication token}} 
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' 
  -F 'file=@C:directoryfile.csv'

Request Parameters:

This endpoint requires a CSV file with list of Participant IDs, and the Study Event related information. The CSV file must adhere to the following:

File must have ONE column with header as ‘ParticipantID’. This column must contain the Participant ID.
File must have a column for StudyEventOID
The following additional columns are required based on the action to be performed on the given StudyEventOID:
- To Create a new Study Event
  - StudyEventRepeatKey must be EMPTY
  - StartDate must be present (time is optional)
  - EndDate is optional (time is optional)
  - StudyEventStatus is not used
- To Update the Study Event
  - StudyEventRepeatKey must be present and a valid integer
  - StartDate is optional (time is optional)
  - EndDate is optional (time is optional)
  - StudyEventStatus is optional
File columns can be in any order.
Below are the restrictions on the values in these columns:
- ParticipantID and StudyEventOID must be valid identifiers under the given study site
- StudyEventRepeatKey must be an integer value
- StartDate and EndDate must be in ‘yyyy-MM-dd’ format (or ‘yyyy-MM-dd hh:mm’ format if including time)
- StudyEventStatus may include the values: ‘data entry started’, ‘stopped’, ‘skipped’, ‘locked’ and ‘completed’.

Here’s a sample CSV file for creating study event and modifying the study events for the given participants.

Response Body on Success:

Endpoint will submit the job in the background and will return the unique job uuid.

job uuid: ddbadff4-f015-4a2d-81e0-e3daf507bbfc

Response Body on Failure to Submit the Job:

{
  "message": "errorCode.siteNotExist",
  "params": {
    "siteOid": "S_OHIO(PRD)",
    "studyOid": "S_JUNO(PROD)"
  }
}

Below is the List of Error Codes with their Descriptions:

errorCode.studyNotExist: The Study OID specified in the request is not found.
errorCode.siteNotExist: The Site OID specified in the request is not found.
errorCode.notSupportedFileFormat: The file format is not supported. Only CSV files are accepted.
errorCode.noRoleSetUp: The user has no role assigned for the given Study/Site.
errorCode.noSufficientPrivileges: The user does not have sufficient privileges to perform this operation.

Once the job has completed you can access the job’s log file in the OpenClinica UI via Tasks and Bulk Actions Log

In case of in processing any particular record in the file, an appropriate errorCode will be returned for that record within the logfile.

Here is the List of Possible Error Codes with their Descriptions:

errorCode.participantNotFound: No participant record was found for the given Participant ID value.
errorCode.missingParticipantID: Participant ID value is missing in the record.
errorCode.missingStudyEventOID: Study event OID value is missing in the record.
errorCode.invalidStudyEventOID: Study event OID value in the record is not a valid study event OID.
errorCode.CommonEventCannotBeScheduled: Study event OID in the record is a common event and hence cannot be scheduled.
errorCode.missingStartDate: Start date is missing and therefore study event cannot be scheduled.
errorCode.invalidStartDate: Start date in the record is invalid.
errorCode.endDateBeforeStartDate: End date is before the start date.
errorCode.invalidEndDate: End date in the record is invalid.
errorCode.studyEventRepeatNotFound: Study event repeat key in the record is not found for the given participant.
errorCode.invalidEventStatus: Status in the record is not a valid status.
errorCode.invalidEventTransitionStatus: When the study event transition status from the current status of the given study event repeat to the status provided in the record is not allowed.

Export PDF