Understanding the Oracle Transport Agent Messaging Protocol

An Oracle White Paper July 2001 (Revised July 2006)

Understanding the Oracle Transport Agent Messaging Protocol

Overview............................................................................................................. 3 The Oracle Transport Agent Protocol stack................................................. 3 Oracle Transport Agent Post Message........................................................... 4 Transport Agent Protocol................................................................................ 5 Oracle Transport Agent Response Message.................................................. 8 Connecting to Non-OTA Servers................................................................. 10 CONCLUSION .............................................................................................. 11

Understanding the Oracle Transport Agent Messaging Protocol

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

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.

Understanding the Oracle Transport Agent Messaging Protocol

Page 3

The OTA Message Propagation flow (with SSL enabled)

OXTA Server as client (Sender) OXTA Server as server (Receiver)

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; base 64 encoding is used for the username:password encryption):

HTTP Header Http-Version: HTTP/1.1

Authorization: BASIC c3lzYWRtaW46c3lzYWRtaW4=

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.me.com/servlets/oracle.apps.ecx. oxta.TransportAgentServer USERNAME=myusername PASSWORD=myloginpassword ATTRIBUTE1= ATTRIBUTE2= ATTRIBUTE3=

Understanding the Oracle Transport Agent Messaging Protocol

Page 4

ATTRIBUTE4= ATTRIBUTE5= PAYLOAD=<xml ..>

TRANSPORT AGENT 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 TRANSPORT_PROTOCOL TRANSPORT_PROTOCOL_VERSION REQUEST_TYPE USERNAME PASSWORD Sample OXTA 1.0 AUTH MYUSERNAME 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:
Parameter TRANSPORT_PROTOCOL TRANSPORT_PROTOCOL_VERSION REQUEST_TYPE USERNAME PASSWORD PARTY_SITE_ID TRANSACTION_TYPE Sample OXTA 1.0 AUTH2 MYUSERNAME MYPASSWORD 123 PO

Understanding the Oracle Transport Agent Messaging Protocol

Page 5

TRANSACTION_SUBTYPE

PROCESS

EME E-mail 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 TRANSPORT_PROTOCOL TRANSPORT_PROTOCOL_VERSION REQUEST_TYPE USERNAME PASSWORD PROTOCOL_ADDRESS PAYLOAD Sample OXTA 1.0 EME MYUSERNAME MYPASSWORD Me@mydomain.com <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.
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.

Understanding the Oracle Transport Agent Messaging Protocol

Page 6

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 HTTP HTTPS HTTP-OXTA HTTPS-OXTA SMTP Meaning Straight HTTP post Straight HTTP post using SSL Use OTA protocol over HTTP Use OTA protocol over Send document via SMTP (email)

PROTOCOL_ADDRESS

This is the fully qualified address used by OTA to transmit the document to. Examples:
PROTOCOL_TYPE HTTP HTTP-OXTA HTTPS-OXTA SMTP PROTOCOL_ADDRESS http://www.me.com:8080/servlets/mycustom http://www.me.com:9000/servlets/oracle.apps.ecx.oxta.Transp ortAgentServer https://www.me.com/servlets/oracle.apps.ecx.oxta.TransportA gentServer 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.
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.

Understanding the Oracle Transport Agent Messaging Protocol

Page 7

ATTRIBUTE1

This contains the identifier of the system sending the message. This is a userdefined 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 userdefined 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:

Understanding the Oracle Transport Agent Messaging Protocol

Page 8

The HTTP Response Body is created for information only and is not read by the 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 lists the valid response status codes returned in the HTTP Response by the OTA server:
Status Code 1000 2000 2001 Description OK Database Unavailable Unknown Serverside Error What happened on the server/client side Request handled successfully Cannot get connection to the database Unexpected exceptions on the server side due to whatever reasons. Client should retry in this case. Values of TRANSPORT_PROTOCOL, TRANSPORT_PROTOCOL_VERSION or MESSAGE_TYPE is missing Value of MESSAGE_TYPE is unrecognized Username or password not found in request User-password didnt get through OTA Protocol version not supported by server For an SEND post, some required parameters is missing from the request Content-length is not set in request Size of content too large, when checking content size in the header For an AUTH2 request, parameter is missing from the request (party_site_id or transaction_type)

3000

Bad Request

3001 3002 3003 3004 3100 3101 3102 3200

Unknown Request Type Incomplete Credentials Authentication Failure OTA Version Not Supported Value Missing For SEND Length Required Length Too Large Values Missing For AUTH2

Understanding the Oracle Transport Agent Messaging Protocol

Page 9

3201 3300 3301 3302 4000 4001 4002 4003 4100 4101 4102 4200 4201 4202 4203 4300 4301 4302

AUTH2 Failure Values Missing For EME Incorrect E-mail Address Format For EME Mail Server Not Set Unknown Protocol Type Timeout Exceeded Unknown Clientside Exception Max Transport Attempts Exceeded Mail Server Not Set Incorrect E-mail Address Format Cannot Send E-mail Incorrect URL Format Failure Connecting to Proxy Failure Connecting to Server Unknown Response From Server Invalid CACert File SSL Handshake Failure SSL Verify Cert Chain Failure

AUTH2 failed for any reason EMAIL address or payload is not passed in the EME request

Mail server not set up in config Send protocol type unknown (not HTTP, HTTPS, SMTP) Time out for this transport action reached Any other exceptions on the client side. Exceeded the max number of attempts for transport Mail server not set up in config Email address format incorrect Error when trying to send mail URL format incorrect Cannot open connection to the proxy server Cannot connect to host:port Response from the server not in a format which the client can understand Failed to open the cert file / failed to read cert from the file Failure to perform handshake when getting SSL Connection 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:

No guaranteed delivery No guaranteed only-once delivery No message tracking ID available to the sender Message ownership completely with the servlet that received the message

Understanding the Oracle Transport Agent Messaging Protocol

Page 10

CONCLUSION

The Oracle Transport Agent provides a secured means of delivering and receiving messages using SMTP, HTTP, or HTTPS protocols and guarantees that a message is sent once and only once.

Understanding the Oracle Transport Agent Messaging Protocol

Page 11

Understanding the Oracle Transport Agent Messaging Protocol July 2006 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.