Extract Data Matrix Value

GS1 specifications

GS1 General Specifications

GS1 Data Matrix Guideline

Usage

d2:extractDataMatrixValue( <gs1Key>, <gs1Value> )

Parameter	Supported values
gs1Key[^1]	A string of any application identifier (ai) from figure 3.2-1 in the GS1 General Specification doc. Any of the GS1 data matrix string keys[^2]
gs1Value	GS1 formatted string (Hardcoded, rule variable or rule expression)

[^1]: Data Matrix specific identifiers as seen in table 2-1 in GS1 Data Matrix Standard doc have been coded to allow both the numeric and named key.

[^2]: gtin, lot number, batch number, production date, best before date, expiration date, serial number

Usage example

Given the value ]d20108470006991541211008199619525610DXB200517220228

gs1Key	value returned
01	08470006991541
gtin	08470006991541
serial number	10081996195256
best before date	empty string

Code in the rule engine

Related classes:

• RuleFunctionExtractDataMatrixValue

• GS1 Classes

GS1Elements.java

This enumerator lists all GS1 elements:

GS1 format identifier

Named GS1_XX_IDENTIFIER with a string value of "]XX". XX denotes the GS1 type. For example "]d2" is the GS1 Data Matrix identifier

Group separators

Application identifiers can have a fixed or a variable lenght. In this last case, a variable lenght ai will be preceded by the group separator identifier (FNC1). It has the string value "\u001d" which is the GS unicode character

Application identifiers (ai)

All named ai and their respected string value.

Some values will end with a * symbol that means it can be any digint from 0-9 and denotes the number of decimal points the value will have. For exampe, the HEIGHT_M (height in meter) has the ai value of "313*". Processing "31325512" will result in 55.12.

This class expose the following utility methods and variables:

• GS1Identifiers: List of all GS1 identifiers
• fromKey: Returns the Application Identifier for a given string key (Only GS1 data matrix are supported as explained above)
• getApplicationIdenfier: Returns the leading application identifier form a gs1 value

GS1Table.java

This class provides two HashMaps with the GS1 Data Matrix application identifiers and their length. The variable lenght map values indicates the maximun length of the value.

GS1ValueFormatter.java

This is an interface with the methods needed to process a GS1 formatted string and extract the individual values.

GS1BaseValueFormatter.java

Implements the GS1ValueFormatter interface and provides a common code for the getFormatterFromValue and the removeGS1Identifier.

• getFormatterFromValue: Reads the GS1 string value and returs the correct formatter based on the leading GS1 Identifier. For now, only GS1 Data Matrix ("]d2") and GS1 QR Code ("]Q3") are supported. Other GS1 values will require the implementation of its own formatter according to specifications.

• removeGS1Identifier : Removes the leading GS1 Idenfier from the GS1 string value.

GS1DataMatrixValueFormatter.java

This is the specific formatter in charge of extracting the indivual values. It follows the decode scheme of the GS1 DataMatrix Guideline which consists on the following steps to extract a given application identifier:

1. Initialize the data map where all individual values will be stored.

dataMap = new HashMap<>();

2. Remove GS1 Identifier and if the value includes any GS, split the value into any different parts.

String[] gs1Groups = removeGS1Identifier( value ).split( GS1Elements.GS1_GROUP_SEPARATOR.getElement() );

3. For each of these groups (if not empty) we get the leading "Application Identifier" (ai). Then we use the GS1Table to get the length linked to the GS1Element of the ai. If the length is null, then it is a variable length value. The value is stored in the data map and handles the next part of the group.

private void handleGroupData( String gs1Group )
    {
        if ( !gs1Group.isEmpty() )
        {
            int gs1GroupLength = gs1Group.length();
            String ai = GS1Elements.getApplicationIdentifier( gs1Group );
            Integer nextValueLength = GS1Table.aiFixedLengthMap().get( ai );
            if ( nextValueLength == null )
                nextValueLength = gs1GroupLength;
            dataMap.put( ai, gs1Group.substring( 2, nextValueLength ) );
            handleGroupData( gs1Group.substring( nextValueLength ) );
        }
    }

4. After completing all groups, we return the desired GS1 element from the data map or throw an exception if the value is not available.

if ( dataMap.containsKey( valueToReturn.getElement() ) )
        {
            return dataMap.get( valueToReturn.getElement() );
        }