17.3 Participants/bulk (Add and Update Bulk list of Participants)

The participants/bulk endpoint is used to perform the participants endpoint function on a list of participant IDs.

The functionality, stipulations and the access control all applies as per the participants endpoint. Click here to learn about the participants 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}/participants/bulk

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/studies/S_JUO%28TEST%29/sites/S_BOSTON_7642%28TEST%29/participants/bulk?register=y \
  -H 'Authorization: bearer {{authentication token}} 
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
  -F 'file=@C:\directory\file.csv'

Request Parameters:

  • register: Possible values: y or n.
    • When set to n, participants will NOT be registered for OpenClinica Participate application
    • When set to y, the system generates an access code for each participant and registers them for OpenClinica Participate application

This endpoint also requires a CSV file with list of participant IDs and their corresponding contact information, if desired. Below are the requirements for the CSV file content:

  • File must have ONE column with header as 'ParticipantID'. This column must contain the Participant ID.
  • File can have either of the following columns: (They are all optional)
    • firstName
    • lastName
    • emailAddress
    • phoneNumber
    • identifier
  • File columns can be in any order.
  • The following restrictions pertain to the values in these columns:
    • firstName and lastName -- Must be less than or equal to 35 characters in length
    • emailAddress -- Must be an email address and must be less than 255 characters in length
    • phoneNumber -- Must be in the format of +# ##########
      • Starts with +
      • Up to 3 digits after + for the country code
      • A space after the country code
      • Up to 14 digits after space for the area code and local code
      • No other characters permitted
      • Up to 17 characters total
    • identifier -- Must be less than or equal to 35 characters in length

"participantList.csv" should be replaced with a CSV file that contains the list of participant IDs that need to be added to the study.

Here's a sample CSV file for adding two participant IDs: JUNO-005 and JUNO-006

Response Body on Success:

job uuid: d2dbdc07-c0f9-4e4d-9ae2-81f5bfaed1c9

Response Body on Failure:

errorCode.invalidSiteIdentifier

Below is the list of error codes with their descriptions:

  • errorCode.studyNotExist: The study OID specified in the request is not found.
  • errorCode.invalidSiteIdentifier: The site OID specified in the request is not found.
  • errorCode.bulkUploadNotSupportSystemGeneratedSetting: Bulk Pparticpant ID upload is not supproted when participant ID setting is set to system-generated. Change the settings to manual Participant ID and try again.
  • 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.
  • errorCode.participateInActive: Participate module is not active for the given study and register flag is set as y in the request.

Once the job has completed, you can access job's log file in the OpenClinica UI via Tasks > Bulk actions log

If the system encounters a proble processing any particular record in the file, an appropriate error code will be returned for that record and displayed within the log file. Here are the possible error codes and their descriptions:

  • errorCode.participantIDContainsUnsupportedHTMLCharacter: Participant ID contains unsupported HTML (<, >) characters.
  • errorCode.participantIDLongerThan30Characters: Participant ID exceeds 30 characters limit.
  • errorCode.participantsEnrollmentCapReached: Participant enrollment limit has reached. No new participants can be added.
  • errorCode.firstNameTooLong: First name value supplied in the record exceeds 35 character limit.
  • errorCode.emailAddressTooLong: Email address value supplied in the record exceeds 255 character limit.
  • errorCode.mobileNumberTooLong: Mobile number value supplied in the record exceeds 17 character limit.
  • errorCode.invalidMobileNumber: Mobile number value supplied in the record not a valid mobile number.
  • errorCode.invalidEmailAddress: Email address value supplied in the record not a valid email address.

 


Functional approval by Paul Bowen (pbowen), Director of Product. Signed on 2019-10-30 3:15PM

Approved for publication by Benjamin Baumann (bbaumann), Principal. Signed on 2019-10-30 4:16PM

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