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:

• 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 documents, locations, products, assets, etc. is identified by universal identifiers. Starting from EPCIS 2.0, these universal Identifiers can be either represented using the EPC URI (Pure Identity URI) or Digital Link WebURI (until EPCIS 1.2 these identifiers were represented using only URN format). Applications that are using the EPCIS standard must use one of the syntaxes to identify the 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 newly introduced format 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 organization likes to make use of both formats for better visibility and accessibility so they need the option to translate the from URN to DL URI and vice versa. Hence, this OpenEPCIS utility has been developed which can convert the 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 standard. 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 without extension
GLN without extension : Global Location Number with extension
Party GLN : Party Global Location Number

Usage

Following section provides quick overview of how to convert 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 an URN or DL WebURI EPCIS identifiers as input. The web application can be accessed from here.

API Endpoint

With their identifiers serving as request, users/developers can use the API endpoint to send request to OpenEPCIS identifier converter and receive back the converted identifier 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 Identifiers 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 URN to digitallink web URI:

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 follow the GS1 identifier syntax format then it will throw an 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 the Map<String, String> with various information. If the inputURI does follow the GS1 identifier syntax format then it throws corresponding Exception.

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

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 the existing URN. The code will automatically detect the type of identifier and converts it to appropriate Web URI. If any error found in the identifier then same 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 GCP Length. If GCP Length has not been provided then the code will automatically detect the GCP Length 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 the URN formatted CBV values into bare string, call the following method and pass the CBV string:

ConverterUtil.toBareStringVocabulary(eventVocabulary);

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

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

Conversion from Bare String to URN

To convert the 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 bare string business step value to CBV formatted value:

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