Transmission Schema

Schema Files

The following schema files contain all definitions for the Transmission schema:

• Transmission.xsd: Definitions for all Primary Documents.
• TransmissionCommon.xsd: Definitions for types shared across interfaces.
• Transaction.xsd: This is a convenient schema which imports all other Transaction definition schemas.
• OTMGTM.xsd: This file can be used to include/import all schema definitions contained in all other schema files.
• GTM.xsd: Transaction interfaces for Global Trade Management Cloud application functionality.
• LocationContact.xsd: Transaction interfaces for Location and Contact business objects and other related common types used in other interfaces e.g. Involved Party.
• ShipUnit.xsd: Transaction interfaces for Ship Units common to Orders, Shipments etc.
• Item.xsd: Transaction interfaces for Item and Package related business objects.
• Document.xsd: Transaction interfaces for Document Content for Content Management Systems.
• Configuration.xsd: Low level transaction interfaces e.g. User management.
• Shipment.xsd: Transaction interfaces for Shipment related business objects including Planned, Actual and Tendered shipments.
• Order.xsd: Transaction interfaces for Purchase Orders and Order Release business objects.
• Planning.xsd: Transaction interfaces related to planning of Orders onto Shipments.
• Finance.xsd: Transaction interfaces related Invoices, Payments etc.
• Rate.xsd: Transaction interfaces related to Rating structures used for cost calculations.
• Job.xsd: Transaction interfaces for Brokerage and Forwarding.
• GenericTransaction.xsd: Miscellaneous transaction interfaces that can apply to many business object types e.g. for object status updates.

XML Namespaces

The following table lists the namespace URLs and associated physical file name for each schema:

XML Namespaces

XSD Schema File	Namespace
Transmission.xsd and all other non-Global Trade Management Cloud schemas (listed in the Transmission Schema table).	http://xmlns.oracle.com/apps/otm/transmission/v6.4
GTM.xsd	http://xmlns.oracle.com/apps/gtm/transmission/v6.4

Inbound Transmission XML documents that do not declare a namespace association are supported but they are assumed to be based on the XML schema definitions prior to version 6.4.2. Therefore, these documents may incur a runtime performance penalty due to the transformation required to convert the XML to the current namespace. If, however, the XML conforms to the current namespace definitions but does not declare a namespace, then adding a Version attribute to the root Transmission element will avoid the transformation overhead. For example:

<Transmission Version=”CURRENT”>

…

Note: The value of the Version attribute must be either CURRENT or PRE642 where the latter is the default value if no attribute is specified, i.e. the XML is assumed to require transformation.

Primary XML Documents

There are primary XML documents defined in the Transmission schema that are used inbound and outbound for both Transportation and Global Trade Management Cloud interfaces:

• Transmission: The Transmission is the primary document used for messages inbound to and outbound from the system. Each Transmission can contain multiple transactions to be processed. A unique Transmission Number is assigned to each inbound and outbound message.
• TransmissionAck: The TransmissionAck is the response message to the receipt of the Transmission. It contains the confirmation for the receipt of the Transmission with the unique assigned Transmission Number, or an error if the Transmission could not be persisted.
• TransmissionReport: The TransmissionReport summarizes the errors that were detected during the processing of the Transmission. The report is optionally sent after all the transactions in the Transmission have been completed (successfully processed or with generated errors). The requirement to receive a TransmissionReport is indicated in the inbound Transmission Header.

Transmission Processing Styles

There are different styles for processing the contents of a Transmission:

• Transactional style: where the Transactions within the Transmission are processed as messages used to create, modify or delete transactional content or to trigger processing for transactional content.
• Query style: where the Transactions within the Transmission are request/reply transactions to retrieve content or return the results of processing against transactional content.

The style used is based on a combination of the value of the Transmission Type Transmission header property and the interfaces present in the Transmission body content. If no Transmission Type value is specified the style defaults to Transactional.

It is not supported to mix Transactional style content with Query style content in the same Transmission. It is also not valid to request Query style processing for interfaces which do not support that style.

Transactional Style Interfaces

Transactional Interfaces are 'submitted' to Transportation and Global Trade Management Cloud for subsequent processing similar to asynchronous processing. (Strictly speaking the process is a synchronous transaction that accepts the message for later processing followed by the asynchronous processing of message. The synchronous part returns the reference which can be used to track the results of processing.) This allows the Transportation and Global Trade Management Cloud Application server to manage workload and ensure changes to persistent object data are handled within a transactional context.

The following diagram shows how the documents are used when processing an inbound transactional Transmission XML into Transportation and Global Trade Management Cloud.

1. Transmission XML document is sent to Transportation and Global Trade Management Cloud. The nature of the sending component depends on the transport protocol used e.g. it will be an HTTP client if sending the message via HTTP POST.
2. Transmission message is persisted for later processing generating a unique Transmission number in the process.
3. A TransmissionAck document is returned which will contain the Transmission number.
4. The background Transmission processing workflow retrieves the Transmission at some time later and processes it. For example, it creates or updates the business object using the original XML message content.
5. Optionally, a TransmissionReport is sent to confirm the status (PROCESSED or ERROR) of the Transmission message. The report message contains the Transmission number for correlation. The sending of the report is configurable i.e. 'always', 'never' or 'on error only'. The nature of the receiving component depends on transport method e.g. it can be a Servlet URL or Web Service endpoint and the transport method can be different to original inbound transport method.

Large Transmission XML Processing Style

In step 2 above, the persistence of the Transmission involves the creation of a record in the transmission table and a record in the transaction table for each Transaction in the message. This is referred to as "staging". The TransmissionAck response is only sent once all these records are committed. If the inbound Transmission contains a large number of Transactions, then the time taken to respond with a TransmissionAck may exceed the external client’s configured time out value.

There is an alternative process, referred to as "pre-staging", where the TransmissionAck is returned after the record is committed to the transmission table but before each transaction record is created. This process should not exceed any reasonable external client time out. The behaviour is property controlled and is described below.

1. The transmission XML document is sent to Transportation and Global Trade Management Cloud. The nature of the sending component depends on the transport protocol used, e.g. it will be an HTTP client if it is sending the message via HTTP POST.
2. The full transmission message is saved in the I_TRANSMISSION table with the status of "NEW" for later processing and generating a unique transmission number in the process.
3. A TransmissionAck document is returned which contains the transmission number.
4. The background transmission processing workflow retrieves the transmission for further processing by the pre-staging process. In this process, all of the transactions in the transmission XML are stored in the I_TRANSACTION table.
5. After completing the pre-staging process, the transmission now continues further processing identical to that performed after normal staging processing.
6. The background transmission processing workflow retrieves the transmission and processes it. For example, it creates or updates the business object using the original XML message content.
7. Optionally, a TransmissionReport can be sent to confirm the status (PROCESSED or ERROR) of the transmission message. The report message contains the transmission number for correlation. The conditions that trigger the sending of the report are configurable, i.e. "always," "'never," or "on error only". The nature of the receiving component depends on transport method, e.g. it can be a servlet URL or web service endpoint, and the transport method can be different from the original inbound transport method.

Transmission Status (NEW): Indicates that the transmission is in a pre-staging state. This means that the transmission is stored in the I_TRANSMISSION table and queued for further processing. In its next step, it will process all the transactions in the transmission table and store the data in the I_TRANSACTION table.

This functionality is enabled by setting the following property: glog.integration.transmission.enableInboundPreStaging=true.

Query Style Interfaces

Query style interfaces are used when synchronous processing is required for example, for a rating request.

The following diagram shows the documents used when processing an inbound query Transmission.

1. Transmission XML is sent to Transportation and Global Trade Management Cloud. The nature of the sending component depends on the transport protocol used e.g. it will be an HTTP client if sending message via HTTP POST.
2. The internal processing is called. The Transmission Type property must be present and be either "QUERY" or "SERVICE" depending on the interface to be processed.
3. The processing results are returned as either a TransmissionAck or a new Transmission document. The document used can depend on:
   1. The protocol used. For example, Web Service calls must always return the document declared in the WSDL output parameter.
   2. Customer-defined property settings (if not using a Web Service). For example, when sending multiple RIQ requests via HTTP, the following property will result in a Transmission being returned: glog.integration.remoteQuery.WrapReplyInTransmission=1

Transmission Structure

The Transmission XML document has a root element with local name Transmission. The current namespace URL is http://xmlns.oracle.com/apps/otm/transmission/v6.4.

The Transmission contains a TransmissionHeader and a TransmissionBody. The TransmissionBody contains one or more interface transactions, each wrapped in a GLogXMLElement element. Each GLogXMLElement can contain an optional TransactionHeader element but must contain an interface element which must be a type of GLogXMLTransaction element. See figure below for schema diagram representation.

The Transmission schema uses Substitution Groups to define the possible interface elements that can be contained by a GLogXMLElement. This removes the need for the Transmission schema to list all possible interface elements. This approach allows external clients to only import the necessary schemas for implemented interfaces.

Note: Some application integration tools may not fully support schema definitions which use substitution groups. The TransmissionCommon.xsd file comes with the commented out equivalent definitions and so can be edited to support such tools. Use the following process:

1. Obtain the set of XSD schema files for the relevant product version.
2. Open the TransmissionCommon.xsd file in a suitable schema editor, e.g. JDeveloper.
3. Follow the instructions in the documentation for the GLogXMLElementType definition to edit and save the file for use by the external tool.

The GLogXMLTransaction is essentially a marker element which specifies the base type – GLogXMLTransactionType - of the elements that can be used in its place i.e. substituted for it. Only elements whose type extends the GLogXMLTransactionType can be substituted for the GLogXMLTransaction element. At present there are three types which extend GLogXMLTransactionType to further qualify the interface and provide additional control for how the interface can be used. See the figure below for a schema diagram of the three types and the subsequent explanation.

• OTMTransactionIn: Interfaces which are only valid for inbound processing must extend this type
• OTMTransactionOut: Interfaces which are only valid for outbound processing must extend this type
• OTMTransactionInOut: Interfaces which are valid for both inbound and outbound processing must extend this type

For example, the TransOrder interface is valid inbound and outbound and so has the following schema definition (some information has been removed to aid clarity for this discussion):

<xsd:element name="TransOrder" type="TransOrderType" substitutionGroup="GLogXMLTransaction">
...
   <xsd:complexType name="TransOrderType">
...
      <xsd:complexContent>
         <xsd:extension base="OTMTransactionInOut">
            <xsd:sequence>
               <xsd:element name="TransOrderHeader" type="TransOrderHeaderType">
...

The TransOrder element definition declares that the element is a TransOrderType and that the element can be substituted for the GLogXMLTransaction element. The TransOrderType extends the OTMTransactionInOut type which ensures that it is a valid substitution (because it in turn extends the GLogXMLTransactionType). The OTMTransactionInOut type declares that is valid for both inbound and outbound Transmissions.

The following is an example Transmission XML document containing two transaction interfaces (TransOrder followed by ShipmentStatus).

<?xml version="1.0" encoding="UTF-8"?>
<Transmission xmlns="http://xmlns.oracle.com/apps/otm/transmission/v6.4">
    <TransmissionHeader>
        <SenderTransmissionNo>987654321</SenderTransmissionNo>
        <AckSpec>
            <ComMethodGid>
                <Gid>
                    <Xid>HTTPPOST</Xid>
                </Gid>
            </ComMethodGid>
            <ContactGid>
                <Gid>
                    <DomainName>GUEST</DomainName>
                    <Xid>MY_CONTACT_ID</Xid>
                </Gid>
            </ContactGid>
        </AckSpec>
    </TransmissionHeader>
    <TransmissionBody>
        <GLogXMLElement>
            <TransOrder>
                ...etc...
            </TransOrder>
        </GLogXMLElement>
        <GLogXMLElement>
            <ShipmentStatus>
                ...etc...
            </ShipmentStatus>
        </GLogXMLElement>
    </TransmissionBody>
</Transmission>

AckSpec

The AckSpec element controls whether or not a TransmissionReport message is sent when the transactions within a Transmission have been completely processed i.e. when they have been persisted and any dependent workflow has been completed.

Note: AckSpec is only valid for Transactional Style interfaces.

The AckOption child element specifies when to receive a TransmissionReport. If unspecified, the behavior is property controlled where the default property setting (glog.integration.TransmissionReport="on error") is equivalent to the ERROR option.

• ERROR: Send Transmission Report only when there are errors.
• YES: Send Transmission Report in all cases.
• NO: Do not send Transmission Report, even if there are errors.

The ComMethodGid element identifies the transport method to be used to send the report. The ContactGid element identifies a contact record with an associated External System containing the relevant details – user credentials, email address, servlet URL etc. – for the selected method.

Common Schema Elements and Types

The following sections describe, at a high level, a few of the most common data elements that are likely to be present in many interfaces. More detailed information is available in the Inbound Transmission Processing chapter and the Outbound Transmission Processing chapter.

Global IDs (GIDs)

GIDs are global identifiers that Transportation and Global Trade Management Cloud uses to define a primary key for various types of information (e.g., orders, shipments, locations, payment vouchers, etc.). A GID consists of the following two parts:

• Domain name: (optional). The domain name typically identifies a company or business unit and is used to separate data and secure it from other data in a shared, web-based environment. For example, if you are using Transportation and Global Trade Management Cloud in an environment where many companies may be using the same Transportation and Global Trade Management Cloud installation, the domain allows you to isolate data in Transportation and Global Trade Management Cloud for each company. Therefore, many users from different companies can work in the same Transportation and Global Trade Management Cloud installation (or web site) and use data that is private and specific to their company. If you do not include a domain name in a GID, it can be viewed across all domains in your system.
• External ID (XID): (optional). The ID that defines the item on the external system. An external system is any system other than Transportation and Global Trade Management Cloud. If no value is specified, the GID is assumed to be completely null.

It is recommended to only use uppercase characters in GIDs and XIDs in your transmissions. The Transportation and Global Trade Management Cloud user interface normally only search for uppercase text strings and therefore it may be difficult to find records with mixed case XIDs. The following characters SHOULD NOT be present in XID strings. Failure to follow these rules may result in inconsistencies when referring to the business objects concerned:

• \
• ,
• x
• .
• <
• >
• =
• /
• &
• ?
• ;
• #
• $
• '
• "
• (
• )

Note: You should also be careful not to create GIDs with trailing spaces, as these records will not be retrievable via the User Interface.

Transaction Code

Transaction Codes tell Transportation and Global Trade Management Cloud what to do with the transactions it receives from other systems. Transaction Code elements will have the type TransactionCodeType which is an enumerated type and should contain one of the following values:

• I: Insert. Use this transaction code to send new information to Transportation and Global Trade Management Cloud. Transportation and Global Trade Management Cloud creates a new record. If the record already exists, then the transaction will generate a "record already exists" error.
• II: Insert and Ignore. When used, if the record already exists, then it is not updated and the "record already exists" error message is not logged. If it does not exist, then it is inserted.
• U: Update. Transportation and Global Trade Management Cloud updates an existing record.
• UU: Transportation and Global Trade Management Cloud updates the existing record while suppressing "no data found" constraint violations.
• IU: Insert and Update. Transportation and Global Trade Management Cloud creates a new record unless it already exists, in which case Transportation and Global Trade Management Cloud updates the existing record with the new information.
• UI: Update and Insert. This works the same way as IU.
• D: Delete. Use this transaction code to delete an existing record.
• DD: Transportation and Global Trade Management Cloud deletes the existing record while suppressing "no data found" constraint violations.
• NP: No Persist. Use this transaction code to keep Transportation and Global Trade Management Cloud from persisting data to the database. For example, enter NP if you do not want to persist public locations. This is the default TransactionCode when the data is sent outbound from Transportation and Global Trade Management Cloud.
• RC: Replace Children. Use this transaction code to delete all child data corresponding to the top level parent, update the top level parent, and insert the new child data. If a child is added with the same primary key as one being replaced, then all the values in the existing record are replaced rather than deleting the record and inserting a new one. You use the ReplaceChildren element to specify what child elements Transportation and Global Trade Management Cloud should replace. The remaining elements are processed using the IU transaction code.
• RP: Replace Primary/Parent. Use this transaction code to replace the primary/parent object without replacing the child objects. This will remove all fields in the primary/parent object that are not contained in the incoming xml, and will perform an insert/update on all the child data.
• R: Replace. Use this transaction code to replace the primary/parent and child objects. This is a combination of the RC and RP transaction codes.

Replace Children

Replace Children content is for inbound use only and is defined in elements whose type is ReplaceChildrenType. It is used in conjunction with a TransactionCode value of "RC". By specifying the ManagedChild content elements, it is possible to limit which child objects are replaced by new values within the present Transmission. See the Extended Inbound Validation section for more details.

Send Reason

Send Reason information is outbound only and is defined in elements whose type is SendReasonType. The information is used to show the internal application event which resulted in the generation of the outbound Transmission, for example, a SHIPMENT CREATED event.

Integration Saved Query

Integration Saved Queries are used in inbound transmissions and are defined by elements whose type is IntSavedQueryType. It allows an interface to support a method of identifying an object to be modified when the objects primary key is not known. An Integration Saved Query essentially represents an SQL query that must already have been created in the user interface. The element content will then contain the GID of this query and any parameters required by the query as arguments.

See Using Integration Saved Queries for more details.

Flex Fields

Flex fields are so called because they provide a flexible set of table columns for Transportation and Global Trade Management Cloud implementers to configure their data model to suit their functional needs. They can be entered via the User Interface and/or via Integration.

Flex fields cover a number of data types and have been added to most of the major business objects and their corresponding interfaces and are available for both inbound and outbound messages.

The valid schema types are described in the following table.

Valid Schema Types

Schema Type	DB Data type	(Maximum) Number	Description
FlexFieldStringType	VARCHAR2(150)	20	Holds string data
FlexFieldNumberType	NUMBER()	20	Holds numbers with any precision
FlexFieldCurrencyType	OTM Currency UOM	10	Holds financial amount
FlexFieldDateType	DATE	20	Holds date/time values

Note: Not all flex field types have been added to all interfaces and not all interfaces can support the maximum number of fields. Please consult the relevant XML schema documentation to determine the support available for each business object and the associated database schema documentation to determine if underlying table supports the maximum number.

In addition to the above, the RATE_GEO and RATE_OFFERING outbound interfaces have equivalent Flex Fields available which are defined slightly differently due to the database centric nature of these (outbound only) interfaces. These interfaces use the following elements:

RATE_GEO and RATE_OFFERING Outbound interface Elements

Schema Element	DB Data type	Number	Description
ATTRIBUTE1…n	VARCHAR2(150)	20	Holds string data
ATTRIBUTE_NUMBER1…n	NUMBER()	10	Holds numbers with any precision
ATTRIBUTE_DATE1…n	DATE	10	Holds date/time values

Date & Time

The GLogDateTimeType schema type is a platform neutral representation of the date and time to the accuracy of seconds. It is a string in the format YYYYMMDDHHMMSS where:

• YYYY: The year e.g. 2012
• MM: The month e.g. 01 is January, 12 is December
• DD: The day number e.g. 01 to 31
• HHMMSS: The time in 24 hour clock e.g. 231530

An example value is "20121031083030" which represents October 31st, 2012 at 30 seconds after 8.30a.m.

Additionally, the GLogDateTimeType can hold a Time Zone ID element (TZId) and a Time Zone Offset. When date elements are inbound the Time Zone ID is used to calculate times relative to the system time. On outbound messages, the Time Zone Offset will be populated to show the offset in hours from the system Time Zone compared to the target system locale. See the Time Zone Override section for details.

Strict Schema Validation

Strict schema validation can be applied to all incoming XML messages. This is an Optional Feature – XML SCHEMA VALIDATION – which can be enabled or disabled via the Optional Features UI Manager. In version 22C, the feature will be promoted and cannot be disabled by the user.

Any validation error will be reported immediately as part of the synchronous TransmissionAck response. The details of the error – i.e. which element is thought to be in error – is reported in the EXCEPTION log.

Note: If an XML format causing an error was known to be accepted before strict validation was enabled then the most common explanations are:

• elements are in an incorrect sequence.
• an invalid element name is used (e.g. incorrect cased letters).
• Mandatory elements are either missing or are specified but empty.
• Whitespace is present and is considered "empty".

The schema for the associated interface should be reviewed to verify and correct the XML message.