Oracle Transport Agent

This chapter covers the following topics:

Oracle Transport Agent Overview

Oracle Transport Agent (OTA) is a lightweight messaging platform for transmitting documents over HTTP and Secure HTTP (HTTPS). OTA implements a messaging protocol on top of the HTTP Application protocol.

The OTA server is a Java-based servlet that uses the OTA messaging protocol to support the following requirements:

Oracle Transport Agent Protocol Stack

The OTA protocol stack is as follows:

OTA (Messaging Protocol)

HTTP (Application Protocol)

TLS (Encryption/Security Protocol - optional)

TCP/IP (Network Protocol)

The OTA protocol defines the conversation semantics used by two Web servers running the OTA Servlet. The two OTA Servlets "talk" to each other to provide guaranteed, exactly-once delivery of the message.

OTA Message Propagation Flow

In this document, the Sender refers to the "Client" that sends a document or requests connection. The Receiver refers to the "Server" that receives the document or connection request.

The following diagram displays the message propagation flow of an OTA message with TLS enabled:

OTA Message Propagation Flow (with TLS Enabled)

the picture is described in the document text

  1. The OTA client dequeues the message from the ECX_OUTBOUND queue.

  2. The OTA client verifies the maximum retry count.

  3. The OTA client constructs the HTTP message.

  4. The client initiates the HTTP handshake and request for certification with the destination server.

  5. The destination Web server sends its certification.

  6. The client receives and verifies the server's certification.

  7. If verified, the client starts the HTTP message head and body data stream.

  8. The server optionally verifies the username and password.

  9. The server verifies the transport protocol and version.

  10. The server verifies the Oracle E-Business Suite username and password.

  11. The server verifies that the message ID is not a duplicate.

  12. The server enqueues the message for consumption.

  13. The server builds the HTTP response message.

  14. The server sends the HTTP response back to the client.

  15. The client reads the response and updates the status tables. If the response indicates the message failed, the retry count is updated and the message is enqueued for retry.

Oracle Transport Agent Post Message

Two OTA servers communicate by sending and receiving a series of name/value pairs in the HTTP body of an HTTP POST/RESPONSE. Following is an example post from the sending OTA server (Note: the header authorization encryption follows the W3C standard):

HTTP Header
Http-Version: HTTP/1.1
Authorization: Digest username="myusername",
realm="testrealm@example.com",
 nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093",
 uri="/dir/index.html",
qop=auth,
nc=00000001,
cnonce="0a4f113b",
response="6629fae49393a05397450978507c4ef1",
opaque="5ccc069c403ebaf9f0171e9517f40e41"
 Content-length: 12345
Content-type: text/html
HTTP Body
TRANSPORT_PROTOCOL=OXTA
 TRANSPORT_PROTOCOL_VERSION=1.0
REQUEST_TYPE=SEND
MESSAGE_ID=A1234567890ZZ0987654321
MESSAGE_TYPE=XML
MESSAGE_STANDARD=OAG
 TRANSACTION_TYPE=PO
TRANSACTION_SUBTYPE=PROCESS
 DOCUMENT_NUMBER=12345
 PARTYID=9999
PARTY_SITE_ID=8888
 PROTOCOL_TYPE=HTTPS-OXTA
 PROTOCOL_ADDRESS=HTTPS://www.example.com/servlets/oracle.ecx.oxta. transportAgentServer
USERNAME=myusername
PASSWORD=password
 ATTRIBUTE1=
 ATTRIBUTE2=
 ATTRIBUTE3=
 ATTRIBUTE4=
 ATTRIBUTE5=
 PAYLOAD=<xml   ... ...>

The HTTP Body contains the message envelope, message payload, and the following transport parameters:

Oracle Transport Agent Response Message

The OTA server uses standard HTTP response codes to determine if the HTTP post (at the HTTP protocol level) was successful. If successful, OTA will examine the HTTP header to determine if the OTA message was successfully delivered. If the HTTP response does not equal 200, OTA assumes the post failed and will requeue the message for retry (until maximum retry has been reached).

The following is an example of an HTTP response:

HTTP Header
 HTTP/1.1 200 OK
 Server: Apache/1.2.0
 Date: Fri, 15 Jun 2002 16:20:46 GMT
 Content-Length: 567
 STATUS_CODE: 1000
 STATUS_DESCRIPTION: OK
 MESSAGE_RECEIPT_ID: A9876543210987654321
 Content-type: text/html
HTTP Body
 <HTML><BODY> <TABLE>   <TR><TD>Status Code</TD><TD>1000</TD></TR> <TR><TD>Status Description</TD><TD>Message Successfully received</TD></TR>  <TR><TD>Message Receipt ID</TD><TD>A9876543210987654321</TD> </TR> </TABLE> </BODY></HTML>

The HTTP Response body is created for information only and is not read by the sending OTA server. The sending OTA server uses the STATUS_CODE in the HTTP Response header to determine the success or failure.

If the Status Code value is 1000 (meaning success), the MESSAGE_RECEIPT_ID in the HTTP Response body contains a unique identifier generated by the receiving OTA server. This completes the cycle for the guaranteed delivery process.

If the Status Code is anything other than 1000, a failure has occurred. The STATUS_DESCRIPTION field will contain a brief description of the error. Refer to HTTP Status Codes for a list of status codes.

OTA and Attachments

For outbound documents, the OTA client uses information in the Message Map to fetch and bundle the attachment in its outbound package.

For inbound documents, OTA extracts the associated attachments from the inbound MIME message and deposits them into the FND module of the receiving instance.

Note: Oracle Transport Agent also supports MIME messages without attachments. Similarity to the message process with attachments, OTA uses the same approach to process the message, but without further processing attachments if they do not exist.

For more information about how OTA handles attachments, see Attachments and Oracle Transport Agent (OTA).

Certificate-Based Authentication Methods

OTA operates according to the security layer implemented at your site. It supports server authentication as well as mutual authentication methods.

Both the client and server certificates are issued by a Certification Authority (CA). Oracle E-Business Suite users can choose to support any CA they wish. Examples of CAs are Identris and Verisign.

Configuring XML Gateway for TLS Authentication

This section provides XML Gateway specific configurations for TLS authentication methods. The following topics are included in this section:

For information on configuring OTA client for TLS authentication using Oracle Wallet, see Configuring OTA Client for TLS Authentication Using Oracle Wallet.

Configuring TLS Authentication for Inbound Transactions

In this document, OTA server refers to Oracle E-Business Suite with Oracle Transport Agent, which receives the message; client refers to the application that sends the message. That is, server receives inbound XML transactions, whereas client sends outbound XML transactions.

Configuring OTA Server for Server Authentication

Configuring TLS in Oracle E-Business Suite ensures that server authentication is enabled for Oracle XML Gateway inbound transactions through OTA.

For information on configuration details, refer to Section 5.2 Configure Inbound Connections, as described in My Oracle Support Knowledge Document 1367293.1, Enabling TLS in Oracle E-Business Suite Release 12.2.

Configuring OTA Server for Mutual Authentication (Optional)

If you want to restrict access to OTA server to only trusted clients, then you may opt for mutual authentication. Perform the following steps to enable mutual authentication on the OTA server:

  1. Configure TLS in Oracle E-Business Suite, if this is not performed.

    For information on configuration details, refer to Section 5.2 Configure Inbound Connections, as described in My Oracle Support Knowledge Document 1367293.1, Enabling TLS in Oracle E-Business Suite Release 12.2.

  2. Import the trusted CA into the wallet.

    Import the trusted root-CA certificate that signed your client certificate.

    Refer to Step 5 in Section 5.2 Configure Inbound Connections, My Oracle Support Knowledge Document 1367293.1, Enabling TLS in Oracle E-Business Suite Release 12.2.

  3. Enable client authentication by using the following steps:

    1. Log in to Oracle Enterprise Manager Fusion Middleware Control Console (for example, http://<hostname>:<domain>:<AdminServer Port>/em).

    2. Select "Web Tier Target" under the EBS Domain.

    3. Select Administration and then Advanced Configuration.

    4. Select the ssl.conf file for edit.

    5. Copy and paste the following directives. (Ensure that SSLVerifyClient is set to "require" (without quotes) only within the Location directive).

      SSLVerifyClient optional

SSLWallet {s_web_ssl_directory}/Apache/cwallet.sso

<Location /webservices/TransportAgentServer>

SSLVerifyClient require

</Location>

      The default location for the wallet is {s_web_ssl_directory}/Apache. Refer to the Application Context file for the exact location of the {s_web_ssl_directory} variable.

    6. Click Apply.

    7. Restart the Oracle HTTP Server instance by navigating to Oracle HTTP Server, then Control, and then Restart.

      $FMW_HOME/webtier/instances/<EBS-OHS-Instance>/bin/opmnctl startproc process-type=OHS

Configuring TLS Authentication for Outbound Transactions

In this document, OTA client refers to Oracle E-Business Suite with Oracle Transport Agent, which sends the message; server refers to the application that receives the message. That is, server receives inbound XML transactions, whereas client sends outbound XML transactions.

Oracle recommends using Java KeyStore and TrustStore as the repository to store digital certificates for outbound transactions over HTTPS from Oracle E-Business Suite. This section describes the required steps to configure OTA client using Java KeyStore and TrustStore. If you plan to use Oracle Wallets to store digital certificates, refer to Configuring OTA Client for TLS Authentication Using Oracle Wallet.

Configuring OTA Client for Server Authentication

Perform the following steps to configure OTA to send messages to the TLS-enabled server that is configured with server authentication only:

  1. Import the server's trusted CA into the Java TrustStore by performing the following steps:

    1. Navigate to the $OA_JRE_TOP/lib/security directory.

    2. Backup the existing cacerts file.

    3. Copy the rootCA.crt file to this directory.

    4. Execute the following command to ensure that cacerts has the write permissions:

      $ chmod u+w cacerts

    5. Add rootCA.crt and intermediate certificates (intCA.crt) to the cacerts file:

      $ keytool -importcert -keystore cacerts -alias rootCA -file rootCA.crt -v

      $ keytool -importcert -keystore cacerts -alias intCA -file intCA.crt -v

      Enter the keystore password when prompted.

      If either one of the certificates already exists in cacerts, keytool will warn you and allow you to cancel the import. Cancel the import.

    6. When you have completed the modifications to the cacerts file, reset the permissions:

      $ chmod u-w cacerts

  2. Update the following TLS related AutoConfig variables:

    Parameter Name AutoConfig Variable Change Value To
    javax.net.ssl.trustStore s_ssl_truststore $OA_JRE_TOP/lib/security/cacerts
    javax.net.ssl.trustStoreType s_ssl_truststoretype JKS
    test.trustmanager.algorithm s_ssl_trustmanageralgorithm SunX509
    If IBM AIX JRE is used, set the value of test.trustmanager.algorithm to "IbmX509" instead.

    Note: The parameter names listed in the table are in the $INST_TOP/appl/admin/oafm_wls.properties file.

  3. Run AutoConfig in the application tier.

    Refer to the Oracle E-Business Suite Setup Guide Release 12.2 for information on changing AutoConfig variables and executing AutoConfig in the application tier.

    As part of executing AutoConfig, you would be asked to restart the application tier services. Before you restart, ensure to perform step 4 mentioned below.

  4. Manually add the following property to the oafm_wls.properties file:

    javax.net.ssl.trustStorePassword=<password to access cacerts>

    This parameter is not configured through AutoConfig. Hence, you may have to set it manually every time you run AutoConfig.

  5. Stop and restart the application tier services as part of the AutoConfig execution.

Configuring OTA Client for Mutual Authentication

Perform the following steps to configure OTA to send messages to the TLS-enabled server, that is configured with mutual authentication:

  1. Follow steps described in Configuring OTA Client for Server Authentication to import the server's trusted CA into the Java TrustStore.

  2. If Oracle E-Business Suite is not already TLS-enabled, perform the following steps:

    1. Create Java Keystore by performing the following steps:

      1. Navigate to the web ssl directory as defined in the context file:

        $ grep s_web_ssl_directory $CONTEXT_FILE

      2. Create a new directory with the name j2ee, and then change to this j2ee directory.

        $ mkdir j2ee
$ cd j2ee

      3. Determine the values for the following parameters which will be used when you create the keystore for your instance:

        Parameter Name Value
        server Name of the server where you are creating the keystore
        domain The fully qualified domain of the server
        password In Release 12, the default password is changeit. Record the new password after you change it in step 5.
        O Name of your organization
        L Your city or locality
        ST Your state or province
        C Your two-letter country code

      4. Create your keystore by entering the following command:

        $ keytool -genkeypair -keyalg "RSA" -sigalg SHA256withRSA -keystore oxtakey.jks -alias client -keysize 2048 -dname "CN=server.domain, OU=JKS, O=O, ST=ST, C=C"

        Enter the key password and keystore password when prompted.

        You should now see the file oxtakey.jks in your directory.

    2. Create your certificate request by performing the following steps:

      1. Execute the following command to generate a certificate request signed by CA for the keypair:

        $ keytool -certreq -keystore oxtakey.jks -alias client -sigalg SHA256withRSA -file client.csr

      2. Submit the client.csr file to your Certificate Authority.

      3. When you receive your signed certificate, such as client.crt, copy it to the <s_web_ssl_directory>/j2ee directory.

      4. Verify client.crt is PEM (base64) encoded certificate.

        Please note that keytool does not like extra data to be present in the PEM file. If the file you received contains anything but the BEGIN and END lines with base64-encoded data between them, delete the extra data before importing the PEM file with keytool.

      5. Use the following command to verify the textual and technical attributes of the certificate:

        $ keytool -printcert  -file client.crt

    3. Execute the following command to import CA-signed certificate to Java Keystore:

      $ keytool -import -keystore oxtakey.jks -alias client -trustcacerts -file client.crt

      Note: If CA's root certificate and intermediate certificates are not in the cacerts file, ensure to import CA's root certificate (rootCA1.crt) and intermediate certificates (intCA1.crt) in the following order of sequence to Java Keystore, before importing CA-signed certificate:

      $ keytool -importcert -keystore oxtakey.jks -alias rootCA1 -trustcacerts -file rootCA1.crt

$ keytool -importcert -keystore oxtakey.jks -alias intCA1 -trustcacerts -file intCA1.crt

    4. Update the following TLS related parameters:

      Parameter Name AutoConfig Variable Value
      javax.net.ssl.trustStore s_ssl_truststore $OA_JRE_TOP/lib/security/cacerts
      javax.net.ssl.trustStoreType s_ssl_truststoretype JKS
      test.trustmanager.algorithm s_ssl_trustmanageralgorithm SunX509
      If IBM AIX JRE is used, set the value of test.trustmanager.algorithm to "IbmX509" instead.
      javax.net.ssl.keyStore s_ssl_keystore <s_web_ssl_directory>/j2ee/oxtakey.jks
      javax.net.ssl.keyStoreType s_ssl_keystoretype JKS
      test.keymanager.algorithm s_ssl_keymanageralgorithm SunX509
      If IBM AIX JRE is used, set the value of test.keymanager.algorithm to "IbmX509" instead.

      Note: The parameter names listed in the table are in the $INST_TOP/appl/admin/oafm_wls.properties file.

    5. Run AutoConfig in the application tier.

      Refer to the Oracle E-Business Suite Setup Guide Release 12.2 for information on changing AutoConfig variables and executing AutoConfig in the application tier.

      As part of executing AutoConfig, you would be asked to restart the application tier services. Before you restart, ensure to perform step 6 mentioned below.

    6. Manually add the following property to the oafm_wls.properties file:

      • javax.net.ssl.trustStorePassword=<password to access cacerts>

      • javax.net.ssl.keyStorePassword=<password to access keystore>

      These parameters are not configured through AutoConfig. Hence, you may have to set them manually every time you run AutoConfig.

    7. Stop and restart the application tier services as part of the AutoConfig execution.

  3. If Oracle E-Business Suite is already configured for TLS, the AutoConfig variables for SSL Keystore and Truststore would be configured by this step.

Setup Parameters

In Release 12.2, OTA runs in the oafm managed server and the system properties are read from the oafm_wls.properties file of the oafm managed server which is $INST_TOP/appl/admin/oafm_wls.properties.

Parameters Set Through AutoConfig

The following parameter is set through AutoConfig:

applSysSchema=%s_applsys_user% : APPLSYS

This parameter indicates that the queues in applsys schema are used.

Proxy Parameters

The following parameters control whether a proxy is used for outgoing socket connections:

OXTAOutUseProxy=%s_oxta_proxy% : false

OXTAOutProxyHost=%s_oxta_proxyhost% : ""

OXTAOutProxyPort=%s_oxta_proxyport% : ""

TLS Parameters

In Release 12.2, OTA uses SSO wallet and uses JSSE APIs to operate the wallet with the following TLS parameters contained in the oafm_wls.properties file:

Note: There are two sets of variables; one is used for TrustMaterial and the other one is for KeyMaterial. The AutoConfig by default sets them to the same sets of values since both KeyMaterial and TrustMaterial are present in the default cwallet.

TLS Parameters
Parameter Name AutoConfig Variable Description Default Specified by AutoConfig
javax.net.ssl.trustStore s_ssl_truststore Indicates the location of the trust material for the TrustManager. $INST_TOP/certs/Apache/cwallet.sso
javax.net.ssl.trustStoreType s_ssl_truststoretype Specifies the trustStore file type of trust material for the TrustManager. SSO
test.trustmanager.algorithm s_ssl_trustmanageralgorithm Specifies the TrustManager instance corresponding to this algorithm. OracleX509
javax.net.ssl.keyStore s_ssl_keystore Indicates the location of the key material for the KeyManager. $INST_TOP/certs/Apache/cwallet.sso
javax.net.ssl.keyStoreType s_ssl_keystoretype Specifies the keyStore file type of key material for the KeyManager. SSO
test.keymanager.algorithm s_ssl_keymanageralgorithm Specifies the KeyManager instance corresponding to this algorithm. OracleX509

The default values for the parameters listed in the table may change, depending on the type of the truststore you use. For more information on these parameter values, see Configuring TLS Authentication for Outbound Transactions.

Parameters Controlling Throughout

These parameters set the number of database connections in your system for inbound and outbound requests. The optimum settings for these depend on the load in your system. Setting them too high could result in performance degradation. However, setting them too low could result in transactions having to wait for an excessive time before they are able to get a connection in or out. Both parameters default to 1.

OXTAInPoolSize=%s_oxtainpool_size% : 1

This parameter sets the number of database connections available for inbound requests.

OXTAOutThreads=%s_outbound_threads : 1%

This parameter sets the number of database connections available for outbound requests.

Load OXTA Servlet (s_load_oxta_servlet) Parameter

This parameter s_load_oxta_servlet is used to control loading of the Oracle Transport Agent servlets (both inbound and outbound) when managed server starts up.

Parameters Not Set Through AutoConfig

The following parameters must be manually added to the oafm_wls.properties file if you wish to change the default settings. The default settings are shown with each parameter.

Time Parameters

The following parameters control the amount of time allowed for transactions to complete over OTA:

OXTAOutBaseTimeout=10

The time in seconds allowed by OTA to complete the entire process flow for an outbound request. That is, the time it takes to:

  1. Open a connection.

  2. Send data.

  3. Receive a response.

    Note that this base time is adjusted for higher payloads based on the OutLinearTimeout factor described below.

OXTAOutLinearTimeout=500

This parameter sets a factor that applies to the timeout based on the size of the payload.

The timeout for a given request is calculated based on the following formula:

Timeout = OXTABaseTimeOut + (OXTAOutLinearTimeout/1000) * payload size/1024

where the payload size is in bytes.

For example, for a payload of 1 MB, the timeout using the default parameter settings is:

10 sec + [(500/1000) * 1048576/1024] = 523 seconds

In other words, by default, the factor 500 adds 513 seconds for every MB of data in the payload.

OXTAOutMaxAttempts=5

The number of times to attempt to send an outbound request.

OXTAOutResendDelay=1800

The time in seconds to wait before retrying to send a transaction.

OXTAThreadSleepTime=60

The amount of time in seconds the primary thread sleeps between monitoring the Transport Handler threads.

OXTAMaxDbConnectAttempts=20

The maximum number of DB failures that can be tolerated before refraining from making any more connection attempts and going to long sleep for a time given by the parameter below.

OXTABackoffTime=3600

If the Transport Handler threads have died for OXTAMaxDbConnectAttempts number of times due to DB failure, the primary thread refrains from further attempts and goes to sleep for a time period in seconds given by this parameter.

OXTAOutDequeueRate=120000

The time in milliseconds for an OTA client to dequeue the message from the ECX_OUTBOUND queue. To reduce the dequeue time for each transaction, change the default value 120000 to a smaller value, such as 30000 (30 seconds).

Payload Size

OXTAInMaxContent=1000000

The maximum payload size in bytes.

Debug Setting

FND logging is used for OTA, and the AFLOG parameters should be used for enabling the logging. They can be either set in the FND profile options or can be set specifically to the oafm managed server in which the OTA is running. If the latter option is used, set the following parameters in the oafm_wls.properties file:

AFLOG_ENABLED=true

AFLOG_LEVEL=<1 for Statement level, 6 for Unexpected level. OTA logs only at either of these 2 levels>

AFLOG_MODULE=ecx.oxta%

AFLOG_FILENAME=<filename on application tier>

Since OTA uses Anonymous AppsLog instance, logging does not go to database if this parameter is omitted.

The old parameter OXTALogDebugMsg=false/true is used only in the standalone mode.

Oracle Transport Agent Inbound Test Page

Oracle Transport Agent provides Oracle Transport Agent Inbound Test Page to test inbound XML message processing.

Oracle Transport Agent Inbound Test Page presents an HTML page that lets you provide inbound payload and other OTA parameters, as explained in the Oracle Transport Agent Inbound Test Page Parameters table at the end of this section. To access this test page, open a web browser and enter the following URL:

http://<EBS hostname>:<port>/webservices/ECXOTAInbound

When prompted, provide Oracle E-Business Suite username and password. Then, provide the required input XML payload and other input parameters used by OTA messaging protocol. After authenticating the user credentials, the XML message will be posted to OTA for further processing. OTA messaging protocol parameters used in this test page are described in the Oracle Transport Agent Inbound Test Page Parameters table.

Note: Oracle Transport Agent Inbound Test Page is included for testing purposes and should not be used in a production environment. For production, send inbound requests to http(s)://<EBS hostname>:<port>//webservices/TransportAgentServer.

Important: As part of the January 2017 CPU update, the access to the Oracle Transport Agent Inbound Test Page is restricted to trusted nodes or servers. Therefore, to use this page to send an inbound XML message, you should add a fully-qualified node name or IP address as a trusted node in Oracle E-Business Suite. To extend access to additional hosts, perform the following tasks:

  1. Add space-separated node names, fully qualified node names, or client machine IP addresses to the existing content of the s_admin_ui_access_nodes context variable.

  2. Run AutoConfig.

  3. Restart the Oracle HTTP Server.

For more information, refer to the Known Issues section in My Oracle Support Knowledge Document 2212223.1, Oracle E-Business Suite Release 12 Critical Patch Update Knowledge Document (January 2017) for details.

This test page will prompt you for the input parameters used by the OTA messaging protocol.

Oracle Transport Agent Inbound Test Page Parameters
Column Name Description
TRANSPORT_PROTOCOL Defaults to OXTA.
TRANSPORT_PROTOCOL_VERSION Defaults to 1.0.
REQUEST_TYPE Select "Send".
MESSAGE_ID Enter the unique reference number that identifies the transaction.
MESSAGE_TYPE Defaults to XML.
MESSAGE_STANDARD Defaults to OAG.
TRANSACTION_TYPE (Required) Enter the type of transaction, such as PO for Purchase Order Inbound.
TRANSACTION_SUBTYPE (Required) Enter the subtype of the transaction.
DOCUMENT_NUMBER Enter the document number.
PARTYID (Optional) Enter the trading partner ID for the sender.
SOURCE_TP_LOCATION_CODE (required) Enter the Source Trading Partner Location Code (should match the Trading Partner Details column of the same name).
PROTOCOL_TYPE Not required for inbound messages.
PROTOCOL_ADDRESS Required only if REQUEST_TYPE is EME.
USERNAME (Required) Enter a valid user name for the receiving system.
PASSWORD (Required) Enter the password for the user name entered.
ATTRIBUTE1 Optional
ATTRIBUTE2 Optional
ATTRIBUTE3 Required for pass-through transactions only.
ATTRIBUTE4 Optional
ATTRIBUTE5 Optional
PAYLOAD Enter the message payload.

Connecting to Non-OTA Servers

The OTA server (client) includes the capability to send documents to non-OTA servlets that do not employ the OTA messaging protocol. When sending a message, the OTA server initiates an HTTP post to transmit the document. The HTTP response from the receiving Web server indicates whether the receiver was an OTA server.

If the HTTP response does not contain the OTA protocol response body, the sending OTA server assumes the message was received by a non-OTA server. In this case, the standard HTTP response code (that is, 200 meaning "success") is used to determine the success or failure of the message. If the sending OTA server receives an HTTP-200, the message delivery is assumed to be successful. If the sending OTA server receives any other response, it is assumed the delivery failed.

Successful transmissions of documents to non-OTA servers are logged as successfully delivered to a non-OTA server. Delivering to a non-OTA server has the following disadvantages:

Please note that you can set up the OTA server to use HTTP 1.1 for sending documents to a specific non-OTA server by adding a system property with the following syntax:

HttpProtocolVersion-<servername>\:<serverport>="1.X"

For example, add a system property HttpProtocolVersion-www.example.com\:8080="1.1".

If there is no server port specified in the URL for the application, the port in the system property will have to be set to '-1'. For example, HttpProtocolVersion-www.example.com\:-1="1.1".

Code Connection Samples

The following are code examples for remote Web servers to post a message to the Oracle E-Business Suite using either the HTTP or HTTPS protocol. Use this as a guide to create your own code.

The code to post a message to the Oracle E-Business Suite consists of three parts: the message envelope, the message payload, and the message response.

The message envelope attributes are as follows:

Define these as name-value pairs in your code. The USERNAME and PASSWORD should be set to something meaningful for the receiving Web server.

The PAYLOAD corresponds to your business document represented in XML format.

The receiving Web server sends the message response back to the sending Web server. The message response includes Message Receipt ID, Status Code, and Status Description. A status code of 1000 implies the message was successfully posted.

OTA Connection over HTTP

import java.sql.*;
import java.net.*;
import java.io.*;
import java.util.*;
public class SendHTTP
{
  final  String[] columnNames = new String[] { "MESSAGE_TYPE", "MESSAGE_STANDARD",
"TRANSACTION_TYPE", "TRANSACTION_SUBTYPE", "DOCUMENT_NUMBER", "PARTYID", "PARTY_SITE_ID", "PARTY_TYPE",
  "PROTOCOL_TYPE", "PROTOCOL_ADDRESS", "USERNAME", "PASSWORD", "ATTRIBUTE1", "ATTRIBUTE2", "ATTRIBUTE3",
  "ATTRIBUTE4", "ATTRIBUTE5", "PAYLOAD" };
   Object[] columnVals = new Object[18];
  int numCols = 0;
  String Encoding = "UTF-8";
    URL url = null;
  String username = null;
  String password = null;
  String target = null;
  String filename = null;
  String MessageID = "SEND" + System.currentTimeMillis();
  String VALUE_SEP  = "=";
  String PAIR_SEP   = "&";
  tring NEW_LINE   = "\n";
    public SendHTTP()
  {
    numCols      = columnNames.length;
    columnVals   = new Object[numCols];
  }
  public   void createBasicMessage() throws Exception
  {
    logMessage("Creating the message");
    StringBuffer tmp = new StringBuffer("This is a test message sent from the Sample java program.");
   columnVals[0] = "XML"; //MESSAGE_TYPE
  columnVals[1] = "OAG"; //MESSAGE_STANDARD
  columnVals[2] = "ECX"; //TRANSACTION_TYPE
  columnVals[3] = "CBODO"; //TRANSACTION_SUBTYPE
  columnVals[4] = "12" ; //DOCUMENT_NUMBER
  columnVals[5] =  "206"; //PARTYID
  columnVals[6] =  "206"; //PARTY_SITE_ID
  columnVals[7] =  "I"; //PARTY_TYPE
  columnVals[8] =  "HTTP"; //PROTOCOL_TYPE
    columnVals[9] =  target;
  columnVals[10] = username ; //USERNAME
  columnVals[11] = password; //PASSWORD
  columnVals[12] = null  ; //ATTRIBUTE1
  columnVals[13] = null  ; //ATTRIBUTE2
  columnVals[14] = null  ; //ATTRIBUTE3
  columnVals[15] = null  ; //ATTRIBUTE4
columnVals[16] = null  ; //ATTRIBUTE5
  columnVals[17] = getPayload();// tmp  ;//Payload
  }
     public void sendMessage() throws Exception
  {
     int bytesRead;
     int total_bytes = 0;
     int bufSize     = 1024;
     char[] buf = new char[bufSize];
     logMessage("Started Sending the message.");
     url = new URL((String)columnVals[9]);
     int port = url.getPort();
     if(port == -1)
     port = 80;
     URL newurl = new URL(url.getProtocol(),url.getHost(),port, url.getFile());
     logMessage("Connecting to " + newurl.getHost() + " port " + port);
          HttpURLConnection conn = (HttpURLConnection)newurl.openConnection();
     conn.setDoOutput(true);
     conn.setDoInput(true);
     OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
     String httpReq = getRequestStr();
     logMessage("Sending to URL.");
     wr.write(httpReq);
     wr.flush();
     logMessage("Response Received  :-");
 logMessage("Message Receipt ID = "+conn.getHeaderField("MESSAGE_RECEIPT_ID"));
     logMessage("Status Code        = "+conn.getHeaderField("STATUS_CODE"));
     logMessage("Status Description = "+conn.getHeaderField("STATUS_DESCRIPTION"));
  }
  public  String getRequestStr() throws Exception
  {
       StringBuffer buf = new StringBuffer();
    StringBuffer httpBody = getHttpBody();
    long bodyLen = 0;
    bodyLen = httpBody.length();
    buf.append(httpBody);
    buf.append("\n");
    return buf.toString();
  }
  public StringBuffer getHttpHeader(long contentLength) throws Exception
  {
    StringBuffer buf = new StringBuffer();
    buf.append("POST " + url.getFile() + " HTTP/1.0\r\n");
    buf.append("Host: " + url.getHost() + ":" + url.getPort() + "\n");
    String userpass = username+ ":" +password;
    buf.append("Content-type: application/x-www-form-urlencoded\n");
    buf.append("Content-length: " + contentLength + "\n");
    buf.append("\r\n");
    return buf;
 }
  public StringBuffer getHttpBody() throws Exception
  {
    StringBuffer contentBuf = new StringBuffer();
    contentBuf.append(encode("TRANSPORT_PROTOCOL"));
    contentBuf.append(VALUE_SEP);
    contentBuf.append(encode("OXTA"));
    contentBuf.append(PAIR_SEP);
    contentBuf.append(encode("TRANSPORT_PROTOCOL_VERSION"));
    contentBuf.append(VALUE_SEP);
    contentBuf.append(encode("1.0"));
    contentBuf.append(PAIR_SEP);
    contentBuf.append(encode("REQUEST_TYPE"));
    contentBuf.append(VALUE_SEP);
    contentBuf.append(encode("SEND"));
    contentBuf.append(PAIR_SEP);
    contentBuf.append(encode("MESSAGE_ID"));
    contentBuf.append(VALUE_SEP);
    contentBuf.append(encode(MessageID));
    contentBuf.append(PAIR_SEP);
      for (int i = 0; i < 18; i++)
    {
       if(columnVals[i] != null)
       {
         contentBuf.append(encode(columnNames[i]));
         contentBuf.append(VALUE_SEP);
                  if(columnVals[i] != null)
            contentBuf.append(encode((String)columnVals[i]));
         else
         contentBuf.append("");
       if(i != 17 )
        contentBuf.append(PAIR_SEP);
       }
      }
     return contentBuf;
  }
  public  void logMessage(String msg)
  {
     System.out.println(msg);
  }
  public String encode(String str)
  {
     String str1 = null;
      try{
     str1 = URLEncoder.encode(str,Encoding);
     }catch(Exception e)
     {
       System.out.println("Unsupported Encoding format");
       System.exit(1);
     }
     return str1;
  }
  public String getPayload()
  {
    StringBuffer tmp = null;
    try 
    {
      BufferedReader in = new BufferedReader(new FileReader(filename));
      String s = null;
      tmp = new StringBuffer();
      while((s = in.readLine())!= null)
      {
         tmp.append(s + "\n");
      }
      in.close();
    }
    catch(Exception ex)
    {
      logMessage("Exception: in reading file");
      logMessage("Sending a string : 'This is a Test String' as payload");
    }
    if(tmp == null || tmp.length() == 0)
    return "This is a Test String";
    else
    return tmp.toString();
  }
  public static void main(String args[])
  {
    //USAGE Target username password;
    SendHTTP sp = new SendHTTP();
    try
    {
      if(args.length < 4)
      {
         sp.logMessage("Usage java sample <Target> <username> <password> <filename>");
         System.exit(1);
      }
      else
      {
        sp.target = args[0];
        sp.username = args[1];
        sp.password = args[2];
        sp.filename = args[3];
        sp.createBasicMessage();
        sp.sendMessage();
        sp.logMessage("Program exiting ");
      }
    }
    catch(Exception e)
    {
      sp.logMessage("Exception = "+e);
    }
  }   
}

OTA Connection over HTTPS

import java.sql.*;
import java.net.*;
import java.io.*;
import java.util.*;
import javax.net.ssl.*;
public class SendHTTPS
{
  final  String[] columnNames = new String[] { "MESSAGE_TYPE", "MESSAGE_STANDARD",
  "TRANSACTION_TYPE", "TRANSACTION_SUBTYPE", "DOCUMENT_NUMBER", "PARTYID", "PARTY_SITE_ID", "PARTY_TYPE",
  "PROTOCOL_TYPE", "PROTOCOL_ADDRESS", "USERNAME", "PASSWORD", "ATTRIBUTE1", "ATTRIBUTE2", "ATTRIBUTE3",
  "ATTRIBUTE4", "ATTRIBUTE5", "PAYLOAD" };
    Object[] columnVals = new Object[18];
  int numCols = 0;
  String Encoding = "UTF-8";
  URL url = null;
  String username = null;
  String password = null;
  String target = null;
  String filename = null;
  String MessageID = "SEND" + System.currentTimeMillis();
  String VALUE_SEP  = "=";
  String PAIR_SEP   = "&";
  String NEW_LINE   = "\n";
   public SendHTTPS()
  {
    numCols      = columnNames.length;
    columnVals   = new Object[numCols];
  }
  public   void createBasicMessage() throws Exception
  {
    logMessage("Creating the message");
    StringBuffer tmp = new StringBuffer("This is a test message sent from the Sample java program.");
  columnVals[0] = "XML"; //MESSAGE_TYPE
  columnVals[1] = "OAG"; //MESSAGE_STANDARD
  columnVals[2] = "ECX"; //TRANSACTION_TYPE
  columnVals[3] = "CBODO"; //TRANSACTION_SUBTYPE
  columnVals[4] = "12" ; //DOCUMENT_NUMBER
  columnVals[5] =  "206"; //PARTYID
  columnVals[6] =  "206"; //PARTY_SITE_ID
  columnVals[7] =  "I"; //PARTY_TYPE
  columnVals[8] =  "HTTPS"; //PROTOCOL_TYPE
  columnVals[9] =  target;
  columnVals[10] = username ; //USERNAME
  columnVals[11] = password; //PASSWORD
  columnVals[12] = null  ; //ATTRIBUTE1
  columnVals[13] = null  ; //ATTRIBUTE2
  columnVals[14] = null  ; //ATTRIBUTE3
  columnVals[15] = null  ; //ATTRIBUTE4
  columnVals[16] = null  ; //ATTRIBUTE5
  columnVals[17] = getPayload();// tmp  ;//Payload
  }
  public void sendMessage() throws Exception
  {
     int bytesRead;
     int total_bytes = 0;
     int bufSize     = 1024;
     char[] buf = new char[bufSize];
     String proxyHost = "www-proxy.us.example.com";
     String proxyPort  = "80";
     Properties systemProperties = System.getProperties();
     systemProperties.setProperty("https.proxyHost",proxyHost);
     systemProperties.setProperty("https.proxyPort",proxyPort);
      logMessage("Started Sending the message.");
     url = new URL((String)columnVals[9]);
     int port = url.getPort();
     if(port == -1)
     port = 80;
     URL newurl = new URL(url.getProtocol(),url.getHost(),port, url.getFile());
     logMessage("Connecting to " + newurl.getHost() + " port " + port);
          HttpsURLConnection conn = (HttpsURLConnection)newurl.openConnection();
     conn.setDoOutput(true);
     conn.setDoInput(true);
     OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
     String httpReq = getRequestStr();
     logMessage("Sending to URL.");
     wr.write(httpReq);
     wr.flush();
     logMessage("Response Received  :-");
     logMessage("Message Receipt ID = "+conn.getHeaderField("MESSAGE_RECEIPT_ID"));
     logMessage("Status Code        = "+conn.getHeaderField("STATUS_CODE"));
     logMessage("Status Description = "+conn.getHeaderField("STATUS_DESCRIPTION"));
  }
  public  String getRequestStr() throws Exception
  {
    StringBuffer buf = new StringBuffer();
    StringBuffer httpBody = getHttpBody();
    long bodyLen = 0;
    bodyLen = httpBody.length();
    buf.append(httpBody);
    buf.append("\n");
    return buf.toString();
  }
  public StringBuffer getHttpHeader(long contentLength) throws Exception
  {
    StringBuffer buf = new StringBuffer();
    buf.append("POST " + url.getFile() + " HTTP/1.0\r\n");
    buf.append("Host: " + url.getHost() + ":" + url.getPort() + "\n");
    String userpass = username+ ":" +password;
    buf.append("Content-type: application/x-www-form-urlencoded\n");
    buf.append("Content-length: " + contentLength + "\n");
    buf.append("\r\n");
    return buf;
  }
  public StringBuffer getHttpBody() throws Exception
  {
    StringBuffer contentBuf = new StringBuffer();
    contentBuf.append(encode("TRANSPORT_PROTOCOL"));
    contentBuf.append(VALUE_SEP);
    contentBuf.append(encode("OXTA"));
    contentBuf.append(PAIR_SEP);
    contentBuf.append(encode("TRANSPORT_PROTOCOL_VERSION"));
    contentBuf.append(VALUE_SEP);
    contentBuf.append(encode("1.0"));
    contentBuf.append(PAIR_SEP);
    contentBuf.append(encode("REQUEST_TYPE"));
    contentBuf.append(VALUE_SEP);
    contentBuf.append(encode("SEND"));
    contentBuf.append(PAIR_SEP);
    contentBuf.append(encode("MESSAGE_ID"));
    contentBuf.append(VALUE_SEP);
    contentBuf.append(encode(MessageID));
    contentBuf.append(PAIR_SEP);
        for (int i = 0; i < 18; i++)
    {
       if(columnVals[i] != null)
       {
         contentBuf.append(encode(columnNames[i]));
         contentBuf.append(VALUE_SEP);
                if(columnVals[i] != null)
         contentBuf.append(encode((String)columnVals[i]));
         else
         contentBuf.append("");
         if(i != 17 )
        contentBuf.append(PAIR_SEP);
       }
     }
     return contentBuf;
  }
  public  void logMessage(String msg)
  {
    System.out.println(msg);
  }
  public String encode(String str)
  {
     String str1 = null;
     try{
     str1 = URLEncoder.encode(str,Encoding);
     }catch(Exception e)
     {
       System.out.println("Unsupported Encoding format");
       System.exit(1);
     }
     return str1;
  }
  public String getPayload()
  {
    StringBuffer tmp = null;
    try 
    {
      BufferedReader in = new BufferedReader(new FileReader(filename));
      String s = null;
      tmp = new StringBuffer();
      while((s = in.readLine())!= null)
      {
         tmp.append(s + "\n");
      }
      in.close();
    }
    catch(Exception ex)
    {
      logMessage("Exception: in reading file");
      logMessage("Sending a string : 'This is a Test String' as payload");
    }
    if(tmp == null || tmp.length() == 0)
    return "This is a Test String";
    else
    return tmp.toString();
  }
  public static void main(String args[])
  {
    //USAGE Target username password;
    SendHTTPS sp = new SendHTTPS();
    try
    {
      if(args.length < 4)
      {
         sp.logMessage("Usage java sample <Target> <username> <password> <filename>");
         System.exit(1);
      }
else
      {
        sp.target = args[0];
        sp.username = args[1];
        sp.password = args[2];
        sp.filename = args[3];
        sp.createBasicMessage();
        sp.sendMessage();
        sp.logMessage("Program exiting ");
      }
    }
    catch(Exception e)
    {
      sp.logMessage("Exception = "+e);
    }
  }   
}

Troubleshooting

For information on TLS issues, see Common TLS Issues.

HTTP Status Codes

The following table lists the error response codes returned in the HTTP Response by the OTA server.

Status Code Error Code Description
1000 OK Request handled successfully.
2000 ECX_OXTA_DB_UNAVAIL Database unavailable. Cannot get connection to the database.
2001 ECX_OXTA_SERVER_ERR Unexpected server-side error. Client should retry.
3000 ECX_OXTA_BAD_REQ Missing TRANSPORT_PROTOCOL, TRANSPORT_PROTOCOL_VERSION, or MESSAGE_TYPE.
3001 ECX_OXTA_UNKNOWN_REQ Invalid value for MESSAGE_TYPE.
3002 ECX_OXTA_AUTH_MISSVAL Incomplete credentials. Username or Password not available for request.
3003 ECX_OXTA_AUTH_FAILURE Authentication failure. Invalid user password.
3004 ECX_OXTA_PROTCL_NOTSUPP Oracle Transport Agent protocol version not supported by server.
3005 ECX_OXTA_PAYLOAD_NULL Message has NULL payload.
3100 ECX_OXTA_SEND_MISSVAL Required parameters for the SEND post are missing.
3101 ECX_OXTA_LEN_MISS Request header content length attribute not set.
3102 ECX_OXTA_LEN_TOOLARGE Size of content larger than specified in request header content length attribute.
3200 ECX_OXTA_AUTH2_MISSVAL Parameter missing for AUTH2 request. Verify that the party_site_id and the transaction_type are valid.
3201 ECX_OXTA_AUTH2_FAILURE AUTH2 request failed.
3300 ECX_OXTA_EME_MISSVAL E-mail address or payload was not passed in the EME request.
3301 ECX_OXTA_EME_INVALID_EMAIL Incorrect e-mail address format for EME request.
3302 ECX_OXTA_EME_SMTP_NOTSET Mail server not set up in config.
4000 ECX_OXTA_UNKNOWN_PROTCL Invalid protocol type for SEND request.
4001 ECX_OXTA_TIMEOUT Time out for this transport request reached.
4002 ECX_OXTA_CLIENT_ERR Unexpected client side exception.
4003 ECX_OXTA_MAX_ATTEMPTS Exceeded the max number of attempts for transport.
4100 ECX_OXTA_SMTP_NOTSET Mail server not set up in config.
4101 ECX_OXTA_INVALID_EMAIL Incorrect e-mail address format.
4102 ECX_OXTA_MAIL_ERR Error when trying to send mail.
4103 ECX_OXTA_MAILJAR_NOT_EXISTS SMTP not enabled. Ensure that mail.jar is present in your Java classpath.
4104 ECX_OXTA_ACTJAR_NOT_EXISTS SMTP not enabled. Ensure that activation.jar is present in your Java classpath.
4200 ECX_OXTA_INVALID_URL Incorrect URL format.
4201 ECX_OXTA_PROXY_FAILURE Cannot open connection to proxy server.
4202 ECX_OXTA_CONNECT_FAILURE Cannot connect to host:port.
4203 ECX_OXTA_UNKNOWN_RES Response from the server not in a format understood by the client.
4300 ECX_OXTA_INVALID_CACERT Failed to open the certificate file/failed to read certificate from the file.
4301 ECX_OXTA_SSLHANDSHAKE_FAILURE Failed to perform handshake when getting TLS connection.
4302 ECX_OXTA_SSLVERICHAIN_FAILURE Error when verifying chain certificate.
5000 ECX_OXTA_PROTOCOL_MISS Protocol value missing from inbound message.
5001 ECX_OXTA_USERNAME_MISS Username value missing from the inbound message.
5002 ECX_OXTA_PASSWORD_MISS Password value missing from the inbound message.