Guidelines Table

A Guidelines Table contains message requirements for both the message request and response:

Data Element Occurs Format Length Enums Req Description
soapenv:Envelope 1...1 - - - M Soap envelope.
  soapenv:Header 0...1 - - - O Not used by TraceLink, therefore the element can be null or omitted.
  soapenv:Body 1...1 - - - M Soap message body.
    urn:serialNumbersRequest 1...1 - - - M The serialNumbersRequest message payload.
      SendingSystem 0...1 String 1/* - M Identifier for site manager system requesting serial numbers. This value must match the configured value for the requesting system in the Serial Number Exchange configuration. This value will be repeated in the response message as the ReceivingSystem. 1
      ReceivingSystem 0...1 String 1/* - M Identifier for target service that will respond to serial number requests. This value must match the configured value for the app in the Serial Number Manager configuration. This value will be repeated in the response message as the SendingSystem. 2
      IdType 0...1 String 1/* IdType O Specifies the type of serial numbers requested. 3
      EncodingType 0...1 String 1/* EncodingType M Specifies the encoding format for the type of serial numbers requested. SGTIN is used for both GTIN-14 and NTIN numbers. 4

The following columns are included in the Guidelines Table:

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

Hovering over a linked footnote in the Data Element column displays sample data for that element. When using the printed version of the document, simply refer to the matching footnote at the bottom of the screen.

This column indicates the minimum and maximum amount of times that the particular element can occur within the API call (note that repeating elements are indicated in the "Description" column). In the example above, the urn:serialNumbersRequest element must occur a minimum of once and can only occur up to once for the maximum occurrence as indicated by the "1...1". If "*" is indicated, the element has an unbounded maximum occurrence.

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

This column indicates the length of the element. For the SendingSystem example element above, the value must have at least one character, but does not have a maximum restriction (therefore can be any length). However, be mindful of the description column, as further criteria may be indicated that impacts the field length (such as serial number formatting).

Certain elements are restricted to a list of specified enumeration values. A link to the enumerations and their definitions is provided in this column. For example, EncodingType links to the available enumerators.

Each table indicates if the field is required for the message. Use the key below to interpret the information in this column:

  • C = Conditionally: A "C" indicates that this element is contingent on other factors. For example, an element could be required for the US but not for any other country. Therefore the element's requirement is contingent on location. Another conditional scenario is that an element may be mandatory, but only if another related parent element is populated.

    • If indicated as "C", read the "Description" column as conditional values may still be mandatory in certain cases.

  • M = Mandatory: An "M" indicates the element must be included in the message.
  • O = Optional: An "O" indicates that an element may be included in the message but is not required.

Any important notes regarding this section of the API call are included here (required countries, formatting notes, etc.) along with a brief description of the element/attribute.

Export a Guidelines Table to Excel

  1. Navigate to a message in the appropriate API Guide and open the Guidelines table.
  2. Click the Download icon ().

    The file downloads locally.

In the Excel output of the API Guidelines:

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

  • The footnote data input sample is located in the data element description. Format is *[footnote number] †[footnote content]. The two footnote character symbols do not change the value of the data and are present to visually separate the footnote number from the footnote content.