Version Converter between EPCIS 2.0 and 1.2
OpenEPCIS solution to convert EPCIS XML document from version 1.2 to 2.0 and vice versa.
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:
• 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
The newest EPCIS version i.e. EPCIS 2.0, offers several improvements over earlier versions, including the inclusion of sensor data (How dimension), a new event type (AssociationEvent), a new property (PersistentDisposition), etc. which were not supported in earlier versions as standard EPCIS attributes. Additionally, EPCIS 1.2 used <extension> wrappers to include some of the common EPCIS attribute information; however, in EPCIS 2.0, these <extension> wrappers has been removed to make the event more simpler and straightforward. The implementers may view this as a major change. Therefore, a tool was required to make it simple for implementers to switch from EPCIS 1.2 to EPCIS 2.0 XML documents and vice versa. Also, support the EPCIS standard with backward and forward compatibility. The OpenEPCIS team identified the issue and created a tool that makes it simple to convert XML EPCIS documents from version 1.2 to 2.0 and vice versa.
Usage
Following section provides quick overview of how to convert the XML EPCIS document from 1.2v to 2.0v:
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
If you have a EPCIS 1.2 XML document which you want to convert to EPCIS 2.0 XML then provide it as InputStream to convert method of 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 document : " + IOUtils.toString(convertedDocument, StandardCharsets.UTF_8));
Converting EPCIS 2.0 XML to 1.2 XML
If you have a EPCIS 2.0 XML document which you want to convert to EPCIS 1.2 XML then provide it as InputStream to convert method of VersionTransformer.class:
final InputStream inputDocument = getClass().getResourceAsStream("/version/Epcis_2_0.xml");;
final VersionTransformer versionTransformer = new VersionTransformer();
final InputStream convertedDocument =
versionTransformer.convert(
inputDocument,
Conversion.builder()
.generateGS1CompliantDocument(true)
.fromMediaType(EPCISFormat.XML)
.toMediaType(EPCISFormat.XML)
.toVersion(EPCISVersion.VERSION_1_2_0)
.build());
System.out.println("Converted XML document : " + IOUtils.toString(convertedDocument, StandardCharsets.UTF_8));