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:

• Format converter web application : https://tools.openepcis.io/ui/format-converter

• Format converter API endpoint : https://tools.openepcis.io/q/swagger-ui/#/Format%20Converter

• Format converter application code : https://github.com/openepcis/openepcis-document-converter

Introduction

The previous versions of the EPCIS standard i.e until EPCIS 1.2, supported event generation only in XML format. However, from EPCIS 2.0 events can be generated and transmitted in either XML or JSON/JSON-LD format. As the EPCIS standard has been adopted by various industry sectors such as automotive, food, healthcare, retail, and many more, where objects need to be tracked within or across multiple organizations, there is a need to convert the large EPCIS event document from either XML -> JSON/JSON-LD or JSON/JSON-LD -> XML format. This conversion can be useful for organizations to exchange data easily or maintain a single standard format throughout the application or for various other convenience purposes. Although there are many open-source ready-to-use tools available online and offline that offer these format conversions, they may not be able to convert the EPCIS events accurately or support large data. Also, during the conversion, some EPCIS attributes such as user extensions, sensor elements, etc need to be handled carefully and according to standards. Therefore, until now, there is no converter that effectively and efficiently converts the large EPCIS event document from XML to JSON/JSON-LD format and vice versa.

OpenEPCIS wants to support the EPCIS community by providing means to convert the EPCIS documents from one format to another with ease. The developed utility aimed to convert the bulk EPCIS events effectively and efficiently with little to no load on the memory by using advanced techniques, and technologies. The application also provides a single solution for converting EPCIS events irrespective of the industry, use case, or supply chain system. It reduces the time and effort for the various organizations as each of them does not have to develop the conversion tool. Also, maintain and incorporate modifications according to the different release versions of EPCIS. The converted EPCIS events conform to the latest version of the EPCIS, i.e. EPCIS 2.0.

Usage

Following section provides quick overview of how to convert the EPCIS document from one format to other:

Web application

By providing either an XML or JSON/JSON-LD EPCIS document as input, users can easily access and obtain the transformed EPCIS document using the web application. You can access the web tool from here.

Swagger-UI

Users/develoers can make use of the API to send requests to the OpenEPCIS document format converter API using an EPCIS document as the input, and to receive the converted document back as a response. These APIs can also be utilized from within another application’s code or directly online. 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 Format Converter supports the conversion of EPCIS document/event using the cURL command. Users can make requests to the Document Format Converter service https://tools.openepcis.io/api/convert/json/2.0 or https://tools.openepcis.io/api/convert/xml/2.0 using their preferred document. Following is an example of a cURL request to convert the JSON document to XML format:

curl -X 'POST' \
  'https://tools.openepcis.io/api/convert/xml/2.0' \
  -H 'accept: application/xml' \
  -H 'Content-Type: application/json' \
  -d '{
  "@context": ["https://gs1.github.io/EPCIS/epcis-context.jsonld",{"example": "http://ns.example.com/epcis/"}],
  
  "id": "https://id.example.org/document1",
  "type": "EPCISDocument",
  "schemaVersion": "2.0",
  "creationDate":"2019-11-01T14:00:00.000+01:00",
  "epcisBody": {
   "eventList": [
     {
        "eventID": "ni:///sha-256;025ac144187a8c5e14caf4d1cfa69250a33dc59a5bc42a68d31b1b5e55a3f15a?ver=CBV2.0",
        "type": "AssociationEvent",
        "eventTime": "2019-11-01T14:00:00.000+01:00",
        "eventTimeZoneOffset": "+01:00",
        "parentID":"urn:epc:id:grai:4012345.55555.987",
        "childEPCs":["urn:epc:id:giai:4000001.12345"],
        "action": "ADD",
        "bizStep": "assembling",
        "readPoint": {"id": "urn:epc:id:sgln:4012345.00001.0"}
     }

   ]
  }
}'

Application Code

The application has been primarily 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.

Converting XML to JSON/JSON-LD document

If you have a EPCIS 2.0 XML document which you want to convert to JSON/JSON-LD then provide it as InputStream to convert method of VersionTransformer.class:

final InputStream xmlStream = getClass().getResourceAsStream("/convert/xmlDocument.xml");
final VersionTransformer versionTransformer = new VersionTransformer();
final InputStream convertedDocument =
        versionTransformer.convert(
        inputStream,
        b -> b
        .fromMediaType(EPCISFormat.XML)
        .toMediaType(EPCISFormat.JSON_LD)
        .toVersion(EPCISVersion.VERSION_2_0_0));
System.out.println("Converted Version Transformer JSON : \n" + IOUtils.toString(convertedDocument, StandardCharsets.UTF_8));

Converting JSON/JSON-LD to XML document

If you have a EPCIS 2.0 JSON/JSON-LD document which you want to convert to XML then provide it as InputStream to convert method of VersionTransformer.class:

final InputStream jsonStream = getClass().getResourceAsStream("/convert/JsonDocument.json");
final Conversion conversion = Conversion.builder()
        .generateGS1CompliantDocument(false)
        .fromMediaType(EPCISFormat.JSON_LD)
        .fromVersion(EPCISVersion.VERSION_2_0_0)
        .toMediaType(EPCISFormat.XML)
        .toVersion(EPCISVersion.VERSION_2_0_0)
        .build();
final InputStream convertedDocument = new VersionTransformer().convert(inputStream, conversion);
System.out.println("Converted XML document : " + IOUtils.toString(convertedDocument, StandardCharsets.UTF_8));

Dependencies

The event conversion logic depends on the openepcis-models package.