EPCIS 2.0 Repository

📘

Enterprise feature in beta

If you are interested in using this feature, please contact us.
This a beta capability - we may make significant changes before the final version.

EPCIS is a GS1 standard for the integration of supply chain information systems. EPCIS is especially valuable to facilitate the seamless exchange of information in supply chains that span multiple organisations. EPCIS 2.0 is the work in progress update of the GS1 EPCIS standard. It was driven by the need to bring EPCIS to the Web. EPCIS 2.0 currently being developed by the EPCIS and CBV 2.0 MSWG which EVRYTHNG is part of. The standard has not been ratified yet, hence consider everything you see here tentative.

In this tutorial, you will learn how to use your EVRYTHNG account as an Electronic Product Code Information Services (EPCIS) version 2.0 repository. We built an EPCIS proxy for the EVRYTHNG platform, which is a (partial) implementation of the EPCIS 2.0 bindings.

By adding support for EPCIS, your EVRYTHNG account becomes the platform for a frictionless integration of your business processes in complex supply chain information systems as well as consumer-facing apps. A related topic is the Digital Link, which turns the humble QR code on product packages and labels into the bridge between business facing IT systems and consumer facing consumer apps.


EPCIS Events and EPCIS Repository

EPCIS systems communicate by sending events. EPCIS supports four event types, namely ObjectEvent, AggregationEvent, TransformationEvent and TransactionEvent. EPCIS events are snapshots of supply chain transactions, describing the following dimensions:

  • What: One or more items (pallet, individual products, etc...) that are concerned
  • When: At what time did this event occur
  • Where: The place where items are being shipped, received and where items are being expected
  • Why: The business context that describes the process-related information

An EPCIS repository is an append-only database, because events are snapshots of the state of a supply chain. This is important to ensure transparency, accountability and traceability. If for example a supplier ships 10 pallets to a manufacturer and that shipment only contains 5 pallets on arrival, the manufacturer will not ask the supplier to change the event. Instead, the manufacturer will create a new EPCIS event that captures the discrepancy.

EPCIS 1.2, the latest stable release, uses XML to represent messages and XSD for the schema definition. By default, EPCIS 2.0 encodes EPCIS events as JSON objects and uses JSON-LD or JSON-Schema to formalise the EPCIS data definition.

The following example labels each dimension in this EPCIS ObserveEvent.

{
  // Event Type
  "isA": "ObjectEvent",

  // When
  "eventTime": "2005-04-03T20:33:31.116-06:00",
  "eventTimeZoneOffset": "-06:00",

  // What
  "epcList": [
    "urn:epc:id:sgtin:0614141.107346.2017",
    "urn:epc:id:sgtin:0614141.107346.2018"
  ],

  // Where
  "readPoint": "urn:epc:id:sgln:0614141.07346.1234",

  // Why
  "action": "OBSERVE",
  "bizStep": "urn:epcglobal:cbv:bizstep:shipping",
  "disposition": "urn:epcglobal:cbv:disp:in_transit",
  "bizTransactionList": [
    {
      "type": "urn:epcglobal:cbv:btt:po",
      "bizTransaction": "http://transaction.acme.com/po/12345678"
    }
  ]
}

Using the EVRYTHNG platform as an EPCIS 2.0 repository

We created an EPCIS 2.0 proxy for the EVRYTHNG platform that maps EPCIS events and resources to EVERYTHING's data model. This means you can keep using your EVRYTHNG account to build consumer-facing applications and at the same time seamlessly connect your EVRYTHNG account as EPCIS repository to a supply chain environment.

This proxy is a partial implementation of the EPCIS 2.0 bindings as a proxy for the EVRYTHNG platform. We designed it to allow our customers to preview the features of the upcoming EPCIS 2.0 standard. Currently supported are the /capture and /events endpoints. /capture is to store events, /events is to access events individually or entire event collections. The /queries endpoint will allow clients to run complex queries and to subscribe to queries to receive real-time updates when new events emerge that meet the query constraints. If you have an EVRYTHNG account, you can view events as actions.

You can either use the default account or create your own account and project. If you don't specify an API key, you'll automatically interact with the default account. If you want to setup your own environment, you'll need an EVRYTHNG account, create a project and within that project, create an Application to obtain a Trusted Application API Key. and create four action types, one for each EPCIS event type: _ObjectEvent, _ AggregationEvent, _TransformationEvent , and _TransactionEvent . When you use the service include the Trusted Application API key in the header: Authorization: O5yO...Ma3o. Please note that if you omit the header, you will not get an error but simply be using the default account. Also note that browsable links only work with the default account, because the EPCIS 2.0 standard does not support encoding an API key as URL query parameter.


Capturing EPCIS Events

To create your first ObjectEvent, take for instance the first example from https://mimasu.nl/epcis/xmljson and try:

curl -H "Content-Type: application/json" \
    -H "Authorization: O5yO...Ma3o" \
  -X POST https://epcis.evrythng.io/v2_0/capture \
  -d '{
  "@context": "https://id.gs1.org/epcis-context.jsonld",
  "isA": "EPCISDocument",
  "creationDate": "2005-07-11T11:30:47+00:00",
  "schemaVersion": 1.2,
  "format": "application/ld+json",
  "epcisBody": {
    "eventList": [
      {
        "isA": "ObjectEvent",
        "eventTime": "2005-04-03T20:33:31.116-06:00",
        "eventTimeZoneOffset": "-06:00",
        "epcList": [
          "urn:epc:id:sgtin:0614141.107346.2020",
          "urn:epc:id:sgtin:0614141.107346.2021"
        ],
        "action": "ADD",
        "eventId": "_:event1",
        "bizStep": "urn:epcglobal:cbv:bizstep:shipping",
        "disposition": "urn:epcglobal:cbv:disp:in_transit",
        "readPoint": "urn:epc:id:sgln:0614141.07346.1234",
        "bizTransactionList": [
          {
            "type": "urn:epcglobal:cbv:btt:po",
            "bizTransaction": "http://transaction.acme.com/po/12345678"
          }
        ]
      }
    ]
  }
}'
HTTP/2 200 OK
Content-Type: application/json

[
  {
    "action": "ADD",
    "bizStep": "urn:epcglobal:cbv:bizstep:shipping",
    "bizTransactionList": [
      {
        "bizTransaction": "http://transaction.acme.com/po/12345678",
        "type": "urn:epcglobal:cbv:btt:po"
      }
    ],
    "disposition": "urn:epcglobal:cbv:disp:in_transit",
    "epcList": [
      "urn:epc:id:sgtin:0614141.107346.2020",
      "urn:epc:id:sgtin:0614141.107346.2021"
    ],
    "eventId": "_:event1",
    "eventTime": "2005-04-03T20:33:31.116-06:00",
    "eventTimeZoneOffset": "-06:00",
    "isA": "ObjectEvent",
    "readPoint": "urn:epc:id:sgln:0614141.07346.1234",
    "recordTime": "2019-07-26T14:55:54.644Z"
  }
]

Sensors data

The EPCIS 2.0 standard will also bring support to add sensor data to events (e.g., temperature).
Our EPCIS 2.0 proxy supports the current draft specification for sensory and location data.

This is done by adding a sensorElementList field with a sensorReport in a OBSERVE event.
For example:

curl -X POST "https://epcis.evrythng.io/v2_0/capture" -H "Content-Type: application/json" -d "@-" << EOF
{
    "@context": "https://id.gs1.org/epcis-context.jsonld",
    "isA": "EPCISDocument",
    "creationDate": "2019-13-06T11:30:47+00:00",
    "schemaVersion": 1.2,
    "format": "application/ld+json",
    "epcisBody": {
      "eventList": [
        {
           "eventID":"eventID",
           "eventTimeZoneOffset":"-06:00",
           "eventTime":"2005-04-03T20:33:31.116-06:00",
           "isA":"ObjectEvent",
           "epcList":[
              "urn:epc:id:sgtin:0614141.107346.2017",
              "urn:epc:id:sgtin:0614141.107346.2018"
           ],
           "action":"OBSERVE",
           "bizStep":"urn:epcglobal:cbv:bizstep:shipping",
           "disposition":"urn:epcglobal:cbv:disp:in_transit",
           "readPoint":"urn:epc:id:sgln:0614141.07346.1234",
           "sensorElementList":[
              {
                 "sensorReport":[
                    {
                       "type":"gs1:Temperature",
                       "value":17.0
                    },
                    {
                       "type":"gs1:Latitude",
                       "stringValue":"53.553747"
                    },
                    {
                       "type":"gs1:Longitude",
                       "stringValue":"8.562372"
                    }
                 ]
              }
           ],
           "bizTransactionList":[
              {
                 "type":"urn:epcglobal:cbv:btt:po",
                 "bizTransaction":"http://transaction.acme.com/po/12345678"
              }
           ]
        }
      ]
    }
  }
HTTP/2 200 OK
Content-Type: application/json

[
    {
        "action": "OBSERVE",
        "bizStep": "urn:epcglobal:cbv:bizstep:shipping",
        "bizTransactionList": [
            {
                "bizTransaction": "http://transaction.acme.com/po/12345678",
                "type": "urn:epcglobal:cbv:btt:po"
            }
        ],
        "disposition": "urn:epcglobal:cbv:disp:in_transit",
        "epcList": [
            "urn:epc:id:sgtin:0614141.107346.2017",
            "urn:epc:id:sgtin:0614141.107346.2018"
        ],
        "eventID": "eventID",
        "eventTime": "2005-04-03T20:33:31.116-06:00",
        "eventTimeZoneOffset": "-06:00",
        "isA": "ObjectEvent",
        "readPoint": "urn:epc:id:sgln:0614141.07346.1234",
        "sensorElementList": [
            {
                "sensorReport": [
                    {
                        "type": "gs1:Temperature",
                        "value": 17
                    },
                    {
                        "stringValue": "53.553747",
                        "type": "gs1:Latitude"
                    },
                    {
                        "stringValue": "8.562372",
                        "type": "gs1:Longitude"
                    }
                ]
            }
        ],
        "recordTime": "2020-09-29T09:32:07.350Z"
    }
]

Return events of any type

Try this link to get a list of all events from your browser. Or with curl:

curl -X GET https://epcis.evrythng.io/v2_0/events/all \
    -H "Authorization: O5yO...Ma3o" \
  -H "Content-Type: application/json"
HTTP/2 200 OK
Content-Type: application/json

[
  {
    "action": "ADD",
    "bizLocation": "urn:epc:id:sgln:0614141.00888.0",
    "bizStep": "urn:epcglobal:cbv:bizstep:receiving",
    "destinationList": [
      {
        "destination": "urn:epc:id:sgln:0614141.00001.0",
        "type": "urn:epcglobal:cbv:sdt:owning_party"
      },
      {
        "destination": "urn:epc:id:sgln:0614141.00777.0",
        "type": "urn:epcglobal:cbv:sdt:location"
      }
    ],
    "disposition": "urn:epcglobal:cbv:disp:in_progress",
    "eventID": "oe3",
    "eventTime": "2013-06-08T14:58:56.591+00:00",
    "eventTimeZoneOffset": "+02:00",
    "example:myField": {
      "#text": "Example of a vendor/user extension",
      "@xmlns:example": "http://ns.example.com/epcis"
    },
    "isA": "ObjectEvent",
    "quantityList": [
      {
        "epcClass": "urn:epc:class:lgtin:4012345.012345.998877",
        "quantity": 200,
        "uom": "KGM"
      }
    ],
    "readPoint": "urn:epc:id:sgln:0614141.00777.0",
    "sourceList": [
      {
        "source": "urn:epc:id:sgln:4012345.00001.0",
        "type": "urn:epcglobal:cbv:sdt:possessing_party"
      },
      {
        "source": "urn:epc:id:sgln:4012345.00225.0",
        "type": "urn:epcglobal:cbv:sdt:location"
      }
    ],
    "recordTime": "2019-05-21T09:42:00.862Z"
  },
  
  // more events...
]

Return all object events

Try this link to get a list of ObjectEvents from your browser. Or with curl:

curl -X GET https://epcis.evrythng.io/v2_0/events/ObjectEvent \
    -H "Authorization: O5yO...Ma3o" \
  -H "Content-Type: application/json"
HTTP/2 200 OK
Content-Type:application/json

[
  {
    "action": "OBSERVE",
    "bizLocation": "urn:epc:id:sgln:0614141.00888.0",
    "bizStep": "urn:epcglobal:cbv:bizstep:receiving",
    "destinationList": [
      {
        "destination": "urn:epc:id:sgln:0614141.00001.0",
        "type": "urn:epcglobal:cbv:sdt:owning_party"
      },
      {
        "destination": "urn:epc:id:sgln:0614141.00777.0",
        "type": "urn:epcglobal:cbv:sdt:location"
      }
    ],
    "disposition": "urn:epcglobal:cbv:disp:in_progress",
    "eventID": "oe3",
    "eventTime": "2013-06-08T14:58:56.591+00:00",
    "eventTimeZoneOffset": "+02:00",
    "example:myField": {
      "#text": "Example of a vendor/user extension",
      "@xmlns:example": "http://ns.example.com/epcis"
    },
    "isA": "ObjectEvent",
    "quantityList": [
      {
        "epcClass": "urn:epc:class:lgtin:4012345.012345.998877",
        "quantity": 200,
        "uom": "KGM"
      }
    ],
    "readPoint": "urn:epc:id:sgln:0614141.00777.0",
    "sourceList": [
      {
        "source": "urn:epc:id:sgln:4012345.00001.0",
        "type": "urn:epcglobal:cbv:sdt:possessing_party"
      },
      {
        "source": "urn:epc:id:sgln:4012345.00225.0",
        "type": "urn:epcglobal:cbv:sdt:location"
      }
    ],
    "recordTime": "2019-05-21T09:42:00.862Z"
  },
  
  // Other events...
]

 Show me the ObjectEvent event1

Access a single event using its identifier.

curl -X GET https://epcis.evrythng.io/v2_0/events/ObjectEvent/:event1 \
    -H "Authorization: O5yO...Ma3o" \
  -H "Content-Type: application/json"

Use filters to narrow down returned events

Use a filter to list events that are either Aggregation or ObjectEvents with a business step urn:epcglobal:cbv:bizstep:shipping. With curl:

curl -X GET 'https://epcis.evrythng.io/v2_0/events/all?EQ_bizStep=urn:epcglobal:cbv:bizstep:shipping' \
    -H "Authorization: O5yO...Ma3o" \
  -H "Content-Type: application/json"
HTTP/2 200 OK
Content-Type:application/json

[
  {
    "action": "ADD",
    "bizStep": "urn:epcglobal:cbv:bizstep:shipping",
    "bizTransactionList": [
      {
        "bizTransaction": "http://transaction.acme.com/po/12345678",
        "type": "urn:epcglobal:cbv:btt:po"
      }
    ],
    "disposition": "urn:epcglobal:cbv:disp:in_transit",
    "epcList": [
      "urn:epc:id:sgtin:0614141.107346.2020",
      "urn:epc:id:sgtin:0614141.107346.2021"
    ],
    "eventId": "_:event1",
    "eventTime": "2005-04-03T20:33:31.116-06:00",
    "eventTimeZoneOffset": "-06:00",
    "isA": "ObjectEvent",
    "readPoint": "urn:epc:id:sgln:0614141.07346.1234",
    "recordTime": "2019-07-26T14:55:54.644Z"
  },
  {
    "action": "ADD",
    "bizStep": "urn:epcglobal:cbv:bizstep:shipping",
    "bizTransactionList": [
      {
        "bizTransaction": "http://transaction.acme.com/po/12345678",
        "type": "urn:epcglobal:cbv:btt:po"
      }
    ],
    "disposition": "urn:epcglobal:cbv:disp:in_transit",
    "epcList": [
      "urn:epc:id:sgtin:0614141.107346.2017",
      "urn:epc:id:sgtin:0614141.107346.2018"
    ],
    "eventID": "oe1",
    "eventTime": "2005-04-03T20:33:31.116-06:00",
    "eventTimeZoneOffset": "-06:00",
    "isA": "ObjectEvent",
    "readPoint": "urn:epc:id:sgln:0614141.07346.1234",
    "recordTime": "2019-07-26T14:53:14.185Z"
  }
]

To Summarise

In this tutorial, we introduced the upcoming EPCIS 2.0 standard for the exchange of messages in a supply chain environment. You’ve learned how EPCIS events can be translated into EVRYTHNG events back and forth. Allowing your business to create product experiences that are can talk to all stakeholders in a supply chain: suppliers, manufacturers, logistics companies - and consumers! And all this using the tools your developers already know.

Send us your comments, suggestions and questions. We’d love to hear from you!


Related Projects

REST API:

Payload specifications:

Updated about a month ago

EPCIS 2.0 Repository


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.