/
Bulk Importing CP(s) via API (Example)
Got feedback or spotted a mistake?

Leave a comment at the end of this page or email contact@krishagni.com

Bulk Importing CP(s) via API (Example)

Owned by Swapnil Ingle (Unlicensed)
Last updated: May 15, 2024 by Kaustubh Wadagavi

Introduction

Follow these steps to bulk import CP(s) via the BulkImport API.

  1. Download the CSV template file
  2. Fill the CSV file with details
  3. Upload the CSV file
  4. Create and run the import job
  5. Check the job status

Steps

Download the CSV template file

AttributeValue
URL<app-url>/rest/ng/import-jobs/input-file-template?schema=cp
MethodGET
Request Type

application/json

Response
"Title","Short Title","Code","Start Date","End Date","IRB ID","Anticipated Participants Count","PPID Format","Visit Name Format","Label Format","Derivative Label Format","Aliquot Label Format","User inputs PPID","User inputs Visit Name","User inputs Specimen Label","Label Pre-print Mode","Description URL","Activity Status","Sites#1#Name","Sites#1#Code","Sites#2#Name","Sites#2#Code","PI#PI Email","Coordinator#1#Coordinator Email","Coordinator#2#Coordinator Email","Label Print Setting#1#Lineage","Label Print Setting#1#Print Mode","Label Print Setting#1#Copies","Label Print Setting#2#Lineage","Label Print Setting#2#Print Mode","Label Print Setting#2#Copies"

How to import custom fields?

Once the form is attached at Collection Protocol custom fields level, run the URL mentioned in the 'Download the CSV template file' step, and you will get a custom field along with standard once in the output.

Example:

  1. The below form is attached to the CPs at Collection Protocol custom fields level.

    2. Go to the 'Rest API Invoker', run the URL (<app-url>/rest/ng/import-jobs/input-file-template?schema=cp) using GET 

"\"Identifier\",\"Title\",\"Short Title\",\"Code\",\"Start Date\",\"End Date\",\"IRB ID\",\"Anticipated Participants Count\",\"PPID Format\",\"Visit Name Format\",\"Label Format\",\"Derivative Label Format\",\"Aliquot Label Format\",\"User inputs PPID\",\"User inputs Visit Name\",\"User inputs Specimen Label\",\"Label Pre-print Mode\",\"Description URL\",\"Activity Status\",\"Sites#1#Name\",\"Sites#1#Code\",\"Sites#2#Name\",\"Sites#2#Code\",\"PI#PI Email\",\"Coordinator#1#Coordinator Email\",\"Coordinator#2#Coordinator Email\",\"Label Print Setting#1#Lineage\",\"Label Print Setting#1#Print Mode\",\"Label Print Setting#1#Copies\",\"Label Print Setting#2#Lineage\",\"Label Print Setting#2#Print Mode\",\"Label Print Setting#2#Copies\",\"CP custom fields#Protocol Number\",\"CP custom fields#Study Type\",\"CP custom fields#Study Design\",\"CP custom fields#Study Description\"\n"


You can see these are the "CP custom fields#Protocol Number", "CP custom fields#Study Type", "CP custom fields#Study Design", "CP custom fields#Study Description" CP level custom fields from the #1 form.
CSV file: CP_Custom_Fields.csv

Fill the CSV file with details

With the template obtained in step#1 as the header row, fill the details for the Collection Protocols to be bulk-imported.

Example file.

Upload the CSV file

URL<app-url>/rest/ng/import-jobs/input-file
MethodPOST
Request Type

form-data

Response
{
    "fileId": "c3d1cdb4-fbb0-49da-a2ac-ca136f3d9428"
}

Create and run the import job

URL<app-url>/rest/ng/import-jobs
MethodPOST
Request Type

application/json

Request
{
  "objectType" : "cp",
  "importType" : "CREATE",
  "inputFileId" : "c3d1cdb4-fbb0-49da-a2ac-ca136f3d9428"
}
Response
{
    "id": 274,
    "name": "cp",
    "type": "CREATE",
    "status": "QUEUED",
    "totalRecords": null,
    "failedRecords": null,
    "createdBy": {
        "id": 2,
        "type": "SUPER",
        "firstName": "System",
        "lastName": "Administrator",
        "loginName": "admin",
        "domain": "openspecimen",
        "emailAddress": "admin@localhost",
        "instituteName": "Biobank Institute",
        "primarySite": "BIO SITE",
        "admin": true,
        "instituteAdmin": false,
        "manageForms": true,
        "cpCount": 0,
        "creationDate": null,
        "activityStatus": "Active"
    },
    "creationTime": 1563780247635,
    "endTime": null,
    "params": {}
}

Note the 'id' field's value, this is the 'job Id' which refers to this bulk-import job.

Check the job status

URL<app-url>/rest/ng/import-jobs/274
MethodGET
Request Type

application/json

Response
{
    "id": 274,
    "name": "cp",
    "type": "CREATE",
    "status": "COMPLETED",
    "totalRecords": 1,
    "failedRecords": 0,
    "createdBy": {
        "id": 2,
        "type": "SUPER",
        "firstName": "System",
        "lastName": "Administrator",
        "loginName": "admin",
        "domain": "openspecimen",
        "emailAddress": "admin@localhost",
        "instituteName": "Biobank Institute",
        "primarySite": "BIO SITE",
        "admin": true,
        "instituteAdmin": false,
        "manageForms": true,
        "cpCount": 0,
        "creationDate": null,
        "activityStatus": "Active"
    },
    "creationTime": 1563780248000,
    "endTime": 1563780252000,
    "params": {}
}
  1. 'status' refers to the status of the bulk-import job. The status of a bulk-import job can be 'COMPLETED', 'STOPPED', 'FAILED'.
  2. 'totalRecords' refer to the total number of records in the incoming CSV file.
  3. 'failedRecords' refer to the total number of records that failed during processing.
    1. You can see the output file to investigate the error messages for the corresponding failed records.

Get output file for the job

AttributeValue
URL<app-url>/rest/ng/import-jobs/274/output
MethodGET
Request Type

application/json

Response
"Title","Short Title","Code","Start Date","End Date","IRB ID","Anticipated Participants Count","PPID Format","Visit Name Format","Label Format","Derivative Label Format","Aliquot Label Format","User inputs PPID","User inputs Visit Name","User inputs Specimen Label","Label Pre-print Mode","Description URL","Activity Status","Sites#1#Name","Sites#1#Code","Sites#2#Name","Sites#2#Code","PI#PI Email","Coordinator#1#Coordinator Email","Coordinator#2#Coordinator Email","Label Print Setting#1#Lineage","Label Print Setting#1#Print Mode","Label Print Setting#1#Copies","Label Print Setting#2#Lineage","Label Print Setting#2#Print Mode","Label Print Setting#2#Copies","OS_IMPORT_STATUS","OS_ERROR_MESSAGE"
"BOCP1","BOCP1","","","","","","","","","","","","","","","","Active","BIO SITE","","","","admin@localhost","","","","","","","","","SUCCESS",""

Download the 'Postman Collection' file

You can use 'Postman' application to test these API endpoints.

For ease of operation, a 'Postman Collection' file which has all the above REST APIs pre-created can be downloaded from here.

You need to Import the file in the 'Postman' application after downloading.

Got feedback or spotted a mistake?

Leave a comment at the end of this page or email contact@krishagni.com