Using XML Gateway of Oracle Application Server Adapter

This chapter covers the following topics:

• Overview of XML Gateway
• Design-Time Tasks for XML Gateway Inbound Messaging
• Creating a New BPEL Project
• Creating a Partner Link
• Configuring the Invoke Activity
• Adding a Partner Link for the File Adapter
• Configuring the Receive Activity
• Configuring the Assign Activity
• Run-Time Tasks for XML Gateway Inbound Messaging
• Deploying the BPEL Process
• Testing the BPEL Process
• Verifying Records in Oracle Applications
• Design-Time Task for XML Gateway Outbound Messaging
• Configuring XML Gateway for Outbound Messaging
• Run-Time Task for XML Gateway Outbound Messaging
• Testing the BPEL Process
• Troubleshooting and Debugging

Overview of XML Gateway

The OracleAS Adapter for Applications provides a bridge between Oracle Applications and third party applications. Inbound and outbound XML data is exchanged between Oracle Applications and third party applications through the XML Gateway.

Oracle XML Gateway provides a common, standards-based approach for XML integration between Oracle Applications and third party applications, both inside and outside your enterprise. XML is key to an integration solution, as it standardizes the way in which data is searched, exchanged, and presented thereby enabling interoperability throughout the supply chain.

Oracle XML Gateway is a set of services that allows easy integration with Oracle Applications to support XML messaging. Oracle Applications utilize the Oracle Workflow Business Event System to support event-based XML message creation and consumption.

OracleAS Adapter for Applications can be configured to use XML Gateway to interact with third party applications. The tight integration provided by open interface tables is not suitable for those scenarios where trading partners change frequently. XML Gateway is an ideal solution when you need to interact with third party applications that use open standards. Moreover, it is also suitable for scenarios where trading partners change frequently.

Standards-Based Messaging

As a provider of broad based business application solutions to support all industries, Oracle XML Gateway supports all Document Type Definition (DTD) based XML standards. The majority of the Oracle prebuilt messages delivered with Oracle Applications are premapped using the Open Application Group (OAG) standard. Any Oracle prebuilt message map may be remapped to your standard of choice using the XML Gateway Message Designer.

Integration Architecture

XML Gateway provides an application integration infrastructure that is flexible enough to accommodate the integration requirements of any application that needs to integrate with Oracle Applications. XML Gateway enables you to create an efficient and responsive supply chain that links all customers, factories, warehouses, distributors, carriers, and other trading partners. All these entities can seamlessly operate as a single enterprise.

Oracle XML Gateway supports both Business-to-Business (B2B) and Application-to-Application (A2A) initiatives. B2B initiatives include communicating business documents and participating in industry exchanges. An example of an A2A initiative is data integration with legacy and disparate systems.

XML Gateway enables bidirectional integration with Oracle Applications by allowing you to insert and retrieve data from Oracle Applications. The Oracle Applications adapter for XML Gateway supports two operations, namely, enqueue and dequeue. The enqueue operation is used to put messages in the queue. This is used to insert inbound data into Oracle Applications. The dequeue operation polls for messages from the queue. This is used to retrieve outbound data from Oracle Applications. Only one operation can be defined for each adapter service.

XML Gateway Integration Architecture

Message Queues

The XML Gateway uses queues specifically at two points in the process as well as employing a general error queue. The first point is at the transport agent level between the transport agent module and the XML Gateway. The second point is at the transaction level between base Oracle Applications products and the XML Gateway.

Inbound Queues

Inbound message queues are used for XML messages inbound into Oracle Applications. Inbound message queues are positioned between the Transport Agent and the Oracle Workflow Business Event System.

The messages must be formatted according to the XML Gateway envelope message format. The envelope message format is discussed under XML Gateway Envelope. Oracle Workflow Business Event System copies the inbound messages to the proper inbound Transaction Queue.

Outbound Queues

Outbound message queues are used for XML messages outbound from Oracle Applications. The outbound Message Queue is positioned between the XML Gateway and the Transport Agent.

The XML Gateway creates XML messages, then enqueues them on this queue. The Transport Agent dequeues the message and delivers it to the Trading Partner.

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 also transmitted. Collectively, these attributes are called the XML Gateway envelope. The following table describes some of these attributes.

Envelope Attributes

Attribute	Description
MESSAGE_TYPE	Payload message format. This defaults to XML. Oracle XML Gateway currently supports only XML.
MESSAGE_STANDARD	Message format standard as displayed in the Define Transactions form and entered in the Define XML Standards form. This defaults to OAG. The message standard entered for an inbound XML document must be the same as the message standard in the trading partner setup.
TRANSACTION_TYPE	External Transaction Type for the business document from the Trading Partner table. The transaction type for an inbound XML document must be the same as the transaction type defined in the Trading Partner form.
TRANSACTION_SUBTYPE	External Transaction Subtype for the business document from the Trading Partner table. The transaction subtype for an inbound XML document must be the same as the transaction subtype defined in the Trading Partner form.
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.
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.
PARTY_SITE_ID	The party site identifier for an inbound XML document must be the same as the Source Trading Partner location defined in the Trading Partner form.
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. Note: For more information, see Destination Trading Partner Location Code in the Oracle XML Gateway User's Guide. This guide is a part of the Oracle Applications documentation library. Oracle Applications documentation can be accessed from the following link: http://www.oracle.com/technology/documentation/applications.html
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

Note: See Oracle XML Gateway User's Guide for details on the XML Gateway Execution Engine, Trading Partner validation, and so on. This guide is a part of the Oracle Applications documentation library. Oracle Applications documentation can be accessed from the following link:

http://www.oracle.com/technology/documentation/applications.html

Design-Time Tasks for XML Gateway Inbound Messaging

OracleAS adapter for Oracle Applications is deployed using the BPEL Process Manager (PM) in Oracle JDeveloper. The BPEL PM creates the WSDL interfaces for the XML Gateway message map.

This section describes configuring the OracleAS Adapter for Oracle Applications to use XML Gateway. It describes the tasks required to configure OracleAS Adapter for Oracle Applications using the Adapter Configuration Wizard in Oracle JDeveloper.

Prerequisites to Configure XML Gateway Inbound

You need to populate certain variables in the BPEL PM in order to provide context information for Oracle Applications. The MESSAGE_TYPE, MESSAGE_STANDARD, TRANSACTION_TYPE, TRANSACTION_SUBTYPE, and PARTY_SITE_ID are the mandatory header variables that you need to populate for the XML transaction to complete successfully. Refer to Configuring the Assign Activity for more information.

You also need to configure and schedule two listeners on the Oracle Applications side. These are the ECX Inbound Agent Listener and the ECX Transaction Agent Listener. Use the following steps to configure these listeners in Oracle Applications:

1. Log in to Oracle Applications with the responsibility of Workflow Administrator.

2. The Navigator page . Click the Workflow Administrator Web Applications link.

3. Click the Workflow Manager link under Oracle Applications Manager.

4. Click the status icon next to Agent Listeners.

5. Configure and schedule the ECX Inbound Agent Listener and the ECX Transaction Agent Listener. Select the listener, and select Start from the Actions box. Click Go.

Following is a list of the procedures required to accomplish the design-time tasks.

1. Create a new BPEL project.

2. Create a partner link.

3. Configure the Invoke activity.

4. Add a partner link for the file adapter.

5. Configure the Receive activity.

6. Configure the Assign activity.

Creating a New BPEL Project

To create a new BPEL project

1. Open JDeveloper BPEL Designer.

2. From the File menu, select New.

   The New Gallery dialog box appears.

3. Select All Items from the Filter By box. This displays a list of available categories.

4. Expand the General node, and then select Projects.

5. Select BPEL Process Project from the Items group.

   Creating a New BPEL Process Project

   

6. Click OK. The BPEL Process Project dialog box appears.

7. In the BPEL Process Name field, enter a descriptive name. For example, InsertPurchaseOrder.

8. From the Template box, select Empty BPEL Process. Keep the default selection for Use Default under Project Content.

   Specifying a Name for the New BPEL Process Project

   

9. Click OK. A new BPEL process, with the required source files including bpel.xml, InsertPurchaseOrder.bpel, and InsertPurchaseOrder.wsdl, is created.

   New BPEL Process Project

   

Creating a Partner Link

The next task is to add a partner link to the BPEL process. A partner link defines the link name, type, and the role of the BPEL process that interacts with the partner service.

To create a partner link

1. Drag and drop PartnerLink, from the Component Palette, into the border area of the process diagram. The Create Partner Link dialog box .

2. Click the Define Adapter Service icon in WSDL Settings. The Adapter Configuration Wizard .

3. Click Next. The Adapter Type dialog box .

4. Select Oracle Applications.

   Selecting OracleAS Adapter for Oracle Applications

   

5. Click Next. The Service Name dialog box appears. Enter the following information:

   1. In the Service Name field, enter a service name.

   2. In the Description field, enter a description for the service. This is an optional field.

   Specifying the Service Name

   

6. Click Next. The Service Connection dialog box appears.

   Creating a New Database Connection

   

7. Click New to define a database connection. The Create Database Connection Wizard appears. Alternatively, you can select an existing database connection from the Connection list.

   Note: You need to connect to the database where Oracle Applications is running.

8. Enter the following information in the Type dialog box:

   1. In the Connection Name field, specify a unique name for the database connection.

   2. From the Connection Type box, select the type of connection for your database connection.

   Specifying the Connection Name and Type of Connection

   

9. Click Next. The Authentication dialog box appears.

10. Enter information in the following fields:

    1. In the UserName field, specify a unique name for the database connection.

    2. In the Password field, specify a password for the database connection.

11. Click Next. The Connection dialog box appears.

12. Enter information in the following fields:

    1. From the Driver list, select Thin.

    2. In the Host Name field, specify the host name for the database connection.

    3. In the JDBC Port field, specify the port number for the database connection.

    4. In the SID field, specify a unique SID value for the database connection.

    Specifying the New Database Connection Information

    

13. Click Next. The Test dialog appears.

14. Click Test Connection to determine whether the specified information establishes a connection with the database.

15. Click Next. The Service Connection dialog box appears, providing a summary of the database connection.

16. The JNDI (Java Naming and Directory Interface) name corresponding to the database connection appears automatically in the Database Server JNDI Name field. Alternatively, you can specify a JNDI name.

    Note: When you specify a JNDI name, the deployment descriptor of the Oracle Applications adapter must associate this JNDI name with configuration properties required by the adapter to access the database.

    The JNDI name acts as a placeholder for the connection used when your service is deployed to the BPEL server. This enables you to use different databases for development and later for production.

    Note: For more information about JNDI concepts, see Oracle Application Server Adapter Concepts.

17. Click Finish to complete the process of creating a new database connection.

    Once you have completed creating a new connection for the service, you can add an XML Gateway map by browsing through the maps available in Oracle Applications.

18. Click Next in the Service Connection dialog box. The Operation dialog box appears.

    Note: If you are connecting to a pre-11.5.10 Oracle Applications instance, you must select the interface type in the Adapter Configuration Wizard. Select XML Gateway to proceed. Select Enqueue or Dequeue depending respectively on whether data is inbound into Oracle Applications or outbound from Oracle Applications. Next, choose the DTD file that is converted into an XSD schema file.

19. Click Get Object to open the Oracle Applications Module Browser.

    Specifying the XML Gateway Message Map

    

    Oracle Applications Module Browser includes the various product families that are available in Oracle Applications. For example, the Marketing Suite or the Order Management Suite are product families in Oracle Applications. The product families contain the individual products. For example, the Order Management Suite contains the Order Management product. The product contains the business entities associated with the product. For example, the Order Management product contains the Sales Order business entity.

    Business entities contain the various application modules that are exposed for integration. These modules are grouped according to the interface they provide. XML Gateway message maps can be found under the XML Gateway category.

20. Select an inbound or outbound XML Gateway message map. You can select only one XML Gateway message map for each adapter service. Click OK to generate the XML schema.

    • You can also search for an XML Gateway message map by entering the name or part of the name for the message map in the Object Name field. Select the XML Gateway check box and click Search.

    • The custom message maps that you might have saved can be found in the Others category.

    Adding the XML Schema

    

21. Click Next.

22. Click Finish. The wizard generates the WSDL file corresponding to the XML schema. This WSDL file is now available for the partner link.

    Completing the Partner Link Configuration

    

23. Click OK. The partner link is created with the required WSDL settings.

Configuring the Invoke Activity

After adding and configuring the partner link, the next task is to configure the BPEL process itself. You can start by configuring the Invoke process activity to enqueue the XML Gateway inbound messages.

To configure the Invoke activity

1. Drag and drop the Invoke activity into the process map window.

   Adding the Invoke Activity

   

2. Double-click Invoke in the process map to open the Invoke dialog box. The General tab is selected by default.

   Configuring the Invoke Activity

   

3. In the Partner Link box, select the partner link to invoke. This is the partner link that you configured in the previous section. The Operation is automatically selected, depending on the message map that you chose when configuring the partner link. If you selected an inbound message map, then the Enqueue operation is selected.

4. Click the Create icon next to the Input Variable field. Enter a descriptive name for the variable in the Create Variable dialog box that appears. You can also accept the default name. Click OK.

   Creating the Input Variable

   

5. Click the Adapters tab in the Invoke dialog box. You need to specify the Input Header Variable here. Click the Browse icon next to the Input Header Variable field.

6. In the Variable Chooser dialog box that appears, select the Variables node and click Create.

   Specifying the Input Header Variable

   

7. The Create Variable dialog box appears. Type a descriptive name for the variable in the Name field. Select the Message Type option and click the Browse icon next to it.

   Creating the Input Header Variable

   

8. In the Type Chooser dialog box that appears, select the appropriate message type and click OK.

   Specifying the Message Type

   

9. In the Create Variable dialog box, click OK. In the Variable Chooser dialog box, click OK.

10. In the Invoke dialog box, click Apply, then OK.

    Note: If you have configured a partner link for outbound messages from Oracle Applications, then you need to configure a Receive activity in place of the Invoke activity. The Receive activity is used to dequeue the XML Gateway outbound messages.

Adding a Partner Link for the File Adapter

If you are configuring an inbound message, then you would need to add another partner link for the file adapter. This allows the inbound message to pick up an XML file received from the third party application. The data is inserted into Oracle Applications through the partner link that was configured earlier.

To add a partner link for the file adapter

1. Drag and drop PartnerLink into the border area of the process diagram. The Create Partner Link dialog box appears.

2. Click the Define Adapter Service icon in the WSDL Settings section. The Adapter Configuration Wizard appears.

3. Click Next. The Adapter Type dialog box appears.

4. Select File Adapter and click Next. The Service Name dialog box appears.

5. Enter a name for the file adapter service in the Service Name field. You can also enter an optional description. Click Next.

   Specifying the Service Name

   

   The Operation dialog box appears.

6. Select the Operation Type. The Operation Type specifies whether you are polling for files or creating outgoing files. Select Read File if you need to read files for inbound operations. Enter a name for the Operation in the Operation Name field. You can also use the default name. Click Next.

   Specifying the Operation Name and Type

   

   Note: If you are configuring the BPEL Process for outbound XML messages from Oracle Applications, you must choose Write File in place of Read File..

7. The File Directories dialog box appears. Enter the physical path for the XML files. You can also choose the location by using Browse. Click Next.

   Specifying the Physical Path for the XML Files

   

8. The File Filtering dialog box appears. This enables you to specify the pattern using which you want to match the XML files that need to be picked. Specify a pattern and click Next.

   Specifying File Filtering Parameters for the Read Operation

   

   The File Polling dialog box appears.

9. You must specify the frequency at which the directory needs to be polled for the XML files. Specify a Polling Frequency and click Next.

   Specifying the Polling Frequency

   

   The Messages dialog box appears.

10. You must specify the schema file location and select the schema element that defines the messages in the incoming files. You can use Browse to select the schema file location. Enter the required information, then click Next.

    Specifying the Schema File Location and Schema Element

    

11. Click Finish to finish creating the File Adapter service. Click OK in the Create Partner Link dialog box to create the partner link for the File Adapter service.

    Note: The File Adapter is just one of the ways to read or write XML messages. The XML messages can also be exchanged using an FTP Adapter, SMTP Adapter, or through another BPEL process.

Configuring the Receive Activity

The next task is to configure a Receive activity to receive XML data from the partner link that you configured for the file adapter service.

To configure the Receive activity

1. Drag and drop Receive into the process map window. The Receive activity should be placed in between Start and Invoke.

   Adding the Receive Activity

   

2. Double-click Receive in the process map to open the Receive dialog box. The General tab is selected by default.

   Configuring the Receive Activity

   

3. In the Partner Link box, choose the partner link corresponding to the file adapter service. The Operation is selected by default depending on the Partner Link that you select.

4. Click the Create icon next to the Variable field. The Create Variable dialog box appears.

5. Enter a Name for the variable. You can also accept the default name. Click OK.

   Creating the Receive Variable

   

6. Click Apply in the Receive dialog box, and then click OK. This associates the Receive activity with the partner link configured for the file adapter service.

   Note: If you are configuring the process for outbound XML messages from Oracle Applications, you must link the file adapter partner link to the Invoke activity. The Invoke process activity invokes the file adapter interface to write the XML message to an XML file.

Configuring the Assign Activity

The next task is to add an Assign activity to the process map. This is used to populate parameters that provide context information to Oracle Applications.

To configure the Assign activity

1. Drag and drop the Assign activity into the process map. The Assign activity needs to be dropped in between the Receive and Invoke activities.

   Adding the Assign Activity

   

2. You now need to configure the Assign activity. Double-click the Assign activity in the process map.

3. The Assign dialog box appears. The Copy Rules tab appears by default. Click Create.

4. The Create Copy Rule dialog box appears. In the To group, expand the Variables node by clicking the plus sign next to it. Expand in turn the Variable_Header, Header, ns1:Header, and ns1:PayloadHeader child nodes.

   Specifying Context Information for Oracle Applications

   

5. Select the MESSAGE_TYPE variable. In the From group, select Expression as the Type. Enter a message type in the Expression field. For example, the message type for XML Gateway is 'XML'. Click OK.

6. Repeat steps 3 and 4, then select the MESSAGE_STANDARD variable. MESSAGE_STANDARD specifies the XML message standard that you are using. Enter an Expression for the message standard, for example, 'OAG'. Click OK.

7. Repeat steps 3 and 4, then select the TRANSACTION_TYPE variable. This variable defines the type of transaction that you are performing, say a purchase order operation. Enter an Expression for the transaction type, for example, 'PO'. Click OK.

8. Repeat steps 3 and 4, then select the TRANSACTION_SUBTYPE variable. This variable defines the subtype for the transaction that you are performing. Enter an Expression for the transaction subtype, for example, 'Process'. This means that you are processing a Purchase Order transaction type. Click OK.

9. Repeat steps 3 and 4, then select the PARTY_SITE_ID variable. The party site ID identifies the trading partner. Enter an Expression for the party site ID. Click OK.

   Note: MESSAGE_TYPE, MESSAGE_STANDARD, TRANSACTION_TYPE, TRANSACTION_SUBTYPE, and PARTY_SITE_ID are the mandatory header variables that you need to populate for the XML transaction to complete successfully.

Run-Time Tasks for XML Gateway Inbound Messaging

After designing the BPEL process, the next step is to deploy, run and monitor it.

1. Deploy the BPEL process.

2. Test the BPEL process.

3. Verify records in Oracle Applications.

Deploying the BPEL Process

You need to deploy the BPEL process before you can run it. The BPEL process is first compiled and then deployed to the BPEL server.

To deploy the BPEL process

1. Select the BPEL project in the Applications window.

2. Right-click the project name. Select Deploy from the menu that appears.

3. If you are deploying the process on the local BPEL server, select Local BPEL Server, then Deploy to Default Domain.

   Deploying the BPEL Process

   

   Note: You can select Invoke Deployment Tool if you want to deploy to a different BPEL server.

4. The Password Prompt dialog box appears. Enter the password for the default domain in the Domain Password field. Click OK.

   Specifying the Domain Password

   

5. The BPEL process is compiled and deployed. You can check the progress in the Messages window.

   Messages Window

   

Testing the BPEL Process

Once the BPEL process is deployed, it can be seen in the BPEL console. You can manage and monitor the process from the BPEL console. You can also test the process and the integration interface by manually initiating the process.

To test the BPEL process

1. To open the BPEL console, click Start, and then choose Programs. In the Programs menu, select Oracle - oracle_home, Oracle BPEL Process Manager 10.1.3, and then select BPEL Console.

2. The BPEL console login screen appears. Select Default in the Domain box. Enter the password for the default domain in the Password field. Click Login.

3. Oracle BPEL console appears. The list of deployed processes is shown under Deployed BPEL Processes.

   Deployed BPEL Processes

   

4. Click the BPEL process that you want to initiate. The Initiate page appears. Enter the input values required by the process. You can also specify an XML file for the file adapter to pick.

5. Click Post XML Message to initiate the process.

6. The BPEL process is now initiated. You can check the process flow by clicking the Visual Flow icon.

   BPEL Console Initiate Page

   

7. The audit trail provides information on the steps that have been executed. The audit trail also records the Reference ID that is returned for the transaction. You can check the audit trail by clicking the Audit Instance icon.

   If the BPEL process runs into an error, then a corresponding error code is returned. The following table lists the common error codes, their descriptions, and the fix that you can use for them.

   Error Codes for the BPEL Process

   Code No.	Code Name	Description	Fix
   12400	APPS_MESSAGE_STANDARD_NOT_FOUND	Message Standard not set in the header	Set the Message Standard value in the header
   12401	APPS_TRANSACTION_TYPE_NOT_FOUND	Transaction Type not set in the header	Set the Transaction Type value in the header
   12402	APPS_TRANSACTION_SUBTYPE_NOT_FOUND	Transaction Subtype not set in the header	Set the Transaction Subtype value in the header
   12403	APPS_PARTY_SITE_ID_NOT_FOUND	Party Site Id not set in the header	Set the Party Site Id value in the header
   12404	APPS_MESSAGE_TYPE_NOT_FOUND	Message Type not set in the header	Set the Message Type value in the header
   12406	APPS_CONTEXT_ERROR	Error in setting Apps Context	Check the username and responsibility values
   12407	APPS_AUTHENTICATION_ERROR	Invalid FND username/password	Check the username and password values
   12408	APPS_UNKNOWN_EX	Unknown error in Apps Interaction	Check if all the header values are valid
   12409	APPS_XMLG_HEADER_NULL	XML Gateway header is null	Pass the required parameters in header

Verifying Records in Oracle Applications

You can verify all successful entries in Oracle Applications. You need to look at the relevant module in Oracle Applications to check for the new records. For example, you can look for a Sales Order entry in the Order Management module.

You can check for unsuccessful entries in corrections. You can use the Reference ID of a transaction to look for a particular record. This is the same Reference ID that you noted in the BPEL audit trail. You can reprocess a record after making the necessary configuration changes. However, you cannot alter the data in the record.

Using Transaction Monitor

The Transaction Monitor is a tool for monitoring the status of inbound and outbound transactions originating from and going into Oracle Applications that have been processed by the XML Gateway and delivered or received by the Oracle Transport Agent. The Transaction Monitor shows a complete history and audit trail of these documents.

You can navigate to the Transaction Monitor page using the Workflow Administrator Web responsibility. The Transaction Monitor provides the following:

• Flexible search criteria to support access to a specific document or group of documents

• Search results at the document header level with drill down by document ID

• Resend capability for outbound messages

• Viewing capability of the XML message content

Note: For details on using the Transaction Monitor, see Oracle XML Gateway User's Guide. This guide is part of the Oracle Applications documentation library. Oracle Applications documentation can be accessed from the following link:

http://www.oracle.com/technology/documentation/applications.html

Design-Time Task for XML Gateway Outbound Messaging

This section discusses the design-time steps, for an XML Gateway outbound message, that are different from the design-time steps for an inbound message.

Prerequisites to Configure XML Gateway Outbound

You need to set up a trading partner. In the trading partner setup, ensure that Protocol Type is set to BPEL.

For invoking an outbound partner link, you need to set up the correlation identifier in Oracle Applications. The correlation identifier enables you to label messages meant for a specific agent, in case there are multiple agents listening on the outbound queue. The agent listening for a particular correlation picks up the messages that match the correlation identifier for the agent.

To set up the correlation identifier:

1. Log in to Oracle Applications with the XML Gateway responsibility. The Navigator page appears.

2. Click the XML Gateway link.

3. Click the Define Lookup Values link under XML Gateway.

4. Enter COMM_METHOD for the Type field.

5. Enter BPEL for the Code field. Fill in the other mandatory fields. Oracle XML Gateway puts the correlation of BPEL when enqueueing the message on the ECX_OUTBOUND queue.

The following procedure is required to accomplish the design-time task.

Configuring XML Gateway for Outbound Messaging

When configuring the OracleAS Adapter for Oracle Applications to use an outbound XML Gateway map, you need to configure the Receive activity for the associated partner link. The Receive activity dequeues the outbound XML messages.

To configure the Receive activity

1. Drag and drop Receive into the process map window.

2. Double-click the Receive activity to configure the Receive properties. The Receive dialog box appears.

   Configuring the Receive Activity

   

3. Select the Partner Link corresponding to the partner link configured with the outbound XML Gateway map.

4. The Dequeue Operation is automatically selected if the partner link has been configured with an outbound XML Gateway map.

5. The next task is to specify a Variable to receive the message data from the partner link. Click the Create icon to the right of the Variable field. The Create Variable dialog box appears.

   Creating a Variable to Receive Message Data

   

6. Type a Name for the variable. You can also accept the default name. Click OK.

7. Click Apply in the Receive dialog box, then click OK.

   Note: You can define a Header Variable under the Adapters tab of the Receive dialog box. This header variable is populated with context information from the outbound XML message. Values for fields like MESSAGE_TYPE, MESSAGE_STANDARD and trading party information like PARTY_SITE_ID are returned through this variable.

Run-Time Task for XML Gateway Outbound Messaging

After designing the BPEL process, you can compile, deploy and test it.

Test the BPEL process.

Testing the BPEL Process

In Oracle Applications, you can check for outbound transactions that have been processed by the XML Gateway and delivered to the Transaction Agent, by using the Transaction Monitor. You can also use the Transaction Monitor to resend an outbound document, if necessary. Run-Time Tasks for XML Gateway Inbound Messaging discusses the Transaction Monitor.

Note: For details on using the Transaction Monitor, see Oracle XML Gateway User's Guide. This guide is a part of the Oracle Applications documentation library. Oracle Applications documentation can be accessed from the following link:

http://www.oracle.com/technology/documentation/applications.html

If you have used a file adapter to write outbound messages from Oracle Applications to files, you can check the output directory location for the presence of these files after the BPEL process has run.

Troubleshooting and Debugging

If you experience problems with your Oracle XML Gateway integration, you can take the following troubleshooting steps:

• Confirm that you have the correct settings for the following elements of the trading partner setup:

  • Standard Code

  • Transaction Type

  • Transaction Subtype

  • Source Trading Partner Location Code (Party Site ID)

• Confirm that the correct transaction is enabled for the trading partner.

• Check the status of the XML transaction in Transaction Monitor.

• Ensure that the document number is unique within this transaction type.

• For inbound transactions, confirm that ECX Listeners are running.

• For outbound transactions, confirm that Background Engine is running.

• In the trading partner setup, ensure that the Protocol Type is set to BPEL.

• Specify the same correlation ID for Oracle Applications as for the Adapter.

  The Adapter Configuration wizard of OracleAS Adapter for Oracle Applications does not specify a correlation ID for XML Gateway transactions for inbound or outbound interfaces. Instead, a default correlation ID of BPEL is automatically set in the WSDL file. To make this configuration work, you must configure Oracle Applications to set the same correlation ID value of BPEL for the corresponding XML Gateway transactions.

  If you want the Adapter to use a different correlation ID than the default, you need to configure a correlation ID in Oracle Applications, then edit the Correlation="BPEL" line contained in the section of the adapter service WSDL. Replace BPEL with the string value of the correlation ID you specified in Oracle Applications.

If you still experience problems with your integration, you can enable debugging.

Enabling Debugging

You can enable debugging for XML gateway using the BPEL Process Manager.

To enable debugging:

1. Log into your BPEL Process Manager domain.

2. Select yourdomain.collaxa.cube.ws

3. Select Debug.

4. Enable FND Logging to debug XML Gateway Transactions.

Debugging information is output to the log file for your domain. To examine the log file in the BPEL Process Manager, navigate to Home > BPEL Domains > yourdomain > Logs. The log file is yourdomain.log.