Execution Engine
This chapter covers the following topics:
- Execution Engine Overview
- Protocol Type
- XML Gateway Envelope
- Trading Partner Validation for Inbound Messages
- Trading Partner Validation for Outbound Messages
- Dynamic Embedding of XML Fragments
- How to Implement the OAG Confirmation Business Object Document
Execution Engine Overview
The XML Gateway consists of three components: the Message Designer, Setup, and the Execution Engine. It interfaces with the following Oracle products:
-
Oracle Transport Agent for message delivery
-
Oracle Advanced Queuing for message propagation, and queue management
-
Oracle Workflow Business Event System to publish and subscribe to business events. Workflow also provides an active e-mail notification to report errors detected by the XML Gateway Execution Engine, Advanced Queuing (AQ), or the transport agent
The following diagram illustrates the process flow of XML messages through the XML Gateway Execution Engine using all the components mentioned above. Details of the XML Gateway Execution Engine are summarized below.
The XML Gateway Execution Engine can process messages properly after the following:
-
Message maps are created and loaded into the repository along with their associated DTDs.
-
Trading Partners are defined.
-
Code Conversions are defined.
-
Transactions are defined.
-
Oracle Workflow Business Event System events are published by the Oracle E-Business Suite and subscriptions to those events are defined.
-
Engine and listeners are started.
The XML Gateway listeners are actively polling for interested events. The Execution Engine will begin processing once Oracle Workflow Business Event System detects an outbound transaction to be processed, or that an inbound message has arrived on the queue.
The XML Gateway Execution Engine does the following during processing:
-
(Inbound Message) Dequeue Message from Inbound Queue
-
Validate Message via XML Parser
(Inbound Message) Uses the XML Parser to validate the inbound message to determine if it is well-formed and valid (based on a DTD stored in the DTD directory) before proceeding further.
(Outbound Message) Uses the XML Parser to validate the newly created message to ensure that it is well-formed and valid. A poorly formed or invalid message (based on a DTD stored in the DTD directory) will not be enqueued onto the Outbound Queue.
-
Validate Trading Partner or Hub
If the inbound message is both well-formed and valid, the Execution Engine proceeds to validate that the Trading Partner and document are defined. If the Trading Partner is not defined or the document is not defined for the Trading Partner, the XML message will not be processed further.
-
Get Message Map from Repository
If the message map associated with the Trading Partner is not available in the XML Gateway repository, the XML message will not be processed further.
-
Execute the Message Map
-
(Outbound Messages) Gather Application Data
If the Trading Partner is valid and the message map exists in the repository, the Execution Engine gathers the application data from the Oracle e-Business Suite using the database views and columns identified in the message map.
-
(Inbound Messages) Maps Data
If the Trading Partner is valid and the message map exists in the repository, the Execution Engine maps the data in the XML message to its target data fields in Oracle e-Business Suite tables and columns identified in the message map. These are often the Application Open Interface tables.
-
Apply Code Conversion
Apply code conversion for source columns enabled for code conversion.
-
Apply Actions
Apply actions where defined (may be document, element, or root level).
(Inbound Message) Action codes include inserting data into the Application Open Interface tables, then executing the Application Open Interface API to populate the base application tables.
-
(Outbound Messages) Create XML Message
Create XML message using the message map and the application data as described above.
-
-
Dynamically Add XML Fragments
XML Gateway allows the dynamic addition of XML Segments at runtime as a child, not a sibling, to any element defined on the Outbound XML Gateway Map.
-
Detect and Report Processing Errors
Errors may be detected by the Oracle XML Gateway Execution Engine, Oracle Advanced Queuing, Oracle Workflow, or Oracle Transport Agent. Information regarding the error is enqueued onto the Error Queue. An e-mail notification is sent via Oracle Workflow to notify the trading partner regarding data errors, or the XML Gateway system administrator regarding system or process errors.
In addition, for system or process errors, a copy of the XML message is placed in the XML message directory for use in troubleshooting the reported error. For trading partner-related data errors, the trading partner can refer to the copy of the XML message.
-
Copy XML Message
For system or process errors, a copy of the XML message is placed in the XML message directory for use in troubleshooting the reported error. For trading partner-related data errors, the trading partner can refer to their copy of the XML message.
-
(Outbound Messages) Enqueue Message to Outbound Queue
Enqueue well-formed and valid message onto the Outbound Queue. Oracle Transport Agent will dequeue the message from the Outbound Queue and deliver it to the trading partner.
-
Create or Consume Confirmation Messages
(Inbound Message) Receive confirmation message, if it is enabled for the Trading Partner and confirmation is requested on the outbound message, or a default is set up for the trading partner.
(Outbound Message) Create a confirmation message, if it is enabled for the Trading Partner and confirmation is requested on the inbound message, or a default is set up for the trading partner.
Protocol Type
Each message enabled for a Trading Partner includes a protocol type (also known as communication method) that identifies the message delivery method. The associated correlation ID is determined internally and is associated with the message enqueued onto the agent (queue). Listeners defined for the agent will dequeue messages based on the correlation ID defined for it. For example, Oracle Transport Agent will only dequeue messages with a correlation ID of OXTA.
The following table shows the Protocol Type, Correlation ID, and Message System.
| Protocol Type | Correlation ID | Message System |
|---|---|---|
| NONE | N/A | Message disabled |
| HTTP, HTTP-OXTA, HTTPS, HTTPS-OXTA, SMTP | OXTA | Oracle Transport Agent without attachments |
| OTAH-ATCH, OTAHS-ATCH | OXTA | Oracle Transport Agent with attachment using standard OTA envelope |
| HTTP-ATCH, HTTPS-ATCH | OXTA | Oracle Transport Agent with attachment and no OTA envelope |
| ITG03 | ITG03 | Oracle iProcurement Connector, must be enabled |
| IAS | IAS | Oracle Application Server, must be enabled |
| HTTP-WM, HTTPS-WM | WebMethods | Third party system available only to users of Oracle Exchange |
| SOAP | N/A | Web Service Agent |
| JMS | N/A | JMS Provider |
The following graphics display the construction for each protocol type:
-
For protocol types HTTP(S) and HTTP(S)-OXTA, the OTA servlet dequeues the message payload and constructs the OTA envelope.
-
For protocol type OTAH(S)-ATCH, the OTA servlet dequeues the message payload, constructs the OTA envelope, and assembles the attachment(s).
-
For protocol type HTTP(S)-ATCH, the OTA servlet dequeues the message payload and assembles any attachments, if present.
For protocol type SOAP, the Web Services provider dequeues the message payload, assembles any attachments, and constructs the SOAP envelope.
XML Gateway Envelope
In addition to the business document such as a purchase order or invoice in the XML Payload, a set of message attributes are transmitted. Collectively, these attributes are called the XML Gateway envelope.
This section discusses the XML Gateway envelope and its data in the validation process for inbound messages, or its source of data for its creation for outbound messages. Data entered into the Trading Partner Setup form is referred to as data in the trading partner table. Data entered into the Define Transactions form is referred to as data in the transaction table.
Most of the data elements are copied from the Trading Partner tables or the Transaction tables to the XML Gateway envelope.
Transaction direction is determined by the XML Gateway. The direction values used by the XML Gateway are the following:
-
IN for inbound messages
-
OUT for outbound messages
The XML Gateway envelope consists of the data presented in the following table:
| Attribute | Contents | Sample Values | Data Source |
|---|---|---|---|
| MESSAGE_TYPE | Payload message format | XML | (Hard-coded) |
| MESSAGE_STANDARD | Message format standard | OAG | Transaction table |
| TRANSACTION_TYPE | External Transaction Type for that business document | INVOICE | Trading Partner table |
| TRANSACTION_SUBTYPE | External Transaction Subtype for that business document | PROCESS | Trading Partner table |
| DOCUMENT_NUMBER | Business document number such as invoice number | (Not Used) | N/A |
| PARTYID | (Not Used) | (Not Used) | Trading Partner table. This is not used by the XML Gateway. |
| SOURCE_TP_LOCATION_CODE | Source Trading Partner Location Code | ACME_CHICAGO | SOURCE TP LOCATION (if not recreated) or TARGET TP LOCATION CODE (if recreated) from Trading Partner table |
| PARTY_TYPE | (Not Used) | (Not Used) | (Not Used) |
| PROTOCOL_TYPE | Transmission Protocol | SMTP, HTTP, HTTP-WM | Trading Partner table |
| PROTOCOL_ADDRESS | Transmission Address | me@co.com, http://www.co.com:5555 | Trading Partner table |
| USERNAME | User Name | User1 | Trading Partner table if Connection is "DIRECT"; Hub Definition if "HUB" |
| PASSWORD | password | ****** | Trading Partner table if Connection is "DIRECT"; Hub Definition if "HUB" |
| ATTRIBUTE1 | (determined by application) | N/A | (determined by application) |
| ATTRIBUTE2 | (determined by application) | N/A | (determined by application) |
| ATTRIBUTE3 | Rerouting Location (used only if the message is rerouted) | TARGET TP LOCATION CODE from Trading Partner table | |
| ATTRIBUTE4 | (determined by application) | N/A | (determined by application) |
| ATTRIBUTE5 | (determined by application) | N/A | (determined by application) |
| PAYLOAD | XML business document | (XML Message) |
MESSAGE_TYPE
Payload message format. This defaults to "XML".
MESSAGE_STANDARD
(Defaults to OAG.) Message format standard as displayed in the Define Transactions form and entered in the Define XML Standards form.
TRANSACTION_TYPE
External Transaction Type for the business document from the Trading Partner table.
TRANSACTION_SUBTYPE
External Transaction Subtype for the business document from the Trading Partner table.
DOCUMENT_NUMBER
The document identifier used to identify the transaction, such as a purchase order or invoice number. This field is not used by the XML Gateway, but it may be passed on inbound messages.
SOURCE_TP_LOCATION_CODE
Source Trading Partner Location Code if no data is found in the Destination Trading Partner Location Code in the Trading Partner table.
PROTOCOL_TYPE
Transmission Protocol as defined in the Trading Partner table.
PROTOCOL_ADDRESS
Transmission address as defined in the Trading Partner table.
USERNAME
USERNAME as defined in the Trading Partner table.
PASSWORD
The password associated with the USERNAME defined in the Trading Partner table.
ATTRIBUTE3
For outbound messages, this field has the value from the Destination Trading Partner Location Code in the Trading Partner table.
For inbound messages, the presence of this value generates another XML message that is sent to the trading partner identified in the Destination Trading Partner Location Code in the Trading Partner table. This value must be recognized by the hub to forward the XML message to the final recipient of the XML Message. Refer to XML Gateway Setup for details.
PAYLOAD
The XML message.
Parameters defined by the Application
The following parameters may be defined by the base application:
-
ATTRIBUTE1
-
ATTRIBUTE2
-
ATTRIBUTE4
-
ATTRIBUTE5
Parameters Not Used
The following parameters are not used:
-
PARTYID
-
PARTYTYPE
Trading Partner Validation for Inbound Messages
Events Raised in Oracle Workflow Business Event System
Oracle Workflow Business Event System is a tool used to integrate with the Oracle e-Business Suite for event-based XML message creation and consumption.
Before XML Gateway processes the message:
Messages sent by the trading partner are staged onto a message queue. An Oracle Workflow listener dequeues the message from the message queue and raises an event to the XML Gateway to begin processing.
Refer to Message Queues for details.
After XML Gateway processes the message:
When XML Gateway completes processing the data according to the instructions in the message map associated with the trading partner, an event is published by XML Gateway to inform the Oracle e-Business Suite that it has successfully processed the inbound message. Any Oracle e-Business Suite module interested in this event may register a subscription to continue with the transaction.
XML Gateway Processing
Inbound messages can take two paths:
-
Standard XML Messages
If ATTRIBUTE3 in the XML Gateway envelope is NULL, the XML message is processed according to the message map.
-
"Pass-Through" Messages
If ATTRIBUTE3 in the XML Gateway envelope has data, the inbound message will be recreated as an outbound message according to a message map for the trading partner identified in ATTRIBUTE3. This transaction is referred to as a "pass-through" message and defined as a message with "Dynamic Routing." Refer to Static and Dynamic Routing for details.
Standard XML Messages
The following table summarizes the required data in the XML Gateway envelope to identify standard XML messages. How this data is validated for an inbound message is described below.
| Attribute | Sample Values | Used in Trading Partner Lookup |
|---|---|---|
| MESSAGE_STANDARD | OAG | YES |
| TRANSACTION_TYPE | INVOICE | YES |
| TRANSACTION_SUBTYPE | PROCESS | YES |
| PARTY_SITE_ID | ACME_CHICAGO | YES |
| ATTRIBUTE3 | NULL | NO |
| PAYLOAD | (XML MESSAGE) | N/A |
Note: USERNAME and PASSWORD can be placed in the XML Gateway envelope by the system that created the XML message. The transport agent uses the USERNAME and PASSWORD for delivery purposes. These fields are not passed to the XML Gateway from the transport agent software.
"Pass-Through" XML Messages
XML Gateway can recreate, then route messages to another trading partner without loading the transaction into a base Oracle E-Business Suite application. This case is recognized by the presence of a trading partner code in ATTRIBUTE3 in the XML Gateway envelope in the inbound message.
If a trading partner location code is identified in ATTRIBUTE3 for an inbound message the following happens:
-
A Trading Partner Setup table entry for an outbound message for this same TRANSACTION_TYPE and TRANSACTION_SUBTYPE is found for the Trading Partner identified in ATTRIBUTE3. The values in ATTRIBUTE3 must match an entry in the Destination Trading Partner Location Code defined in the Trading Partner Setup form.
-
If the entity in ATTRIBUTE3 is found in the Trading Partner Setup tables, then another XML Gateway message is created according to the message map for that trading partner. This new XML message is then routed to the trading partner identified in the original ATTRIBUTE3.
The following table summarizes the required data in the XML Gateway envelope to identify these messages, and key data for the pass through XML message.
| Attribute (Original XML Message) | Sample Inbound Message Values | Pass-Through Message Created (Find its corresponding Trading Partner Setup for an OUTBOUND message where the Trading Partner is identified in ATTRIBUTE3 of the original message) |
|---|---|---|
| MESSAGE_STANDARD | OAG | OAG |
| TRANSACTION_TYPE | INVOICE | INVOICE |
| TRANSACTION_SUBTYPE | PROCESS | PROCESS |
| PARTY_SITE_ID | ACME_CHICAGO | BETA-LONDON (from original ATTRIBUTE3) |
| ATTRIBUTE3 (the DESTINATION TRADING PARTNER LOCATION CODE in the Trading Partner Setup table. This becomes the PARTY_SITE_ID for the outbound message.) | BETA-LONDON | |
| PAYLOAD | (XML Message) | (XML Message) |
Validation Against Data in the Trading Partner Setup Form
Inbound messages validate data only against data that was entered in the Trading Partner Setup form.
Source Trading Partner Location Code
Source Trading Partner Location Code is the code found in the XML envelope in PARTY_SITE_ID to identify the source of the message. This field must contain a value stored in Source Trading Partner Location Code in the Trading Partner setup table.
When a trading partner is entered into the Trading Partner Setup form, the Trading Partner Name and Trading Partner Site are selected from a list of values obtained from Oracle Receivables, Oracle Payables, or Oracle HR Locations. Associated with each Trading Partner site is a table ID in the base application. See Derive Address ID from Location Code action and Get Predefined Variable Value action if you wish to use this table ID in a message map.
The parameters listed in the table below compose a search key against the Trading Partner table. This key is used to determine if the Trading Partner is enabled for that transaction, then to retrieve the message map name to process the transaction.
| Search Parameters | Description | Sample |
|---|---|---|
| PARTY_SITE_ID | Source Trading Partner Location Code | ACME_CHICAGO |
| TRANSACTION_TYPE | External Transaction Type for that business document | INVOICE |
| TRANSACTION_SUBTYPE | External Transaction Subtype for that business document | PROCESS |
| DIRECTION | Determined by the XML Gateway | IN |
The following table shows data that is returned from a search against data that was entered in the Trading Partner Setup form:
| Returned Data | Description | Sample |
|---|---|---|
| Trading Partner Site enabled for the message | This data is stored in the table given the trading partner that was selected. This data is not displayed. | 12345 (a table ID) |
| Message Map to use for this inbound transaction for the given trading partner | OAG_IN_INVOICE |
Note that transaction direction is determined by the XML Gateway. The direction values used by the XML Gateway are the following:
-
IN for inbound messages
-
OUT for outbound messages
Trading Partner Validation for Outbound Messages
Event Raised in Oracle Workflow Business Event System
Application business events for outbound messages are raised by the Oracle e-Business Suite module responsible for the transaction. The raise occurs at an application point of interest, such as when a purchase order is approved or an invoice is confirmed.
Event Subscription Defined in Oracle Workflow Business Event System
A corresponding event subscription is defined to consume the event. The event subscription may be based on the XML Gateway Rule Function or the Workflow Default Rule Function. Embedded in the XML Gateway Rule Function is a check to determine if the Trading Partner is defined and the message is enabled.
With the Workflow Default Rule Function, the Transaction Delivery Required function activity is used to make the same evaluation. The outbound document is generated and sent only if the Trading Partner is defined and the transaction is enabled. Which approach is used depends on what is known about the Trading Partner before the subscription is executed.
See: Integrating Oracle XML Gateway with Oracle Workflow Business Event System.
Dynamic Embedding of XML Fragments
XML Gateway can dynamically add XML segments at runtime as a child to any element defined on the Outbound XML Gateway Map during message generation.
To use this feature, users should create an In Process 'Execute Procedure' Action to execute procedure ECX_ACTIONS.GET_XML_FRAGMENT at the element under which the dynamic XML segment needs to be added. This procedure is available under APPS schema.
The API Signature
ECX_ACTIONS.get_xml_fragment
(proc_name IN varchar2,
xml_fragment OUT NOCOPY varchar2);
-
Proc_name: Name of the called procedure. This procedure should have the signature with the first IN parameter Event as wf_event_t and second OUT parameter xml_fragment as varchar2. In other words, this procedure takes wf_event_t as an input parameter and gives xml_fragment as an output.
For example,
my_pkg.my_procedure (event IN wf_event_t, xml_fragment OUT NOCOPY varchar2);The workflow event passed as an input parameter is packaged with all the global variables. Users need to use global variables in case context needs to be passed to the called procedure.
-
xml_fragment: Name of the node at which the XML fragment will be returned.
How to Implement the OAG Confirmation Business Object Document
Purpose of the Confirmation Message
The purpose of the confirmation message is to communicate the status of a business document. In addition to providing general document status information, details regarding any errors detected may be included in the confirmation message.
The confirmation message is a general-purpose document that may be used to acknowledge any business document. It may be used in addition to but not as a substitute for specific purpose acknowledgements such as Purchase Order Acknowledgment or Purchase Order Change Acknowledgment documents.
Refer to www.openapplications.org for details regarding the Confirm Business Object Document (BoD) DTD.
Structure of the Confirmation Message
The confirmation message contains the following two parts:
-
CONFIRM_BOD/CONFIRM
The CONFIRM data type is used to describe the business document it is acknowledging. Included are the document status, description of the document, and an identifier for the original business document.
-
CONFIRM_BOD/CONFIRMMSG
The CONFIRMMSG data type is used to provide a detailed description of the document status. Included are the description and any reason codes. Each CONFIRM data type may have many CONFIRMMSG data types associated with it.
XML Gateway Seeded Confirmation Message Maps
Oracle XML Gateway provides seeded maps for both the inbound and outbound Confirm BoD message. The names of the seeded message maps are as follows:
-
ECX_CBODI_OAG72_IN_CONFIRM
-
ECX_CBODO_OAG72_OUT_CONFIRM
The XML Gateway seeded maps are incorporated into the Oracle E-Business Suite application business process where necessary.
E-Business Suite Seeded Events and Event Subscriptions
Usage of the Confirm BoD varies between application modules of the Oracle E-Business Suite. For application modules that have incorporated the Confirm BoD into their business processes, the process is modeled as follows:
Outbound Confirmation
Oracle XML Gateway sends an outbound confirmation message in response to an inbound business document.
The inbound business document initiates the process (Step 1). As with all inbound messages, XML Gateway notifies the Oracle E-Business Suite application that it has processed an inbound business document.
The application event subscription defined for the inbound document is executed (Step 2) and is followed by a raise event (Step 3) to notify XML Gateway to create and send the outbound confirmation (Step 4).
Steps 2 and 3 are defined separately to allow for application business processes between the consumption of the inbound business document and the creation and delivery of the outbound confirmation message.
Inbound Confirmation
Oracle XML Gateway will process an inbound confirmation message received from a the Trading Partner in response to an outbound business document. It will notify the Oracle E-Business Suite that it has processed an inbound confirmation message.
The application event subscription defined for the inbound confirmation message is executed. The behavior of the event subscription will vary by application module and is dependent on whether the application module is interested in negative, positive, or both types of confirmations.
How to Implement or Disable a Seeded Confirmation Message
The application event subscriptions to create and send an outbound message or to consume an inbound message are delivered by the Oracle E-Business Suite application modules.
The seeded event name for the inbound or outbound Confirm BoD message is as follows:
ORACLE.APPS.<COMPONENT>.<TASK>.CONFIRM
COMPONENT is the internal transaction type entered on the Define Transactions form. It represents the product short name.
TASK is the internal transaction subtype entered on the Define Transactions form. It represents a description of the object.
An example of an event name for a confirmation event associated with an outbound purchase order is: ORACLE.APPS.PO.POO.CONFIRM.
The corresponding seeded event subscription is defined as enabled. Use the Oracle Workflow Administrator: Add Events/Event Group window to view or disable the seeded events and event subscriptions if you do not wish to implement the Confirm BoD message.
To implement the seeded event subscriptions, define the Trading Partner and enable the confirmation message as follows:
-
Define the Trading Partner using the XML Gateway Define Trading Partners form.
-
Enable the business document and set the Document Confirmation flag to one of the following:
1 = Send confirmation only if there are errors
2 = Always send confirmation
Important: Ensure that for an outbound business document you enable an inbound confirmation document (Transaction Subtype CBODI); and for an inbound business document you enable an outbound confirmation document (Transaction Subtype CBODO).
Note: Make sure that the value for Source Trading Partner Location Code is the same for the original business document and its corresponding confirmation document.
Refer to Trading Partner Setup for more details on setting up the Trading Partner to implement the confirmation message.