Inbound Integration

HTTPPOST

HTTPPOST integration is achieved by posting XML documents to the following URL: https://otmgtm-[identity_domain].otmgtm.[data_center].ocs.oraclecloud.com

The [identity_domain] value should be replaced with the values that were specified during provisioning. For example: See the Input Provided During Provisioning and Resulting URLs sections.

Refer to the Integration Guide for a description on the supported servlet endpoints and their corresponding use cases.

Input Provided During Provisioning

Identity Domain: companyname
Data Center: us-phoenix-1

Resulting URLs

Production: https://otmgtm-companyname.otmgtm.us-phoenix-1.ocs.oraclecloud.com
Test: https://otmgtm-test-companyname.otmgtm.us-phoenix-1.ocs.oraclecloud.com

If a specific port number is required by the upstream posting system, the port that should be used is 443. For proper security, the downstream system should require a username/password for user authentication. When the username and password fields are specified on an External System, they are automatically added to the Transmission Header in the generated XML document.

SOAP Web Services

You can also send data to Oracle Transportation and Global Trade Management via a SOAP web service call.

The web service call can be generated using the WSDL URL. The following URL is for the TransmissionService:

https://otmgtm-[identity_domain].otmgtm.[data_center].ocs.oraclecloud.com/GC3Services/TransmissionService/call?wsdl

The [identity_domain] value should be replaced with the values that were specified during provisioning.

Input Provided During Provisioning

Identity Domain: companyname
Data Center Name: us-phoenix-1

Resulting URLs:

Production: https://otmgtm-companyname.otmgtm.us-phoenix-1.ocs.oraclecloud.com/GC3Services/TransmissionService/call?wsdl
Test: https://otmgtm-test-companyname.otmgtm.us-phoenix-1.ocs.oraclecloud.com/GC3Services/TransmissionService/call?wsdl

Alternatively, the WSDL file and corresponding XSD schema files can be retrieved via Process Automation > Integration > Integration Manager > Retrieve WSDLs. The WSDL should be saved to a file and subsequently imported into the source system.

Transportation and Global Trade Management enforces Web Service Security policies on all inbound and outbound Web Services. The Web Service Security Specification is an OASIS standard for defining security related information as part of a SOAP message. See http://www.oasis-open.org/. Transportation and Global Trade Management only supports the WS-Security User name Token Profile.

Inbound

For Inbound integration, the user name and password must be specified in the SOAP Header of the XML document. Please see the example below:

 <SOAP-ENV:Header>
 <Security xmlns="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
 <UsernameToken>
 <Username>XYZ.OTMUSER</Username>
 <Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">password</Password>
 </UsernameToken>
 </Security>
 </SOAP-ENV:Header>

Integration User Role

To send data to Oracle Transportation and Global Trade Management, it's necessary for the remote system to authenticate with valid user credentials. In addition this user must have the correct Access Control List entry points. To facilitate this, Oracle Transportation and Global Trade Management provides by default the following options for inbound integration users:

"INTEGRATION" user role for your inbound integration users. Assign this user role to your user.
"INTEGRATION" ACL for your inbound integration users. Assign this parent ACL to your customer-defined user role or your user.
"External Integration" ACL for your inbound integration users. Assign this child ACL to your customer-defined user role or your user.

Inbound Integration and SSL Certificates

All inbound integration requires that the transport be protected using HTTPS. Communications over HTTPS are encrypted using SSL. These SSL communications are initiated using SSL Certificates. The SSL Certificates must be from a trusted signing authority (no self-signed certificates). It is possible that the list of trusted signing authorities on the system doesn't contain the signing authority used for the Oracle Transportation and Global Trade Management Cloud certificates. In that case it might be necessary to download and install the Certificate in the source system.

The following instructions explain how to obtain the Root and Intermediate Certificate for an Oracle Transportation and Global Trade Management instance. Both the Root and Intermediate Certificates must be imported to prevent issues when the Certificate expires each year. You should install the root and intermediate certificate only, NOT the complete certificate chain. The instructions below assume the use of the Firefox web browser, but the steps will be similar with other browsers.

Follow these instructions to retrieve the SSL certificate:

Open the Firefox browser and sign into your instance. You must ensure you're logged in successfully to the Oracle Transportation and Global Trade Management application otherwise you'll be downloading the Identity Cloud Service certificates.
After confirming you're successfully logged into Oracle Transportation and Global Trade Management, click the padlock (lock symbol) next to the URL.
Click the arrow next to Connection Secure to show connection details, then click the More Information option at the bottom of the window.
Under the Security tab, click the View Certificate button.
There will be 3 tabs, one for the Site Certificate, the Intermediate Certificate, and Root Certificate. You must export both the Root and Intermediate certificates and import them into your keystore to recognize the OTM certificate. It isn't necessary to install the site certificate. If you install the site certificate you'll need to update this at every yearly certificate renewal.
Select the intermediate certificate "DigiCert Global CA G2" and then click the "Download PEM (CERT)" link. This should prompt you to save the file. You must remember the location where you saved the files.
Repeat the above step 6 for the root certificate "DigiCert Global Root G2".
Import both the root and intermediate certificates into the sending system keystore to recognize the OTM certificate by application using the keystore.
To confirm installation check your local copy of "keystores" on the source system making the calls to make sure that the intermediate and root certs are present.

For more details on this topic, see the following My Oracle Support Note:

OTM/GTM Gen2 OCI: How to Retrieve Security Certificates for Inbound Integration using Firefox (Doc ID 2905156.1)

Note: For Inbound Integration which uses the Oracle E-Business Suite – GTM ITM Adapter, see the following MOS Note for details on how to handle SSL Certificates: How to Retrieve and Change Security Certificates for Inbound Integration to GTM from EBS ITM (Doc ID 2455210.1). To avoid an interruption of service when the Certificate is renewed, you'll need to open a Service Request to obtain the latest SSL Certificate from Oracle a month before the current Certificate will expire.

IP Allow List for Inbound Integration

Follow these steps to obtain the Public IP Address for Inbound Integration to Oracle Transportation and Global Trade Management.

Sign in to the My Services Cloud Portal.
Click the “Transportation Management” link.
Scroll down to the “Service Environments” section.
Copy the “Service Environment URL” for each environment by right-clicking on the URL and select “Copy Link Address”.

Run nslookup using only the Host from the URL. For example.

nslookup otmgtm-test-myotminstance.otmgtm.us-ashburn-1.ocs.oraclecloud.com
Server:         10.1.1.1
Address:        10.1.1.1#53

Non-authoritative answer:
otmgtm-test-myotminstance.otmgtm.us-ashburn-1.ocs.oraclecloud.com      canonical name = 1586234534085.otmgtm.us-ashburn-1.ocs.oraclecloud.com.
Name:   1586234534085.otmgtm.us-ashburn-1.ocs.oraclecloud.com
Address: 199.999.99.99

In this example, the Public IP Address for Inbound Integration is 199.999.99.99.

Integration Data Queues

It is important to note that in the Cloud service all Inbound integration uses the Integration Data Queue feature. This feature persists all inbound Transmissions into a database table. A polling process on the application server queries the corresponding table and processes Transmissions in batches. The Cloud Service is configured by default to have 4 polling threads with a batch size of 8, that poll every 2 seconds. This allows for a maximum throughput of 57,600 Transmissions per hour. You can change these settings using the Data Queue manager, available on the menu at Business Process Automation > Integration > Data Queues. The "INTEGRATION IN" Data Queue controls the processing of Inbound Integration.

The Integration Data Queue feature prevents the application server from being overwhelmed by a peak in integration volume. Customers can increase the inbound integration throughput by adjusting this configuration. However, the risk is that unnecessarily increasing the throughput could negatively affect the performance of other parts of the system. For more details on this topic, please see the Integration Guide. It is important to note though that the configuration of the Integration Data Queue feature is limited.

XSL Stylesheets for Inbound Integration

Oracle Transportation and Global Trade Management service supports the ability to transform XML Documents during Inbound Transmission Processing. This capability is supported using the TransformerServlet. Use the following steps to load your customer-defined XSL files for Inbound Integration.

Create Stylesheet Content: Create a Stylesheet Content record and upload the corresponding XSL file. This page is located at Business Process Automation > Power Data > Event Management > Stylesheet Content.
Set the stylesheet_name attribute in your XML file to the Stylesheet Content GID: <?gc3-int-translate stylesheet_name="db:GUEST.MYSTYLESHEETCONTENTGID"?>

Note: For more detail on this topic, please refer to the "Transform Inbound XML with XSL" section in the Transportation and Global Trade Management Integration Guide.

REST API

Transportation and Global Trade Management provides multiple public REST APIs that can be used to access data stored in Transportation and Global Trade Management and construct integrations to other systems. You can make many types of HTTP requests using Oracle REST APIs. You can easily make requests to view, create, update, or delete records.

Where possible a REST API should be used in preference to the Transmission XML via SOAP or HTTP. REST supports synchronous and asynchronous messaging for almost all resources which is an expansion of the Transmission XML capabilities. However, REST does not yet support all the capabilities available using Transmission XML and these capabilities will be added over the next few updates to the REST API. In cases where the feature is not yet available the Transmission XML message must be used.

For detailed instructions on how to use REST APIs, see the REST API for Transportation and Global Trade Management guide.

OAuth Client Credentials Flow

The inbound HTTP POST and REST interfaces also support authentication and authorization using OAuth in addition to HTTP Basic Authentication. See the Integration Guide for configuration details.