Introducing Oracle XML Gateway

This chapter describes the following sections:

What is XML Gateway? Oracle XML Gateway Services Oracle XML Gateway Architecture XML Gateway Services - Message Designer XML Gateway Services - Message Set Up XML Gateway Services - Execution Engine A Word About XML Standards

What is XML Gateway?

With Release 11i.4 of the Oracle e-Business Suite, Oracle XML Gateway emerges as a key component of Oracle's application integration framework. XML Gateway is a set of services that allows for easy integration with the Oracle e-Business Suite to create and consume XML messages triggered by business events. It integrates with Oracle Advanced Queuing to enqueue/dequeue a message which is then transmitted to/from the business partner via any message transport agent.

Oracle XML Gateway Services

Oracle XML Gateway provides the following services:

Wizard-guided, GUI-oriented, repository-based Message Designer to define data source and targets, create hierarchy and element maps plus define actions for data transformation and process control.

Robust execution engine integrated with the Oracle e-Business Suite to create and consume XML messages based on a business event. Messages are created or consumed based on the message map (associated with the trading partner) stored in the XML Gateway repository.

Flexible trading partner definition to accommodate a hub, all trading partners exchanging on a hub, or a specific business partner.

Site level trading partner directory Service to enable a message, identify a message map, and identify the communication protocol.

Flexible message set up to define code conversion values and transaction names between the sender and recipient.

Integration with the XML Parser to ensure that XML Gateway creates or consumes well-formed and valid (if DTD available) XML messages.

Active notification via Oracle Workflow to report errors detected by the XML Gateway Execution Engine, Oracle Advanced Queuing or a transport agent.

Integration with Oracle Advanced Queuing to en-queue/de-queue outbound or inbound XML messages. In addition, Oracle AQ is used to en-queue/de-queue error messages to support active error notification.

Integration of Oracle Advanced Queuing with Oracle Workflow to deliver/receive XML messages.

Oracle XML Gateway Architecture

The services supported by Oracle XML Gateway are grouped into three major components as follows:

Message Designer Message Set Up Execution Engine

Text description of the illustration adxml107.gif XML Gateway components are integrated with the following Oracle tools and technologies to provide a complete solution:

XML Parser to validate XML message is well-formed and valid (if DTD or XML Schema is available) Oracle Workflow to report processing errors Oracle Advanced Queuing to en-queue/de-queue an XML message Oracle Workflow and transport agent to deliver/receive an XML message

XML Gateway Services - Message Designer

The XML Gateway Message Designer is a wizard-guided, GUI-oriented, repositorybased tool that allows you to do the following:

Create Data Source. Every message must get it's data from some data source to create the target message meaningful to the recipient. The possible data sources supported by the Message Designer are database tables, database views, DTD or sample XML message. The common data source for outbound messages is database views (new or existing) and the relevant view columns required by the message. The common data source for inbound messages is a DTD from any XML standards body or a sample XML message. Selecting a sample XML message as a data source is a wise choice if you are transitioning from an existing implementation/legacy system to the Oracle eBusiness Suite. For each source column identified, you can use Message Designer to perform the following:
o

Define document levels if source is a DTD or XML Schema as they (DTDs) do not have the concept of document level

o o o o

Set default values Enable code conversion Indicate whether column is mandatory or not Add/delete sibling (same hierarchy) or child (next level of detail) node as necessary

Create Data Target. As with data sources, every message must have a data target. The possible data targets supported by the Message Designer are identical to what's supported for data sources. The common data target for outbound messages is a DTD from any XML standards body or a sample XML message. The common data target for inbound messages is the Application Open Interface tables (new or existing) and the relevant columns required by the message. Selecting a sample XML message as a data target is a wise choice if you are transitioning from an existing implementation/legacy system to the Oracle eBusiness Suite. For each target column identified, you can use Message Designer to perform the following:
o

Define document levels if target is a DTD as DTDs do not have the concept of document level

o o o

Set default values Indicate whether column is mandatory or not Add/delete sibling (same hierarchy) or child (next level of detail) node as necessary

Code conversion is enabled at the data source only as you are converting the source value to the value required by the recipient.

Perform Hierarchy Mapping. Once the data source and data target is created, use the Message Designer's hierarchy mapping to relate the source data structure to the target data structure.

If the document levels between the source and target are different, use the Message Designer to expand or collapse document levels as necessary.

Perform Element Mapping. Once the source and target are created and the hierarchy between the source and target is defined, use the Message Designer to map the source data element to the target data element. The Message Designer displays the data source on the left pane and the data target on the right pane. A simple drag and drop between the source and target data element creates a map relationship. The source data element name is noted next to the target data element name to identify the map relationship.

Define Actions. As part of the hierarchy or element mapping process, you can use the Message Designer to define actions for data transformation or process control. An action may be defined as follows:
o o o

At the source or target Applied at the data element, document, or root level Applied before, during or after the message is created or consumed

An action may be based on a pre-defined condition. If no condition is defined, the action will always be applied.

Table 17-1 Actions Supported by XML Gateway Action Category Action Description Assignments Create global variable Assign value from another variable Math Functions Add Subtract Multiple Divide String Functions Sub-string Concatenate Database Functions Assign next sequence value Append where clause Insert into database table Procedure Call Function Call XSLT Transformation OAG Standard Conversions Execute procedure with send and return parameters Execute function and assign function return value Execute procedure to perform XSLT transformation

Convert Oracle date to OAG date format Convert Oracle operational amount to OAG operational amount format Convert Oracle quantity to OAG quantity format Convert Oracle amount to OAG amount format Convert OAG date to Oracle date format Convert OAG operational amount to Oracle operational amount Convert OAG quantity to Oracle quantity format Convert OAG amount to Oracle amount format

Return Error Code to Sender

Return error code and error message to sender

Get Global Variable Value

Get global variable value

DOCUMENT_ID RETURN_CODE RETURN_MESG SENDER_TP_ID RECEIVER_TP_ID CODE_CONVERSION

Other

Exit program

The most common actions are the OAG standard conversions to convert Oracle's representation for date, operational amount, quantity, and amount values to the OAG format and vice versa. The ability to inquire on the status of the Execution Engine allows flexible process control based on the severity of an error. For serious errors, the process may be aborted with error messages returned to the sender via an Oracle Workflow process. The convenience of calling out to existing procedures or functions enables tight integration with the Oracle e-Business Suite. Once the message map is defined, it is loaded into the XML Gateway repository for use by the Execution Engine to create outbound or consume inbound XML messages.

XML Gateway Services - Message Set Up

To implement a message with a trading partner, use XML Gateway Services message set up to define the trading partner or hub, code conversion values, and transaction name cross references. In addition, you can identify where on the file system to store the DTDs, XML messages and process LOG files.

Define Trading Partner/Hub. E.-Business may be conducted directly with a business partner commonly known as a trading partner or via a hub such as Exchange where many buyers and sellers converge to conduct electronic commerce. With Oracle XML Gateway services, you can define the hub or the actual business partner as a trading partner. If you define the hub as the trading partner, you can identify all the buyers and sellers who are conducting business on the hub as trading partners to the hub. Included in the trading partner/hub definition is the following information:
o o o o

Trading Partner/Hub name Message enabled Message map to use for message creation or consumption Communication protocol - SMTP, HTTP, HTTPS and username/password as necessary

Trading partner specific code conversion values

Define Code Conversion. The Oracle XML Gateway service for code conversion allows you indicate what to convert an Oracle code to so that it is meaningful to the recipient or vice versa. Common Oracle e-Business Suite codes requiring code conversion are units of measure and currency code.

Oracle XML Gateway provides a seeded master list of code conversion values which may be applied to any data element of any message. Additional code conversion values may be added to the master list if the seeded list is insufficient. In addition, you may define a trading partner specific code conversion value which will be applied for that trading partner only.

Define Transaction. Use Oracle XML Gateway to define a cross reference between the Oracle transaction name and a transaction name meaningful to the recipient. For the pre-built messages delivered with the Oracle e-Business Suite, the cross referenced name is the verb/noun (i.e. Process PO or Show Delivery) combination defined by the OAG Business Object Document (OAG BOD).

Identify DTD Directory. Use Oracle XML Gateway to identify a directory on the file system to store the DTD used to implement the message. The XML Gateway Execution Engine and XML Parser will use the DTDs stored in this directory to validate all outgoing and incoming messages to ensure that they are well-formed and valid.

Identify XML Message and Process Log Directory. Use Oracle XML Gateway to identify a directory on the file system for the XML Gateway Execution Engine to store a copy of the XML message and it's associated process log file. Both the XML message and process log file may be archived or used for trouble shooting.

XML Gateway Services - Execution Engine

The XML Gateway Execution Engine interfaces with the Oracle e-Business Suite, XML Gateway Set Ups and Oracle Advanced Queuing to perform the following functions:

Start/Stop Engines associated with the inbound, outbound, and error queues Allow users to manually trigger message creation if message creation is not trigger by a business event in the Oracle e-Business Suite

Interface with Oracle e-Business Suite to produce an outbound message Validate Trading Partner/Hub. If the Trading Partner is not defined or the document is not defined for the Trading Partner, no message will be produced.

Get Message Map from Repository. If the message map associated with the Trading Partner is not available in the XML Gateway repository, no message will be created.

Gather Application Data. If the Trading Partner is valid and the message map exist in the repository, the XML Gateway Execution Engine gathers the application data from the Oracle e-Business Suite using the database view and columns identified in the message map.

Apply Code Conversion. Apply code conversion for source columns enabled for code conversion

Apply Actions. Apply actions where defined (may be document or element level) Create XML Message. Create XML message using the message map and the application data

Validate Message via XML Parser. Use 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 DTD stored in DTD directory) will not be en-queued onto the Outbound Queue.

Enqueue Message to Outbound Queue. Enqueue well-formed and valid message onto the Outbound Queue to be picked up by the transport agent for delivery to the trading partner.

Interface with Oracle e-Business Suite to consume an inbound message Dequeue Message from Inbound Queue Validate Message via XML Parser. Use the XML Parser to validate the inbound message to determine if it is well-formed and valid (based on DTD stored in DTD directory) before proceeding further.

Validate Trading Partner/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 message cannot 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 message cannot be processed further.

Apply code conversion for source columns enabled for code conversion Apply actions where defined (may be document or element level) including inserting data into the Application Open Interface tables and then finally executing the Open Interface API to populate the base application tables.

Detect and Report Processing Errors. Errors may be detected by the Oracle XML Gateway Execution Engine, Oracle Advanced Queuing, or a transport agent. Information regarding the error is en-queued onto the Error Queue. A notification is sent via Oracle Workflow to notify the trading partner regarding data errors or the XML Gateway system administrator regarding system/process errors.

In addition, for system/process errors, a copy of the XML message is placed in the XML message directory for use in trouble shooting the reported error. For trading partner related data errors, the trading partner can refer to their copy of the XML message. The XML Gateway listeners are actively polling for messages and will begin processing once it detects that something has arrived on the transaction queue. The XML Gateway Execution Engine will take the document information from the transaction queue and begin the process of creating or consuming an XML message as described above.

A Word About XML Standards

Many standards bodies (for example, EbXML, Rosettanet, SOAP, iFX) exist with published Document Type Definitions (DTD) each claiming to be better than the other. Some standards are strong at managing the message content while others excel at managing both the message content and its related processes. As a provider of software to support all industries, Oracle has chosen to align with Open Application Group's (OAG) XML standards for broad based message implementation. OAG is also the standard most widely adopted by the Oracle customer base. All Oracle pre-built messages delivered with the Oracle e-Business Suite will be based on the OAG standards. However, all pre-built messages may be re-mapped to any standard of choice using the XML Gateway Message Designer provided a DTD or XML Schema Definition is available.