17.5 Events (Create and Update Single Study event)

Study event endpoints are used to:

  • Create a new study event repeat for a given participant
  • Update the properties of a given study event repeat

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

Create new study event repeat

This endpoint creates a new repeat of a visit-based study event for a given participant. The Endpoint requires at a minimum: participant ID, study event OID, and a start date. Using these attributes, the system creates either a new study event repeat with the given start date or returns an error as outlined below.

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

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

Sample cURL request:

curl -X POST \
  {{serverName}}/pages/auth/api/studies/{studyOID}/sites/{siteOID}/events \
  -H 'Authorization: bearer {{authentication token}}' \
  -H 'content-type: application/json' \
  -d '{
  "subjectKey": "MGH-001",
  "studyEventOID": "SE_DEMOGRAPHICS",
  "startDate": "2000-01-01",
  "endDate": "2000-01-01" 
}'

Sample response body when 'Success'

{
    "subjectKey": "MGH-001",
    "studyEventOID": "SE_DEMOGRAPHICS",
    "studyEventRepeatKey": "1",
    "startDate": "2000-01-01",
    "endDate": "2000-01-01",
    "eventStatus": "scheduled"
}

Sample response body when 'Failure'

When there is a failure to create new study event repeat then an errorCode is returned. Plan the follow-up steps based on the returned errorCode.

{
    "message": "errorCode.endDateBeforeStartDate",
    "params": {
        "siteOid": "S_OHIO(TEST)",
        "studyOid": "S_JUNO(TEST)"
    }
}

 

Here is a list of the various error codes and their descriptions. You can also review the error code process in the create study event workflow diagram.

  • errorCode.studyNotExist: The Study OID specified in the request is not found.
  • errorCode.studyNotAvailable: The Study OID specified in the request is in Design, Frozen or Locked status.
  • errorCode.siteNotExist: The Site OID specified in the request is not found.
  • errorCode.siteNotAvailable: The Study OID specified in the request is in Design, Frozen or Locked status.
  • 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.missingParticipantID: The Participant ID (SubjectKey) [participantID] is not present in the request body.
  • errorCode.participantNotFound: The Participant ID (SubjectKey) [participantID] specified in the request is not found under the given Study and/or Site OID.
  • errorCode.missingStudyEventOID: Study event OID is not present in the request body.
  • errorCode.invalidStudyEventOID: Study event OID specified in the request is not valid and/or found in the given Study and/or Site OID.
  • errorCode.commonEventCannotBeScheduled: Returned when the study event OID specified in the request is a common event. This endpoint can be called only for visit based events.
  • errorCode.missingStartDate: Start date is required in order to create a new visit based study event repeat. When start date is missing this error code is returned.
  • errorCode.invalidStartDate: Start date specified in the request is not in valid format. Supported format: yyyy-MM-dd
  • errorCode.invalidEndDate: End date specified in the request is not in valid format. Supported format: yyyy-MM-dd
  • errorCode.endDateBeforeStartDate: End date of a visit based study event can be either same as start date or greater than start date. This error code is returned when end date value passed is less than start date.
  • errorCode.eventAlreadyExists: Study event OID specified in the request is a non-repeating event and that repeat 1 is already when this endpoint is called.

 

Update properties of a study event repeat

This endpoint updates the properties of a given study event for a given participant. For a visit-based event, properties are Start date, end date, and status. For a common event, properties include only the status of the event.

This endpoint requires participant ID, study event OID, and study event repeatKey in order to lookup the appropriate study event. When a match is found, the properties of that event repeat are updated with the values of start date, end date, and/or status passed in the request. 

Please note: 

  • Status of an event follows a strict transition path. Please see the status transition diagram.
  • If no update is required for a given property, remove that property from the request body. An empty value will not be accepted. 

PUT {serverName}/pages/auth/api/studies/{studyOID}/sites/{siteOID}/events

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

Sample cURL request:

curl -X POST \
  {{serverName}}/pages/auth/api/studies/{studyOID}/sites/{siteOID}/events \
  -H 'Authorization: bearer {{authentication token}}' \
  -H 'content-type: application/json' \
  -d '{
  "subjectKey": "participantID",
  "studyEventOID": "studyEventOID",
"studyEventRepeatKey": "1", "startDate": "YYYY-MM-DD", "endDate": "YYYY-MM-DD",
"status": "data entry started"
}'

Sample response body when 'Success'

{
    "subjectKey": "participantID",
    "studyEventOID": "studyEventOID",
    "studyEventRepeatKey": "1",
    "startDate": "2000-01-01",
    "endDate": "2000-01-01",
    "eventStatus": "scheduled"
}

Sample response body when 'Failure'

When there is a failure to update the study event repeat properties, an error code is returned. 

{
    "message": "errorCode.endDateBeforeStartDate",
    "params": {
        "siteOid": "S_OHIO(TEST)",
        "studyOid": "S_JUNO(TEST)"
    }
}

 

Here is the list of the error codes and their desciptions for this endpoint. You can also view the error code processing in the complete update study event workflow diagram.

  • errorCode.studyNotExist: The Study OID specified in the request is not found.
  • errorCode.studyNotAvailable: The Study OID specified in the request is in Design, Frozen or Locked status.
  • errorCode.siteNotExist: The Site OID specified in the request is not found.
  • errorCode.siteNotAvailable: The Study OID specified in the request is in Design, Frozen or Locked status.
  • 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.missingParticipantID: The Participant ID (SubjectKey) [participantID] is not present in the request body.
  • errorCode.participantNotFound: The Participant ID (SubjectKey) [participantID] specified in the request is not found under the given Study and/or Site OID.
  • errorCode.missingStudyEventOID: Study event OID is not present in the request body.
  • errorCode.invalidStudyEventOID: Study event OID specified in the request is not valid and/or found in the given Study and/or Site OID.
  • errorCode.missingStudyEventRepeatKey: Study event repeatKey is required for the lookup. When its not present in the request then this error code is returned.
  • errorCode.invalidStudyEventRepeatKey: When repeatKey specified in the request is not a valid integer.
  • errorCode.studyEventRepeatNotFound: When no results are found for the given participant ID, study event OID, and study event repeatKey.
  • errorCode.invalidStartDate: Start date specified in the request is not in valid format. Supported format: yyyy-MM-dd
  • errorCode.invalidEndDate: End date specified in the request is not in valid format. Supported format: yyyy-MM-dd
  • errorCode.endDateBeforeStartDate: The end date of a visit based study event can be either the same as start date or greater than start date. This error code is returned when end date value passed is less than start date.
  • errorCode.invalidStatus: Status specified in the request body is not a valid status.
  • errorCode.eventStatusTransitionNotAllowed: The status of the given study event repeat is not allowed to be moved to the status that's specified in the request body then this error code is returned.
  • errorCode.eventStatusTransitionNotAvailable: The status of the given study event repeat cannot be moved to the status that's specified in the request body because there are other conditions that must be met before it is possible. When those conditions are not satisfied at the time of request then this error code is returned. For example: event status can move from data entry started to completed only when all the forms in that event are completed. In this case, if one of the forms is in initial data entry started when user made a request to update the study event status to be completed then this error code will be returned.

Approved for publication by rbhatnagar. Signed on 2019-08-02 5:36PM

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