ota revised

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



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.


The OTA Message Propagation flow (with SSL enabled)

OXTA Server as client OXTA Server as server

(Sender) (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=


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 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:

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 – 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 Sample TRANSPORT_PROTOCOL OXTA TRANSPORT_PROTOCOL_VERSION 1.0 REQUEST_TYPE EME USERNAME MYUSERNAME PASSWORD MYPASSWORD PROTOCOL_ADDRESS [email protected] 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.

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 [email protected]

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.


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:


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 Description What happened on the server/client 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 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 Exceeded the max number of attempts for transport

4100 Mail Server Not Set Mail server not set up in config 4101 Incorrect E-mail Address Format Email address format incorrect

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

Server Response from the server not in a format 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:

• 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


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 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.

ota revised

Documents