Inbound Integration
Sending data to Oracle Transportation and Global Trade Management is supported using one of the following methods:
- HTTP POST
- REST JSON (See REST API section)
- SOAP Web Services.
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.
- 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.
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.
In this example, the Public IP Address for Inbound Integration is 199.999.99.99.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
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"?>
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.