Table of contents
Asynchronous messages allow Owners and Partners to send large amounts of data back and forth, using different file formats (e.g. EPCIS v1.2, XML). When a company sends an inbound message to TraceLink, TraceLink processes that message from the format provided in the inbound file to the TraceLink standard format. At that point, the data is stored in TraceLink (e.g. in a serial number repository), and then TraceLink processes the data into the outbound file format requested by the receiver of the message. The message is then routed to the company that receives the message.
The file size limit for inbound asynchronous messages sent to TraceLink is 300MB.
Message Type and Info Exchange display name
The relevant message type (e.g. SOM_DESTROY_EVENT) and Info Exchange display name (e.g. Destroy Event) are included within each Guidelines drop-down. Use the message type when setting up B2B connections and the Info Exchange display name in Track & Trace Services Info Exchange to monitor and troubleshoot messages exchanged with Partners. See the Info Exchange Online Help for more information.
The location of the message type depends on the type of B2B connection:
- AS2 – The message type is in the AS2 header (e.g. SOM_DESTROY_EVENT).
- HTTP Post – The message type is part of the URL (e.g. https://prodb2b.tracelink.com:5443/server?request=send&directory=inbox/SOM_DESTROY_EVENT&filename=
). - SFTP – The message type is the folder in which the message is saved.
In Info Exchange Profiles, the message type is included in the transaction element header of the CSV file.
Error messages
Errors with asynchronous messages usually indicate issues with message file validation, data configuration, duplicate files, adapter issues, authorization failures, or database look-up failures (i.e. look-ups for missing product master data attributes triggered by a look-up code in the file). These errors display in the Track & Trace Services Info Exchange Web UI. See the Info Exchange Online Help for more information.
Example error When interpreting errors:
- The Scope identifies whether the error is in the input or output.
- The Description defines the error message and provides some context about why the error occurred. The Detail fields can also help troubleshoot errors in submitted data.
- Depending on the type of error, the InputAddress, OutputAddress, InterfacePath, and Value information identifies the full path to the field and the instance of that field that triggered the error.
The following Map In error is an example of what an error with the input and the output might look like in Info Exchange:
MapInput:
ERRORS
ID: Input_Presentation_Mismatch
Severity: Error
Category: Input_Data_Error
Description: Cannot parse input data according to the presentation.
Scope: InputDetail[Input Path]: SNXDispositionAssignedMessage | MessageBody | choice_1[0] | CommissionEvent | CommissionEventDetail[0] | EventDateTime
Detail[Input Data]: 2015-04621T08:18:00.140Z
Detail[Type]: DateTime - General Characters & XML Schema
Detail[Presentation]: YYYY-MM-DDThh:mm:ss[.sss][-hh:mm] - 2003-06-15T13:20:00.000-05:00Detail[Error Name]: Presentation_Mismatch
InputAddressInterfacePath: SNXDispositionAssignedMessage | MessageBody | choice_1[0] | CommissionEvent | CommissionEventDetail[0] | EventDateTime
XPath:
ParentElement: false
Value: /SNXDispositionAssignedMessage/MessageBody[1]/snx:CommissionEvent[1]/snx:CommissionEventDetail[1]/cmn:EventDateTime[1]/EventDateTime
OutputAddress
XPath:
ParentElement: false
Value: /can:CanonicalSNXDispositionAssignedEventType/can:MessageBody[1]/can:CommissionEvent[1]/can:CommissionEventDetail[1]/cmn:EventDateTime[1]
ID: Empty_Tag_Creation_For_Output_Field
Severity: Error
Category: Output_Data_Error
Description: An empty tag was created for a target field, but an empty tag is not valid data for the field.
Scope: Output
Detail[Output Path]: CanonicalSNXDispositionAssignedEventType | MessageBody | choice_1[*] | CommissionEvent | CommissionEventDetail[*] | EventDateTime
Detail[Minimum Target Iteration Count]: 1
Detail[Actual Iteration Count]: 0
OutputAddress
InterfacePath: 1
XPath:
ParentElement: false
Value: /can:CanonicalSNXDispositionAssignedEventType/can:MessageBody[1]/can:CommissionEvent[1]/can:CommissionEventDetail[1]/cmn:EventDateTime[1]
Error types Map In Failed (Class 1)
This error happens during the first step in the validation process as a file is received by TraceLink. This error is most often caused when required data is either missing or incorrect. This failure indicates that the file was poorly structured (e.g. data elements are in an incorrect order) or contained other errors that prevented TraceLink from integrating and processing the file. These instances trigger schema validation errors and indicate that an inbound message has failed data translation. Map In Failed and Map Out Failed can also point to system errors in the map itself.
An inbound message is designed to convert a sender party’s data format to TraceLink's format (i.e. the sender party sends data to TraceLink for data transformation, and TraceLink is the recipient of the data).
Processing Failed (Class 2)
This error happens during the second step in the validation process, where most of the business logic is found. This error indicates a failure at any point in a transformation document life cycle (e.g. transmission failure or backend code failure).
Map Out Failed
This error happens when TraceLink maps the outbound data, which converts it into the receiving party's preferred format. Sometimes the rules can vary based on the file format. This error indicates an outbound message has failed at some point in this data conversion process. Map In Failed and Map Out Failed can also point to system errors in the map itself.
Blocked
A blocked error indicates a system blockage or processing failure.
Needs Investigation
This error indicates a processing error or message data translation failure. This error type requires investigation to determine the root of the failure. Often, this error occurs when the file appears to be a duplicate. These messages can be processed again manually through the Track & Trace Services Info Exchange Web UI if investigation discovers that the message should not have returned an error. See the Info Exchange Online Help for more information.
How to use this guide
Read the guidelines table A guidelines table contains element requirements for a message.
- Element – The source or element name included in the API.
- Occurs | Length – Occurs indicates the minimum and maximum amount of times that the particular element can occur within the message. Length indicates the length of the value for the given element. An asterisk (*) indicates that an unlimited number of the element can occur or there is no limit on the length of the value. Additional information about the number of occurrences and the length can also be included in the Description column.
- Type – This column indicates the element's data format type (e.g. String, Integer, Boolean, Date, or Time).
- Description – This column indicates whether the element is required for the message and provides a brief description of the element, including any relevant notes (e.g. country requirements, formatting notes, etc.).
| Element | Occurs Length | Type | Description | |||
|---|---|---|---|---|---|---|
| epcis:EPCISDocument | 1…1 - | - | Required. The EPCIS message root element. | |||
| @schemaVersion | 1…1 0/* | Decimal | Required. The version of the EPCIS schema used to populate the EPCIS document elements. Valid value is 1.2. | |||
| @creationDate | 1…1 1/* | DateTime | Required. The date and time of the Standard Business Document's creation (i.e. the GMT create date and time for the EPCIS message). The system expects the Z to be appended; however, if the Z is not included, the system assumes that the time is GMT and therefore appends the Z (e.g. 2021-12-18T22:08:02Z). | |||
| EPCISHeader | 0…1 - | - | Required. The XML file control header. This message supports the following use cases:
| |||
| sbdh:StandardBusinessDocumentHeader | 1…1 - | - | Required. The business header information, including the EPCIS header version, sender and receiver information, and the document identification. | |||
| sbdh:HeaderVersion | 1…1 0/* | String | Required. The version of the Standard Business Document Header (SBDH). Valid value is 1.0. | |||
Read the errors table Class 1
Class 1 errors are Map In errors.
Class 2
Class 2 errors are data translation Processing Failed errors.
Class 3 Errors
Class 3 errors occur when data translation to a third party (i.e. the Partner receiving the message) fails due to an internal server error. Class 3 errors are rare, though they can also occur due to missing or incorrect information in master data. If a message returns a class 3 error, check master data first, add missing information or edit incorrect data, and resubmit the message. If the class 3 error continues to occur when master data is definitely correct, contact TraceLink Support.