Skip to content

doc Message Types

Josh Horton edited this page Feb 25, 2019 · 3 revisions

IBM Food Trust™ 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:

  1. Master Data
  2. Business Transactions
  3. EPCIS Events
  4. Certificate Data
  5. Payload Data
  6. Cryptographic Signing

These data types, and their associated message types, are explained in the following sections.


Master Data

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  

masterdata.png

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

Master Facility Data

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)

Master Item Data

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)

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.


Business Transactions

Three types of business transactions are recognized by IBM Food Trust (Figure 2):

Figure 2. Business Transaction Types

businesstransactions.png

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

Purchase Order (PO)

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

Despatch Advice (DA)

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.

Receiving Advice (RA)

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.


EPCIS Events

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

epcisevents.png

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

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

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

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

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 (Agg)

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 (DisAgg)

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

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"
}

Payload

Submit generic string-encoded payloads can be submitted to IBM Food Trust.

An annotated sample of the XML payload can be found here.

Cryptographic Signing

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.

IBM Food Trust wiki

WELCOME!
    Modules
    Membership
    Updates

ONBOARDING
    Onboarding Steps
    Data Requirements
       Data Types
       Supplier Data
       Test Data

HOW-TO
    Authenticate Human Users
    Authenticate System Users
       Java Code Sample        Typescript Code Sample        IBM Integration Bus (IIB)     Assign User Roles
    Upload Data
    Automate Data Upload
    Convert Spreadsheets
    Convert Data
    Manage Certificates

APIs
    Connector API
    Converter API
    Certificates API
    API Error Codes

REFERENCE
    GS1
    Authentication
    Identifiers
    Message Codes
    Cryptographic Signatures
    Signature Header
    Access Control
    Firewall Settings

FAQ

GET SUPPORT

DEPRECATED TOOLS
    XML Generator
    XML Validator

Clone this wiki locally
You can’t perform that action at this time.