doc Message Types
To enable supply chain tracking and tracing, the IBM Food Trust™ solution leverages several message (data) types. Each data type is an XML message in a unique format, derived from GS1 standards.
With the exception of Facility Certificates, each message uploaded to IBM Food Trust must be in the supported XML format for its data type. The following data types are implemented by the IBM Food Trust solution:
These data types, and their associated message types, are explained in the following sections.
Master Data describes organization facility locations (GLNs or IBM Food Trust Facility IDs) and trade items (GTINs or IBM Food Trust Product IDs), and are expected to be largely static. Three types of Master Data are supported by IBM Food Trust (Figure 1):
Figure 1. Master Data Types
Master Data Types, their corresponding Message Types, and Samples are shown in Table 1:
Table 1. Master Data Message Types
| Master Data Type | Message Type | Sample XML Message |
|---|---|---|
| Master Facility Data | Basic Facility Registration | MasterData_Facility_Annotated |
| Master Item Data | Item Data Notification | MasterData_Item_Annotated |
| Instance/Lot Master Data (ILMD) | Object Add or Transformation | EPCIS_Commission / EPCIS_Transformation |
The Master Facility Data XML message type is derived from the GS1 Basic Party Registration XML message type, and describes facility information in IBM Food Trust.
Master Facility Data is generally uploaded by a facility representative, and consists of the following data points:
- Facility GLN (Global Location Number) or IBM Food Trust Facility ID
- Facility Address (physical)
- Facility Type (e.g. farm, warehouse)
The Master Item Data XML message type is derived from the GS1 Item Data Notification XML message type, and is used for registering trade items (products) in IBM Food Trust.
Master Item Data is class-level master data corresponding to a GTIN (Global Trade Item Number) or IBM Food Trust Product ID, is generally uploaded by the creator of the trade item in IBM Food Trust, and consists of the following data points:
- Text description
- GTIN (or IBM Food Trust Product ID)
- SKU (Stock Keeping Unit)
Instance/Lot Master Data (ILMD) has no message type specific to IBM Food Trust, unlike Master Facility Data and Master Item Data. For ILMD, IBM Food Trust uses EPCIS Commission and EPCIS Transformation events (i.e. events that lead to the creation of an object), with optional ILMD fields.
Instance/Lot Master Data (ILMD) is Master Data corresponding to a specific item lot or item instance, and includes the following data:
- Item expiration (best by) date
- Item weight
- Item harvest date
When a specific item lot is defined on the network, an LGTIN (GTIN with a preceding Lot/Batch number) is used in ILMD; when a specific item instance is defined, an SGTIN (Serialized GTIN) is used.
Three types of business transactions are recognized by IBM Food Trust (Figure 2):
Figure 2. Business Transaction Types
Business Transaction Data Types, their corresponding Message Types, and Samples are shown in Table 2:
Table 2. Business Transaction Message Types
| Business Transaction Data Type | Message Type | Sample XML Message |
|---|---|---|
| Purchase Order | Order | PurchaseOrder_Annotated |
| Despatch Advice (Advanced Shipping Notice; ASN) | Despatch Advice | DespatchAdvice_Annotated |
| Receiving Advice | Receiving Advice | ReceiveAdvice_Annotated |
The Purchase Order (PO) XML message type corresponds to the GS1 Order XML message type, and describes a specific trade item transaction in IBM Food Trust.
Purchase Order Data is generally uploaded by the buyer, and includes the following data points:
- Buyer GLN (or IBM Food Trust Facility ID)
- Receiving Facility GLN (or IBM Food Trust Facility ID)
- Trade Item GTINs (or IBM Food Trust Product IDs) and Quantities
The Despatch Advice (DA) XML message type corresponds to the GS1 Despatch Advice XML message type (aka Advance Shipping Notice or ASN), and describes the trade items being sent (one Purchase Order per line).
Despatch Advice Data is generally uploaded by the shipper, and includes the following data points:
- Shipper GLN
- Receiver GLN
- Shipping Facility GLN
- Receiving Facility GLN
- Trade Item GTINs and Quantities
- Purchase Order Identifiers
Note: For GLNs and GTINs, IBM Food Trust-generated IDs are also supported.
The Receiving Advice (RA) XML message type corresponds to the GS1 Receiving Advice XML message type, and describes the trade items received and their condition.
Receiving Advice Data is generally uploaded by the receiver, and includes the following data points:
- Shipper GLN
- Receiver GLN
- Shipping Facility GLN
- Receiving Facility GLN
- Trade Item GTINs and Quantities
- Condition of Received Trade Items
- Purchase Order Identifiers
- Despatch Advice Identifiers
Note: For GLNs and GTINs, IBM Food Trust-generated IDs are also supported.
Electronic Product Code Information Service (EPCIS) Events correspond to the GS1 EPCIS XML message type, and describe trade item observations, transformations, and creation and removal, for both individual and aggregated objects.
The GS1 EPCIS standard is used to codify the event data that members upload to the network. An EPCIS event specifies the What, Where, When and Why of an event, for one or more trade items.
Six EPCIS event types are recognized by IBM Food Trust (Figure 3):
Figure 3. EPCIS Event Types
Event Data Names, their corresponding EPCIS Event Types, Event Actions, and Samples are shown in Table 3:
Table 3. EPCIS Event Message Types
| Event Data Name | EPCIS Event Type | Event Action | Sample XML Message |
|---|---|---|---|
| Commission | Object | ADD | EPCIS_Commission |
| Decommission | Object | DELETE | EPCIS_Decommission |
| Observation | Object | OBSERVE | EPCIS_Observation |
| Transformation | Transformation | Transformation | EPCIS_Transformation |
| Aggregation | Aggregation | ADD | EPCIS_Aggregation |
| Disaggregation | Aggregation | DELETE | EPCIS_Disaggregation |
Commission Event Data describe the creation of objects (commissioning of a new object EPC), such as a new trade item lot from a harvest event, or a new pallet Serial Shipping Container Code (SSCC).
Each commission event involves one of the following data points:
Commission events can also contain Instance/Lot Master Data (ILMD).
Decommission Event Data describe the deletion of trade items (removal of an object EPC).
Each decommission event involves one of the following data points:
- SSCC
- List of class-level trade items (LGTINs) or instance-level trade items (SGTINs) (or both).
Observation Event Data describe trade item observations, such as a product scan at a retailer.
In general, observation events involve one of the following data points, observed at a specific location at a specific time in the course of a business process:
- SSCC
- List of class-level trade items (LGTINs) or instance-level trade items (SGTINs) (or both).
Transformation Event Data describe an irreversible combination of input objects into output objects, such as the creation of chicken breasts from live chicken.
Each transformation event involves both of the following data points:
- List of class-level input items (LGTINs) or instance-level input items (SGTINs) (or both)
- List of class-level output items (LGTINs) or instance-level output items (SGTINs) (or both).
Transformation events can also contain Instance/Lot Master Data (ILMD).
Aggregation Event Data describe a reversible aggregation of input objects into output objects, such as boxes of produce into pallets of produce. Outbound shipping from a supplier to a retailer distribution center is mandated to be an aggregation event.
Each aggregation event involves both of the following data points:
- Single parent item (represented, for example, by an SSCC)
- List of class-level child items (LGTINs) or instance-level child items (SGTINs) (or both).
Disaggregation Event Data describe a disaggregation of objects from a reversible aggregation, such as pallets of produce into boxes of produce.
Each disaggregation event involves both of the following data points:
- Single parent item (represented by an SSCC, e.g.)
- List of class-level child items (LGTINs) or instance-level child items (SGTINs) (or both).
Certificate data describe facility certificates, such as certificate binaries with descriptive metadata for the auditing body, audit dates and scores, expiration dates and location GLNs, e.g.
The following example shows facility certificate metadata (JSON):
{
"certificateID": "1234",
"timestamp": "01-02-03T04:05:06.789Z",
"expiryDate": "d",
"issueDate": "f",
"locationGLNList": [
"1234567890123"
],
"fileType": "pdf",
"auditedBy": "auditor",
"auditReferenceNumber": "1234",
"auditStartDate": "01-02-3004",
"certificationStatus": "valid",
"scheme": "SQF",
"schemeOwner": "GFSI",
"scope": "Something"
}Submit generic string-encoded payloads can be submitted to IBM Food Trust.
An annotated sample of the XML payload can be found here.
Submit encoded public signing keys to IBM Food Trust with an XML format. Detailed information can be found on the Cryptographic Data page.
An annotated sample of the XML payload can be found here.