External System

This page is accessed via Business Process Automation > Communication Management > External Systems.

An external system is any remote system where you can store and/or use Oracle Transportation Management data. For example, you may want to send a copy of all orders to a remote directory where they can be viewed by others in your organization.

Use the External System Manager to define the outside source where you want to forward records. The records are transmitted as XML documents starting with a <Transmission> tag, containing a header and a body. Most transmissions are sent out via HTTP POST, and an HTTP message is posted to the external system containing the transmission XML. However, you can also send out transmissions via email message. (To allow the external system to accept outbound transmissions via email, make sure the " forwardingProtocol" section of the external system URL is properly configured for email instead of HTTP.)

Note: To be notified if an HTTP POST fails, enter yourself as contact for the contact notification for each domain that sends transmissions.

Note: The base structure of a transmission message is independent of the communication protocol.

To export data, identify the external system, and then execute the action entitled Send Interface Transmission on the Results page containing the data you want to send. Alternatively, you can schedule transmissions from the Process Manager.

For example, in the Process Manager you can schedule the transmission of shipment data based on the current status (or other criteria) of your shipments. It is common to receive thousands of orders, plan the orders on shipments, execute the shipments, tender the shipments, and then transmit the shipments to a downstream warehouse management system either on a regularly scheduled basis, automatically or on-demand, so that the necessary pick, pack, and ship activities can be executed. Using Send Integration, you can specify SHIPMENT as the integration interface; define a saved query to search the qualified data; specify the receiving external system by assigning URL and optional credentials to integrate with the receiving system; schedule when the interfaces should be transmitted, and how the transmission should be interpreted.

Test Your External System

If you want to test your new external system, most managers contain a Send Interface Transmission action. You can also send transmissions in the Process Manager. See each integration interface for a description of how that interface can be sent.

Errors

If your external system does not receive your transmission, verify that your external system is running and then search for your transmission in the transmission manager.

Health Check

You can run the External System Health Check and get notified if there are errors with your external systems.

External System

Before you can send data to an external system, you must define where to send the data.

1. The External System ID uniquely identifies your system.
2. Description contains a brief summary of the external system.
3. Enter an Integration Preference ID. Outbound XML sent to this external system will have UOM data as per the settings in this integration preference.
4. Use Credential indicates that the user name in the outbound integration should be the Oracle Transportation Management requesting user ID. So if you are logged in as GUEST.ADMIN and you initiate an outbound integration through the Send Integration action, the username for the transmission authentication would be specified as GUEST.ADMIN. For security reasons, the password is not specified from the user requesting the action.
5. Enter User Name and Password if your external system requires authentication or is behind a firewall that requires authentication. User name and password are sent in the HTTP header.
6. All transmissions before 6.4.2 either did not use a namespace, or if present, contained one or both of the following URLs: "http://xmlns.oracle.com/apps/otm" or "http://xmlns.oracle.com/apps/gtm". In 6.4.2 this URL has changed to identify the new version and is "http://xmlns.oracle.com/apps/otm/transmission/v6.4" or "http://xmlns.oracle.com/apps/gtm/transmission/v6.4," respectively. Use the Target Namespace field to choose the XML format for outbound transmissions. The options are:
   • Current: All XML messages will use the 6.4.2 namespace URL version.
   • Versions prior to 6.4.2: Uses the namespace URLs for previous versions.
   • None: Use the 6.4.2 Transmission XML with the namespace URLs stripped from the result.
   • None (Compatibility Mode): Use the pre-6.4.2 Transmission XML version with namespace URLs stripped.
7. Enter a Content Type to select the media type (format) of the outbound data. For example, "text/xml" or "application/xml" are used to produce XML format messages, and "application/json" should be used for JSON messages. Enter the value which corresponds with the integration service you have selected.
8. Select a Domain Name.
9. Select an Active Mode from the drop-down list. You can use the active mode to enable/disable sending to the external system. You can choose from the following options:
   • Enabled: your system will generate and send XML.
   • Build XML, Disable Send: The XML is generated and stored but is not sent.
   • Disabled, Log Entry: Logs an entry in the i_transmission and i_transaction tables without generating XML.
   • Disabled: The system will not log entries, generate XML or send any information to the external system.
10. Select the Enable Debug check box to enable debugging for the external system. The log messages are stored in the i_log table and are available as part of the transmission report.
11. Select the Log Response check box if you want to log the responses.
12. Select the Reattempt Mode from the drop-down list. The reattempt mode defines the system reattempts to send to the external system. You can choose from the following options:
    • None - ERROR Status: No reattempts are made. The status of the transmission is set to ERROR when an error occurs.
    • Use Redo Processing: The status of the transmission is set to REDO when an error occurs and the REDO transmission processing will manage a resend.
    • Use Time Delay: The Reattempts Delay field indicates how long to wait before again attempting to resend information.
13. Specify the maximum number of attempts to send the transmission to the external system in the Max Reattempts field.
14. If the Transport Through Data Stream check box is selected (default), the XML is loaded before sending out and transporting through data stream.
15. In the Reattempts Delay field, enter the amount of time to wait before another attempt to send is made. This field is used if the Reattempt Mode is set to Use Time Delay.
16. In the Reattempt Deadline field, enter the maximum time from when the transmission is created that an attempt is made to send the transmission. This field is used if the Reattempt Mode is set to Use Time Delay.
17. Max Bytes Per Trans and Max Transaction Per Trans: The external system may only allow transmissions of a certain maximum size. Consult the documentation provided with the external system to determine any limits on transmission size.
18. The Socket Timeout is the timeout for the network/socket connection for communication. You can set the property "glog.socket.timeout" to define how long the system will wait for a response when pinging a server. The default is 5 seconds.
19. The Authentication Type describes the authentication and authorization protocol to be used for HTTP/HTTPS communication. Your choice here directly affect the sections and fields that are available on the page in the For HTTP/HTTPS section. Options are HTTP Authentication (Basic), Pre-Authenticated Request, and OAuth 2.0 - Client Credentials. If no value is selected but there are values for Username and Password, then this is equivalent to HTTP Authentication (Basic).

For HTTP/HTTPS

HTTP Authentication (Basic) is defined by RFC2617 and relates to the "Authorization: Basic <encoded credentials>" HTTP header. Depending the Authentication Type selected, the information entered in this section varies.

HTTP Authentication (Basic)

When you select HTTP Authentication (Basic) as the authentication type, use the following fields.

1. URL: Specify URLs with both HTTP or HTTPS in this field. Depending on how you want to send your data, enter one of the following:
   • HTTP POST: URL of the system you want to send the data to.
   • Username
   • Password
2. Select the Read Response Code check box if you want the HTTP response code to be validated.

   Note: On some JVMs, data may not be sent unless this check box is selected.

3. Select the Trans Acknowledgement Expected check box if you expect the transaction acknowledgement to be received when sending via synchronous protocol.
4. The Use Acknowledgement Status check box specifies if the transmission acknowledgement status should be used as the status of the transmission.
5. Select the Close HTTP Connection check box to close the HTTP connection after interacting with the external system.
6. Enter an HTTP Profile ID to define a connection to an EBS instance.
7. Enter an Acknowledgement Stylesheet Profile ID.
8. Enter an HTTP Header Profile ID. The Header Profile is used to define additional HTTP header parameters to be sent on outbound HTTP messages. Only supported by the REST communication method.
9. Select an HTTP Method. This is used to declare the HTTP method specified in the outbound message. Only supported by the REST communication method. Defaults to POST.
10. If the method selected in the HTTP Method field is PATCH and you select the Use HTTP Post Override check box, then the actual HTTP method sent in the message is POST and the X-HTTP-Method-Override HTTP header is sent with the value PATCH. Only supported by the REST communication method.

11. Select the Allow Follow Redirect check box to let the External System follow redirect responses.

Pre-Authenticated URL

When you select the Pre-Authenticated Request authentication type, the Pre-Authenticated URL field is visible.

Enter the Pre-Authenticated URL. This URL is only visible when you initially create the external system. If you edit the external system, you only see asterisks and cannot change the URL.

Pre-authenticated URL provides a way to let users access an object without having their own credentials, as long as the request creator has permissions to access those objects. Only use this option if you receive the pre authenticated URL from the source whose data you need to access. For example, Logistics Machine Learning uses a pre authenticated URL to allow customers to save objects to an OCI object store.

OAuth 2.0 - Client Credentials

The OAuth 2.0 - Client Credentials flow is a two step protocol used to support token based access to resources on a resource server. The first step authenticates with an authorization service to obtain a token and the second step sends this token to the resource server to access resources. Typically, a one time administrative step will have been performed to configure access for one application to another. The details required and the properties used for subsequent access depend on the physical implementation of the authorization service but will typically include, but not be limited to, some kind of unique client ID and secret.

When you select OAuth 2.0 - Client Credentials as the authentication type, the following fields are available:

1. Select an Authorization Service Authentication Type. The option you choose determines what fields are available in this section. Different authorization servers can use different authentication methods. This is the method used to request authorization from authorization service on behalf of the client.
   1. If you select the HERE OAuth 1.0 Signature option, the following fields are available:
      • Consumer Key: This is the key required by authentication service authentication type. This is provided by HERE.
      • The Consumer Secret: This is the secret required by authentication service authentication type. This is provided by HERE.
      • The Signature Hashing Algorithm: This is the algorithm used to sign the message if required by the authentication type.

      Note: See Integrating with HERE Engine for details on how to configure this section for HERE.

   2.  If you select the Microsoft Graph API option, the Client ID and Client Secret fields are available. These are the client ID and secret that are generated when you integrate with Microsoft REST API to avail SharePoint Online as a content management system option in OTM. For details, see Setup for Using SharePoint with OTM.
   3. If you select the Client Credentials in Message option, the Client ID and Client Secret fields are available. These are the client ID and secrets that are generated when you integrate with FedEx rate and transit API to calculate rates and transit days of a shipment. For details, see How to Set Up FedEx Rating Engine.
2. Enter the Authorization Service URL to call the authorization service. This is the endpoint on the authorization server which is called to authenticate and authorize the access and obtain a token. It must be obtained from the specified REST API documentation for the external resources. HERE has a specific value to use. Microsoft provides a specific value. FedEx has a specific value to use.
3. Enter the Application Scope. This is an optional, space-delimited string defined by the authorization service and must also be obtained when configuring access to the resources. Typically this would be performed using the administration interface for the external authorization service. Microsoft provides a specific value.
4. Enter the URL. This is the HTTP URL for accessing the actual external application resource. The token obtained from the Authorization Service will be sent to this URL as a Bearer token. See the HERE configuration to determine the value to use. Microsoft provides a specific value. FedEx has a specific value to use.
5. Select the Trans Acknowledgement Expected check box if you expect the transaction acknowledgement to be received when sending via synchronous protocol.
6. The Use Acknowledgement Status check box specifies if the transmission acknowledgement status should be used as the status of the transmission.
7. Enter an Acknowledgement Stylesheet Profile ID. 

For FTP

1. The Hostname of the FTP server you want to send to.
2. Enter a Port. When sending out FTP/FTPS messages, they are sent using the supplied port. If the port is left blank, it is based on the default port for the protocol.
3. Remote Directory refers only to FTP. Enter the directory you want to access on the remote FTP server. Make sure the remote directory exists on the remote FTP server, otherwise the transmission fails.
   
   The Remote Directory can be either an absolute path which the remote FTP server finds from its root directory or a relative path which the FTP server finds relative to the home directory of the FTP user. It is often better to use a relative path since the FTP user may not have access to the root.
4. Select whether the Connection Mode should be active or passive. If it is set to Active, then the system opens an active FTP connection to the external system.
5. Select the Use FTP Append check box if you want the FTP protocol to use the append file mode to send the data to the FTP server in batches, or should use the "put" mode where the whole transmission is sent at once.
6. Select the Use Secure FTP check box if you want your FTP transactions to be secure. PROT P encryption for SSL file transfers is not supported. The FTP server cannot enforce PROT P.

Web Service

1. Select the Trans Acknowledgement Expected check box if you expect the transaction acknowledgement to be received when sending via synchronous protocol.
2. The Use Acknowledgement Status check box specifies if the transmission acknowledgement status should be used as the status of the transmission.
3. If you want to communicate application to application, enter a web service.
4. Select a service operation from the drop-down list. Service operations are defined in the WSDL for the web service.
5. If the service endpoint is not identified in the WSDL, enter it in the Service Endpoint field. The service endpoint is the machine and the URL. For example, http://c< hostname_of_OTM_server>:7001/GC3Service/ WMService/call.

External System Translations

Use the Integration Translations section, if you want Oracle Transportation Management to transform outbound XML transmissions with XSL. XSL enables you to change from one XML format to another. You can also change from an XML format to a flat file.

1. Sequence Number: If you need to apply multiple transformations to a transmission, Oracle Transportation Management applies the stylesheets in the order you specify here.
2. XML Element ID determines which GLogXMLElement the XSL stylesheet applies to.

   Note: Use the Upload an XML/CSV Transmission page in Integration Manager to upload the XSL files you need for integration translations.

3. Enter a Stylesheet Profile ID. The stylesheet content present on the stylesheet profile is used for formatting of the outbound XML message.
4. Stylesheet Name is the name of the specific XSL stylesheet that transforms the transmissions.
5. Select the Add XML Declaration check box if an xml declaration should be added to the final output XML element. This field is used when staging outbound integration and applying XSL to what is staged. When staging, transactions are stored one at a time and the XSL is applied when storing the transaction. When staging, the individual transactions are later concatenated to produce the full XML.
6. The Root Element Name field indicates what the root element of the XML document should be. This field is also used when staging outbound integration.
7. Click Save for each sequence you define.

Out XML Profiles

By assigning an Out XML Profile ID to a specific XML Element, you can exclude specific portions XML from your outbound messages.

1. In the Out XML Profile ID field, select the profile that contains the exclusions to apply to the Element you just selected.
2. In the XML Element field, select the XML element that you want the exclusion to apply to.
3. Enter a Priority for the Out XML Profile to give processing precedence to certain transaction type. For example, you may want to send all Releases before sending PlannedShipments.
4. Click Save. Repeat if there are multiple exclusions you want to apply to this external system.