Guide: Integrating with IBM Food Trust ™ Blockchain

Karthikeyan .
IBM Food Trust Integration Guide

Walmart has mandated its leafy green suppliers to conform to one-step back traceability on their blockchain network by Jan 31, 2019. And each supplier should then make their suppliers conform to the same by September 20th, 2019.

This means transmitting key events (harvesting, packaging, transformation etc) happening across your supply chain to IBM Food Trust ™ Blockchain — the platform chosen by Walmart. This empowers Walmart to find the source of the food within 2.2 seconds according to Frank Yiannas, it’s Vice President of Food Safety. At this point, we are not sure how the statistics were arrived at. What’s known is, it used to take days in order to track the source of a product and not an easy process.

If you are in charge of your company’s IT, this is a guide on integrating with IBM Food Trust ™.

High-level problem statement

If your company is new to blockchain or doesn’t have blockchain experts or developers, it’s perfectly fine. Because IBM has simplified the integration by exposing APIs to their blockchain platform. You need to transmit XML files formatted per the standards set by GS1, to the IBM Food Trust ™ API. That’s the high-level problem statement for the integration.

Apples to Apple Puree Example

To demonstrate how the integration with IBM Food Trust ™ is done, we will take “processing of apple puree” as the example (the same example demonstrated in some of IBM’s documents)

IBM Food Trust Example Process

Transmitting Events

So how exactly do you transmit these events that happen across your farm, your factory and the rest of your supply chain to IBM Food Trust ™? IBM Food Trust ™ has listed a standard set of events (totaling six) to represent these real world events happening across your supply chain.

  • Commission – An event signifying the creation of an object. When you pick your apples from the farm — that’s commissioning.
  • Decommission – An event signifying deletion of an object.
  • Transformation – An event signifying an irreversible transformation of an object. An example would be making the puree out of your apples. You can’t reverse it. You can’t make apples out of apple puree. That’s a transformation.
  • Aggregation – An event signifying grouping of objects. For example, aggregating 10 apples as a case of apples and loading them.
  • Disaggregation – Ungrouping objects to a smaller group. For example, disaggregating a pallet of apple to boxes of apples, boxes of apples to individual apples.
  • Observation – An event signifying an observation, such as scanning at the store.

Let’s relook at our process and assign each event in our process a corresponding an IBM Food Trust ™ event

IBM Food Trust EPICS Events


Data should be transmitted as an XML file (GS1 Standards)

These events are sent to IBM Food Trust ™ API as XML messages. IBM has decided to use GS1 EPCIS standard for formatting these XML messages. GS1 EPCIS events are meant to communicate the What, Where, When and Why of an event. We have provided links to the official GS1 documentation of the EPCIS standard in the references section.

This standard was created by GS1 with the intention of connecting disparate applications to create and share visibility event data within and across companies. IBM Food Trust ™ is an example of how such standards can be very useful. In this case, IBM didn’t have to come up with their standard from the ground up, which by the way would have been a humungous effort.

Sharing Your Master Data

You should upload your master data to the IBM Food Trust blockchain during the initial setup —  Well before you begin to transmit the EPCIS events. Your master data includes the following two things,

  • Locations – Your farms, warehouses, manufacturing plants or any other location where these events occur.
  • Item and lot data – The details of the products you are trading (SKU, Expiry date, Weight, etc).

Once again, IBM relies on standards set by GS1 for constructing the XML messages (GS1 Basic Party Registration for Locations and GS1 Item Data Notification XML for Item and Lot data).

Business transactions

As of now, with IBM Food Trust ™ you can register the following business transactions,

  • Purchase Order
  • Shipment Notification
  • Receipt Confirmation

The format in which you should send the XML is dictated by GS1 Standard (GS1 Order XML, GS1 Despatch Advice XML, GS1 Receiving Advice XML)

Setting visibility level for your data

For each message you send to IBM Food Trust ™, you can set an access level dictating whether it’s visible to other companies in the food chain. IBM supports the following access levels,

  • Open – Data is visible to all parties in the IBM Food Trust ™. You can probably use this to publish your SKUs
  • Restricted – Data is visible to you and the immediate trading partner. As an example the company that is sending you the PO or the company that is receiving your ASN.
  • Linked – Data is visible to all the organizations that are part of your supply chain.
  • Private – Data is visible only to your organization.

Familiar challenges (Mapping, Integration with ERP)

To summarize, you are expected to share your master data (locations, inventory), key events, business transactions (PO, ASN, RC) to Walmart. This might sound familiar. We all have been doing something similar for a long time now in the form of EDIs. Instead of sending EDI files to FTP or AS2 connection, you will be transmitting XML files to a REST API.

You are still faced with the familiar challenges of mapping data from your ERP or WMS or wherever your data resides and translate them to the XML files.

The transmission process can be automated by registering your transmission service/software as an application with IBM Food Trust ™ dashboard which will generate a Service ID and API key. The Service ID and the API key is used to generate an authentication token by calling the authentication API. You can then use the generated token to authenticate your service for subsequent API requests.


Successfully integrating with IBM Food Trust ™ and complying with Walmart means that you will need to plan the following steps,

  • Sign up with IBM Food Trust ™ and choose a plan that fits you
  • Play around with the API documentation and get yourself familiar with it
  • Understand GS1 XML standards involved in the compliance
  • Map out events happening in your supply chain to EPCIS events supported by IBM
  • Map out data from your ERP or WMS to GS1 XML documents using your custom code or a tool of your choice.
  • Manually submit your first XML message to API for testing.
  • If things look okay, automate and move ahead into production.

More Reads

  • Letter from Walmart to its suppliers [Link]
  • GS1 EPCIS Events standard [Link]
  • GS1 documentation for business transactions & master data [Link]
  • IBM Food Trust ™ developer documentation on GitHub [Link]

IBM Food Trust Integration Guide

Karthikeyan is the CEO of ByteAlly Software. An entrepreneur who can design and code, he has a passion for building products that solve a hard problem yet simple to use. He has led and delivered software products ranging from consumer applications to enterprise products and custom I.T solutions for SMEs and large enterprises. Karthikeyan is also a member of the Forbes Tech Council.