Co-authored by Max Zuo and Nathan Barry
Summary
The IBM Blockchain Transparent Supply Trace API can help supply chain members quickly trace products both upstream and downstream across all the data they are entitled to. This blog post demonstrates some of the capabilities the Trace API offers and outlines some example use cases that can help resolve common recall scenarios. We encourage you to download the code (here) and follow the steps (here) to run these scenarios against your own data. Furthermore, you can explore the Trace API Swagger page to learn more about the additional functionality that the Trace API offers.
*All references to URLs containing developer.transparentsupply.ibm.com require signing up for a trial to the Transparent Supply Developer Playground to get access (contact our team about this here), but can be replaced with the base domain for any existing IBM Food Trust or Blockchain Transparent Supply customers (e.g. food.ibm.com)
Trace API Use Case 1: Determine the impact of a recall in regard to products you produced and shipped
A recall has been issued for some number of products originating from a particular region. As a producer submitting data, you need to know what products have been created using those recalled ingredients, who you shipped those products to, and the purchase orders or transaction documents that delivered recalled goods.
This scenario is common in the context of food producers in IBM Food Trust (an instance of IBM Blockchain Transparent Supply). In these cases, there are typically a number of specific product identifiers (GTINs) that are all under the same family of products that are being recalled. The food producers often have a single location representing the growing region that was impacted.
Step 1: Locate all lots for products produced in the impacted growing region
When a recall is announced, the producer's first task is to locate all of the lots for any of those products which were commissioned in that region during a specific timeframe. The /harvested-epcs endpoint in the example code can do exactly what is needed here, taking those input parameters and resulting in a set of Electronic Product Codes (EPCs) to identify the lots harvested. This can be done with a single trace API call to the /events API which searches for the commission events that meet these criteria.
Sometimes these lots have been shipped to retailers directly, but some of them might have been used as ingredients in the production of other products.
Step 2: Find products created from the impacted lots
The next step is to find which products were created from these lots. For this, we would again use the /events API, searching for transformation events where the harvested EPCs from the first step were input ingredients. The /impacted-epcs endpoint combines the harvested EPCs with the outputs from the transformation events to produce a complete list of impacted products.
Step 3: Identify purchase orders for impacted products
The last step for this use case is to identify the purchase orders that were satisfied using these lots. In this food supply chain scenario, the lots are typically packed into a pallet and shipped to the retailer in an aggregation event. The /impacted-transactions endpoint again uses the /events API to find the aggregation events, and from each of those events finds the referenced business transactions, which include the purchase orders fulfilled using these.
Advantages and limitations of this approach
This approach uses a single API call (/events) and is able to pinpoint the desired data without any complex logic. It is fairly fast to execute and simple to understand. However, this approach is somewhat tailor-made for this supply chain. It makes assumptions that may not be true in each supply chain, such as:
- All products had commission events uploaded
- There was no more than one transformation
- All business transactions are referenced by aggregation events
Use case 2 uses a different API that does not have such limitations.
Trace API Use Case 2: Find the source information for your finished products
In this scenario, a recall is announced and you think some of your goods might be impacted. Here, you can provide your product information to the /ingredient-sources endpoint to download a spreadsheet that will list the ingredient details for each relevant product. From this spreadsheet, you can search and sort to find if you are in possession of products that originated from a location impacted by the recall, determine which EPCs are impacted, and which stores or distribution centers those EPCs were last recorded in.
Step 1: Find EPCs in your facilities
The first step here is to find EPCs matching the products you are interested in using the /lots_and_serials API. An EPC identifies a specific unit of that product with a lot or serial number (e.g. {EPC} Lot 1234 of {product} Honeycrisp Apples). In general, you are entitled to EPCs when they are shipped to you, so if an EPC is returned you can expect that you are in possession of it or that its en route to your facility.
Step 2: Trace to find history
The heavy lifting is then done with the /epcs/{epc_id}/trace API, which is called for each of the EPCs to trace them upstream to their origins. The output is a tree, in JSON format with each node being a single EPC. The tree will describe what events the EPC has gone through (was it just picked from the farm? (commission event) or was it shipped from the distribution to the store? (observation or aggregation event)). If the product traced has ingredients, the tree will also show the ingredients as input EPC nodes, along with any events associated with those EPCs. And if the product traced was used as an ingredient for other products, those will be shown as output nodes.
This API is extremely powerful and there are other parameters beyond what is used in this example as well. The depth defaults to 5 and describes how far to trace, or rather limits the depth of the EPC tree returned. You can also specify the direction of the trace: The upstream parameter is a boolean and will set your results to include the ingredients and input EPCs for the product you're searching for, while the downstream parameter sets your results to include output EPCs as well. If both these parameters are set to be true, both input and output EPCs for the good you searched for will be returned.
Step 3: Supplement & filter
Now that you have all the related EPCs, their EPC ids, and their event asset ids, you can make calls to /events, /products, and /transactions, for example, to collect finer details. With this data, you can make any additional manipulations that you require.
Now that you have all the necessary information, filter for the EPCs/events/transactions that matter for your use case. In this example, we would filter out any transformation events or events where the source location and destination location is the same – as these events do not provide useful information on shipment or source locations of goods involved in producing the final product.
Step 4: Format
Finally, what should the output look like? Should it be in JSON, CSV, or another format? Take your filtered results and go ahead and format it in the best way to present your data. For further programmatic manipulation, this example offers JSON output, but the default is CSV so that you can manually manipulate in Excel.