Workflows¶

This is an example workflow:

Process receipt of a shipment:
- Get shipment by tracking ID
- Update shipment status
- List containers in shipment
- Update status of each container
- Update location of each container
- List biosamples in each container
- Update status of each biosample
- Update tracking ID for each biosample (if non-unique)

Get shipment by tracking ID¶

Let us use a known “tracking_id” : 285590095441.

Use the GET /shipments/tracking/{tracking_id} endpoint to get a shipment by it’s tracking id.

The curl request would be:

  curl -X 'GET' \
'https://vbr-api.a2cps.cloud/shipments/tracking/285590095441' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

A successful response would look like:

 {
     "shipment_id": "76zV8EM980jA4",
     "tracking_id": "285590095441",
     "shipment_name": "Northshore Shipping -1",
     "sender_name": "MR/VW",
     "project_name": "A2CPS Multisite Clinical Center 1",
     "ship_from": "MCC1: NorthShore University HealthSystem",
     "ship_to": "Receiving: University of California San Diego",
     "status": "shipment.shipped"
 }

Update shipment status¶

Use the PATCH /shipments/tracking/{tracking_id}/status endpoint to update the shipment status.
Permitted status values are [‘created’, ‘shipped’, ‘received’, ‘processed’, ‘delayed’, ‘lost’].

The curl request would be:

 curl -X 'PATCH' \
'https://vbr-api.a2cps.cloud/shipments/tracking/285590095441/status' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
  "status": "created",
  "relocate_containers": false,
  "comment": "string"
  }'

A successful response would be:

 {
     "shipment_id": "76zV8EM980jA4",
     "tracking_id": "285590095441",
     "shipment_name": "Northshore Shipping -1",
     "sender_name": "MR/VW",
     "project_name": "A2CPS Multisite Clinical Center 1",
     "ship_from": "MCC1: NorthShore University HealthSystem",
     "ship_to": "Receiving: University of California San Diego",
     "status": "shipment.created"
 }

List containers in shipment¶

The /shipments/tracking/{tracking_id}/containers endpoint can be used to get the containers in a shipment.

 curl -X 'GET' \
'https://vbr-api.a2cps.cloud/shipments/tracking/285590095441/containers' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

A successful response would be:

  [
  {
      "container_id": "eAbV8nryeVoX",
      "container_tracking_id": "K_NS_BOX_ALI0001",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "P4KAOZ088xbpZ",
      "container_tracking_id": "K_NS_BOX_ALI0002",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "8em97go61M29W",
      "container_tracking_id": "K_NS_BOX_ALI0003",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "8L62j5zZ7yWP6",
      "container_tracking_id": "K_NS_BOX_ALI0004",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "7ykNrLzkZR3g3",
      "container_tracking_id": "K_NS_BOX_ALI0005",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  },
  {
      "container_id": "8PAnJWgwJNKLp",
      "container_tracking_id": "K_NS_BOX_ALI0006",
      "container_type": "blood aliquot freezer box",
      "location": "MCC1: NorthShore University HealthSystem",
      "status": "created",
      "tracking_id": "285590095441"
  }
]

Update status of each container¶

The PATCH /containers/{container_id}/status endpoint can be used to update the status of a container.

Let us pick a container_id of interest and update it’s status.

curl -X 'PATCH' \
'https://vbr-api.a2cps.cloud/containers/8PAnJWgwJNKLp/status' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
    "status": "created",
    "comment": "string"
}'

A successful response would look like:

{
     "container_id": "8PAnJWgwJNKLp",
     "container_tracking_id": "K_NS_BOX_ALI0006",
     "container_type": "blood aliquot freezer box",
     "location": "MCC1: NorthShore University HealthSystem",
     "status": "container.created",
     "tracking_id": "285590095441"
 }

We can modify the status of each container using this endpoint.

Update location of each container¶

To update the location of each container, we need to find out the location_id of the location of interest. For e.g: “location”: “MCC1: NorthShore University HealthSystem”, let us find it’s location_id by following the procedure below.

Use the GET /locations/ endpoint to get a list of locations with their details.

 curl -X 'GET' \
'https://vbr-api.a2cps.cloud/locations/?offset=0&limit=50' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token

[
   {
      "location_id": "PAPmJLX2Pr4yM",
      "display_name": "MCC1: Institute for Translational Medicine",
      "address1": "",
      "address2": "",
      "address3": "",
      "city": "Chicago",
      "state_province_country": "IL",
      "zip_or_postcode": "60637",
      "organization": "ITM"
   },
   {
      "location_id": "PAPmqezqm8rOn",
      "display_name": "MCC1: The University of Chicago Medical Center",
      "address1": "",
      "address2": "",
      "address3": "",
      "city": "Chicago",
      "state_province_country": "IL",
      "zip_or_postcode": "60637",
      "organization": "UCMC"
   },
   {
      "location_id": "PAPmqjv157Moe",
      "display_name": "MCC1: NorthShore University HealthSystem",
      "address1": "",
      "address2": "",
      "address3": "",
      "city": "Evanston",
      "state_province_country": "IL",
      "zip_or_postcode": "60201",
      "organization": "NS"
   }
]

From the above response, we can see the the MCC1: NorthShore University HealthSystem corresponds to location_id : PAPmqjv157Moe

With the location_id in hand, we can now update the location of a container of interest.

The PATCH /containers/{container_id}/location endpoint can be used to update the location of each container.
Let us update the location of the container_id : 8PAnJWgwJNKLp

curl -X 'PATCH' \
'https://vbr-api.a2cps.cloud/containers/8PAnJWgwJNKLp/location' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
   "location_id": "PAPmqjv157Moe",
   "comment": "string"
}'

A successful response would look like:

{
   "container_id": "8PAnJWgwJNKLp",
   "container_tracking_id": "K_NS_BOX_ALI0006",
   "container_type": "blood aliquot freezer box",
   "location": "MCC1: NorthShore University HealthSystem",
   "status": "container.created",
   "tracking_id": "285590095441"
}

List biosamples in each container¶

The GET /containers/{container_id}/biospecimens can be used to list the biospecimens in a container.

The curl request would be:

 curl -X 'GET' \
'https://vbr-api.a2cps.cloud/containers/8PAnJWgwJNKLp/biospecimens' \
-H 'accept: application/json' \
-H 'Authorization: Bearer Tkeno

A successful response would look like:

  [
  {
      "biospecimen_id": "PdrmvReLkjeNB",
      "tracking_id": "K_NS_P_0050",
      "creation_time": "2021-09-08T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "8P6R89Y60NBn8",
      "collection_tracking_id": "K_NS_KIT_0050",
      "container_id": "8PAnJWgwJNKLp",
      "container_tracking_id": "K_NS_BOX_ALI0006",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "67c83cf9-4e9e-985d-1003-e776efecee86",
      "subject_id": "1bnoL9dYY8xx8",
      "bscp_time_blood_draw": "2021-09-08T11:03:00",
      "bscp_time_centrifuge": "2021-09-08T11:23:00",
      "bscp_aliquot_freezer_time": "2021-09-08T11:28:00",
      "bscp_deg_of_hemolysis": 0,
      "bscp_phleb_by_init": "AV",
      "bscp_procby_initials": "MR",
      "bscp_protocol_dev": false,
      "bscp_comments": "",
      "location": "MCC1: NorthShore University HealthSystem"
  },
  {
      "biospecimen_id": "1yv0R0NvKBYXm",
      "tracking_id": "K_NS_P_0047",
      "creation_time": "2021-09-13T00:00:00",
      "biospecimen_type": "serum or plasma",
      "collection_id": "7kgm6XRjgkvmb",
      "collection_tracking_id": "K_NS_KIT_0047",
      "container_id": "8PAnJWgwJNKLp",
      "container_tracking_id": "K_NS_BOX_ALI0006",
      "project": "A2CPS Multisite Clinical Center 1",
      "status": "created",
      "unit": "plasma_aliquot_tube",
      "subject_guid": "24caec78-fd6d-5843-6338-d01d21d966a9",
      "subject_id": "P4Z1nP60yYkqX",
      "bscp_time_blood_draw": "2021-09-13T09:34:00",
      "bscp_time_centrifuge": "2021-09-13T09:54:00",
      "bscp_aliquot_freezer_time": "2021-09-13T09:59:00",
      "bscp_deg_of_hemolysis": 0,
      "bscp_phleb_by_init": "SL",
      "bscp_procby_initials": "MR",
      "bscp_protocol_dev": false,
      "bscp_comments": "",
      "location": "MCC1: NorthShore University HealthSystem"
  }
]

Update status of each biosample¶

We can update the status of a biospecimen using the PATCH /biospecimens/{biospecimen_id}/status endpoint.

The permitted values for status are: “inflight”, “present”, “spoiled”, “depleted”, “lost”, “destroyed”.

The curl request would be:

curl -X 'PATCH' \
   'https://vbr-api.a2cps.cloud/biospecimens/7yAnxZN36BJJb/status' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer Token \
   -H 'Content-Type: application/json' \
   -d '{
      "status": "inflight",
      "comment": "string"
   }'

A successful response would look like:

{
   "biospecimen_id": "7yAnxZN36BJJb",
   "tracking_id": "K_RU_P_0017",
   "creation_time": "2021-04-30T00:00:00",
   "biospecimen_type": "serum or plasma",
   "collection_id": "PdV482PnBozxe",
   "collection_tracking_id": "K_RU_KIT_0021",
   "container_id": "8PqD2Xb7AgzA2",
   "container_tracking_id": "K_RU_BOX_ALI_0002",
   "project": "A2CPS Multisite Clinical Center 1",
   "status": "measurement.inflight",
   "unit": "plasma_aliquot_tube",
   "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
   "subject_id": "Pxk1yXJPV3ADX",
   "bscp_time_blood_draw": "2021-04-30T11:53:00",
   "bscp_time_centrifuge": "2021-04-30T12:13:00",
   "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
   "bscp_deg_of_hemolysis": 1,
   "bscp_phleb_by_init": "KB",
   "bscp_procby_initials": "MM",
   "bscp_protocol_dev": true,
   "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
   "location": "MCC1: Rush University Medical Center"
}

Update tracking ID for each biosample (if non-unique)¶

We can update the Tracking Id of a biospecimen to an Id of our choice.

The curl request would be:

curl -X 'PATCH' \
   'https://vbr-api.a2cps.cloud/biospecimens/7yAnxZN36BJJb/tracking_id' \
   -H 'accept: application/json' \
   -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJqdGkiOiI0ZTcyNTM2NC1hNzUzLTRkMjEtYmI2Ni1kYTgxZDEzZjRmNzIiLCJpc3MiOiJodHRwczovL2EyY3BzZGV2LnRhcGlzLmlvL3YzL3Rva2VucyIsInN1YiI6InNnb3BhbEBhMmNwc2RldiIsInRhcGlzL3RlbmFudF9pZCI6ImEyY3BzZGV2IiwidGFwaXMvdG9rZW5fdHlwZSI6ImFjY2VzcyIsInRhcGlzL2RlbGVnYXRpb24iOmZhbHNlLCJ0YXBpcy9kZWxlZ2F0aW9uX3N1YiI6bnVsbCwidGFwaXMvdXNlcm5hbWUiOiJzZ29wYWwiLCJ0YXBpcy9hY2NvdW50X3R5cGUiOiJ1c2VyIiwiZXhwIjoxNjQzNjcwODI3LCJ0YXBpcy9jbGllbnRfaWQiOm51bGwsInRhcGlzL2dyYW50X3R5cGUiOiJwYXNzd29yZCJ9.DwyzMvLGm1hPvxFmMRpPGJ9DhyZqQTlp_newlgRCFvKsywDVnGofOD3s62OBxRJvuaxdlfSKoWTnPzGTfuFfItKCGzOWl9USkvKnroRq8m47z5gX1m3DkqOE_zrzyQn-u4nqJvFGWOLOPB94W5mgf4jFncU2LXmNdjy5eJvmqSXe3FqKYHxsPRweZc12ykgUYeaJSmd45Pce8bG2-KTLEcvX3ECh6sjtJ7w5rZY5ASn0BPBayYMUtUsJrV5dKwmAmRWbxjDvBf9sHysxpUj2FwkbIsMTwSyDUN9Euii0zbKfYcUg3fBJUYF86ll3CNpixzxe23T6Tr9jbf2HE5PDTQ' \
   -H 'Content-Type: application/json' \
   -d '{
      "tracking_id": "1234check",
      "comment": "Optional comment explaining or documenting the change"
   }'

A successful response would hold the new tracking_id for our biospecimen.

{
   "biospecimen_id": "7yAnxZN36BJJb",
   "tracking_id": "1234check",
   "creation_time": "2021-04-30T00:00:00",
   "biospecimen_type": "serum or plasma",
   "collection_id": "PdV482PnBozxe",
   "collection_tracking_id": "K_RU_KIT_0021",
   "container_id": "8PqD2Xb7AgzA2",
   "container_tracking_id": "K_RU_BOX_ALI_0002",
   "project": "A2CPS Multisite Clinical Center 1",
   "status": "measurement.inflight",
   "unit": "plasma_aliquot_tube",
   "subject_guid": "90f8fc45-5d53-0de4-6853-284607a8c4e6",
   "subject_id": "Pxk1yXJPV3ADX",
   "bscp_time_blood_draw": "2021-04-30T11:53:00",
   "bscp_time_centrifuge": "2021-04-30T12:13:00",
   "bscp_aliquot_freezer_time": "2021-04-30T12:24:00",
   "bscp_deg_of_hemolysis": 1,
   "bscp_phleb_by_init": "KB",
   "bscp_procby_initials": "MM",
   "bscp_protocol_dev": true,
   "bscp_comments": "Unable to collect blood at baseline. Blood collected DOS.",
   "location": "MCC1: Rush University Medical Center"
}

Workflows¶

Get shipment by tracking ID¶

Update shipment status¶

List containers in shipment¶

Update status of each container¶

Update location of each container¶

List biosamples in each container¶

Update status of each biosample¶

Update tracking ID for each biosample (if non-unique)¶

VBR API

Navigation

Related Topics