Understanding the Oracle

Transport Agent Messaging

Protocol
An Oracle White Paper
July 2001

Oracle Transport Agent Page 2

 Understanding the Oracle Transport
Agent Messaging Protocol

OVERVIEW

The 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 to
provide guaranteed exactly once delivery of messages. This paper explains the
OTA messaging protocol and how this protocol is used to implement
messaging. This paper is not intended to discuss the technical aspects of the
OTA Server but rather discuss the functional aspects of the OTA protocol.

The OTA Server is a Java based servlet that uses the OTA Messaging Protocol
to support the following requirements:

• Simple to install, configure and manage

• Guaranteed, exactly once delivery of messages
• Complete audit and history tracking of messages sent/received
• Support outbound email delivery of messages (SMTP)
• Support the HTTP/S Application protocol
• Support server certificate authentication (when using SSL mode)
• Provide built in Application user authentication to Oracle e-Business Suite
and Oracle Exchange.

The Oracle Transport Agent Protocol Stack

OTA (Messaging Protocol)

HTTP (Application Protocol)
SSL (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 in order
to provide guaranteed, exactly once delivery of messages.

Oracle Transport Agent Page 3

The OTA Message Propagation flow (with SSL enabled)

OXTA Server as client OXTA Server as server

(Sender) (Receiver)
2) Verify max retry count 8) Verify web server user/pass (optional)
3) Construct http message 9) Verify transport protocol/version
10) Verify App user/pass
11) Verify msg id for duplicate
15) Read http response
a. Update status tables
4) Initiate http handshake/request cert
b. If fail, update retry count 13) Build http response
and enqueue msg for retry 5) Web Server sends server cert
7) Start http head/body data stream

14) Send http response

12) Enqueue message

1) Dequeue message
Server Certificate

rt
cer
rve
se
rify
Ve
6)
I BM
IB M

Certificate
Authority

Oracle Transport Agent Post Message

Two OTA servers communicate by sending/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: Header Authorization
encryption follows W3C standard):

HTTP Header
Http-Version: HTTP/1.1
Authorization: Digest username="myusername",
realm="testrealm@host.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

Oracle Transport Agent Page 4

 PROTOCOL_ADDRESS=https://www.me.com/servlets/oracle.apps.ecx.oxta.Tr
ansportAgentServer
USERNAME=myusername
PASSWORD=myloginpassword
ATTRIBUTE1=
ATTRIBUTE2=
ATTRIBUTE3=
ATTRIBUTE4=
ATTRIBUTE5=
PAYLOAD=<xml …..>

TRANSPORT_PROTOCOL
The Transport Protocol indicates to the receiving servlet the Messaging
Protocol being used. This will always be OTA when being sent from an OTA
server. The inbound OTA server will validate to ensure transport_protocol is
OTA and will then send back the appropriate response in the HTTP response
body.

TRANSPORT_PROTOCOL_VERSION
The Transport Protocol version indicates the version of the Messaging Protocol
being used. The sending OTA server dictates this value based on the version of
the OTA server being used.

REQUEST_TYPE
This parameter indicates the type of request being sent from the OTA server.
This valid values are:
SEND - This is a real send and not a test send. The OTA receiving
server will treat this as a live, production send from the sending OTA
server .

AUTH - Authorization test. The receiving OTA server will treat this as a
request for a test according to the OTA AUTH test protocol. This
protocol requires only the following parameters:

Parameter Sample
TRANSPORT_PROTOCOL OXTA
TRANSPORT_PROTOCOL_VERSION 1.0
REQUEST_TYPE AUTH
USERNAME MYUSERNAME
PASSWORD MYPASSWORD

If the authorization passes, the response will contain an HTTP 200 signal and an
OXTA 1000 status message (see the OTA HTTP response protocol below ).

AUTH2 - Authorization test, method 2. The receiving OTA server will

treat this as a request for a test according to the OTA AUTH2 test
protocol. This protocol requires only the following parameters:

Oracle Transport Agent Page 5

 Parameter Sample
TRANSPORT_PROTOCOL OXTA
TRANSPORT_PROTOCOL_VERSION 1.0
REQUEST_TYPE AUTH2
USERNAME MYUSERNAME
PASSWORD MYPASSWORD
PARTY_SITE_ID 123
TRANSACTION_TYPE PO
TRANSACTION_SUBTYPE PROCESS

EME - Email me. The receiving OTA server will receive the message
and place it on the outbound queue for delivery to the address specified
in PROTOCOL_ADDRESS. This protocol requires only the following
parameters:

Parameter Sample
TRANSPORT_PROTOCOL OXTA
TRANSPORT_PROTOCOL_VERSION 1.0
REQUEST_TYPE EME
USERNAME MYUSERNAME
PASSWORD MYPASSWORD
PROTOCOL_ADDRESS Me@mydomain.com
PAYLOAD <xml …..>

MESSAGE_ID
This is the unique message identifier of the sending OTA server. The receiving
OTA server will use this identifier to determine if it is a duplicate message. The
sending OTA server uses the Oracle AQ message ID from the outbound XML
Gateway queue.

MESSAGE_TYPE
This indicates the type of content in the payload. When used with XML
Gateway, this will always contain a value of XML.

TRANSACTION_TYPE
Used by XML Gateway to determine the type of document being
communicated. This is a user-defined value entered in the External Transaction
Type field in the Transactions form of XML Gateway. Sample values include
PO, Invoice, and Shipping.

TRANSACTION_SUBTYPE
Used by XML Gateway to determine the sub transaction type of the document
being created. This is a user-defined value entered in the External Transaction
Subtype field in the Transactions form of XML Gateway. Sample values
include Create or Change.

Oracle Transport Agent Page 6

DOCUMENT_NUMBER
This is the primary identifier for the business document in the payload.
Examples include Purchase Order number, Invoice number. This parameter is
used in the Monitoring pages to help users identify documents sent/received.

PARTYID
The sender/receiver negotiated identifier that identifies the receiver of the
document (company level). This is a user-defined value that is entered in the
External Source Location Code of the Trading Partner Definition form within
XML Gateway.

PARTY_SITE_ID
The sender/receiver negotiated identifier that identifies the receiver of the
document (company site level).

PROTOCOL_TYPE
This is the Application Protocol to use to transmit the document. This also
contains an identifier as to the program to use to transmit the document over
the protocol.

PROTOCOL_TYPE Meaning
HTTP Straight HTTP post
HTTPS Straight HTTP post using SSL
HTTP-OXTA Use OTA protocol over HTTP
HTTPS-OXTA Use OTA protocol over
SMTP Send document via SMTP (email)

PROTOCOL_ADDRESS
This is the fully qualified address used by OTA to transmit the document to.
Examples :

PROTOCOL_TYPE PROTOCOL_ADDRESS
HTTP http://www.me.com:8080/servlets/mycustom
HTTP-OXTA http://www.me.com:9000/servlets/oracle.apps.ecx.oxta.Transp
ortAgentServer
HTTPS-OXTA https://www.me.com/servlets/oracle.apps.ecx.oxta.TransportA
gentServer
SMTP Me@mydomain.com

USERNAME
This is the username to be used for authentication on the receiving server. The
OTA server will use this username and validate it against valid Applications
users in Applications or valid Exchange users (buyer/supplier login) in
Exchange.

Oracle Transport Agent Page 7

PASSWORD
This is the password associated with the USERNAME to be used for
authentication.

Note the username/password values are also put in the Authorization section of
the HTTP header for optional web server level authentication.

ATTRIBUTE1
This contains the identifier of the system sending the message. This is a user-
defined value entered in the ECX_OAG_LOGICALID Applications profile
option.

ATTRIBUTE2
Not used.

ATTRIBUTE3
This contains the identifier of the final destination for the document. This is a
user-defined value entered in the Target Location Code field in the Trading
Partner Definition for of XML Gateway. This is used as a routing mechanism
to
tell the receiver of the message to route the document to another trading partner
known to the receiver.

ATTRIBUTE4
Not used.

ATTRIBUTE5
Not used.

PAYLOAD
This contains the actual XML document to be processed.

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 look
at the HT TP header to determine if the OTA message was successfully
delivered. If the HTTP response is anything other than 200, OTA will assume
the post failed and will requeue the message for retry (assuming max retry has
not been reached).

Sample HTTP Response

HTTP Header
HTTP/1.1 200 OK
Server: Apache/1.2.0
Date: Fri, 15 Jun 2001 16:20:46 GMT
Content-Length: 567
STATUS_CODE: 1000
STATUS_DESCRIPTION: OK
MESSAGE_RECEIPT_ID: A9876543210987654321

Oracle Transport Agent Page 8

 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 correct success or failure code.

STATUS_CODE
This the status message as received by the OTA server. Anything other than a
1000 is considered a failed delivery.

STATUS_DESCRIPTION
This is an English description of the status.

MESSAGE_RECEIPT_ID
If the status code is 1000, this will contain a globally unique identifier of the
message as generated by the receiving OTA server.

The following table list the valid response status codes returned in the HTTP
Response by the OTA server:

Status Description What happened on the server/client

Code side
1000 OK Request handled successfully
2000 Database Unavailable Cannot get connection to the database
2001 Unknown Serverside Error Unexpected exceptions on the server side
due to whatever reasons. Client should
retry in this case.
3000 Bad Request Values of TRANSPORT_PROTOCOL,
TRANSPORT_PROTOCOL_VERSION
or MESSAGE_TYPE is missing
3001 Unknown Request Type Value of MESSAGE_TYPE is unrecognized
3002 Incomplete Credentials Username or password not found in
request
3003 Authentication Failure User-password didn’t get through
3004 OTA Version Not Supported OTA Protocol version not supported by
server
3100 Value Missing For SEND For an SEND post, some required
parameters is missing from the request
3101 Length Required Content-length is not set in request
3102 Length Too Large Size of content too large, when checking
content size in the header
3200 Values Missing For AUTH2 For an AUTH2 request, parameter is missing
from the request
(party_site_id or transaction_type)
3201 AUTH2 Failure AUTH2 failed for any reason

Oracle Transport Agent Page 9

 3300 Values Missing For EME EMAIL address or payload is not passed in
the EME request
3301 Incorrect E-mail Address
Format For EME
3302 Mail Server Not Set Mail server not set up in config
4000 Unknown Protocol Type Send protocol type unknown (not HTTP,
HTTPS, SMTP)
4001 Timeout Exceeded Time out for this transport action reached
4002 Unknown Clientside Exception Any other exceptions on the client side.
4003 Max Transport Attempts Exceeded the max number of attempts for
Exceeded transport
4100 Mail Server Not Set Mail server not set up in config
4101 Incorrect E-mail Address Email address format incorrect
Format
4102 Cannot Send E-mail Error when trying to send mail
4200 Incorrect URL Format URL format incorrect
4201 Failure Connecting to Proxy Cannot open connection to the proxy server
4202 Failure Connecting to Server Cannot connect to host:port
4203 Unknown Response From Response from the server not in a format
Server which the client can understand
4300 Invalid CACert File Failed to open the cert file / failed to read
cert from the file
4301 SSL Handshake Failure Failure to perform handshake when getting
SSL Connection
4302 SSL Verify Cert Chain Failure Error when verifying chain certificates

Connecting to non-OTA Servers

The OTA Server 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 or not by the virtue of the HTTP response contents.

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 (i.e. 200 for success) is used to
determine the success or failure of the message. If the sending OTA server
receives an HTTP-200, the message is assumed to be delivered successfully. If
the sending OTA server receives anything else, it is assumed to be a failure.

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:
1. No Guaranteed Delivery
2. No Guaranteed Once Only Delivery
3. No Message Tracking ID available to the sender
4. Message Ownership completely with the servlet that received the message

CONCLUSION

The Oracle Transport Agent provides a secured means of delivering and

Oracle Transport Agent Page 10

receiving messages using SMTP, HTTP, or HTTPS protocols and guarantees
that a message is sent once and only once.

Oracle Transport Agent Page 11

Understanding the Oracle Transport Agent Messaging Protocol
July 2001
Author: Dav id Wrightson
Contributing Authors:

Oracle Corporation
World Headquarters
500 Oracle Parkway
Redwood Shores, CA 94065
U.S.A.

Worldwide Inquiries:
Phone: +1.650.506.7000
Fax: +1.650.506.7200
www.oracle.com

Oracle Corporation provides the software

that powers the internet.

Oracle is a registered trademark of Oracle Corporation. Various

product and service names referenced herein may be trademarks
of Oracle Corporation. All other product and service names
mentioned may be trademarks of their respective owners.

Copyright © 2000 Oracle Corporation

All rights reserved.