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:

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

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

• Identifier converter application code : https://github.com/openepcis/openepcis-epc-digitallink-translator

Introduction

Every digital or physical object, such as a document, location, product, or asset, is identified by universal identifiers. Starting from EPCIS 2.0, these universal identifiers can be represented using either the EPC URI (Pure Identity URI) or Digital Link WebURI (until EPCIS 1.2 these identifiers were represented using only URN format). Applications using the EPCIS standard must use one of these syntaxes to identify objects. Pure Identity URI is represented using the URN (Uniform Resource Name) format. An example of an SSCC (Serial Shipping Container Code) represented using the URN format is as follows:

urn:epc:id:sscc:234567.18901234567

Digital Link URI (Uniform Resource Identifier) is a format newly introduced with EPCIS 2.0 in which identifiers can be represented using the Web URI format. The above SSCC identifier example can be represented in Digital Link URI format as follows:

https://id.gs1.org/00/123456789012345675

In certain scenarios, organizations like to use both formats for better visibility and accessibility, so they need the option to translate from URN to DL URI and vice versa. Hence, this OpenEPCIS utility was developed to convert standard application identifiers from URN to Digital Link URI format and vice versa. It can be used independently or in conjunction with the other OpenEPCIS tools. It supports the following identifier types:

Supported instance-level identifiers:

SSCC : Serial Shipping Container Code
GTIN with serial (SGTIN) : Serialised Global Trade Item Number
UPUI : Unit Pack Identifier
GDTI with serial : Global Document Type Identifier
SGCN with serial : Serialised Global Coupon Number
GINC : Global Identification Number for Consignment
GSIN : Global Shipment Identification Number
GRAI with serial : Global Returnable Asset Identifier
GIAI : Global Individual Asset Identifier
ITIP : Individual Trade Item Piece
CPI with serial : Component/Part Identifier
GSRN : Global Service Relation Number - Recipient
GSRNP : Global Service Relation Number – Provider\

Supported class-level identifiers:

GTIN : Global Trade Item Number
GTIN + Lot (LGTIN) : GTIN + Batch/Lot
GTIN + Serial (SGTIN) : GTIN + Serial
GDTI without serial
SGCN without serial
GRAI without serial
CPI without serial\

Supported location/party identifiers:

GLN with extension : Global Location Number with extension
GLN without extension : Global Location Number without extension
Party GLN : Party Global Location Number

Usage

The following section provides a quick overview of how to convert an EPCIS identifier from Digital Link URI to URN and vice versa:

Web Application

The tool is available as a web application that users can access directly to acquire the converted EPCIS identifier by providing either a URN or a DL WebURI EPCIS identifier as input. The web application can be accessed from here.

API Endpoint

Using an identifier as the request, users and developers can send requests to the OpenEPCIS identifier converter API and receive the converted identifier back 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 Identifier Converter supports the conversion of EPCIS identifiers using the cURL command. Users can make requests to the service https://tools.openepcis.io/api/convert/identifier/urn or https://tools.openepcis.io/api/convert/identifier/web-uri using their preferred identifier. Following is an example of a cURL request to convert a URN to a Digital Link WebURI:

curl -X 'POST' \
  'https://tools.openepcis.io/api/convert/identifier/web-uri' \
  -H 'accept: application/json' \
  -H 'Content-Type: text/plain' \
  -d 'urn:epc:id:sgtin:234567890.1123.9999'

Application code

The application has been primarily developed using the Java programming language. Users can obtain and utilize the code from here.

Conversion from URN to DL URI

To convert the URN to DL URI call the following method and pass the URN which needs to be converted:

ConverterUtil.toURI(inputURN);

The utility automatically detects the identifier type and converts it to the corresponding DL URI format. This method returns a String. If the inputURN does not follow the GS1 identifier syntax, it throws a corresponding Exception.

Following is an example of converting the SGTIN from URN to DL URI:

System.out.println(ConverterUtil.toURI("urn:epc:id:sgtin:2345678901.123.9999"));
//https://id.gs1.org/01/12345678901231/21/9999

Conversion from DL URI to URN

To convert from DL URI to URN call the following method and pass the existing DL URI and GCP length:

ConverterUtil.toURN(inputURI,gcpLength);

The utility automatically detects the DL URI type and converts it to the corresponding URN format. This method returns a Map<String, String> with various information. If the inputURI does not follow the GS1 identifier syntax, it throws a corresponding Exception.

Following is an example of converting the SGTIN from DL URI to URN:

System.out.println(ConverterUtil.toURN("https://id.gs1.org/01/12345678901231/21/9999", 10));

// {gtin=12345678901231, asURN=urn:epc:id:sgtin:2345678901.123.9999, 
// asCaptured=https://example.com/path/01/12345678901231/21/9999, 
// serial=9999, canonicalDL=https://id.gs1.org/01/12345678901231/21/9999}

Conversion from class level URN to Web URI

To convert the class level URN to Web URI invoke the following method and pass the existing URN. The code automatically detects the type of identifier and converts it to the appropriate Web URI. If any error is found in the identifier, it will be displayed.

ConverterUtil.toURIForClassLevelIdentifier(inputURN);

Following is an example of converting GTIN from URN to Web URI:

System.out.println(ConverterUtil.toURIForClassLevelIdentifier("urn:epc:idpat:sgtin:3489348.939489.*"));
//https://id.gs1.org/01/93489348394895

Conversion from class level Web URI to URN

To convert the class level DL URI to URN, invoke the following method and pass the existing DL URI with or without the GCP length. If the GCP length is not provided, the code automatically detects it based on the GS1 standards.

ConverterUtil.toURNForClassLevelIdentifier(inputURI,gcpLength);
ConverterUtil.toURNForClassLevelIdentifier(inputURI);

Following is an example of converting GTIN from Web URI to URN:

System.out.println(ConverterUtil.toURNForClassLevelIdentifier("https://id.gs1.org/01/88588588585452"));

// {gtin=88588588585452, asURN=urn:epc:idpat:sgtin:8588588.858545.*,
// asCaptured=https://example.com/path/01/88588588585452, 
// canonicalDL=https://id.gs1.org/01/88588588585452}

Conversion from URN to Bare String

To convert URN formatted CBV values into bare strings, call the following method and pass the CBV string:

ConverterUtil.toBareStringVocabulary(eventVocabulary);

Following is an example of converting a CBV formatted business step value to a bare string:

ConverterUtil.toBareStringVocabulary("urn:epcglobal:cbv:bizstep:inspecting");
//inspecting

Conversion from Bare String to URN

To convert bare string values to URN formatted CBV values, call the following method and pass the bare string:

ConverterUtil.toUrnVocabulary(eventVocabulary);

Following is an example of converting a bare string business step value to a CBV formatted value:

ConverterUtil.toUrnVocabulary("inspecting");
//urn:epcglobal:cbv:bizstep:inspecting