Quick links

Please find below the links to the OpenEPCIS tools and code 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

The EPCIS standard consists of events that are triggered as objects 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 error. 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 of the following hash types: sha-256, sha-224, sha-384, sha-512, sha3-224, sha3-256, and sha3-512.

Usage

The following section provides a quick overview of how to generate hash IDs for an EPCIS document:

Web Application

Users can quickly access the tool in 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

Using an XML/JSON document as the request, users and developers can send requests to the OpenEPCIS Hash Generator API and receive the generated hash IDs as a response. These APIs can also be used directly online or from within another application's code. Users can access the REST endpoint using Swagger-UI from here.

Command Line

Client URL, popularly known as cURL, is a command-line utility used to send data to and receive data from 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 they have a list of EPCIS events, to https://tools.openepcis.io/api/generate/event-hash/events. Following is an example of a cURL request to generate hash IDs for a 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, the 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, the 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 method 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 a HashId is generated, it is printed to the console. With this approach, the process does not have to wait until all events are completed, which makes it much faster and more 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 the official GS1 EPCIS documentation.