10g (10.1.3.5.0)
Part Number E14293-01
Contents
Previous
Next
| Oracle Application Server Adapter for Oracle Applications User's Guide 10g (10.1.3.5.0) Part Number E14293-01 | Contents | Previous | Next |
This chapter covers the following topics:
The OracleAS Adapter for Oracle 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 an XML messaging based integration infrastructure essentially for business partner integration which includes a set of services that allows easy integration between Oracle Applications and third party applications. Oracle Applications utilize the Oracle Workflow Business Event System to support event-based XML message creation and consumption.
OracleAS Adapter for Oracle 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.
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.
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 inbound and outbound XML Gateway message processing. For XML Gateway inbound message processing, the inbound message will be placed in the ECX_INBOUND queue. Agent Listeners running on ECX_INBOUND would enable further processing by the Execution Engine. Oracle XML Gateway picks this XML message, does trading partner validation, and inserts data into Oracle Applications. For XML Gateway outbound message processing, the outbound message will be first enqueued to the ECX_OUTBOUND queue. Oracle BPEL PM listens to ECX_OUTBOUND queue for the message with the same correlation Id BPEL. The message will then be dequeued to retrieve outbound data and then the outbound map will be invoked to update Oracle Applications.
XML Gateway Integration Architecture
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 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 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.
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.
| 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. |
The following parameters may be defined by the base application:
ATTRIBUTE1
ATTRIBUTE2
ATTRIBUTE4
ATTRIBUTE5
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
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 the process of configuring OracleAS Adapter for Oracle Applications to use XML Gateway message map. It also 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
Populating XML Gateway Header Variables
The MESSAGE_TYPE, MESSAGE_STANDARD, TRANSACTION_TYPE, TRANSACTION_SUBTYPE, and PARTY_SITE_ID are the mandatory header variables that you need to populate in order for the XML transactions to complete successfully.
Refer to Configuring the Assign Activity for more information.
Ensuring Agent Listeners Are Up and Running
You 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:
Log in to Oracle Applications with the responsibility of Workflow Administrator.
Select the Workflow Administrator Web Applications link from the Navigator.
Click the Workflow Manager link under Oracle Applications Manager.
Click the status icon next to Agent Listeners.
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.
To create a new BPEL project
Open JDeveloper BPEL Designer.
From the File menu, select New.
The New Gallery dialog box appears.
Select All Items from the Filter By box. This displays a list of available categories.
Expand the General node, and then select Projects.
Select BPEL Process Project from the Items group.
Creating a New BPEL Process Project
Click OK. The BPEL Project Creation Wizard - Project Settings dialog box appears.
In the Name field, enter a descriptive name, for example, XMLGatewayInbound.
Keep the default selection Use Default Project Settings unchanged.
Keep the default selection Template as the Type field. Select Asynchronous BPEL Process as the BPEL process type.
Specifying New BPEL Project Settings
Click Finish.
A new asynchronous BPEL process is automatically created with the receiveInput and callbackClient activities.
The required source files including bpel.xml, XMLGInbound.bpel, and XMLGInbound.wsdl are also generated.
New BPEL Process Project
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
Click Services in the Component palette.
Drag and drop Oracle Applications from the Component palette, into the border area of the process diagram. The Adapter Configuration Wizard Welcome page appears.
Click Next.
The Service Name dialog box appears. Enter the following information:
In the Service Name field, enter a service name. For example, enter XMLGOrderInbound.
In the Description field, enter a description for the service. This is an optional field.
Specifying the Service Name
You can either create a new database connection or use an existing connection.
Note: You need to connect to the database where Oracle E-Business Suite is running.
Creating a New Database Connection:
Perform the following steps to create a new database connection:
Click New in the Service Connection dialog box.
Creating a New Database Connection
The Create Database Connection Wizard appears.
Enter the following information in the Type dialog box:
In the Connection Name field, specify a unique name for the database connection.
From the Connection Type box, select the type of connection for your database connection.
Click Next. The Authentication dialog box appears.
Authenticating the Database Connection
Enter information in the following fields:
In the UserName field, specify a unique name for the database connection.
In the Password field, specify a password for the database connection.
Click Next. The Connection dialog box appears.
Providing Database Connection Details
Enter information in the following fields:
From the Driver list, select Thin.
Enter the host name for the database connection, such as myhost01.example.com.
Enter the JDBC port number 1521 for the database connection.
Select SID and specify a unique SID value for the database connection, such as sid01.
Click Next. The Test dialog appears.
Click Test Connection to determine whether the specified information establishes a connection with the database. The status message "Success!" indicates a valid connection.
Click Finish to complete the process of creating a new database connection.
The Service Connection dialog box appears, providing a summary of the database connection.
Verifying the Database Service Connection
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 Adapter for Oracle Applications 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.
Selecting an Existing Database Connection:
Instead of creating a new database connection, you can use an existing database connection that you have configured.
From the Service Connection dialog box, select an existing database connection from the Connection drop-down list.
The selected database connection information is displayed. The JNDI (Java Naming and Directory Interface) name corresponding to the selected database connection also appears automatically in the Database Server JNDI Name field. Alternatively, you can specify a JNDI name.
Once you have completed a new database connection or selected an existing connection, you can add an XML Gateway inbound map by browsing through the message maps available in Oracle E-Business Suite.
Click Next in the Service Connection dialog box.
For Oracle E-Business Suite Release 12:
If you are connecting to Oracle E-Business Suite Release 12, then the IREP File not present dialog box appears indicating that OracleAS Adapter for Oracle Applications could not find the Oracle Integration Repository data file corresponding to the database you are connecting in your workspace. Absence of the data file would make browsing or searching of Integration Repository tree considerably slow. You can choose to extract the data file and create a local copy of the Integration Repository data file. Once it is created successfully, OracleAS Adapter for Oracle Applications will pick it up automatically next time and retrieve data from your local Integration Repository.
You can select one of the following options:
Click Yes to extract the Integration Repository data file.
Extracting Integration Repository Data File
After the system successfully creates a local copy of the Integration Repository data file, next time when you connect to the database, you will find the IRep Data File field appears in the Operation dialog box indicating where your local copy exists with the creation date and time as part of the file name.
Using the Local Integration Repository Data File
Click No to query the Integration Repository data file from the live database you are connecting to display the Integration Repository tree.
Note: It is highly recommended that you create a local copy of the Integration Repository data file so that OracleAS Adapter for Oracle Applications will query the data next time from the local copy in your workspace to enhance the performance.
For Oracle E-Business Suite pre-Release 11.5.10:
If you are connecting to a pre-11.5.10 Oracle E-Business Suite instance, you must select the interface type in the Adapter Configuration Wizard. Select XML Gateway to proceed.
Click Add to open the Oracle Applications Module Browser.
The Oracle Applications Module Browser combines interface data from Oracle Integration Repository with information about the additional interfaces supported by OracleAS Adapter for Oracle Applications, organized in a tree hierarchy.
Specifying the XML Gateway Message Map
Note: The Oracle Applications Module Browser includes the various product families that are available in Oracle E-Business Suite. Each product family contains the individual products. Each product contains the business entities associated with the product. Business entities contain the various application modules that are exposed for integration. These modules are grouped according to the interface they provide.
Navigate to Order Management Suite > Order Management >Sales Order > XML Gateway to select Inbound: Process Purchase Order XML Transaction (ONT_3A4R_OAG72_IN).
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.
Click OK to generate the XML schema.
Adding the XML Schema
Click Next and then click Finish to complete the process of configuring Adapter for Oracle Applications.
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
Click Apply and then OK. The partner link is created with the required WSDL settings.
Use this step to configure a BPEL process by adding the following two partner links for File Adapter:
To pick up an XML file received from the third party application to get the XML message.
To get the transaction information for the ECX header.
To add the first Partner Link for File Adapter to get the XML Message:
In JDeveloper BPEL Designer, drag and drop the File Adapter service from the Service section of the Component Palette into the Partner Link area of the process diagram. The Adapter Configuration Wizard welcome page appears.
Click Next. The Service Name dialog box appears.
Enter a name for the file adapter service, such as GetXMLMsg. You can add an optional description of the service.
Click Next, and the Operation dialog box appears.
Specifying the Operation
Specify the operation type, for example Synchronous Read File. This automatically populates the Operation Name field.
Click Next to access the File Directories dialog box.
Configuring the Input File
Select Logical Name check box and specify the logical directory for the incoming file. Uncheck the Delete files after successful retrieval check box. Click Next.
Enter the name of the file for the synchronous read file operation. For example, enter order_data_xmlg.xml. Click Next. The Messages dialog box appears.
Select Browse to open the Type Chooser to specify the Schema location and element.
From the Type Chooser window, expand the node by clicking Project Schema Files > PROCESS_PO_007.xsd > PROCESS_PO_007.
Selecting Schema from the Type Chooser
Click OK to populate the selected values in the Messages dialog box.
Populating Selected Message Schema and Element
Click Next and then Finish. The wizard generates the WSDL file corresponding to the partner link. The main Create Partner Link dialog box appears, specifying the new WSDL file GetXMLMsg.wsdl.
Click Apply and then OK to complete the configuration and create the partner link with the required WSDL settings for the File Adapter Service.
The GetXMLMsg Partner Link appears in the following BPEL process diagram:
Adding the Partner Link for File Adapter
To add the second Partner Link for File Adapter to get the transaction information for the XML header:
Repeat Step 1 to Step 6 mentioned in the first partner link creation for File Adapter to create the second partner link called GetECXHeader.
Enter the name of the file for the synchronous read file operation. For example, enter ecx_header_data.xml. Click Next. The Messages dialog box appears.
Select Browse to open the Type Chooser to specify the Schema location and element.
From the Type Chooser window, expand the node by clicking Project Schema Files > SYSTEM_ECXMSG.xsd > SYSTEM_ECXMSG. Click OK to populate the selected schema location and element in the Messages dialog box.
Populated Selected Schema and Element in the Messages Dialog Box
Click Next and then Finish. The wizard generates the WSDL file corresponding to the partner link. The main Create Partner Link dialog box appears, specifying the new WSDL file GetECXHeader.wsdl.
Adding a Partner Link
Click Apply and then OK to complete the configuration and create the partner link with the required WSDL settings for the second File Adapter Service.
The GetECXHeader Partner Link appears in the following BPEL process diagram:
Adding the Partner Link for File Adapter
This step is to configure three Invoke activities:
To get the XML message details that is received from the Receive activity by invoking the GetXMLMsg partner link in an XML file.
To get the ECX Header properties details by invoking GetECXHeader partner link in an XML file.
To enqueue the purchase order information to the ECX_INBOUND queue by invoking XMLGOrderInbound partner link in an XML file.
To add the first Invoke activity for a partner link to get XML message:
In JDeveloper BPEL Designer, drag and drop the first Invoke activity from the Component Palette into the Activity box of the process diagram, between the Receive and Callback activities.
Link the Invoke activity to the GetXMLMsg service. The Edit Invoke dialog box appears.
Enter a name for the Invoke activity, and then click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.
Select Global Variable. Enter a name for the variable. You can also accept the default name. Click OK.
Enter a name for the Invoke activity, and then click the Create icon next to the Output Variable field to create a new variable. The Create Variable dialog box appears.
Select Global Variable and then enter a name for the variable. You can also accept the default name. Click OK.
Click Apply and then OK in the Edit Invoke dialog box to finish configuring the Invoke activity.
The Invoke activity appears in the process diagram.
To add the second Invoke activity for a partner link to get ECX Header properties:
In JDeveloper BPEL Designer, drag and drop the second Invoke activity from the Component Palette into the Activity box of the process diagram, between the first Invoke activity and the Callback activity.
Link the Invoke activity to the GetECXHeader service. The Edit Invoke dialog box appears.
Repeat Step 3 to Step 6 described in the first Invoke activity creation to complete the second Invoke activity.
To add the third Invoke activity for a partner link to enqueue PO information:
In JDeveloper BPEL Designer, drag and drop the third Invoke activity from the Component Palette into the process diagram, between the second Invoke activity and the Callback activity.
Link the Invoke activity to the XMLGOrderInbound service. The Edit Invoke dialog box appears.
Repeat Step 3 to Step 6 described in the first Invoke activity creation to complete the third Invoke activity.
The three Invoke activities appear in the process diagram.
Adding Invoke Activities
This step is to configure two Assign activities:
To pass XML message as an input to the last Invoke activity for enqueuing message.
To pass ECX header variables as input variables to the last Invoke activity in order to provide context information for Oracle Applications.
To add the first Assign activity to pass XML message as input to the Invoke activity:
In JDeveloper BPEL Designer, drag and drop the Assign activity from the Component Palette into the Activity box of the process diagram, between the second and the third Invoke activities.
Double-click the Assign activity to access the Edit Assign dialog box.
Click the General tab to enter the name for the Assign activity, such as 'SetXMLMsg'.
On the Copy Operation tab, click Create, then select Copy Operation from the menu. The Create Copy Operation window appears.
Enter the first pair of parameters:
In the From navigation tree, select type Variable and then navigate to Variable > Process > Variables > Invoke_SynchRead_OutputVariable > Process_PO_007 and select ns4:Process_PO_007.
The XPath field should contain your selected entry.
In the To navigation tree, select type Variable and then navigate to Variable > Process > Variables > Invoke_Enqueue_InputVariable > Process_PO_007 and select ns4:Process_PO_007. The XPath field should contain your selected entry.
Click OK.
The Edit Assign dialog box appears.
Assign Parameters
Click Apply and then OK to complete the configuration of the Assign activity.
To add the second Assign activity to pass ECX header variables to the last Invoke activity:
Add the second Assign activity by dragging and dropping the Assign activity from the Component Palette into the Activity box of the process diagram, between the SetXMLMsg Assign activity and the last Invoke activity.
Adding an Assign Activity
Repeat Step 2 to Step 4 described in creating the first Assign activity to add the second Assign activity called 'SetECXHeader'.
On the Copy Operation tab, click Create and then select Copy Operation from the menu. The Create Copy Operation window appears.
In the To navigation tree, select the Variables node and right-click on mouse to select 'Create Variable' from the drop-down list.
Creating Variables
The Create Variable dialog box opens. Select the Message Type check box and click the Browse icon to open the Type Chooser window.
Declaring Header Variables
Expand the Message Type node and select Partner Links > EnqueueMsg > EnqueueMsg.wsdl > Message Types > Header_msg. Click OK to return to the Create Copy Operation dialog box.
The ECXHeader node appears in the Variables node of the To navigation tree. Expand the ECXHeader node and select ns1: Header > ns1: PayloadHeader.
In the From navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_SynchRead_OutputVariable_1 > ECXMSG and select ns6:ECXMSG.
The XPath field should contain your selected entry.
Assigning Header Variables
Click OK to complete the configuration of the Assign activity.
Modify the Invoke activity to pass the ECXHeader as input header variables you just declared and assigned through the Assign activity.
Double-click the last Invoke activity to open the Invoke edit window.
Editing Invoke Activity
Select Adapters tab and click the Browse Variables... icon next to the Input Header Variables field.
Select ECXHeader from the Variable Chooser. Click OK.
Entering Input Header Variables
The selected ECXHeader is now populated in the Input Header Variables field. Click Apply and then OK.
After designing the BPEL process, the next step is to deploy, run and monitor it.
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.
Note: Before deploying the BPEL Process for XML Gateway Inbound Interface, you should:
Load the ecx_header and order_data_xmlg.xml into C:\Temp folder.
Go to the bpel.xml file and point the logical directory to C:\Temp.
To deploy the BPEL process
Select the BPEL project in the Applications window.
Right-click the project and select Deploy > [Server Connection] > Deploy to Default Domain from the menu.
Deploying the BPEL Process
The BPEL process is compiled and deployed. You can check the progress in the Messages window.
Messages Window
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
Navigate to Oracle Application Server 10g BPEL Console (http://<soaSuiteServerHostName>:<port>/BPELConsole).
The BPEL Console login page appears.
Enter the username and password and click Login.
The Oracle Enterprise Manager 10g BPEL Control appears. The list of deployed processes is shown under Deployed BPEL Processes.
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.
Click Post XML Message to initiate the process.
The BPEL process is now initiated. You can check the process flow by clicking the Visual Flow icon.
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.
| 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 |
Once the BPEL process is successfully initiated and completed, you can validate it through the relevant module in Oracle Applications. For example, you can check for the creation of a purchase order in Oracle Order Management.
To validate it in Oracle Order Management:
Log in to the Forms-based Oracle Applications with the Order Management, Super User responsibility.
Select Order Returns > Sales Order. The Sales Order Forms opens up.
Search for an order by entering the order number in the Customer PO field. This brings up the details of a newly created order.
Sales Orders
You can also select the Items tab for the item details.
Additionally, you can validate it from the 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. It shows a complete history and audit trail of these documents.
To validate it using Oracle Transaction Monitor, you need to log in to Oracle Applications with the Workflow Administrator Web Applications responsibility. Select Transaction Monitor to open the search window to search for the order.
Searching from the Transaction Monitor
Click Go to retrieve all XML inbound messages listed in the Inbound Search Results region.
Listing All XML Gateway Inbound Documents
See Oracle XML Gateway User's Guide for details on using the Transaction Monitor.
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
Setting Up Correlation Identifier
For invoking an outbound XML Gateway message map, 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:
Log in to Oracle Applications with the XML Gateway responsibility. The Navigator page appears.
Click the XML Gateway link.
Click the Define Lookup Values link under XML Gateway.
XML Gateway Lookups
Enter COMM_METHOD for the Type field.
Enter BPEL for the Code field.
Oracle XML Gateway puts the correlation of BPEL when enqueueing the message on the ECX_OUTBOUND queue.
Setting Up XML Gateway Trading Partner
Once you have the correlation identifier set up correctly, you also need to ensure a valid outbound XML Gateway trading partner in the Trading Partner Setup form through XML Gateway responsibility. You want to have the Protocol Type field set to BPEL.
For example, a Trading Partner (such as 'Business World' with Site information '2391 L Street San Jose CA 95106' and partner type 'Customer') has the following details for an outbound transaction:
Transaction type: ECX
Transaction sub type: CBODO
Standard Code: OAG
External transaction type: BOD
External transaction subtype: CONFIRM
Direction: OUT
Map: ECX_CBODO_OAG72_OUT_CONFIRM
Connection/Hub: DIRECT
Protocol Type: BPEL
Source Trading partner location code: BWSANJOSE
Trading Partner Setup
BPEL Process Creation Flow
The following procedure is required to accomplish the design-time task.
To create a new BPEL project
Open JDeveloper BPEL Designer.
From the File menu, select New.
The New Gallery dialog box appears.
Select All Items from the Filter By box. This displays a list of available categories.
Expand the General node, and then select Projects.
Select BPEL Process Project from the Items group.
Creating a New BPEL Process Project
Click OK. The BPEL Project Creation Wizard - Project Settings dialog box appears.
In the Name field, enter a descriptive name, such as XMLGOutbound.
Keep the default selection Use Default Project Settings unchanged.
Keep the default selection Template as the Type field. Select Empty BPEL Process as the BPEL process type.
Specifying New BPEL Project Settings
Click Finish.
An empty BPEL process is created.
The required source files including bpel.xml, XMLGOutbound.bpel, and XMLGOutbound.wsdl are also generated.
You need to add a partner link for the outbound XML message in order for the Receive activity to dequeue it later.
To add a partner link
Click Services in the Component palette.
Drag and drop Oracle Applications from the BPEL Services list into the right part of the process diagram. The Adapter Configuration Wizard Welcome page appears. Click Next.
Enter a service name in the Service Name field. For example, GetAck.
Click Next. The Service Connection dialog appears.
You can perform either one of the following options for your database connection:
Note: You need to connect to the database where Oracle E-Business Suite is running.
You can create a new database connection by clicking the New icon.
Detailed instructions on how to create a new database connection, see Creating a New Database Connection.
You can select an existing database connection that you have configured earlier from the Connection drop-down list.
The selected database connection information appears in the Service Connection dialog box. The JNDI (Java Naming and Directory Interface) name corresponding to the selected database connection also 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 Adapter for Oracle Applications 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.
Once you have created a new connection or selected an existing connection, you can add an outbound message map by browsing through the list of message maps available in Oracle E-Business Suite.
Click Next.
For Oracle E-Business Suite Release 12:
If you are connecting to Oracle E-Business Suite Release 12, then the IREP File not present dialog appears indicating that OracleAS Adapter for Oracle Applications could not find the Oracle Integration Repository data file corresponding to the database you are connecting in your workspace. Absence of the data file would make browsing or searching of Integration Repository tree considerably slow. You can choose to extract the data file and create a local copy of the Integration Repository data file. Once it is created successfully, OracleAS Adapter for Oracle Applications will pick it up automatically next time and retrieve data from your local Integration Repository.
You can select one of the following options:
Click Yes to extract the Integration Repository data file.
Extracting Integration Repository Data File
After the system successfully creates a local copy of the Integration Repository data file, next time when you connect to the database, you will find the IRep Data File field appears in the Operation dialog indicating where your local copy exists with the creation date and time as part of the file name.
Using the Local Integration Repository Data File
Click No to query the Integration Repository data file from the live database you are connecting to display the Integration Repository tree.
Note: It is highly recommended that you create a local copy of the Integration Repository data file so that Adapter for Oracle Applications will query the data next time from the local copy in your workspace to enhance the performance.
Click Next in the Operation page to open the Oracle Applications Module Browser.
For Oracle E-Business Suite pre-Release 11.5.10:
If you are connecting to a pre-11.5.10 Oracle E-Business Suite instance, you must select the interface type in the Adapter Configuration Wizard. Select XML Gateway to proceed.
Click Add in the Application Interface dialog to open the Oracle Applications Module Browser.
The Oracle Applications Module Browser combines interface data from Oracle Integration Repository with information about the additional interfaces supported by Adapter for Oracle Applications, organized in a tree hierarchy.
Specify an API from The Oracle Applications Module Browser
Note: The Oracle Applications Module Browser includes the various product families that are available in Oracle Applications. Each product family contains the individual products. Each product contains the business entities associated with the product. Business entities contain the various application modules that are exposed for integration. These modules are grouped according to the interface they provide.
Navigate to Other Interfaces > Custom Objects >XML Gateway Maps> Outbound to select an outbound map ECX_CBODO_OAG72_OUT_CONFIRM.
Click OK.
The Application Interface dialog box appears with the selected XML schema.
Application Interface Dialog
Click Next and then click Finish to complete the process of configuring Adapter for Oracle Applications.
The wizard generates the WSDL file corresponding to the XML schema. This WSDL file is now available for the partner link.
Click Apply and then OK. The partner link is created with the required WSDL settings.
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
In JDeveloper BPEL Designer, drag and drop the Receive activity from the Component Palette into the process map.
Link the Receive activity to the partner link GetAck you created earlier.
The Receive dialog box appears.
Enter an appropriate name for the Receive activity.
The Dequeue Operation is automatically selected since the partner link has been configured with an outbound XML Gateway map.
Specify a Variable to receive the message data from the partner link by clicking the Create icon to the right of the Variable field. The Create Variable dialog box appears.
Click OK to accept the default name.
Select the Create Instance check box.
Editing the Receive Activity
Click Apply and then OK.
The Receive activity is added to the BPEL process diagram.
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.
Use this step to configure a partner link by writing the purchase order acknowledgement to an XML file.
To add a Partner Link for File Adapter:
In JDeveloper BPEL Designer, drag and drop the File Adapter service from the Service section of the Component Palette into the Partner Link area of the process diagram. The Adapter Configuration Wizard appears.
The Service Name dialog box appears.
Specifying the Service Name
Enter a name for the File Adapter service, such as WriteAck. You can add an optional description of the service.
Click Next. The Operation dialog box appears.
Specifying the Operation
Specify the operation type, for example Write File. This automatically populates the Operation Name field.
Click Next to access the File Configuration dialog box.
Configuring the Output File
For the Directory specified as field, select Logical Path. Enter directory path in the Directory for Outgoing Files field, and specify a naming convention for the output file, for example, POAck%yyMMddJJmmss%.xml.
Confirm the default write condition: Number of Messages Equals 1. Click Next. The Messages dialog box appears.
Select the Browse check box to locate the schema location and schema element.
The Type Chooser dialog box appears. Expand the path by selecting Project Schema Files > CONFIRM_BOD_002.xsd. Select CONFIRM_BOD_002 as the element.
Type Chooser
Click OK to populate the selected schema location and element.
Click Next and then Finish. The wizard generates the WSDL file corresponding to the partner link. The main Create Partner Link dialog box appears, specifying the new WSDL file WriteAck.wsdl.
Completing the Partner Link Configuration
Click Apply and then OK to complete the configuration and create the partner link with the required WSDL settings for the File Adapter service.
The WriteAck Partner Link appears in the BPEL process diagram.
Adding the Partner Link for File Adapter
This step is to configure an Invoke activity to send the purchase order acknowledgement that is received from the Receive activity to the WriteAck partner link in an XML file.
To add an Invoke activity:
In JDeveloper BPEL Designer, drag and drop the Invoke activity from the Component Palette into the process diagram, after the Receive activity.
Link the Invoke activity to the WriteAck service. The Invoke activity will send event data to the partner link. The Edit Invoke dialog box appears.
Editing the Invoke Activity
Enter a name for the Invoke activity, and click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog box appears.
Select Global Variable and then enter a name for the variable. You can also accept the default name. Click OK.
Click Apply and then OK in the Edit Invoke dialog box to finish configuring the Invoke activity.
The Invoke activity appears in the process diagram.
Use this step to pass the purchase order acknowledgement details from the Receive activity to the Invoke activity.
To add an Assign activity:
In JDeveloper BPEL Designer, drag and drop the Assign activity from the Component Palette into the Activity box of the process diagram, between the Receive activity and the Invoke activity.
Adding an Assign Activity
Double-click the Assign activity to access the Edit Assign dialog box.
On the Copy Operation tab, click Create and select Copy Operation from the menu. The Create Copy Operation window appears.
In the From navigation tree, select type Variable. Navigate to Variable > Process > Variables > Receive_DEQUEUE_InputVariable > CONFIRM_BOD_004 and select ns3:CONFIRM_BOD_004. The XPath field should contain your selected entry.
In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_Write_InputVariable > CONFIRM_BOD_004 and select ns3:CONFIRM_BOD_004. The XPath field should contain your selected entry.
Specifying Assign Parameters
Click OK.
Click Apply and then OK in the Edit Assign dialog box to complete the configuration of the Assign activity.
After designing the BPEL process, you can compile, deploy and test it.
You must 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
Select the BPEL project in the Applications window.
Right-click the project name, and then select Deploy > [Server Connection] > Deploy to Default Domain from the menu that appears.
Deploy the BPEL Process
The BPEL process is compiled and deployed. You can check if the deployment is successful in the Apache Ant log.
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.
Note: For details on using the Transaction Monitor, see Oracle XML Gateway User's Guide.
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.
To validate the design-time tasks created earlier, you can log in to Oracle E-Business Suite to manually create and book the order as well as generate the order acknowledgement by submitting a Workflow Background Process concurrent request.
To manually test the BPEL process:
Log in to Oracle Applications with the XML Gateway responsibility.
This is to ensure that the XML Gateway trading partner is set up correctly so that a purchase order can have a valid customer that has been defined.
Select Define Trading Partner from the navigation menu to access the Trading Partner Setup window.
Enter the header values in the Trading Partner Setup form as follows:
Trading Partner Type: Customer
Trading Partner Name: For example, Business World
Trading Partner Site: Enter a trading partner site information. For example, 2391 L Street, San Jose, CA 95106
Company Admin Email: Enter a valid e-mail address.
Enter the following trading partner details:
Transaction Type: ECX
Transaction SubType: CBODO
Standard Code: OAG
External Transaction Type: BOD
External Transaction SubType: CONFIRM
Direction: Out
Map: ECX_CBODO_OAG72_OUT_CONFIRM
Connection / Hub: DIRECT
Protocol Type: BPEL
Username: 'operation'
Password: enter 'welcome' twice
Protocol Address: 'http://ebssoa.sample.com'
Source Trading Partner Location Code: BWSANJOSE
Save your work.
To successfully generated PO Acknowledgement, you need to create an order and then manually book the order through Order Management.
Use the following steps to create an order and then manually book the order:
Switch to Order Management Super User, Vision Operations (USA) responsibility and select Customer > Standard from the navigation menu to open the Enter Customer form.
Search on the 'Business World' in the Name field and click Find.
Select the Business World with the following information from the search results:
Account Name: Business World
Registry ID: 2813
Identifying check box: checked
Address: 2391 L Street, San Jose, CA 95106
Country: United States of America
Select row with the following entries:
Account Number:1608
Account Description: Business World
Status: Active
Click Details to open the Customer Information page.
Click Details in the row with the Business World with Address '2391 L Street, San Jose, CA 95106' and Country 'United States of America'. This opens the Customer Account page.
Enter 'BWSANJOSE' in the EDI Location field.
In the Business Purposes tab, create a new row with the following values:
Usage: Sold To
Check on 'Primary' Check box
Save your work.
Use the following steps to generate acknowledgement for an already created order:
Log in to Oracle Applications with the Order Management Super User, Vision Operations (USA) responsibility. Select Order Returns > Sales Order to open the Sales Order form.
Retrieve the order that you have created earlier by entering the order ID in the Customer PO field, such as order_xmlg_008.
Click Book Order to book the order.
Booking an Order
Switch to the System Administrator responsibility and select Request > Run.
Select Single Request and click OK.
Enter the following information in the Submit Request form:
Specifying Parameters
Name: Workflow Background Process
Enter the following parameters:
Item Type: OM Send Acknowledgement
Process Deferred: Y
Process Timeout: N
Process Stuck: N
Click OK.
Click Submit to submit 'send acknowledgement' request.
View your request by entering the request ID to ensure its status is 'Success'.
Validating Using Oracle Transaction Monitor
To validate it using Oracle Transaction Monitor, you need to log in to Oracle Applications with the Workflow Administrator Web Applications responsibility. Select Transaction Monitor to open the search window to search for the order.
Searching from the Transaction Monitor
Validating Using Oracle BPEL Console
Log in to Oracle BPEL Console to confirm that the XMLGOutbound process has been deployed. This process is continuously polling the ECX_OUTBOUND queue for purchase order acknowledgement.
To verify, select the instance of your deployed process. This opens up in the Instances tab of your selected BPEL process.
Click on the Audit Tab to view the Receive activity. Click the view xml document link to open the XML file received. Please note that the Reference ID in the XML file represents the Customer PO in the Sales Orders form.
Viewing XML File for the Receive Activity
On approval of the order, Oracle E-Business Suite triggers the workflow that creates the Purchase Order Acknowledgement flow and sends out the PO Acknowledgement as an XML file. The workflow delivers the Confirm BOD as the PO Acknowledgement to the ECX_OUTBOUND queue for delivery to the other system.
On the other hand, Oracle BPEL PM listens to the ECX_OUTBOUND queue for the message with the correlation Id = “BPEL” which is the same id for this outbound message. The Confirm BOD as the PO Acknowledgement is written as XML file using File Adapter.
Since the BPEL process is deployed, the process is continuously polling the ECX_OUTBOUND queue for PO acknowledgement. It also writes PO Acknowledgement in the directory you specified after receiving from XML Gateway ECX_OUTBOUND queue.
Go to the directory you specified for the write operation, such as outputDir logical location (typically c:\temp) where the File Adapter has placed the file after writing the PO Acknowledgement in an XML file (POAck060719175318.xml).
Open this POAck060719175318.xml file. You should find the Reference ID as order_xmlg_008 (the order booked) for which the acknowledgement is generated.
Validating the Output File
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, and then edit the Correlation="BPEL" line contained in the <jca:operation> 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.
You can enable debugging for XML Gateway using the BPEL Process Manager.
To enable debugging:
Log in to your BPEL Process Manager domain.
Select yourdomain.collaxa.cube.ws
Select Debug.
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.
Copyright © 2005, 2009, Oracle and/or its affiliates. All rights reserved.