Intro to asynchronous messages

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=<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 Transactional Maps 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.

When interpreting errors:

  1. The Scope identifies whether the error is in the input or output.
  2. 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.
  3. 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]

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

A guidelines table contains element requirements for a message:

Element Type Description
Header

Required. The response header.
headerVersion Integer Required.(missing or bad snippet)
eventName String Required.(missing or bad snippet)
ownerId String Required. The identifier for the Owner company associated with the request.
isErr String

Required. Indicates whether the request was successful. Valid values:

  • true – The call was successful.
  • false – The call was not successful. The errCode and errMsg fields provide error information for troubleshooting.
errCode String

Required. The status code of the response.

errMsg String Conditionally required if the call is unsuccessful. The message associated with the error code (e.g. "Process Type is required.").
licensePlate String Required. The unique identifier for the message instance.
exceptionName String (missing or bad snippet)
Payload –

Required.(missing or bad snippet)
commentId String Conditionally required if the call is successful. The identifier for the added comment.

This column indicates the source/element name included in the API call.

This column indicates the element's data format type (e.g. String, Integer, Boolean, Date, or Time).

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.).

Hover over a footnote to display the data input sample for that Data Element. If using the printed version of the document, refer to the matching footnote at the bottom of the 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.

  1. Navigate to the guidelines table for the message you want to export.
  2. Select the Download icon.
  3. The file downloads locally.

In the Excel output of the API Guidelines:

  • When you open the file in Excel, the following dialog box might display: "The file format and extension of [file name] don't match. The file could be corrupted or unsafe. Unless you trust its source, don't open it. Do you want to open it anyway?" This message is expected. Select Yes to open the file.
  • The Occurs and Length values will be enclosed by square brackets (i.e. [1...1] or [1/20]). These brackets do not change the value of the data and are present to prevent Excel from interpreting the Occurs and Length values as dates or fractions.

API examples can be easily copied and pasted into a text editor by selecting Copy.

  1. Create a blank text file and save it locally.
  2. Navigate to the API example that you want to copy.
  3. Select Copy.
  4. Navigate to the first row of the saved text file, right-click, and select Paste.

    The API example's structure is maintained.

    Syntax highlights will not reflect unless enabled in the file editor.

    There is a known issue in the documentation where the example might have extra spaces or quotation marks added if copied through a Chromium-based browser (e.g. Google Chrome, Microsoft Edge). This issue will be fixed in a future revision. For now, if this problem results in a validation error, either:

    • Manually copy the example by highlighting the full text, right-clicking, and selecting Copy.

      or

    • Use a non-Chromium-based browser (e.g. Mozilla Firefox, Apple Safari) to copy the example.