ESM Aggregation Guidelines (EPCIS v1.2)

See How To Use this Guide before interpreting the guidelines below.

Message Type: SOM_ESM_AGGREGATE

Info Exchange Display Name: ESM Aggregate

When sending an element in Date or DateTime format, a valid date must be given. "00" is not a valid day or month value and "0000" is not a valid year value.
NTINs must follow the GS1 Guidance standards as found on the GS1 website.
  • Ex: urn:epc:id:sgtin:415001647778.0.100000000022
  • Format: urn:epc:id:sgtin:[company prefix].[indicator digit][item ref].[serial number]
Information regarding NTINs cannot be exchanged with trade partners unless the specific format outlined above is followed. If using an NTIN without following this format, an outbound error occurs when passing data from TraceLink to a trade partner.
Data Element Occurs
Length		 Type Description
epcis:EPCISDocument [1…1]
[–]		 - Required. EPCIS message root element.
  @schemaVersion [1…1]
[0/*]		 Decimal Required. The version of the EPCIS schema used to populate the EPCIS document elements. Must equal 1.2. *1
  @creationDate [1…1]
[1/*]		 DateTime Required. Date the message was created in YYYY-MM-DDTHH:MM:SS:mmZ format. *2
  EPCISHeader [0…1]
[–]		 - Required. The XML file control header.
    sbdh:StandardBusinessDocumentHeader [1…1]
[–]		 - Required. Business header information including EPCIS Header Version, Sender, and Receiver information, along with the document identification.
      sbdh:HeaderVersion [1…1]
[0/*]		 String Required. Version of the Standard Business Document Header (SBDH). The HeaderVersion must be set to 1.0. *3
      sbdh:Sender [1…*]
[–]		 - Required. A unique identification key for the Sender party of the message, representing the organization that created the standard business document. The Sender element must be used only once with GS1 XML messages.
        sbdh:Identifier [1…1]
[1/*]		 String Required. The value of the Identifier element may be a GLN, SGLN, or any other supported business party type. *4

Send SGLN and all other party types with the GS1-conformant uri prefix, for example:

  • urn:epc:id:sgln:088202.867701.0
  • http://epcis.gs1us.org/hc/dea/loc/10023141
GLNs do not have a urn/http prefix.
          @Authority [1…1]
[1/*]		 String Required. The sender identifier type. The Authority was previously expected to be set to GLN for GS1 XML messages. An update made in December 2016 changed this to accept additional values. *5

See the BusinessAndLocationId enumeration list for valid values.
      sbdh:Receiver [1…*]
[–]		 - Required. Indicates a unique identification key for the direct Receiver party of the message, representing the organization that receives the standard business document. The Receiver element is used only once with GS1 XML messages.
        sbdh:Identifier [1…1]
[1/*]		 String Required. The value of the Identifier element may be a GLN, SGLN, or any other supported business party type. *6

Send SGLN and all other party types with the GS1-conformant uri prefix, for example:

  • urn:epc:id:sgln:088202.867701.0
  • http://epcis.gs1us.org/hc/dea/loc/10023141
GLNs do not have a urn/http prefix.
          @Authority [1…1]
[1/*]		 String Required. The receiver identifier type. The Authority was previously expected to be set to GLN for GS1 XML messages. An update made in December 2016 changed this to accept additional values. *7

See the BusinessAndLocationId enumeration list for valid values.
      sbdh:DocumentIdentification [1…1]
[–]		 - Required. Contains the identification group for the message.
        sbdh:Standard [1…1]
[0/*]		 String Required. Name of the document standard contained in the file or message. The standard value for this field is EPCglobal. *8
        sbdh:TypeVersion [1…1]
[0/*]		 String Required. Reflects the version of the document included. This is the complete version of the document itself and is different from the HeaderVersion as these are hard-coded values. The TypeVersion is set to 1.0. *9
        sbdh:InstanceIdentifier [1…1]
[1/*]		 String Required. Reference information that uniquely identifies this instance of the Standard Business Document between the Sender and the Receiver. This identifier confirms this document as being distinct from others. *10
        sbdh:Type [1…1]
[0/*]		 String Required. Document type. Value is set to Events for an aggregation event. *11
        sbdh:CreationDateAndTime [1…1]
[0/*]		 DateTime Required. The date and time of the SBDH document's creation. GMT create date and time for the EPCIS message. The system expects the Z to be appended; however, if it is not included, the system assumes that the time is GMT and therefore appends the Z. *12
  EPCISBody [1…1]
[–]		 - Required. Contains all of the EPCIS events for the aggregation message.
    EventList [1…1]
[–]		 - Required. The EventList must contain one or more AggregationEvent data elements for an aggregation message.
      AggregationEvent [0…*]
[–]		 - The AggregationEvent is used in the EventList and indicates an aggregation event when:
  • action = ADD
  • bizStep = urn:epcglobal:cbv:bizstep:packing
  • disposition = urn:epcglobal:cbv:disp:in_progress
        eventTime [1…1]
[1/*]		 DateTime Required. The time stamp of date/time when the event occurred. Must include a time zone indicator as specified in Section 9.5 of [EPCIS1.0.1]. The system expects the Z to be appended; however if it is not included, the system assumes that the time is GMT and therefore appends the Z. *13
        eventTimeZoneOffset [1…1]
[1/*]		 String Required. The time zone offset in the place where the event occurred, consistent with what choice was made for eventTime. A time offset is an amount of time subtracted from or added to UTC (Coordinated Universal Time) to get the current civil time - whether it is standard time or daylight saving time, per Section 7.2.8 of [EPCIS1.0.1]. *14
        parentID [0…1]
[0/*]		 AnyURI Identifier of the parent container in EPC Pure Identity URI format (e.g. for an item-to-case aggregation, the EPC is of the case; for a case-to-pallet aggregation, the EPC is of the pallet). See EPC Pure Identifier Format Examples. *15
        childEPCs [1…1]
[–]		 - Required. Contains a list of identifiers, including the child items, in the parent container in EPC Pure Identity URI format (e.g. for an item-to-case aggregation, the EPCs are of the items; for a case-to-pallet aggregation, the EPCs is of the cases).
          epc [1…*]
[1/*]		 String Required. Identifier of the child items in the parent container in EPC Pure Identity URI format. See EPC Pure Identifier Format Examples. *16
        action [1…1]
[0/*]		 String Required. The action taken in the message. The action value must equal ADD for an aggregation event. *17

See the ActionType enumeration list for valid values.
        bizStep [1…1]
[0/*]		 String Required. The business step taken in the event. The bizStep value must equal urn:epcglobal:cbv:bizstep:packing for an aggregation event. *18
        disposition [1…1]
[0/*]		 String Required. The status of the message. It is grouped with the bizStep and action fields to define the message event. The disposition value must equal urn:epcglobal:cbv:disp:in_progress for an aggregation event. *19
        readPoint [0…1]
[–]		 - Location where the event occurred, i.e. the warehouse SGLN location ID and storage location (shelf, bin, etc.) in URN format, that recorded the aggregation event.
          id [1…1]
[0/*]		 AnyURI The SGLN EPC of the location from where the event occurred. This may be a site-level SGLN, or a finer-grain location identifier. *20
        bizLocation [1…1]
[–]		 - Required. Location of item after the event has occurred.
          id [1…1]
[1/*]		 AnyURI Required. The SGLN EPC of the location from where the event occurred. This may be a site-level SGLN or a finer-grain location identifier. *21
        extension [0…1]
[–]		 - Not used - GS1 Reserved.
        tl:locationId [0…1]
[0/*]		 String Location to associate the aggregation. *22
          @type [0…1]
[0/*]		 String Required. Attribute that identifies the location types. *23

See the LocationIdType enumeration list for valid values.
        tl:aggregationEventExtensions [0…1]
[–]		 - Contains the extensions used for the aggregation event.
          tl:packedStatus [0…1]
[0/*]
 String Packed status of the item or container using the supported enumeration values. *24

See the PackedStatus enumeration list for valid values.
          tl:quantity [0…*]
[–]		 Integer The quantity of child serial numbers aggregated to the parent container in this aggregation event. *25
          tl:resetContainerAggregation [0…1]
[–]		 Boolean Triggers backend processing on aggregation that will disaggregate existing child items from parent container that are not present in the new childEPC list, and aggregate new child items that are present in the new childEPC list.

Default value is false.

If this field is not populated, TL will not trigger the backend reset of the aggregation. The logic will only be triggered if resetContainerAggregation is set to true. *26
          tl:extensionField [0…*]
[–]		 - Customer extension point to pass in 1 or more name/value pairs containing additional data attributes not already supported in this message.

If this element group is populated, both the FieldName and FieldValue elements must be populated.

These extensions are not stored by TraceLink and are used only for outbound mapping purposes when there is a requirement to provide additional data to a trade partner for this message, such as when a CMO is required to provide additional data fields to the brand owner. Different trade partners may have different field requirements and may therefore require that the ExtensionField be populated differently per trade partner.
            tl:fieldName [1…1]
[1/*]		 String Required. Field name provided by the trade partner that will be receiving the mapped outbound message. The field name must match the field name provided by the trade partner exactly, including case, so that it can be properly detected in the outbound mapping. *27
            tl:fieldValue [1…1]
[1/*]		 String Required. Field value content that corresponds to the FieldName. *28