Functional User Guide GS1 Major XML eCom release 3.0
Identification of objects in eCom messages
Document identification & references
The identification of all GS1 XML business documents is based on the common structure of Entity Identification consisting of two components:
- 'entityIdentification’ mandatory element that identifies the business document.
- ‘contentOwner’ optional element that uniquely identifies the creator of the given business document. This element should be used when the information about who created the document identification number is relevant within the business process.
The Entity Identification type is used to:
- identify business documents that constitute the given message
- reference other business documents that are relevant to the current document.
Business document identification
A business document may be identified only by the ‘entityIdentification’ element. This is the placeholder for Order Number, Invoice Number, etc. This identifier is controlled by the creator of the document. The best practice is to keep this value unique for all the documents of the same type (e.g. all Orders or all Invoices) within the domain of the creator of these documents. However, some users may find it impossible due to the limited identifier capacity. If the ‘entityIdentification’ values are ever re-used, the creator of the component should ensure that they are not repeated within the same message (transmission).
The ‘contentOwner’ element should be used when the information about who created the document identification number is relevant to the business process.
Business document reference
Every business document contains references to other documents, e.g.:
- other GS1 BMS – e.g. Order is often referenced in Despatch Advice and Invoice
- non-eCom documents, e.g. Order may reference a Trade Agreement, Invoice may reference Promotional Deal, etc.
This reference can be done at two different levels:
- a reference to the entire document – e.g. the Order or Invoice in general
- a reference to the line item within the document – e.g. the Order line item or Invoice line item
The document reference consists of the following components:
Where:
- ‘entityIdentification’ is a mandatory element that identifies the referenced business document, e.g. Purchase Order referenced in the Invoice document.
- ‘contentOwner’ optional element that uniquely identifies the creator of the referenced business document.
- ‘creationDateTime’ is a optional element that specifies when the referenced document has been created, e.g. the Order date of the Purchase Order referenced in the Invoice document
- ‘lineItemNumber’ is a optional element that uniquely identifies the referenced line item in the referenced document, e.g. Order line item referenced in the Invoice line item.
Party identification
In GS1 System parties and locations are typically identified by the Global Location Number GLNs that in most cases provide sufficient identification. However, in some business scenarios additional information is needed, e.g.
- in Business to Customer applications when the buyer is not a commercial company, but an individual person that does not have assigned GLN
- when delivery point is a building site, managed by a construction company, not by the final owner of the future facility
- some companies need to use other identifiers additionally to the GLN, either for business reasons or to fulfil legal obligations, etc.
For these reasons, the Party identification in GS1 eCom messages is defined as ‘TransactionalPartryType’ used whenever a Party or location need to be identified. This type consists of the following components:
Where:
- ‘gln’ is the primary party identifier, although it is defined as optional, each party identified in the trading relationship should have this primary party identifier apart from justified exceptions (e.g. identification of a private person)
- ‘additionalPartyIdentification’ is an identification of a party by use of a code other than the Global Location Number
- ‘address’ is an address of the party involved in the business transaction
- ‘contact’ is an information about the contact for the party involved in the business transaction
- ‘dutyFeeTaxRegistration’ is an information about the registration for a particular duty, tax or fee, for the party involved in the business transaction
- ‘organisationDetails’ is an Information about the organisation of the party involved in the business transaction
- ‘financialInstitutionInformation’ is a set of information about the financial institution(s) where the party holds an account
For a more detailed overview on the benefits of GLN see GLN Executive Summary.
Item identification
Each trade item, being defined in the widest possible sense, is uniquely identified by a Global Trade Item Number GTIN that in most cases provides sufficient identification. However, in some business scenarios additional information is needed. For this reason, the Trade Item identification in GS1 eCom messages is defined as ‘TransactionalTradeItemType’ used whenever a product or service need to be identified in order to retrieve pre-defined information. This type consists of the following components:
Where:
- ‘gtin’ is the mandatory primary and unique identifier of a trade item
- ‘additionalTradeItemIdentification’ is an additional to the GTIN way to identify a trade item
- ‘tradeItemQuantity’ is the quantity of the trade item specified in the given transaction
- ‘tradeItemDescription’ provides additional variants necessary to communicate to the industry to help define the product
- ‘transactionalItemData’ provides data describing the characteristics and history of the item
- ‘colour’ specifies the colour of the trade item
- ‘size’ provides the physical dimensions of the trade item
Preferably, this additional information should be communicated during master data alignment before any commercial transaction to avoid sending the same data over and over again in every business message. However, if this is not feasible, there is a possibility to add it to the trade item identification.
For more information about the GTIN format in GS1 XML standards see here.
For a more detailed overview on the benefits of GTIN see GTIN Executive Summary.
Logistic Unit identification
Scanning the standard identification number, marked on each logistic unit, allows the physical movement of units to be individually tracked and traced by providing a link between the physical movement of items and the associated information flow provided by eCom messages.
Each logistic unit is uniquely identified with the Serial Shipping Container Code, SSCC that in most cases provides sufficient identification. However, in some business scenarios additional information is needed. For this reason, the Logistic Unit identification in GS1 eCom messages is defined as ‘LogisticUnitIdentificationType’ used whenever a logistic or shipment unit need to be uniquely identified for its lifetime. This type consists of the following components:
Where:
- ‘sscc’ is the mandatory primary and unique identifier of a logistic item
- ‘additionalTradeItemIdentification’ is an additional to SSCC identification attached to a shipping container or shipping package and used for logistical and traceability purposes
For a more detailed overview on the benefits of SSCC see SSCC Executive Summary.
Consignment identification
The consignments: logical groupings of goods (one or more physical entities) that are intended to be transported as a whole from a Shipper (Consignor) to a Receiver (Consignee) by a carrier or freight forwarder in GS1 eCom messages are identified by the Global Identification Number for Consignment, GINC. In most cases they provide sufficient identification. However, in some business scenarios additional information is needed.
For this reason, the Trade Item identification in GS1 eCom messages is defined as ‘ConsignmentIdentificationType’ used whenever a consignment needs to be uniquely identified. This type consists of the following components:
Where:
- ‘ginc’ is the mandatory primary identifier of a consigment
- ‘additionalConsigmentIdentification’ is an additional to GINC identification of a consignment
Asset identification
The assets e.g. a computer, a desk or a component part of an aircraft, in GS1 eCom messages are identified by the Global Individual Asset Identifier, GIAI. In most cases they provide sufficient identification. However, in some business scenarios additional information is needed.
For this reason, the Trade Item identification in GS1 eCom messages is defined as ‘IndividualAssetIdentificationType’ used whenever a consignment needs to be uniquely identified. This type consists of the following components:
Where:
- ‘giai’ is the mandatory primary identifier of an individual asset
- ‘additionalIndividualAssetIdentification’ is an additional to GIAI identification of an asset
Shipment identification
The Service Relations, e.g. reusable package or transport equipment, in GS1 eCom messages are identified by the Global Service Relation Number, GSRN. It identifes the recipient of services in the context of a service relationship. It is used to enable access to a database entry for recording recurring services. In most cases they provide sufficient identification. However, in some business scenarios additional information is needed.
For this reason, the Trade Item identification in GS1 eCom messages is defined as ‘ServiceRelationIdentificationType’ used whenever a Service Relation needs to be uniquely identified. This type consists of the following components:
Where:
- ‘gsrn’ is the mandatory primary identifier of a Service Relation
- ‘additionalServiceRelationIdentification’ is an additional to GRAI identification of a Service Relation.
Document actions
The actions are used to instruct the recipient of the document to perform one of the following:
- ‘ADD’ means that the document sent with this value is new and it should be passed for business processing
- ‘REFRESH’ means that the document sent with this value provides a change on a previously sent document by sending the entire updated document
- ‘DELETE’ means that the document sent with this value requires a deletion of the same document sent previously
This approach allows reducing the overall GS1 message suite. There is no need for business documents such as Order Change or Order Cancellation. These functions can be performed by one Order document sent with the respective document action value.
The use of actions is relevant only to certain business documents, for example it makes sense to use them in the Order, but not in the Order Response.