Payload Data

Payload Data

IBM Food Trust™ provides the payload data upload method to extend support beyond the standard GS-1 data types. Use a payload to attach user-defined data (such as attributes) to events, items (product lots, serial shipping containers, pallets) or locations.

Payload Types

Payloads must specify the type of contained data, using the <payloadTypeURI> tag. IBM Food Trust defines the following payload types:

• Key-value pairs
• Sensor data
• Strings

The examples below show the <payloadTypeURI> value that must be used for each of these payload types. The <payloadContentType> can be set using a media type (formerly MIME type).

Attachment Points

A submitted payload should attach to an item (Product ID), location (Facility ID) or event (EPCIS event ID). Include one of the following data points in your payload:

1. Electronic Product Code (EPC) - Food Product Item or Lot (Product ID)
2. Global Location Number (GLN) - Supply Chain Location (Facility ID)
3. EPCIS Event ID - For a Commission, Decommission, Aggregation, Disaggregation, Transformation or Observation event.

Note: The content type examples below attach to an epc: urn:ibm:ift:product:serial:obj:1234567890123.LiveCow.lc11

Using Multiple Attachment Points

If you specify multiple attachment points, the payload will be retrieved with any of those attachment points. For example, attaching a payload to a location and an event means that a Trace API call that returns that location or event will also return the payload. The application must interpret the payload as applying only to the specified EPC or event.

Similarly, attaching a payload to an EPC and a location means that queries for the EPC or location will return the payload. The application must handle the fact that it applies only to EPCs at the location, or only for events for the EPC when the EPC was at the location.

Submit Payload Data

Submit your payload using the IBM Food Trust Connector API assets endpoint. Simply paste your payload XML into the asset Parameter Value field and click the Try it out! button.

The following examples describe the XML for each payload type:

Key-value Pairs

Key-value pairs payload data must be specified using the following format:

<payloadTypeURI>urn:ibm:ift:payload:type:json:triple</payloadTypeURI>

The following code shows a sample payload specifying key-value pairs payload data:

<ift:payload xmlns:ift="urn:ibm:ift:xsd:1">
  <payloadMessage>
    <payloadID>41b14d7a-5b04-11e9-bdaa-6c4008984c16</payloadID>
    <payloadTime>2019-03-01T08:00:00Z</payloadTime>
    <payloadContentType>application/json</payloadContentType>
    <payloadTypeURI>urn:ibm:ift:payload:type:json:triple</payloadTypeURI>
    <epcList>
      <epc>urn:ibm:ift:product:serial:obj:1234567890123.LiveCow.lc11</epc>
    </epcList>
    <payload>[{"key": "Lot Number", "value": "LiveCow.lc11", "type": "string"}, {"key": "Lairage Intake Date", "value": "2019-03-01 08:00:00", "type": "string"}, {"key": "Herd Number", "value": "Herd-lc11", "type": "string"}, {"key": "Site Code", "value": "Site0001", "type": "string"}, {"key": "Eartag", "value": "Ear-lc11", "type": "string"}]</payload>
  </payloadMessage>
</ift:payload>

Sensor Data

The sensor data payload data type must be specified using the following format:

<payloadTypeURI>urn:ibm:ift:payload:type:json:sensor:v1</payloadTypeURI>

The following code shows a sample sensor data payload:

<ift:payload xmlns:ift="urn:ibm:ift:xsd:1">
  <payloadMessage>
    <payloadID>41b14d7a-5b04-11e9-bdaa-6c4008984c16</payloadID>
    <payloadTime>2019-03-01T08:00:00Z</payloadTime>
    <payloadContentType>application/json</payloadContentType>
    <payloadTypeURI>urn:ibm:ift:payload:type:json:triple</payloadTypeURI>
    <epcList>
    <epc>urn:ibm:ift:product:serial:obj:1234567890123.LiveCow.lc11</epc>
    </epcList>
    <payload>
{
    "payload": {
        "sensorReadings": [
            {
                "sensorId": "S00001",
                "measureType": "TEMPERATURE",
                "uom": "FAH",
                "timestamp": "2018-09-12T01:00:00.000Z",
                "latitude": 40,
                "longitude": -73,
                "value": 80
            },
            {
                "sensorId": "S00002",
                "measureType": "TEMPERATURE",
                "uom": "FAH",
                "timestamp": "2018-09-12T02:00:00.000Z",
                "latitude": 45,
                "longitude": -78,
                "value": 40
            }
        ],
        "alerts": [
            {
                "alertId": "a8aee7dfb536472e8046ad76ce408539",
                "code": "aboveRange",
                "desc": "The sensor reading value is too high",
                "severity": "critical",
                "timestamp": "2018-09-12T01:00:00.000Z",
                "sourceType": "sensor",
                "sensors":[
                    "S00001"
                ]

            }
        ]
    }
}
</payload>
</payloadMessage>
</ift:payload>

Strings

The string payload data type must be specified using the following format:

<payloadTypeURI>string</payloadTypeURI>

The following code shows a sample string payload created from a PDF file, using a Base64 converter:

<ift:payload xmlns:ift="urn:ibm:ift:xsd:1">
  <payloadMessage>
    <payloadID>41b14d7a-5b04-11e9-bdaa-6c4008984c16</payloadID>
    <payloadTime>2019-03-01T08:00:00Z</payloadTime>
    <payloadContentType>application/json</payloadContentType>
    <payloadTypeURI>string</payloadTypeURI>
    <epcList>
    <epc>urn:ibm:ift:product:serial:obj:1234567890123.LiveCow.lc11</epc>
    </epcList>
<payload>
JVBERi0xLjYNJeLjz9MNCjUwIDAgb2JqDTw8L0ZpbHRlci9GbGF0ZURlY29kZS9GaXJzdCA1Ni9MZW5ndGggNjY1L04gOC9UeXBlL09ialN0bT4+c3RyZWFtDQpo3qRTa0/bMBT9K/4I0pgfcV4SqtQHBaTBKhKNaVU/mNS0kdKkSswE/3732kkIrzGYLMe+vsf3HNsnkhNGpCCcRUR6RHCPSEmEx4n0iYhhCIiMJZEhQLyYyIhwAZ/jYzobH9AzXfyGAuktfDbkkM6uIHFSZtU6LzcwXczmsyrrFqAu4K5GIzqvSgNpu12ghCv6S81uiBAOgJBcF+tmuRqNADitiqpO9irTGDQBanWVTu7NaWKUwcRpwlH9E4o0FXgGZEhTifpdelFXWaLNEiXSVN8bIFrS8+l0ohq9JnBUwK2gwPcFuVVFo2FyQThNxm2YXBD2lQmaPuz1owpa7V3eyh43mS4NiZlPp2p/pvPN1pCQR3SmXeZIcE7nhdo0xBNW8mRS3S+PgsAnR56AJ2CMwc2zYGWzc7XLi4eDcZ2r4tCuXKqdpja2YWJqbbItvazqXbt07WglY/TcqCLPxuWm0ITRxOjdDxJLdwSEoqw635uqpj9btT737VHwWhDScnVPSq/zclw2eR
</payload>
  </payloadMessage>
  </ift:payload>

Related Topics

• Payload example XML
• Data types