Quick links

Please find below the links to the OpenEPCIS tools and codes referenced on this documentation page. To enhance your understanding and gain practical experience with these tools, we recommend visiting and utilizing them:

• Hash generator web application : https://tools.openepcis.io/ui/event-hash-generator

• Hash generator API endpoint : https://tools.openepcis.io/q/swagger-ui/#/Event%20Hash%20Generator

• Hash generator core application code : https://github.com/openepcis/openepcis-event-hash-generator

• Hash generator cli application code : https://github.com/openepcis/openepcis-event-hash-generator/tree/main/cli

• Hash generator rest api application code : https://github.com/openepcis/openepcis-event-hash-generator/tree/main/rest-api

Introduction

EPCIS standard consists of events that are triggered when objects involved progress through different steps in the supply chain. These events are sent to other organizations, stored in organization-specific repositories, or used for other purposes. There are times when the same event is triggered multiple times due to faulty hardware, poor implementations, or human mistake. Organizations typically do not want to send or store duplicate events. Consequently, a system that would allow each event to be identified individually was required. OpenEPCIS has developed the Event Hash Generator tool as a solution to this problem. Using the data contained in each event, this tool will create Hash-IDs for each EPCIS event.

The tool follows a predetermined order for properties, and all event data is always canonicalized. Therefore, even if the attributes are in a different order or the information is in URN/WebURI format, it is always guaranteed that the events will have the same Hash-Ids and be considered duplicate events. Storing unique data in the repository and avoiding confusion caused by several copies of the same event, would substantially help organizations. Currently, the tool supports the generation following Hash Ids: sha-256, sha-224, sha-384, sha-512, sha3-224, sha3-256, and sha3-512.

Usage

Following section provides quick overview of how to generate hash ids for EPCIS document:

Web Application

Users can quickly access the tool on their browser and generate Hash-Ids for EPCIS events or documents in XML/JSON format. Additionally, users have the option to view the Pre-Hash string and select multiple hash algorithm types in accordance with their needs. You can access the web application from here.

API Endpoint

With their XML/JSON documents serving as request, users/developers can use the API to send requests to OpenEPCIS's Hash Generator API and receive back the converted document as a response. These API's can also be used directly online or from within another application code. Users can access the REST endpoint using Swagger-UI from here.

Command Line

Client URL or popularly known as cURL is a command-line utility that is used to send and receive data from or to a server. As many developers and users prefer using this utility over normal web applications, OpenEPCIS Event Hash Generator supports the generation of hash ids using the cURL command. Users can make requests to the service https://tools.openepcis.io/api/generate/event-hash/document using their preferred document or if you have list of EPCIS events then make request to https://tools.openepcis.io/api/generate/event-hash/events. Following is an example of a cURL request to generate hash ids for JSON document:

curl -X 'POST' \
  'https://tools.openepcis.io/api/generate/event-hash/document' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "@context": [
    {
      "example": "http://ns.example.com/epcis/"
    }
  ],
  "type": "EPCISDocument",
  "schemaVersion": "2.0",
  "creationDate": "2005-07-11T11:30:47.0Z",
  "epcisBody": {
    "eventList": [
      {
        "type": "ObjectEvent",
        "eventTime": "2005-04-04T04:33:31.116+02:00",
        "eventTimeZoneOffset": "-06:00",
        "action": "ADD",
        "bizStep": "commissioning",
        "disposition": "in_transit",
        "epcList":["urn:epc:id:grai:4012345.55555.987"],
        "readPoint": {
          "id": "urn:epc:id:sgln:0614141.07346.1234"
        }
      }
    ]
  }
}'

Application Code

The utility has been developed using Java. The code is available at the OpenEPCIS GitHub account and can be accessed directly or as dependencies for other projects. The complete code can be found here.

Generating Hash IDs from XML Document

If the users have EPCIS documents in XML format, then they can be provided as InputStream, which serves as the first parameter to the fromXml method, and the second parameter specifies the type of hash algorithm needed (by default sha-256 algorithm is used):

final InputStream xmlStream = getClass().getResourceAsStream("/XmlEpcisDocument.xml");
final EventHashGenerator eventHashGenerator = new EventHashGenerator();
eventHashGenerator.prehashJoin("\\n");
final Multi<Map<String, String>> documentEventHash = eventHashGenerator.fromXml(xmlStream, "prehash", "sha-256");
//final List<String> xmlHashIds = eventHashGenerator.fromXml(xmlStream, "sha-512").subscribe().asStream().toList();

Generating Hash IDs from JSON Document

If the users have the EPCIS documents in JSON/JSON-LD format, then they can be provided as InputStream, which serves as the first argument to the fromJson method, and the second parameter specifies the type of hash algorithm needed (by default sha-256 algorithm is used):

final InputStream jsonStream = getClass().getResourceAsStream("/JsonEpcisDocument.json");
final EventHashGenerator eventHashGenerator = new EventHashGenerator();
final Multi<Map<String, String>> jsonEventHash = eventHashGenerator.fromJson(jsonStream, "prehash", "sha3-512");
//final List<String> jsonHashIds = eventHashGenerator.fromJson(jsonStream, "sha-256").subscribe().asStream().toList();

Subscription logic

If users have a large EPCIS document in XML or JSON/JSON-LD consisting of millions of events, they may supply it to the corresponding fromXml or fromJson of the EventHashGenerator class, as previously mentioned. Additionally, users can subscribe to the method so that they can print or utilize generated HashIds for additional processing as soon as they are generated and returned using the Reactive Stream approach. A simple illustration of how the HashIds may be printed using the subscription logic is shown in the following lines of code. In this simple example, when HashId is generated it is printed out to the console. By using this approach it is not required for the process to wait until all events are completed. Hence making this approach much faster and efficient.

final InputStream xmlStream = getClass().getResourceAsStream("/XmlEpcisDocument.xml");
final InputStream jsonStream = getClass().getResourceAsStream("/JsonEpcisDocument.json");
final EventHashGenerator eventHashGenerator = new EventHashGenerator();

eventHashGenerator.fromXml(xmlStream, "sha-256").subscribe().with(
                xmlHashId -> System.out.println(xmlHashId),
                failure -> System.out.println("XML HashId Generation Failed with : " + failure));

eventHashGenerator.fromJson(jsonStream, "sha-256").subscribe().with(
                jsonHashId -> System.out.println(jsonHashId),
                failure -> System.out.println("JSON HashId Generation Failed with " + failure));

Further References

For more information on Event Hash Generation, ordering of elements, or canonicalization, please refer to the detailed Documentation at GitHub by Ralph Tröger or on official GS1 EPCIS documentation.