Skip to main contentIBM Blockchain Transparent Supply™ Docs

Trace API

The IBM Blockchain Transparent Supply™ Trace API allows authorized users to retrieve trace information for your organization’s supply chain events, transactions, products and facilities.

Prerequisites

To use the IBM Blockchain Transparent Supply™ Trace API, you must meet the following prerequisites:

  1. Your organization has subscribed to the Trace module.

  2. Your data integration experts are familiar with using REST APIs to send data programmatically. Automation of data upload is an ultimate goal to facilitate data sharing.

  3. For IBM Blockchain Transparent Supply™ organizations to share and trace supply chain data, each organization must have defined the appropriate data sharing authorization. For details on restricting and sharing your data, see Data entitlement mode.

Getting started

Take the following steps to get started with the IBM Blockchain Transparent Supply™ Trace API:

  1. Obtain an authentication token, as described in Authenticate human users and Authenticate system users.

  2. Submit a Trace API request with the authentication token in the Authorization header, as shown in the example request. For manual uploads, human users can use Swagger to run the APIs directly.

  3. For help understanding the API response model, refer to the documentation below.

Swagger

To use the Trace API manually, use the Swagger interface:

You must first provide a valid IBM Blockchain Transparent Supply™ authorization token (human user token) on Swagger, using the Authorize button on the top right of the page.

Traces endpoint

The /traces endpoint retrieves trace information based on the specified product identifier (product ID): /ift/api/outbound/v2/traces

Parameters

The product ID (query string) identifies the specific product instance to trace. The supported formats are shown in Table 1:

Table 1. Supported product ID formats

TypeExample and syntax
EPC LGTINurn:epc:class:lgtin:0614141.107346.101
urn:epc:class:lgtin:<CompanyPrefix>.<ItemRefAndIndicator>.<Lot> (13 digits + Lot #)
EPC SGTINurn:epc:id:sgtin:0614141.107346.2017
urn:epc:id:sgtin:<CompanyPrefix>.<ItemRefAndIndicator>.<SerialNumber> (13 Digits + Serial Number)
IBM Blockchain Transparent Supply™ product ID with Lot #urn:ibm:ift:product:lot:class:1234567890123.product-123.lot4
urn:ibm:ift:product:lot:class:<Company Prefix>.<Item Reference>.<Lot Number>
IBM Blockchain Transparent Supply™ product ID with Serial #urn:ibm:ift:product:serial:obj:1234567890123.product-123.serial-number-4567
urn:ibm:ift:product:serial:obj:<Company Prefix>.<Item Reference>.<Serial Number>

Example query

Request:

curl -X GET "https://<solution domain name>/ift/api/outbound/v2/traces?productId=urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-1" -H "accept: application/json" -H "Authorization: Bearer '<VALID_IFT_AUTHORIZATION_TOKEN>'"

Response:

{
"urn:ibm:ift:product:lot:class:999999999999.sliced-mango.lot-1": {
"events": {
"urn:uuid:c50240fc-4df3-4d34-bd16-36031bf8b2a5": {
"data": {
"time": "2018-10-28T00:00:00.000Z",
"type": "commission",
"step": "urn:epcglobal:cbv:bizstep:commissioning",
"facility": {

Response Model

The Trace API returns data pertaining to events, locations, data payloads, products, and the corresponding sequencing of these items, in the following JSON format:

{
"<TRACE_PRODUCT_ID>": {
"events": {
<EVENT_OBJECTS>
},
"facilities": {
<FACILITY_OBJECTS>
},
"payloads": {

For each JSON object, the data model and example JSON are provided below:

Events

Event information related to the product identifier are returned in the events block of the JSON response. By default, only the following event types are returned:

  • Lot creation - Events information collected during the lot creation for products.
    • Lot creation events must meet the following criteria:
      • Event type: Commission
  • Transformation - Events information collected when input products are transformed into new products.
    • Transformation events must meet the following criteria:
      • Event type: Transformation
  • Store scan - Events information collected when the product is scanned at a store.
    • Store scan events must meet the following criteria:
      • Event type: Observation
      • Biz step: Stocking

Model:

"events": {
// Unique ID of the event
"<EVENT_ID>": {
"data": {
// Date and time of the event in the format: "yyyy-mm-ddThh:mm:ss.mmmZ"
"time": "<EVENT_TIME>",
// Type of business transaction (commission, transformation, observation)
"type": "<EVENT_TYPE>",
// Business step that the event was a part of in the format: "urn:epcglobal:cbv:bizstep:Step"

Example:

"events": {
"urn:uuid:c50240fc-4df3-4d34-bd16-36031bf8b2a5": {
"data": {
"time": "2018-10-28T00:00:00.000Z",
"type": "commission",
"step": "urn:epcglobal:cbv:bizstep:commissioning",
"facility": {
"id": "urn:ibm:ift:location:loc:999999999999.farm-1"
},

Facilities

Facility information related to a product trace is returned in the facilities block. The model is shown below:

Model:

"facilities": {
// Unique ID for the facility
"<FACILITY_ID>": {
"data": {
"name": "<FACILITY_NAME>",
// Type of facility (STORE, FARM, SUPPLIER, etc)
"type": "STORE",
"address": {
"street": "<FACILITY_STREET_ADDRESS>",

Example:

"facilities": {
"urn:ibm:ift:location:loc:999999999999.farm-1": {
"data": {
"name": "Tropical Farms",
"type": "FARM",
"address": {
"city": "Miami",
"postalCode": "72814"
}

Payloads

Payload information related to a product trace is returned in the payloads block. One or more trace events, facilities, products, or product instances can reference a payload ID. The model is shown below:

Model:

"payloads": {
// Unique ID of the payload
"<PAYLOAD_ID>": {
"data": {
// Date and time of the payload in the format: "yyyy-mm-ddThh:mm:ss.mmmZ"
"time": "<PAYLOAD_TIME>",
// Customized content in a String format
"content": "<PAYLOAD_CONTENT>",
// HTTP content type of the payload (application/json, application/xml, etc)

Example:

"payloads": {
"urn:uuid:eed87696-40cc-4839-a609-24d8f0429d08": {
"data": {
"time": "2018-11-02T00:00:00.000Z",
"content": "customized data",
"contentType": "application/json",
"typeUri": "typeUriString"
}
}

Product Instances

Product instance (such as lot-level) information related to a product trace is contained in the productInstances block. A productInstance is a specific instance or lot of a product. The model is shown below:

Model:

"productInstances": {
// Unique ID of the product instance
"<PRODUCT_INSTANCE_ID>: {
"data": {
"name": "<PRODUCT_NAME>",
"productId": "<PRODUCT_ID>",
// Date of freeze in YYYY-MM-DD format
"firstFreezeDate": "<DATE>",
// Date of the start of harvest in YYYY-MM-DD format

Example:

"productInstances": {
"urn:ibm:ift:product:lot:class:999999999999.mango.lot-1": {
"data": {
"name": "Mango",
"productId": "urn:ibm:ift:product:class:999999999999.mango"
},
"payloadIds": []
},
"urn:ibm:ift:product:lot:class:999999999999.mango.lot-2": {

Products

General product information related to a trace is returned in the products block. The model is shown below:

Model:

"products": {
// Unique ID of the product
"<PRODUCT_ID>": {
"data": {
"name": "<PRODUCT_NAME>",
"sku": "<PRODUCT_SKU>"
},
// List of associated Payload IDs
"payloadIds": [

Example:

"products": {
"urn:ibm:ift:product:class:999999999999.mango": {
"data": {
"name": "Mango"
},
"payloadIds": []
},
"urn:ibm:ift:product:class:999999999999.sliced-mango": {
"data": {

Sequences

Sequences describes the corresponding sequencing of events, facilities, and products. Each array outlines an ordered list that shows matching source and targets. This information can be used to create a linear timeline or a tree structure, depending on the returned data.

Model:

"sequences": {
"events": [
{
"source": "<EVENT_SOURCE_ID>",
"target": "<EVENT_TARGET_ID>"
},
],
"facilities": [
{

Example:

"sequences": {
"events": [
{
"source": "urn:uuid:c50240fc-4df3-4d34-bd16-36031bf8b2a5",
"target": "urn:uuid:7d87bbfd-e9b0-49ee-9c04-d2938f6138f8"
},
{
"source": "urn:uuid:b3b8ee28-58cb-4f26-9ad5-f27b27cb89d6",
"target": "urn:uuid:7d87bbfd-e9b0-49ee-9c04-d2938f6138f8"

API response caching

By default, API responses are cached for 24 hours. The first query will have a longer response time, but subsequent queries with the same parameters should have faster response times. A separate entry is cached for each unique tuple based on the following information:

  • organization identifier from the request token
  • productId input query parameter

Bypassing or updating the cached response

If you have updated trace data within the previous 24 hours, you may want to retrieve the latest trace information. To bypass the cache, provide an HTTP header named X-ApiCache-Bypass with a value of true. This will bypass the API cache and return the latest available trace information.

Be aware that bypassing the cache will result in much longer response times, so only provide the X-ApiCache-Bypass header when there has been updated trace information. When the cache is bypassed, the latest response information will be added to the current API cache. Therefore, subsequent requests with the same parameters will return the updated trace information.