Introduction
OpenSpecimen supports bulk/batch importing of many entities such as Collection Protocols, Specimen, Visits, Users, etc. Bulk Importing is used in high throughput biobanks or when the user needs to add/update multiple entities to/from OpenSpecimen. (Follow this page for an overview on the BulkImport module)
This page documents the details of bulk import API. Follow this wiki-page for a working example of CP import via API.
Goals for Bulk Import API
- Provide an easy and efficient way to perform a single operation (Insert/Update) on multiple entities.
Steps for Bulk importing
- Download the CSV template file
- Upload the CSV file
- Create and run the import job
- Check the job status
- Download the job report
Download the CSV template file
| Attribute | Value |
|---|---|
| URL | http://<host>:<port>/openspecimen/rest/ng/import-jobs/input-file-template?schema=<schemaName> |
| Method | GET |
| Request Type | application/json |
Replace <schemaName> with the schema name for the entity you wish to bulk import. (Find here the schema name to entity mapping)
Upload the CSV file
| Attribute | Value |
|---|---|
| URL | http://<host>:<port>/openspecimen/rest/ng/import-jobs/input-file |
| Method | POST |
| Request Type | form-data |
| Response | {
"fileId": "fa8e7401-0495-443b-bedc-99a43e0738f5"
}
|
Note down the 'fileId' as this will be used in step #3
Create and run the import job
| Attribute | Value |
|---|---|
| URL | http://<host>:<port>/openspecimen/rest/ng/import-jobs |
| Method | POST |
| Request Type | application/json |
| Request | {
"objectType" : "<objectType>",
"importType" : "<operationType>",
"inputFileId" : "<fileId>"
}
|
- Replace '<objectType>' with the schemaName for the corresponding Bulk Import entity. (Find here the schema name to entity mapping)
- Replace '<operationType>' with 'CREATE' or 'UPDATE' for bulk creating or bulk updating entities respectively.
- Replace '<fileId>' with the fileId retrieved from the step #2
Check the job status
| Attribute | Value |
|---|---|
| URL | http://<host>:<port>/openspecimen/rest/ng/import-jobs/{job-id} |
| Method | GET |
| Request Type | application/json |
Download the job report/output
| Attribute | Value |
|---|---|
| URL | http[s]://<host>:<port>/openspecimen/rest/ng/import-jobs/{job-id}/output |
| Method | GET |
Example of Bulk Importing CP(s) using API
Follow this wiki-page to see an example of bulk importing CP(s) using bulk import API.
Error Cases
| Code | Applies to | Status Message |
|---|---|---|
| 200 | All requests | Bulk Import request was successfully processed. |
| 401 | All requests | Authorisation failed, user doesn’t have the authority. |
| 500 | All requests | Internal server error, encountered server error while performing operations. |