Using XML Gateway Inbound and Outbound Interfaces

Overview

Oracle E-Business Suite Integrated SOA Gateway provides a communication infrastructure between Oracle E-Business Suite and Web consumers. Inbound and outbound XML data is exchanged between the consumers and Oracle E-Business Suite through Oracle XML Gateway.

Oracle XML Gateway provides a common, standards-based approach for XML integration. XML is key to an integration solutions, as it standardizes the way in which data is searched, exchanged, and presented thereby enabling interoperability throughout the supply chain.

Oracle XML Gateway provides a set of services that can be easily integrated with Oracle E-Business Suite to support XML messaging. It uses the message propagation feature of Oracle Advanced Queuing to integrate with Oracle Transport Agent to deliver outbound XML messages to and receive inbound XML messages or transactions from business partners.

To enable bidirectional integration with Oracle E-Business Suite and consumers, Oracle E-Business Suite Integrated SOA Gateway supports XML Gateway Map interface type through the following approaches:

• For an inbound XML Gateway Map interface, once a Web service of an inbound XML Gateway interface is deployed, the deployed service representing in WSDL can be used in creating a BPEL process to insert inbound data into Oracle E-Business Suite.

• For an outbound XML Gateway Map interface, since an outbound message is first enqueued to the ECX_OUTBOUND queue, Oracle E-Business Suite Integrated SOA Gateway supports it through subscription model by first dequeuing the message to retrieve outbound data from Oracle E-Business Suite by using a BPEL process. The retrieved data can then be passed to trading partners or consumers who subscribed to the message.

To better understand how to use a deployed Web service of an inbound XML Gateway interface as well as understand how the subscription model works for an outbound XML Gateway, the following topics are introduced in this chapter:

• Using XML Gateway Inbound Web Services

  • Using XML Gateway Inbound Services at Design Time

  • Deploying and Testing the BPEL Process at Run Time

• Using XML Gateway Outbound Through Subscription Model

  • Using XML Gateway Outbound Messages in Creating a BPEL Process at Design Time

  • Deploying and Testing a BPEL Process at Run Time

For the examples described in the following sections, we use Oracle JDeveloper 10.1.3.3.0 as a design-time tool to create the BPEL processes and use Oracle SOA Suite BPEL server 10.1.3.3.0 for the process deployment.

Using XML Gateway Inbound Services

This section includes the following topics:

• Using XML Gateway Inbound Services at Design Time

• Deploying and Testing the BPEL Process at Run Time

Using XML Gateway Inbound Services at Design Time

BPEL Process Scenario

Take the XML Gateway Inbound Process PO XML Transaction as an example to explain the BPEL process creation. In this example, the XML Gateway inbound message map is exposed as a web service through PROCESS_PO_007 inbound map. It allows sales order data including header and line items to be inserted into Order Management system while an associated purchase order is created.

When a purchase order is sent by a trading partner, the purchase order data is used as input to the BPEL process along with ECX Header properties such as MESSAGE_TYPE, MESSAGE_STANDARD, TRANSACTION_TYPE, TRANSACTION_SUBTYPE, PARTY_SITE_ID, and DOCUMENT_NUMBER. The BPEL process then pushes this purchase order in 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 order data to Order Management Application.

If the BPEL process is successfully executed after deployment, you should get the same order information inserted into the Order Management table once a purchase order is created.

Prerequisites to Configure a BPEL Process Using an XML Gateway Inbound Service

Before performing the design-time tasks for XML Gateway Inbound services, you need to ensure the following tasks are in place:

• An integration repository administrator needs to successfully deploy the XML Gateway Inbound message map to the application server.

• An integration developer needs to locate and record the deployed WSDL URL for the inbound message map exposed as a web service.

• XML Gateway header variables need to be populated for XML transaction.

• Agent listeners need to be up and running.

Deploying XML Gateway Inbound WSDL URL

An integration repository administrator must first create a web service for the selected XML Gateway inbound map, and then deploy the service from Oracle Integration Repository to the application server.

For example, the administrator must perform the following steps before letting the integration developers use the deployed WSDL in creating a BPEL process:

1. To generate a web service, locate the interface definition first (such as an XML Gateway inbound interface INBOUND:Process Purchase Order XML Transaction (ONT:POI)) and click Generate WSDL in the interface details page.

   Once the service is successfully generated, the Web Service - SOA Provider region appears in the interface details page.

   Note: Since XML Gateway Map interface types can be service enabled by Web Service Provider (for Oracle E-Business Suite Release 12.0) and SOA Provider (after the Release 12.0), you may also find the Web Service - Web Service Provider region as well if there are Web services generated through Web Service Provider from Oracle E-Business Suite Release 12.0.

   However, there is no design difference in terms of creating BPEL processes using XML Gateway inbound services whether the services are enabled through SOA Provider or Web Service Provider.

   For detailed instruction on how to generate a web service, see Generating Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

2. To deploy a generated web service, select at least one authentication type and click Deploy in the Web Service - SOA Provider region of the interface details page to deploy the service.

   Once the service is successfully deployed, the selected authentication type(s) will be displayed along with 'Deployed' Web Service Status. For more information on securing web services with authentication types, see Managing Web Service Security, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

   For information on how to deploy a web service, see Deploying, Undeploying, and Redeploying Web Services, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

   Searching and Recording WSDL URL

   An integration developer also needs to log on to the system to locate and record the deployed web service WSDL URL for the inbound message map.

   This WSDL information will be used later in creating a partner link for the inbound map exposed as a web service during the BPEL process creation at design time.

   XML Gateway Interface Details Page to Record a Deployed WSDL URL

   

For information on how to search for an interface and review the interface details, see Searching and Viewing Integration Interfaces.

Populating XML Gateway Header Variables

You need to populate certain variables in the BPEL PM in order to provide XML Gateway header information for Oracle E-Business Suite. The MESSAGE_TYPE, MESSAGE_STANDARD, TRANSACTION_TYPE, TRANSACTION_SUBTYPE, DOCUMENT_NUMBER and PARTY_SITE_ID are the mandatory header variables that you need to populate for the XML transaction to complete successfully.

Refer to Adding an Assign activity for more information.

Ensuring Agent Listeners Are Up and Running

You need to ensure that listeners on the ECX_INBOUND, ECX_TRANSACTION queues are up and running. Use the following steps to configure these listeners in Oracle E-Business Suite:

1. Log in to Oracle E-Business Suite with the Workflow Administrator responsibility.

2. Click the Workflow Administrator Web Applications link from the Navigator.

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 if they are not up and running.

BPEL Process Creation Flow

After deploying the BPEL process, you should get the same order information inserted into the Order Management table once a purchase order is created.

Based on the XML Gateway Inbound Process PO XML Transaction business scenario, the following design-time tasks are discussed in this chapter:

1. Create a new BPEL project

   Use this step to create a new BPEL project called XMLGatewayInbound.bpel using an Synchronous BPEL Process template. This automatically creates two dummy activities - Receive and Reply - to receive input from a trading partner and to reply output of the BPEL process back to the request application.

2. Create a Partner Link

   Use this step to create a partner link to allow the inbound message to be inserted to the Oracle E-Business Suite.

3. Add a Partner Link for File Adapter

   Use this step to add a partner link for File Adapter in order to pick up an XML file received from the trading partner to get the XML message.

4. Add Invoke activities

   Use this step to add two Invoke activities in order to:

   1. To get the XML message details that is received from the Receive activity.

   2. To enqueue the purchase order information to the ECX_INBOUND queue.

5. Add Assign activities

   Use this step to create two Assign activities in order to:

   1. To pass XML message obtained from the first Invoke activity to the second Invoke activity.

   2. To pass ECX header variables to the second Invoke activity as input variables.

For general information and basic concept of a BPEL process, see Understanding BPEL Business Processes and Oracle BPEL Process Manager Developer's Guide for details.

Creating a New BPEL Project

Use this step to create a new BPEL project that will contain various BPEL process activities.

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 produces a list of available categories.

4. Expand the General node and then select Projects.

5. Select BPEL Process Project from the Items group.

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

   BPEL Project Creation Wizard - Project Settings Dialog

   

7. In the Name field, enter a descriptive name such as XMLGatewayInbound.

8. From the Template list, select Asynchronous BPEL Process and then select Use Default Project Settings.

9. Use the default input and output schema elements in the Input/Output Elements dialog box.

10. Click Finish.

    A new asynchronous BPEL process is created with the Receive and Callback activities. The required source files including bpel.xml, using the name you specified (for example, XMLGInbound.bpel) are also generated.

    BPEL Process Diagram

    

Creating a Partner Link

Use this step to create a Partner Link called ONT_POI to insert sales order data to Oracle E-Business Suite.

To create a partner link to insert sales data to Oracle E-Business Suite:

1. In JDeveloper BPEL Designer, drag and drop the PartnerLink service from the Component Palette into the Partner Link border area of the process diagram. The Service Name dialog box appears.

2. Copy the WSDL URL corresponding to the XML Gateway inbound map INBOUND:Process Purchase Order XML Transaction (ONT:POI) that you recorded earlier in the WSDL File field.

   A Partner Link Type message dialog box appears asking whether you want the system to create a new WSDL file that will by default create partner link types for you.

   Click Yes to have the Partner Name value populated automatically. The name is defaulted to ONT_POI.

   Select Partner Role and My Role fields from the drop-down lists.

   Edit Partner Link Dialog

   

   Click Apply.

3. Select the Property tab and click the Create Property icon to select the following properties from the property name drop-down list in order to pass the security header along with the SOAP request:

   • wsseUsername

     Specify the username to be passed in the Property Value box.

   • wssePassword

     Specify the corresponding password for the username to be passed in the Property Value box.

   • wsseHeaders

     Enter credentials as the property value.

   Click Apply to save the selected property values.

   Edit Partner Link Dialog with Property Tab

   

4. Click OK to complete the partner link configuration. The partner link is created with the required WSDL settings, and is represented in the BPEL project by a new icon in the border area of the process diagram.

Adding Partner Links for File Adapter

Use this step to configure a BPEL process by adding a partner link for File Adapter to get the XML Message.

To add the Partner Link for File Adapter to get the XML Message:

1. In JDeveloper BPEL Designer, drag and drop the File Adapter service from the Adapter Service section of the Component Palette into the Partner Link area of the process diagram. The Adapter Configuration wizard welcome page appears.

2. Click Next. The Service Name dialog box appears.

3. Enter a name for the file adapter service, such as GetXMLMsg. You can add an optional description of the service.

4. Click Next and the Operation dialog box appears.

   Operation Dialog

   

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

   File Directories Dialog

   

6. Select Physical Path radio button and enter the physical path for incoming file directory information. For example, enter /usr/tmp/.

   Note: To be able to locate the file from the physical directory you specified here, you must first place the input payload file (such as order_data_xmlg.xml) to the specified directory.

   Alternatively, click Browse to locate the incoming file directory information.

   Uncheck the Delete files after successful retrieval check box. Click Next.

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

8. Select Browse to open the Type Chooser.

   Click Import Schema Files button on the top right corner of the Type Chooser window. This opens the Import Schema File pop-up window.

   Enter the schema location for the service. Such as http://<myhost>:<port>/webservices/SOAProvider/xmlgateway/ont__poi/PROCESS_PO_007.xsd.

   Schema location for your service can be found from the service WSDL URL (for example, http://<myhost>:<port>/webservices/SOAProvider/xmlgateway/ont__poi/?wsdl).

   Import Schema File Pop-up Window

   

   Select the Add to Project check box and click OK.

9. Click OK to the Import Project Schema message prompt.

   Import Project Schema Message Prompt

   

   The Imported Schemas folder is automatically added to the Type Chooser window.

10. Expand the Imported Schemas folder and select PROCESS_PO_007.xsd > PROCESS_PO_007. Click OK.

    The selected xsd is displayed as Schema Location, and PROCESS_PO_007 is selected as Schema Element.

11. Click OK to populate the selected values in the Messages dialog box.

    Messages Dialog with Selected Schema and Element

    

12. 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 BPEL process diagram.

Adding Invoke Activities

This step is to configure three Invoke activities:

1. To get the XML message details that is received from the Receive activity by invoking the GetXMLMsg partner link in an XML file.

2. To enqueue the purchase order information to the ECX_INBOUND queue by invoking ONT_POI partner link in an XML file.

To add the first Invoke activity for a partner link to get XML message:

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

2. Link the Invoke activity to the GetXMLMsg service. The Edit Invoke dialog box appears.

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

4. Select Global Variable and then enter a name for the variable. You can also accept the default name. Click OK.

5. Enter a name for the Invoke activity and click the Create icon next to the Output Variable field to create a new variable. The Create Variable dialog box appears.

6. Select Global Variable, and enter a name for the variable. You can also accept the default name. Click OK.

   Edit Invoke Dialog

   

   Click Apply and then OK in the Edit Invoke dialog box to finish configuring the Invoke activity.

   The first Invoke activity appears in the process diagram.

To add the second Invoke activity for a partner link to enqueue PO information:

1. 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 and Callback activities.

2. Link the Invoke activity to the ONT_POI service. The Edit Invoke dialog box appears.

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

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

5. The process diagram appears.

   BPEL Process Diagram with Two Invoke Activities

   

Adding Assign Activities

This step is to configure two Assign activities:

1. To pass XML message as an input to the Invoke activity for enqueuing message.

2. To pass XML Gateway header variables as input variables to the Invoke activity in order to provide context information for Oracle E-Business Suite.

To add the first Assign activity to pass XML message as input to the Invoke activity:

1. In JDeveloper BPEL Designer, drag and drop the Assign activity from the Component Palette into the Activity box of the process diagram, between the two Invoke activities.

2. Double-click the Assign activity to access the Edit Assign dialog box.

3. Click the General tab to enter the name for the Assign activity, such as 'SetOrderXML'.

4. On the Copy Operation tab, click Create and then select Copy Operation from the menu. The Create Copy Operation window appears.

5. Enter the following information:

   • In the From navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_SynchRead_OutputVariable and select Process_PO_007.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_PROCESSPO_InputVariable and select body.

     Create Copy Operation Dialog to Assign Parameters

     

   • Click OK. The Edit Assign dialog box appears.

6. Click Apply and then OK to complete the configuration of the Assign activity.

To add the second Assign activity to pass XML Gateway header variables to the Invoke activity:

1. 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 SetOrderXML Assign activity and the second Invoke activity.

2. Repeat Step 2 to Step 4 described in creating the first Assign activity to add the second Assign activity called 'SetECXHeader'.

3. On the Copy Operation tab, click Create and then select Copy Operation from the menu. The Create Copy Operation window appears.

4. Enter the first pair of parameters:

   • In the From navigation tree, select type Expression and then enter 'XML' in the Expression box.

   • In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_PROCESSPO_InputVariable > header > ns1:SOAHeader > ns3:ECXMSG and select MESSAGE_TYPE.

     The XPath field should contain your selected entry.

     Create Copy Operation Dialog to Assign Value in the Expression Region

     

   • Click OK.

5. Use the same mechanism described in step 3 and 4 to enter the following additional parameters:

   • MESSAGE_STANDARD: 'OAG'

   • TRANSACTION_TYPE: 'PO'

   • TRANSACTION_SUBTYPE: 'PROCESS'

   • DOCUMENT_NUMBER: 'order_xml_01'

   • PARTY_SIDE_ID: 'BWSANJOSE'

   Edit Assign Dialog with Copy Operation Tab

   

6. Click Apply and OK to complete the configuration of the Assign activity.

Deploying and Testing the BPEL Process at Run Time

After creating a BPEL process using the WSDL URL generated from the XML Gateway inbound message map interface definition, you can deploy it to a BPEL server if needed. To ensure that this process is modified or orchestrated appropriately, you can also manually test the BPEL process by initiating the business process contained in the BPEL process to test the interface integration.

Prerequisites

Before deploying the BPEL process using Oracle JDeveloper, you must ensure that you have established the connectivity between the deign-time environment and the run-time servers including the application server and the integration server.

How to configure the necessary server connection, see Configuring Server Connection.

To validate your BPEL process, perform the following run-time tasks:

1. Deploy the BPEL process

   Once you deploy the process to a BPEL server, it becomes available so that you can run the process manually to test it for validation.

2. Test the BPEL process

   After deploying a BPEL process, you can manage the process from the BPEL console to validate the interface integration contained in your BPEL process.

Deploying the BPEL Process

You must deploy the BPEL process (XMLGatewayInbound.bpel) that you created earlier 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 service, you should:

• Load the order_data_xmlg.xml file into the specified directory '/usr/tmp/' folder of SOA Suite server (or D:\HOL in case of SOA Server in Windows machine).

• Edit the input file order_data_xmlg.xml by entering values for <REFERENCEID> and <POID> such as 'order_xml_01'.

To deploy the BPEL process:

1. In the Applications Navigator of JDeveloper BPEL Designer, select the XMLGInbound project.

2. Right-click the project and click Make action from the menu.

   Look for any compilation error messages in Message Log.

   Messages Window

   

   Right-click the project and select Deploy > Integration Server Connection name > Deploy to Default Domain action from the menu.

   For example, you can select Deploy > BPELServerConn > Deploy to Default Domain to deploy the process if you have the BPEL Process Manager setup appropriately.

3. Look for 'Build successful' message in Apache Ant – Log to ensure that the BPEL project is compiled and successfully deployed.

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. Log in to Oracle Application Server 10g BPEL Console (http://<soaSuiteServerHostName>:<port>/BPELConsole). The BPEL Console login page appears.

2. Enter the username and password and click Login.

   The Oracle Enterprise Manager 10g BPEL Control appears.

3. In the BPEL Console, confirm that XMLGInbound has been deployed.

4. Click the XMLGInbound link to open the Initiate tab

5. Click Post XML Message to initiate the process.

Verifying Records in Oracle E-Business Suite

Once the BPEL process is successfully initiated and completed, you can validate it through the relevant module in Oracle E-Business Suite.

To validate it in Oracle Transaction Monitor:

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 E-Business Suite 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.

1. Log in to Oracle E-Business Suite with the Workflow Administrator Web Applications responsibility.

   Select the Transaction Monitor link to open the search window to search for the order.

   Transaction Monitor: Search Page

   

2. Clear From Date and To Date fields and enter 'order_xml_01' in the Document ID field.

3. Select Customer as the Party Type. Click Go to execute the search.

   This retrieves XML inbound transaction 'order_xml_01' in the Inbound Search Results region.

4. Confirm that the transaction 'order_xml_01' has status 'SUCCESS'.

To validate it in Oracle Order Management:

1. Log in to the Forms-based Oracle E-Business Suite with the Order Management, Super User responsibility.

2. Select Order Returns > Sales Order. Sales Order Forms would open up.

3. Search for an order by entering the order number in the Customer PO field (such as 'order_xml_01'). This would bring up the details of newly created order.

   Sales Orders Forms

   

   You can also select the Items tab for item details.

Using XML Gateway Outbound Through Subscription Model

This section includes the following topics:

• Using XML Gateway Outbound Messages in Creating a BPEL Process at Design Time

• Deploying and Testing a BPEL Process at Run Time

Using XML Gateway Outbound Services at Design Time

For an outbound XML Gateway Map interface, since an outbound message is first enqueued to the ECX_OUTBOUND queue, Oracle E-Business Suite Integrated SOA Gateway supports it through subscription model by first dequeuing the message to retrieve outbound data and then invoking an appropriate outbound XML Gateway map to update Oracle E-Business Suite.

BPEL Process Scenario

Take XML Gateway outbound interface 'PO acknowledgement XML Transaction' as an example. The XML Gateway outbound interface is exposed as a Web service through ECX_CBODO_OAG62_OUT outbound map.

When a purchase order is created and approved, on approval of the purchase order, a workflow will be triggered which 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 ECX_OUTBOUND queue for delivery to the other system.

The correlation Id for this message is set to “BPEL” and the Oracle BPEL PM listens to ECX_OUTBOUND queue for the message with the correlation Id = “BPEL”. Confirm BOD as the PO Acknowledgement is written as an output XML file using File Adapter.

If the BPEL process is successfully executed after deployment, you should get the same order book reference ID (Customer PO) information from the output XML file once a purchase order is approved.

Prerequisites to Create a BPEL Process Using XML Gateway Outbound Messaging

You need to set up the correlation identifier in Oracle E-Business Suite. 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 E-Business Suite 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. Search for COMM_METHOD in the Type field to see if it exists in the system.

5. Add a new record to the COMM_METHOD type by entering BPEL for the Code field and Meaning field. Enter description information and save the record.

   Oracle XML Gateway puts the correlation of BPEL when enqueueing the message on the ECX_OUTBOUND queue.

Once you have the correlation identifier set up correctly, you also need to ensure the trading partner that you want to use has the Protocol Type field set to BPEL.

BPEL Process Creation Flow

Based on the PO acknowledgement XML Transaction scenario, the following design-time tasks are discussed in this chapter:

1. Create a new BPEL project

   Use this step to create a new BPEL project called XMLGOutbound.bpel.

2. Create a Partner Link for AQ Adapter

   Use this step to dequeue the event details from the ECX_OUTBOUND queue.

3. Add a Receive activity

   Use the Receive activity to take PO acknowledgement details as an input to the Assign activity.

4. Add a Partner Link for File Adapter

   This is to write PO acknowledgement details in an XML file as an output file.

5. Add an Invoke activity

   This is to write PO acknowledgement information to an XML file through invoking the partner link for File Adapter.

6. Add an Assign activity

   Use the Assign activity to take the output from the Receive activity and to provide input to the Invoke activity.

For general information and basic concept of a BPEL process, see Understanding BPEL Business Processes and Oracle BPEL Process Manager Developer's Guide for details.

Creating a New BPEL Project

Use this step to create a new BPEL project that will contain various BPEL process activities.

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 Technologies from the Filter By box. This produces a list of available categories.

4. Expand the General node and then select Projects.

5. Select BPEL Process Project from the Items group.

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

7. In the Name field, enter a descriptive name such as XMLGOutbound.

8. From the Template list, select Empty BPEL Process and then select Use Default Project Settings.

9. Click Finish.

   A new BPEL project is created with the required source files including bpel.xml, using the name you specified (for example, XMLGOutbound.bpel).

Creating a Partner Link for AQ Adapter

Use this step to create a Partner Link called GetAck for AQ Adapter to dequeue the XML Gateway outbound message (for example, ECX_CBODO_OAG62_OUT) in the ECX_OUTBOUND queue.

To create a partner link for AQ Adapter:

1. In JDeveloper BPEL Designer, drag and drop the AQ Adapter service from the Component Palette into the Partner Link border area of the process diagram. The Adapter Configuration Wizard appears.

2. Enter a service name in the Service Name dialog box, for example GetAck. You can also add an optional description of the service.

   Service Name Dialog

   

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

4. You can use an existing database connection by selecting a database connection from the Connection list or define a new database connection by clicking New to open the Create Database Connection Wizard.

   Note: You need to connect to the database where Oracle E-Business Suite is running.

   To create a new database connection:

   1. Click New to open the Create Database Connection Wizard. Click Next and enter an unique connection name and then select a connection type, such as Oracle (JDBC), for the database connection. Click Next.

   2. Enter an appropriate username and password to authenticate the database connection in the Authentication dialog box. Click Next

   3. Specify the following information in the Connection dialog box:

      • Driver: Thin

      • Host Name: Enter the host name for the database connection. For example, myhost01.example.com.

      • JDBC Port: Enter JDBC port number (such as 1521) for the database connection.

      • SID: Specify an unique SID value (such as sid01)for the database connection.

   4. Click Next to test your database connection.

      The status message "Success!" indicates a valid connection.

   5. Click Next to return to the Service Connection dialog box providing a summary of the database connection.

5. The JNDI (Java Naming and Directory Interface) name corresponding to the database connection you specified appears automatically in the JNDI Name field of the Service Connection dialog box. Alternatively, you can enter a different JNDI name.

6. Click Next to open Operation dialog box.

   Select Dequeue radio button and this selected value is also populated in the Operation Name field.

   Operation Dialog

   

7. Click Next to open the Queue Name dialog box.

   Select Default Schema as the Database Schema field. Enter 'ECX_OUTBOUND' as the Queue Name field.

   Queue Name Dialog

   

8. Click Next to open the Queue Parameter dialog box.

   Queue Parameters Dialog

   

   Enter the following information:

   • Enter an unique consumer name.

   • Enter message selector rule information (such as tab.user_data.transaction_type='PO' AND tab.user_data.transaction_subtype='POO').

9. Click Next. The Messages dialog box opens.

   Click Browse to open the Type Chooser window to select CONFIRM_BOD_002.xsd as the Schema Location and CONFIRM_BOD_002 as the Schema Element.

10. Click Next to proceed to the Finish dialog box to confirm that you have finished defining the AQ Adapter for the GetAck service.

11. Click Finish. The wizard generates the WSDL file corresponding to the GetAck service.

    Click Apply and then OK to complete the partner link configuration. The partner link is created with the required WSDL settings, and is represented in the BPEL project by a new icon in the border area of the process diagram.

Adding a Receive Activity

This step is to configure a Receive activity to receive XML data from the partner link GetAck that you configured for the AQ adapter service.

The XML data received from the Receive activity is used as an input variable to the Assign activity that will be created in the next step.

To add a Receive activity:

1. In JDeveloper BPEL Designer, drag and drop the Receive activity from the BPEL Activities section of the Component Palette into the Activity box of the process diagram.

2. Link the Receive activity to the GetAck partner link. The Receive activity will take event data from the partner link. The Edit Receive dialog box appears.

3. Enter a name for the receive activity. Click the Create icon next to the Variable field to create a new variable. The Create Variable dialog box appears.

4. Select Global Variable, and then enter a name for the variable. You can accept the default name. Click OK to return to the Edit Receive dialog box.

5. Select Create Instance check box. Click Apply and OK to finish configuring the Receive activity.

   Edit Receive Dialog

   

   The Receive activity appears in the BPEL process diagram.

Adding a Partner Link for File Adapter

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:

1. In JDeveloper BPEL Designer, drag and drop the File Adapter service from the Adapter Service section of the Component Palette into the Partner Link area of the process diagram. The Adapter Configuration wizard appears.

2. The Service Name dialog box appears.

3. Enter a name for the File Adapter service, such as WriteAck. You can add an optional description of the service.

4. Click Next and the Operation dialog box appears.

   Operation Dialog

   

5. Specify the operation type, for example Write File. This automatically populates the Operation Name field.

   Click Next to access the File Configuration dialog box.

   File Configuration Dialog

   

6. 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 such as POAck%yyMMddJJmmss%.xml.

7. Confirm the default write condition: Number of Messages Equals 1. Click Next. The Messages dialog box appears.

8. Select Browse check box to locate the schema location and schema element.

   The Type Chooser dialog box appears. Expand the Project Schema Files > CONFIRM_BOD_002.xsd and select CONFIRM_BOD_002.

   Type Chooser Dialog

   

   Click OK to populate the selected schema location and element.

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

   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 an Invoke Activity

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:

1. In JDeveloper BPEL Designer, drag and drop the Invoke activity from the Component Palette into the Activity box of the process diagram, after the Receive activity.

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

   Edit Invoke Dialog

   

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

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

Adding an Assign Activity

Use this step to pass the purchase order acknowledgement details from the Receive activity to the Invoke activity.

To add an Assign activity:

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

2. Double-click the Assign activity to access the Edit Assign dialog box.

3. On the Copy Operation tab, click Create and then select Copy Operation from the menu. The Create Copy Operation window appears.

4. In the From navigation tree, select type Variable. Navigate to Variable > Process > Variables > Receive_DEQUEUE_InputVariable and select CONFIRM_BOD_002. The XPath field should contain your selected entry.

5. In the To navigation tree, select type Variable. Navigate to Variable > Process > Variables > Invoke_Write_InputVariable and select CONFIRM_BOD_002. The XPath field should contain your selected entry.

6. Click OK.

   Click Apply and then OK in the Edit Assign dialog box to complete the configuration of the Assign activity.

Deploying and Testing the BPEL Process at Run Time

After creating the BPEL process, you can deploy it to a BPEL server. To ensure that this process is modified or orchestrated appropriately, you can also test the BPEL process by initiating the business process contained in the BPEL process to test the interface integration.

Prerequisites

Before deploying the BPEL process using Oracle JDeveloper, you must ensure that you have established the connectivity between the deign-time environment and the run-time servers including the application server and the integration server.

How to configure the necessary server connection, see Configuring Server Connection.

To validate the BPEL process, preform the following run-time tasks:

1. Deploy the BPEL process

   Once you deploy the process to a BPEL server, it becomes available so that you can run the process manually to test it for validation.

2. Manually test the BPEL process

   After deploying a BPEL process, you can manage the process from the BPEL console to manually initiate the business process and test the interface integration contained in your BPEL process.

Deploying the BPEL Process

Before manually test the BPEL process, you first need to deploy it to the BPEL server.

To deploy the BPEL process:

1. In the Applications Navigator of JDeveloper BPEL Designer, select the XMLGOutbound project.

2. Right-click the project and click Make action from the menu.

   Look for any compilation error messages in Message Log.

   Right-click the project and select Deploy >Integration Server Connection name > Deploy to Default Domain action from the menu.

   For example, you can select Deploy > BPELServerConn > Deploy to Default Domain to deploy the process if you have the BPEL Process Manager setup appropriately.

3. Look for 'Build successful' message in Apache Ant – Log to ensure that the BPEL project is compiled and successfully deployed.

Testing the BPEL Process

To validate whether the BPEL process that you created works or not, you need to manually initiate the process after it has been successfully deployed to the BPEL console. You can log on 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.

Log in to the BPEL console to validate the BPEL process which writes purchase order acknowledgement in an output directory after receiving from the XML Gateway ECX_OUTBOUND queue.

To manually test the BPEL process:

1. Log in to Oracle E-Business Suite 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.

2. Select Define Trading Partner from the navigation menu to access the Trading Partner Setup form.

3. Enter the header values on the Trading Partner Setup form as follows:

   • Trading Partner Type: Customer

   • Trading Partner Name: For example, Example Inc.

   • Trading Partner Site: Enter a trading partner site information. For example, 401 Island Parkway Redwood Shores, CA 94065

   • Company Admin Email: Enter a valid email address.

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

   • Connection / Hub: DIRECT

   • Protocol Type: BPEL

   • Username: 'operation'

   • Password: enter password twice

   • Protocol Address: 'http:us.example.com'

   • Source Trading Partner Location Code: Example-01

   Trading Partner Setup Form

   

5. Save the trading partner details. Switch responsibility back to Order Management Super User, Vision Operations (USA) and select Customer > Standard from the navigation menu to open the Enter Customer form.

6. Search on the 'Example Inc' in the Name field and click Find.

7. Select the Business World with the following information from the search results.

   • Party Number: 2813

   • Customer Number: 1608

   • Account Name: Example Inc.

   • Identifying check box: checked

   • Address: 401 Island Parkway Redwood Shores, CA 94065

8. Select and open this customer information. Enter 'Example-01' in the EDI Location field.

9. In Business Purposes tab, create a new row with the following values:

   • Usage: Sold To

   • Check on 'Primary' Check box

   Save your work.

10. Use the following steps to generate acknowledgement for already created order.

    1. Select Order Returns > Sales Order to open the Sales Order form.

    2. Retrieve the order that you have created earlier by entering the order ID in the Customer PO field.

    3. Click Book Order to book the order.

       Booking an Order

       

11. Switch to the System Administrator responsibility and select Request > Run.

12. Select Single Request and click OK.

13. Enter the following information in the Submit Request form:

    Submit Request Form and Parameters Dialog

    

    • Name: Workflow Background Process

    • Enter the following parameters:

      • Item Type: OM Send Acknowledgement

      • Process Deferred: Y

      • Process Timeout: N

      • Process Stuck: N

    • Click OK.

14. Click Submit to submit the 'send acknowledgement' request.

15. 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, log in to Oracle E-Business Suite with the Workflow Administrator Web Applications responsibility. Select Transaction Monitor to open the search page to search for the order.

Transaction Monitor: Search Page

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 which 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 received XML file. Note the Reference ID such as Customer PO.

Viewing XML File for the Receive Activity

Go to the directory you specified for the write operation, for example outputDir - logical location (typically c:\temp) where the File Adapter has placed the file after writing the PO Acknowledgement in an XML file (such as '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.

PO Acknowledgement XML File