Insights data
The IBM Food Trust™ Insights API enables participating Organizations to upload and share supply chain and cold chain metrics for food industry products. To enable this data sharing, authorized users must upload product, location and events data related to food product inventory, such as temperature readings, expiration dates and location entry and exit events.
With the required Insights data uploaded for a specific product instance and its locations (facilities), the Insights API returns metrics to authorized users, including the following location-specific data points:
- Inventory - Product quantities, including at-risk inventory
- Dwell time - Time a product has been held at a facility
- Time since production - Age of a product
- Time until expiration - Remaining shelf life of a product
- Temperature exceptions - Instances over or under a user-defined temperature and time threshold
Insights metrics are calculated by product instance ID, as follows:
- SGTIN (Serial GTIN) or IBM Food Trust Item Number - An individual unit or package of a product instance.
- LGTIN (Lot GTIN) or IBM Food Trust Lot Number - A lot containing one or more individual units or packages of a product instance.
- SSCC (Serialized Shipping Container Code) or IBM Food Trust Pallet Number - A container or pallet containing one or more lots and/or individual units or packages of a product instance.
Insights metrics are calculated by individual location (Facility ID) or sublocation (Facility ID + non-zero extension) and can be aggregated by facility type (party role code). The return of consumable metrics is dependent upon participating Organizations uploading an entry event and an exit event each time a product instance enters and exits a location, as defined in detail below.
Location entry events and exit events are not limited to receiving and shipping events only. They also include entry and exit to and from the supply chain, such as through the creation or consumption of a product instance.
In order for the Insights API to return consumable food freshness and supply chain metrics, specific data points must be uploaded by participating Organizations. At an overview level, these data upload requirements are as follows:
- Each location (Facility ID) or sublocation (Facility ID + non-zero extension) must be defined and have an entry event or exit event uploaded each time a product instance (SGTIN, LGTIN or SSCC) enters or exits the location or sublocation.
- The specific supply chain and cold chain event types that constitute an entry event and an exit event for each location or sublocation, and the required XML fields, are described in detail below.
Attention: The correct Data Entitlement must be in place in order to make Insights metrics available to your selected supply chain partners.
Whenever a supply chain or cold chain item (product instance) enters a location or sublocation, ONE of the following event types must be uploaded (in XML) to constitute the required Insights entry event. Each of the following four IBM Food Trust event types qualify as an entry event:
Commission Event - The product instance (SGTIN, LGTIN, or SSCC) is added to the supply chain (created or produced) at this location. Required XML entries - Both the <source> and <destination> must be left blank OR they must both be this Facility ID (location) or Facility ID + non-zero extension (sublocation).
OR:
Transformation Event - The product instance (SGTIN, LGTIN, or SSCC) is both manufactured and added to the supply chain at this location. Required XML entries - Both the <source> and <destination> must be left blank, OR they must both be this Facility ID (location) or Facility ID + non-zero extension (sublocation).
OR:
Disaggregation Event or Observation Event - The product instance (SGTIN, LGTIN, or SSCC) is received and unpacked (or only received) at this location. Required XML entries - The <source> must be the originating location (Facility ID) or sublocation (Facility ID + non-zero extension) AND the <destination> must be this Facility ID (location) or Facility ID + non-zero extension (sublocation).
In addition, each uploaded entry event must include an accurate time of scan (UTC timestamp) <eventTime> value. Dates must follow ISO 8601 format yyyy-mm-dd and dates with times must follow ISO 8601 format in UTC time.
Whenever a supply chain or cold chain item (product instance) exits a location or sublocation, ONE of the following event types must be uploaded (in XML) to constitute the required Insights exit event. Each of the following four IBM Food Trust event types qualify as an exit event:
Decommission Event - The product instance (SGTIN, LGTIN, or SSCC) is removed from the supply chain at this facility (by sale, loss or destruction). Required XML entries - Both <source> and <destination> must be left blank OR they must both be this Facility ID (location) or Facility ID + non-zero extension (sublocation).
OR:
Transformation Event - The product instance (SGTIN, LGTIN, or SSCC) is removed from the supply chain at this facility, by consumption as input to a new product instance. Both the <source> and <destination> must be left blank OR they must both be this Facility ID (location) or Facility ID + non-zero extension (sublocation).
OR:
Aggregation Event or Observation Event - The product instance (SGTIN, LGTIN, or SSCC) is packed and shipped, or only shipped, at this facility. Required XML entries - The <source> must be this location (Facility ID) or sublocation (Facility ID + non-zero extension) AND the <destination> must be the destination Facility ID (location) or Facility ID + non-zero extension (sublocation).
In addition, each uploaded exit event must include an accurate time of scan (UTC timestamp) <eventTime> value. Dates must follow ISO 8601 format yyyy-mm-dd and dates with times must follow ISO 8601 format in UTC time.
As described previously, the diagram below (Figure 1) shows the IBM Food Trust event types that meet the Insights data requirement for entry events and exit events:
Figure 1. Entry Events and Exit Events
The following Insights rules apply to uploading and querying supply chain and cold chain product data:
- For Facility IDs, both GS1 location syntax and IBM Food Trust location syntax are supported, but are bifurcated.
- Whenever a product instance (SGTIN, LGTIN, or SSCC) enters a location (Facility ID) or sublocation (Facility ID + non-zero extension), it must have a corresponding entry event uploaded to IBM Food Trust.
- Whenever a product instance (SGTIN, LGTIN, or SSCC) exits a Location (Facility ID) or Sublocation (Facility ID + non-zero extension), it must have a corresponding exit event uploaded to IBM Food Trust.
- If entry events and exit events are provided at the location level (Facility ID with no extension, or a zero (.0) extension), then metrics are computed at the location level.
- If entry events and exit events are provided at the sublocation level (Facility ID with non-zero extension), then metrics are computed at the sublocation level.
- For each sublocation specified, both an entry event and an exit event are required. If the sublocation data is incomplete, IBM Food Trust calculates the metrics at the location level.
- Metrics are calculated by Location or by Sublocation, not both. Locations must have a defined Facility ID, and sublocations must have a defined Facility ID + non-zero extension.
- To return Fresh Insights inventory metrics by Location (not sublocation), there must be an Entry Event and an Exit Event defined for each Location.
- To return Insights inventory metrics by sublocation (a defined area within a Location, such as a floor or loading dock), there must be an entry event and an exit event defined for each sublocation.
- For any product instance (SGTIN, LGTIN, or SSCC), metrics are returned starting with the initial creation of the product instance only (by Commission Event, Aggregation Event or Transformation Event). No metrics are returned for any earlier events or product instances (ingredients) that contributed to the finished product instance.
As shown in the following example (Figure 2), Insights calculates metrics for a single product instance only (SGTIN, LGTIN, or SSCC). Because only one product instance is analyzed at a time, Insights returns metrics for the mixed salad, but not for any of its ingredients. Metrics for the carrots or any other ingredients require separate analysis, by unique product instance ID.
Figure 2. Insights metrics are returned by a single unique SGTIN, LGTIN, or SSCC only
