Workflows ========= This is an example workflow: 1. 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: .. code-block:: 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: .. code-block:: :emphasize-lines: 3 { "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: .. code-block:: bash 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: .. code-block:: bash :emphasize-lines: 9 { "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. .. code-block:: 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: .. code-block:: [ { "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. .. code-block:: bash 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: .. code-block:: bash :emphasize-lines: 3, 6 { "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. .. code-block:: bash curl -X 'GET' \ 'https://vbr-api.a2cps.cloud/locations/?offset=0&limit=50' \ -H 'accept: application/json' \ -H 'Authorization: Bearer Token .. code-block:: bash :emphasize-lines: 25,26 [ { "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* .. code-block:: bash 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: .. code-block:: bash :emphasize-lines: 2,5 { "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: .. code-block:: bash 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: .. code-block:: bash [ { "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: .. code-block:: bash 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: .. code-block:: bash :emphasize-lines: 11 { "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: .. code-block:: bash 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. .. code-block:: bash :emphasize-lines: 3, 4 { "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" }