Quick Links

Below are links to the OpenEPCIS tools and code referenced on this documentation page. For enhanced understanding and practical experience with these tools, we recommend visiting and utilizing them:

• GS1 publication of the XSL version transformer : https://ref.gs1.org/tools/epcis/xsl/

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

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

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

Introduction

EPCIS 2.0 introduces several attributes that EPCIS 1.2 doesn't have — the How dimension (sensor data), the AssociationEvent event type, the persistentDisposition property — and removes the <extension> wrappers that EPCIS 1.2 used to nest those attributes that arrived later in the 1.x life. Migrating live EPCIS-1.2 corpora to 2.0, or accepting EPCIS-2.0 traffic from partners while still emitting 1.2 downstream, needs a converter that handles those shape differences correctly.

OpenEPCIS provides one. The OSS version-converter (XSLT-based) handles the standard EPCIS 1.2 ↔ 2.0 XML round-trip for typical event shapes. The Business edition adds a SAX-streaming converter for production-volume migrations — multi-gigabyte 1.2 exports, deep extension trees, mixed 1.2 / 2.0 batches.

Usage

Following section provides quick overview of how to convert the XML EPCIS document from 1.2 to 2.0 and vice versa:

Web Application

The tool is available as a web application that users can access directly to acquire the converted EPCIS XML document by providing either an 1.2 version or 2.0 version document as input. The web application is available here.

API Endpoint

With EPCIS document serving as request, users/developers can use the API to send request to OpenEPCIS's document version converter 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 Document Version Converter supports the conversion of XML document using the cURL command. Users can make requests to the Document Format Converter service https://tools.openepcis.io/api/convert/version/1.2 or https://tools.openepcis.io/api/convert/version/2.0 using their preferred document. Following is an example of a cURL request to convert the EPCIS 1.2 XML document to 2.0 XML:

curl -X 'POST' \
  'https://tools.openepcis.io/api/convert/version/2.0' \
  -H 'accept: application/xml' \
  -H 'Content-Type: application/xml' \
  -d '<?xml version="1.0" encoding="UTF-8"?>
<epcis:EPCISDocument xmlns:epcis="urn:epcglobal:epcis:xsd:1" schemaVersion="1.2"
                     creationDate="2005-07-11T11:30:47.0Z">
    <EPCISBody>
        <EventList>
            <ObjectEvent>
                <eventTime>2005-04-04T20:33:31.116-06:00</eventTime>
                <eventTimeZoneOffset>-06:00</eventTimeZoneOffset>
                <epcList>
                    <epc>urn:epc:id:sgtin:0614141.107346.2018</epc>
                </epcList>
                <action>OBSERVE</action>
                <extension>
                    <extension>
                        <sensorElementList>
                            <sensorElement>
                                <sensorMetadata time="2021-05-27T13:50:00.000+01:00"/>
                                <sensorReport type="gs1:MT-Length" component="Northing" value="-477979.89" uom="MTR"
                                              coordinateReferenceSystem="http://www.opengis.net/def/crs/EPSG/0/27700"/>
                            </sensorElement>
                        </sensorElementList>
                    </extension>
                </extension>
                <example:myField xmlns:example="http://ns.example.com/epcis">Example of a vendor/user extension</example:myField>
            </ObjectEvent>
        </EventList>
    </EPCISBody>
</epcis:EPCISDocument>'

Application Code

The utility has been developed using Java with Apache Xalan. 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 EPCIS 1.2 XML to 2.0 XML

To convert an EPCIS 1.2 XML document to EPCIS 2.0 XML, provide the document as an InputStream to the conversion method: VersionTransformer.class:

final InputStream inputDocument = getClass().getResourceAsStream("/version/Epcis_1_2.xml");;
final VersionTransformer versionTransformer = new VersionTransformer();
final Conversion conversion = Conversion.builder()
        .generateGS1CompliantDocument(false)
        .fromMediaType(EPCISFormat.XML)
        .fromVersion(EPCISVersion.VERSION_1_2_0)
        .toMediaType(EPCISFormat.XML)
        .toVersion(EPCISVersion.VERSION_2_0_0)
        .build();
final InputStream convertedDocument = versionTransformer.convert(inputDocument,conversion);
//System.out.println("Converted XML 2.0 document : " + IOUtils.toString(convertedDocument,StandardCharsets.UTF_8));

Converting EPCIS 2.0 XML to 1.2 XML

To convert an EPCIS 2.0 XML document to EPCIS 1.2 XML, provide the document as an InputStream to the conversion method: VersionTransformer.class:

final InputStream inputDocument = getClass().getResourceAsStream("/version/Epcis_2_0.xml");;
final VersionTransformer versionTransformer = new VersionTransformer();
final Conversion conversion = Conversion.builder()
        .generateGS1CompliantDocument(false)
        .fromMediaType(EPCISFormat.XML)
        .fromVersion(EPCISVersion.VERSION_2_0_0)
        .toMediaType(EPCISFormat.XML)
        .toVersion(EPCISVersion.VERSION_1_2_0)
        .build();
final InputStream convertedDocument = versionTransformer.convert(inputDocument, conversion);
//System.out.println("Converted XML 1.2 document : " + IOUtils.toString(convertedDocument,StandardCharsets.UTF_8));