Message layer

Return to Table of Contents

• Transaction
  • Transaction structure
  • Transaction functionality
• Command
  • Document Command
  • Document Identification Command
  • Link Command

The message layer defines actions that should be performed on the specific document or documents by the receiving application. Those tasks are defined as commands.

Use of this layer allows a reduction in the number of documents needed to perform an efficient exchange of business information. The same document can be used with different commands. Hence, no separate documents like ‘Add Order, ‘Change Order’ or ‘Delete Order’ are needed. The same ‘Order’ document can be sent with a relevant command, e.g. ‘add’, ‘change’ or ‘delete’.

In a similar way, several documents can reuse the same commands, so adding the new commands when such a need is identified, is quick and easy, with no need to make any change to the other document schemas. The component that needs to be added then is a new item in the ‘documentCommandListType’, defining the type of action that should be performed on the corresponding documents by the receiving end.

The Message layer contains three main components:
- transaction
- command
- interface to the Document Layer

The Message layer is linked to the Header layer by the ‘message’ component, introduced in version 2.0.2 of the GS1 XML Standards. It acts simply as a placeholder allowing for appending multiple transactions in one header.

The ‘message’ component is identified by the entity identification, and contains a placeholder where the transaction component can be inserted. This placeholder has a form of the XML schema '##any' element. It can have multiple occurrence, so that many transactions can be appended.

The ‘message component structure

The XML 'any' element has a built-in attribute: processContents indicating how an XML processor should handle the validation of XML documents against the elements specified by the 'any' element. In the message component, the value of this attribute is set to ‘strict’, it means that the XML processor must obtain the schema for the required namespaces and validate any element from those namespaces.

Message layer overview

Each message sent can contain several transactions and every transaction can hold multiple commands concerning one or more documents. This architecture allows great flexibility of business information exchange.

Transaction

• Transaction structure
• Transaction functionality

Transaction structure

A transaction provides functionality of submitting multiple commands simultaneously. It allows the users to process the group of messages together. If one of them fails, all of them may then be discarded.

Transaction elements

The Transaction schema contains two main components:

1. Identification of the transaction - a component called entity identification, consisting of:
a. the party that created the set of commands
b. a unique identifier assigned by that party

The entity identification structure

2. The commands themselves. The ‘command’ element is a container, where one or multiple commands that form one transaction can be inserted

The number of commands in one transaction is unlimited from the XML syntax point of view, however, it is limited by the bandwidth and application processing capabilities. All messages sent in one transaction should be of the same type, e.g. only Orders or Invoices.

Transaction functionality

Transaction applies the principle of 'all or nothing'. If one of the documents in a transaction is not valid, then all of them are rejected.

The transaction element can be considered as a flag indicating that if some of the documents nested within it fail the validation, the processing of all the remaining ones should stop. Obviously, this functionality has to be pre-programmed into the processing application. It is important to note that this relates only to technical level validation, it does not cover the business level validation, since it is not possible to verify the conformance to the business rules at the moment of 'unwrapping' the transaction layer.

The technical validation checks if the tag names, order and data field format are inconsistent with the schema. For example, the GTIN is defined in the schema as strictly 14 digits long, therefore, if in the instance file it has 13 or 15 digits, the document fails the technical validation. On the contrary, if the check digit in the GTIN is not correct, the file will still be considered as valid, as this information can only be verified at the business application level.
In the same way the cardinality of components is checked – if a mandatory component is missing, the file will not be valid, but if the given component had been defined as optional, the file will be valid, even if from business point of view the information should be present, the file will still be technically valid and the full transaction content will be accepted.

Example 1
A sender needs to send two TradeItem messages, one for GTIN 1, the second for GTIN 2. The product 1 is related to product 2. Instead of sending them separately, in two distinct transmissions, he can transmit them together in one transaction:

Both documents have to be correct (valid), otherwise both will be rejected.

Example 2
A sender needs to send three new TradeItem messages to a customer and amend two other TradeItem descriptions, which had been sent earlier. All five TradeItem documents can be sent together in one message – three with a command ADD and two with a command CHANGE BY REFRESH. Both commands could be inserted in one transaction, but since the new TradeItem messages are not related to the amended ones, they can be placed in two separate transactions, sent in one message:

If any of the first three messages (TradeItem for GTIN 1, 2 or 3) is not valid, all three will be rejected but the messages from the second transaction (TradeItem for GTIN 4 and 5) will still be processed.

Example 3
A sender needs to send three new TradeItem messages to a customer and cancel one sent previously. Those messages are not interrelated and even if one of them fails, the sender wants to maintain the other as valid ones. All four messages are sent in one transmission, three with a command ADD and one with a command DELETE, but without the transaction layer:

If any of those messages (TradeItem for GTIN 1, 2, 3 or cancellation of TradeItem for GTIN 4) are not valid, the other ones will still be processed.

TOP

Command

• Document Command
• Document Identification Command
• Link Command

Commands are used by a trading partner to instruct the receiving application about an action that should be performed on a given document. All commands are transitive and are discarded after executing the task.

Some of the actions to be performed are defined by the command itself, while other ones by an attribute of the command.

The ‘command’ is an abstract element, extended by the following elements:

• ‘documentCommand’
• ‘documentIdentificationCommand’
• ‘linkCommand`
  

The Command Type structure

The substituting elements are defined in DocumentCommand.xsd, DocumentIdentificationCommand.xsd and LinkCommand.xsd.

Document Command

The Document Command is used to instruct the recipient of that command to perform a particular action related to the documents within the command. The document in question has to be present, i.e. it must be sent together with the command. The actions, which can be performed on it include:

• ‘Add’
• Refresh’
• ‘Correct’
• ‘Delete’
  
  The Document Command is an extension of the abstract Command. It contains two main components: the ‘documentCommandHeader’ and ‘documentCommandOperand’:

The Document Command structure

The ‘documentCommandHeader’ specifies the action that should be performed on the given document. Those tasks, defined as the required attribute of the header element, include:

The ‘documentCommandOperand’ contains an abstract 'document' element that can be extended by the actual business document elements, defined in the business message schemas. Those are the documents upon which one of the actions defined in the header element should be performed.

The Document Command Operand structure

The list of the possible documents contains all the business messages defined within the given major version.

Document Identification Command

This is an extension of the abstract Command, defining operations that require just an identification of the relevant documents. The only operation currently supported by this method is DELETE, defined as a value of an attribute of the ‘documentIdentificationCommand’ element.

The Document Identification Command structure

The document on which the action should be performed is identified in the ‘documentIdentifierList’ element.

The Document Identifier structure

It can be specified in three ways:

1. By ‘partyIdentification’ – using GLN and optionally, an additional identifier of the concerned party.
2. By ‘tradeItemIdentification’ – using GTIN and optionally, an additional identifier of the trade item concerned by the document in question.
3. By ‘entityIdentification’ - a combination of the unique document identifier assigned by its creator and the unique identification of that document creator (GLN and optionally, an additional identifier).
   

Link Command

This type of command allows to establish parent-child or peer relationships between several entities.

The Link Command consists of two major components: Link Header and Link Operand.

The Link Command structure

Link Header

The ‘linkCommandHeader’ specifies whether the function of the command is to link or unlink the documents concerned. They are defined as the enumeration values: LINK and UNLINK of the element’s attribute ‘LinkCommandListType’.

The Link Command Header structure

The header contains also the unique command identifier assigned by its creator, combined with the creator’s identification (GLN and optionally, an additional one).

Link Operand

The ‘linkCommandOperand’ specifies the parent and children, identified by a document identifier.

The Link Command Operand structure

The term document here can be identified in three ways:

• by Entity Identification
• by Party Identification
• by Trade Item Identification
  

The Document Identifier structure

The first document identifier occurring in the sequence of Link Command Operand sub elements, defines the parent object.

The children objects can be identified using either a Hierarchy List or Associated Document List method.

The child or associated element structure

The ’hierarchyList’ element allows to make a list of child documents, with just one document per child. By using this method it is also possible to specify the quantity of each child.

The child element structure

Therefore, the Hierarchy List can be used to specify the number of lower items in a packaging unit and the content of mixed containers.

The ‘associatedDocumentList’ allows to link some documents to a given parent.

The associated document list element structure

Within both parent and child elements, there is a choice of the components that are meant to be linked or unlinked. It can be ‘partyIdentification’, defining the trading partner that is to be linked to given information. The second option is the ‘tradeItemIdentification’, defining the product to be linked. The last possibility is to specify the document, using the ‘entityIdentification’.

Link Command functionality

As mentioned before, the ‘LinkCommand’ purpose is to create a parent – child relationship between parties, trade items and other entities, e.g. documents. The parent and children are identified by the ‘partyIdentification’, ‘tradeItemIdentification’, or ‘entityIdentification’, depending on the nature of the linked entities. Although they are all referred to as the ‘documentIdentifier’, their use is not restricted to documents.

Example 1

A store may receive various items via different distribution centres. In order to specify where the goods are being delivered, the supplier can use the LinkCommand to link products identified by ‘tradeItemIdentification’ to a specific location identified by ‘partyIdentification’.

The purpose of this command is to make a link between components, therefore the value of the attribute of the ‘linkCommandHeader’ element is LINK. The first occurrence of the ‘documentIdentifier’ element within the ‘linkCommandOperand’ identifies the parent of the linked components, so the ‘partyIdentification’ element has as a value the GLN of the given distribution centre. The child components are the GTINs of the given items. Since the quantity of the items is not important in this case, the items are specified in the ‘associatedDocumentList’.

..........
<linkCommand>
    <linkCommandHeader type="LINK">
        <entityIdentification>
            <uniqueCreatorIdentification>WG-000001 </uniqueCreatorIdentification>
            <contentOwner>
                <gln>0999999999991</gln>
            </contentOwner>
        </entityIdentification>
    </linkCommandHeader>
    <linkCommandOperand>
        <documentIdentifier>
            <partyIdentification>
                <gln>0999999999993</gln>
            </partyIdentification>
        </documentIdentifier>
        <childOrAssociated>
            <associatedDocumentList>
                <documentIdentifier>
                <tradeItemIdentification>
                    <gtin>00046285639566</gtin>
                </tradeItemIdentification>
                <tradeItemIdentification>
                    <gtin>00046285639573</gtin>
                </tradeItemIdentification>
                <tradeItemIdentification>
                    <gtin>00046285639580</gtin>
                </tradeItemIdentification>
                </documentIdentifier>
            </associatedDocumentList>
        </childOrAssociated>
    </linkCommandOperand>
</linkCommand>
..........

Note that the actual business message, e.g. Despatch Advice, is not attached to this command. The link created is independent of any changes of business documents. When the relationship is no longer valid, the same command with the attribute UNLINK can be sent to announce this fact.

Return to Table of Contents

TOP