Using Business Events Through Subscription Model

Overview

The Oracle Workflow Business Event System (BES) is an application service that leverages the Oracle Advanced Queuing (AQ) infrastructure to communicate business events between systems. The Business Event System consists of the Event Manager and workflow process event activities.

The Event Manager lets you register subscriptions to significant events; event activities representing business events within workflow processes let you model complex business flows or logics within workflow processes.

Events can be raised locally or received from an external system or the local system through AQ. When a local event occurs, the subscribing code is processed in the same transaction as the code that raised the event, unless the subscriptions are deferred.

Oracle E-Business Suite Integrated SOA Gateway supports business events through event subscription. An integration administrator can subscribe to a business event from the business event interface details page. The subscription to that event can be enqueued as an out agent. An integration developer can create a SOA composite application with BPEL process in Oracle JDeveloper to include the subscribed event at design time and update application data if needed at runtime.

To better understand how the subscription model works for business events, detailed tasks at design time and runtime are included in this chapter. For the example described in the following sections, Oracle JDeveloper 11g (11.1.1.6.0) is used as a design-time tool to create a SOA composite application with BPEL process, and Oracle SOA Suite 11g (11.1.1.6.0) is used for the process deployment.

Note: While using Oracle JDeveloper with other Oracle Fusion Middleware components (such as Oracle SOA Suite), to enable SOA technologies, you need to manually download Oracle SOA Suite Composite Editor, an Oracle JDeveloper extension for SOA technologies. For more information on installing additional Oracle Fusion Middleware design-time components, see the Oracle Fusion Middleware Installation Guide for Oracle JDeveloper.

Using a Business Event in Creating a SOA Composite Application with BPEL Process at Design Time

SOA Composite Application with BPEL Process Scenario

Take a PO XML Raise business event as an example to explain the SOA composite application with BPEL process creation.

When a purchase order is created and approved, a Purchase Order Approved business event oracle.apps.po.event.xmlpo is raised. Since the subscription to this event is created through the interface details page (internally, an event subscription is automatically created for the selected event with WF_BPEL_QAGENT as Out Agent), and enqueued in WF_EVENT_T structure to Advanced Queue WF_BPEL_Q, we will create a BPEL process to first dequeue the subscription from the WF_BPEL_Q queue to get the event details. The event details will be passed through BPEL process activities and then written in XML file as an output file.

When the BPEL process has been successfully processed after deployment, the same purchase order information should be obtained from the output file once a purchase order is approved.

Prerequisites to Create a SOA Composite Application with BPEL Process Using a Business Event

An integration administrator must first subscribe to a business event from the Oracle Integration Repository user interface. Internally, an event subscription is automatically created for that event with WF_BPEL_QAGENT as Out Agent.

For example, a business event oracle.apps.po.event.xmlpo needs to be subscribed. A confirmation message appears if the event subscription has been successfully created.

To subscribe to a business event, the administrator will first locate an event from the Oracle Integration Repository, and then click Subscribe in the interface detail page to create the subscription.

For information on how to subscribe to business events, see Subscribing to Business Events, Oracle E-Business Suite Integrated SOA Gateway Implementation Guide.

Note: If a BPEL process is created with the business event that you have subscribed to it, in order for the subscribed business event to be successfully enqueued to WF_BPEL_Q queue, you need to make sure:

Once the subscription is created and enqueued, an integration developer can then orchestrate the subscribed event into a meaningful business process in Oracle JDeveloper using BPEL language at design time.

SOA Composite Application with BPEL Process Creation Flow

Based on the PO XML Raise business event scenario, the following design-time tasks are discussed in this chapter:

  1. Create a new SOA Composite Application with BPEL Process

    Use this step to create a new SOA composite application with BPEL process called GetPurchaseOrder.bpel.

  2. Create a Partner Link for AQ Adapter

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

  3. Add a Receive activity

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

  4. Create a Partner Link for File Adapter

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

  5. Add an Invoke activity

    This is to write business event 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 how to create SOA composite applications using BPEL process service component, see the Oracle Fusion Middleware Developer's Guide for Oracle SOA Suite for details.

Creating a New SOA Composite Application with BPEL Process

Use this step to create a new SOA composite application with BPEL process that will contain various BPEL process activities.

To create a new SOA composite application with BPEL process:

  1. Open Oracle JDeveloper.

  2. Click New Application in the Application Navigator.

    The "Create SOA Application - Name your application" page is displayed.

  3. Enter an appropriate name for the application in the Application Name field and select SOA Application from the Application Template list.

    Click Next. The "Create SOA Application - Name your project" page is displayed.

  4. Enter an appropriate name for the project in the Project Name field, for example, GetPOProject.

  5. In the Project Technologies tab, select 'Web Services' and ensure that SOA is selected from the Available technology list to the Selected technology list.

    Click Next. The "Create SOA Application - Configure SOA settings" page is displayed.

  6. Select Composite With BPEL Process from the Composite Template list, and then click Finish. You have created a new application, and a SOA project. This automatically creates a SOA composite.

    The Create BPEL Process page is displayed.

  7. Leave the default BPEL 1.1 Specification selection unchanged. This creates a BPEL project that supports the BPEL 1.1 specification.

    Enter an appropriate name, for example GetPurchaseOrder, for the BPEL process in the Name field.

    Select Define Service Later in the Template field. Click OK.

    An empty BPEL process is created. The required source files including bpel and wsdl, using the name you specified (for example, GetPurchaseOrder.bpel and GetPurchaseOrder.wsdl) and composite.xml are also generated.

  8. Click Finish.

  9. Navigate to SOA Content > Business Rules and double click composite.xml to view the composite diagram.

    Composite Diagram

    the picture is described in the document text

    Double click on the GetPurchaseOrder component to open the BPEL process.

Creating a Partner Link for AQ Adapter

Use this step to create a Partner Link called GetPurchaseOrder for AQ Adapter to dequeue the subscription to oracle.apps.po.event.xmlpo event.

To create a partner link for AQ Adapter to dequeue the event subscription:

  1. In Oracle JDeveloper, drag and drop the AQ Adapter service from the BPEL Services list into the right Partner Link swim lane of the process diagram. The Adapter Configuration wizard welcome page appears.

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

  3. Enter a service name in the Service Name dialog box, for example GetPO.

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

  5. 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 for the database connection. Click Next.

    2. Enter appropriate user name and password information 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.

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

  7. Click Next to open Adapter Interface dialog box.

    Select the Define from operation and schema (specified later) radio button and click Next. The Operation dialog box appears.

  8. Select the Dequeue radio button in the Operation Type field. 'Dequeue' is also populated in the Operation Name field.

    Operation Dialog

    the picture is described in the document text

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

    Select 'APPS' in the Database Schema field. Enter 'WF_BPEL_Q' in the Queue Name field.

    Queue Name Dialog

    the picture is described in the document text

  10. Click Next to open the Queue Parameters dialog box.

    Queue Parameters Dialog

    the picture is described in the document text

    Enter the following information:

    • Enter a unique consumer name.

      Important: In order for the subscribed business event to be successfully enqueued to WF_BPEL_Q queue, the consumer name must be unique.

    • Enter message selector rule information (such as tab.user_data.geteventname()='oracle.apps.po.event.xmlpo').

  11. Click Next. The Messages dialog box opens where you can define the message that will be contained in the Business Event System payload for the APPS.WF_BPEL_Q queue.

    Click Browse for schema file to open the Type Chooser window.

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

    Click the Browse Resources.. icon to display the SOA Resource Browser window. Select the xsd folder as the location and APPS_NE_WF_EVENT_T file from the folder.

    SOA Resource Browser Window

    the picture is described in the document text

    Click OK twice.

    In the Type Chooser window, expand the Project Schema Files and select WF_EVENT_T schema from the APPS_NE_WF_EVENT_T.xsd. Click OK.

    The selected APPS_NE_WF_EVENT_T.xsd is displayed as URL and the WF_EVENT_T element is selected as Schema Element.

    Messages Dialog with Selected Schema

    the picture is described in the document text

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

  13. Click Finish. The wizard generates the WSDL file corresponding to the GetPO 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 GetPO that you configured for the AQ adapter service for the business event.

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 to obtain Purchase Order XML data:

  1. In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Receive activity into the center swim lane of the process diagram.

  2. Link the Receive activity to the GetPO 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 such as 'Receive_PO' and then 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. Click Apply and then OK to finish configuring the Receive activity.

    Edit Receive Dialog

    the picture is described in the document text

    The Receive activity appears in the BPEL process diagram.

Adding a Partner Link for File Adapter

Use this step to configure a business event by writing the event data to an XML file.

To add a Partner Link for File Adapter:

  1. In Oracle JDeveloper, drag and drop the File Adapter service from the BPEL Services list into the right Partner Link swim lane of the process diagram. The Adapter Configuration wizard appears.

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

  3. Enter a name for the file adapter service, such as WritePurchaseOrder.

  4. Click Next. The Adapter Interface dialog box appears.

  5. Select the Define from operation and schema (specified later) radio button and click Next. The Operation dialog box appears.

    Operation Dialog

    the picture is described in the document text

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

    the picture is described in the document text

  7. For the Directory specified as field, select Physical Path. Enter directory path in the Directory for Outgoing Files field, and specify a naming convention for the output file such as PO_%SEQ%.xml.

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

  9. Select Browse for schema file in front of the URL field.

    The Type Chooser dialog is displayed.

    Type Chooser Dialog

    the picture is described in the document text

    Expand the Project Schema Files and select WF_EVENT_T schema from the APPS_NE_WF_EVENT_T.xsd. Click OK.

    The selected APPS_NE_WF_EVENT_T.xsd is displayed as URL and the WF_EVENT_T element is selected as Schema Element.

    Messages Dialog with Selected Schema

    the picture is described in the document text

  10. 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 WritePurchaseOrder.wsdl.

    Edit Partner Link Dialog

    the picture is described in the document text

    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 WritePurchaseOrder Partner Link appears in the BPEL process diagram.

    BPEL Process Diagram with Partner Link Added for File Adapter

    the picture is described in the document text

Adding an Invoke Activity

This step is to configure an Invoke activity to write the purchase order approved event details that is received from the Receive activity to the WritePurchaseOrder partner link in an XML file.

To add an Invoke activity:

  1. In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Invoke activity from the Component Palette into the center swim lane of the process diagram, after the Receive activity.

  2. Link the Invoke activity to the WritePurchaseOrder service. The Invoke activity will send event data to the partner link. 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 to close the Create Variable dialog box.

    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.

    BPEL Process Diagram with Invoke Activity Added

    the picture is described in the document text

Adding an Assign Activity

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

To add an Assign activity:

  1. In Oracle JDeveloper, expand the BPEL Constructs from the Component Palette. Drag and drop the Assign activity from the Component Palette into the center swim lane of the process diagram, between the Receive activity and the Invoke activities.

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

  3. Select the Copy Rules tab and expand the source and target trees:

    • In the From navigation tree, navigate to Variable > Process > Variables > Receive_PO_Dequeue_InputVariable and select WF_EVENT_T element.

    • In the To navigation tree, navigate to Variable > Process > Variables > Invoke_WritePO_Write_InputVariable and select body.

    Drag the source node (WF_EVENT_T) to connect to the target node (body) that you just identified. This creates a line that connects the source and target nodes. The copy rule is displayed in the From and To sections at the bottom of the Edit Assign dialog box.

    Edit Assign Dialog

    the picture is described in the document text

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

Click the composite.xml to display the Oracle JDeveloper composite diagram.

Deploying and Testing the SOA Composite Application with BPEL Process at Runtime

After creating a SOA composite application with the subscribed event in BPEL process, you need to deploy it to the Oracle WebLogic managed server. This can be achieved using Oracle JDeveloper. Once the composite is deployed, it can be tested from the Oracle Enterprise Manager Fusion Middleware Control Console.

Prerequisites

Before deploying the SOA composite with BPEL process using Oracle JDeveloper, you must have established the connectivity between the design-time environment and the runtime server. For information on how to configure the necessary server connection, see Configuring Server Connection.

Note: If a local instance of the Oracle WebLogic Server is used, start the WebLogic Server by selecting Run > Start Server Instance from Oracle JDeveloper. Once the WebLogic Admin Server "DefaultServer" instance is successfully started, the <Server started in Running mode> and DefaultServer started message in the Running:DefaultServer and Messages logs should appear.

Perform the following runtime tasks:

  1. Deploy the SOA Composite Application with BPEL Process

  2. Manually initiate the SOA Composite Application with BPEL Process

Deploying the SOA Composite Application with BPEL Process

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

To deploy the SOA composite application with BPEL process:

  1. In the Applications Navigator of JDeveloper, select the GetPOProject project.

  2. Right-click the project and select Deploy > [project name] > [serverConnection] from the menu.

    For example, you can select Deploy > GetPOProject > SOAServer to deploy the process if you have the connection appropriately.

    Note: If this is the first time to set up the server connection, then the Deployment Action dialog appears. Select 'Deploy to Application Server' and click Next.

    In the Deploy Configuration dialog, ensure the following information is selected before clicking Next to add a new application server:

    • New Revision ID: 1.0

    • Mark composite revision as default: Select this checkbox.

    • Overwrite any existing composites with the same revision ID: Select this checkbox.

    The steps to create a new Oracle WebLogic Server connection from Oracle JDeveloper are covered in Configuring Server Connection.

  3. In the Select Server dialog, select 'soa-server1' that you have established the server connection earlier.

    Click Next.

  4. In the SOA Servers dialog, accept the default target SOA Server ('soa-server1') selection.

    Click Next and Finish.

  5. If you are deploying the composite for the first time from your Oracle JDeveloper session, the Authorization Request window appears. Enter username and password information specified during Oracle SOA Suite installation. Click OK.

  6. Deployment processing starts. Monitor deployment process and check for successful compilation in the SOA - Log window.

    Verify that the deployment is successful in the Deployment - Log window.

Testing the SOA Composite Application with BPEL Process

Once the BPEL process contained in the SOA composite application has been successfully deployed, you can manage and monitor the process from Oracle Enterprise Manager Fusion Middleware Control Console. You can also test the process and the integration interface by manually initiating the process.

Log in to Oracle E-Business Suite to manually initiate the purchase order approval and acknowledgement processes and to confirm that the relevant event is raised and the updated purchased order details is also written in the XML file.

To manually test the BPEL process contained in the SOA composite application:

  1. Navigate to Oracle Enterprise Manager Fusion Middleware Control Console (http://<hostname>:<port>/em). The login page appears.

  2. Enter the username and password information specified during the Oracle SOA Suite installation. Click Login to log in to a farm. The composite (GetPurchaseOrder) you deployed is displayed in the Applications Navigation tree.

    You may need to select an appropriate target instance farm if there are multiple target Oracle Enterprise Manager Fusion Middleware Control Console farms.

    For more information about Oracle SOA Suite, see the Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.

  3. From the Farm navigation pane, expand the SOA > soa-infra node in the tree to navigate through the SOA Infrastructure home page and menu to access your deployed SOA composite applications running on soa-infra managed server.

    Ensure that GetPurchaseOrder has been deployed.

  4. Log in to Oracle E-Business Suite as a user who has 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 supplier that has been defined.

  5. Select Define Trading Partner from the navigation menu to access the Trading Partner Setup window.

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

    • Trading Partner Type: Supplier

    • Trading Partner Name: Enter a trading partner name, such as Example Inc.

    • Trading Partner Site: Enter a trading partner site information.

    • Company Admin Email: Enter a valid email address.

  7. Enter the following trading partner details:

    • Transaction Type: PO

    • Transaction SubType: PRO

    • Standard Code: OAG

    • External Transaction Type: PO

    • External Transaction SubType: Process

    • Direction: Out

    • Map: itg_process_po_007_out

    • Connection / Hub: DIRECT

    • Protocol Type: SOAP

    Trading Partner Setup Form

    the picture is described in the document text

  8. Save the trading partner details. Switch responsibility back to Purchasing, Vision Operations (USA) and select Purchase Order from the navigation menu.

  9. Create a purchase order with the header values reflecting the trading partner you previously defined in the Purchase Orders form:

    • Supplier: Enter a supplier information.

    • Site: Select a site information.

  10. On the Lines tab, enter a data row with the following values:

    • Type: Goods

    • Item: CM13139

    • Quantity: 1

    • Description: Hard Drive - 8GB

    • Promised: Enter any future date in the format of dd-mmm-yyyy (such as 23-JUN-2008).

  11. Save your purchase order. The status of the purchase order is 'Incomplete'.

    Note: Because the trading partner is set up and valid, the transmission method is automatically set to XML.

  12. Click Approve to approve the purchase order.

    Purchase Orders Form

    the picture is described in the document text

    The status of the purchase order is now changed to 'Approved'. For future reference, record the value of the PO, Rev field (for example, the PO number 5789).

    Once the purchase order is approved, the business event oracle.apps.po.event.xmlpo is raised.

  13. Log in to Oracle Enterprise Manager Fusion Middleware Control Console to confirm that the GetPurchaseOrder BPEL process has been completed.

    To verify, click the Instances tab. The SOA composite application instance ID, name, conversation ID, most recent known state of each instance since the last data refresh of the page are displayed.

  14. Click your BPEL service component instance link (such as GetPurchaseOrder) to display the Instances page where you can view the process details of the BPEL activities in the Audit Trail tab. Click the Flow tab to check the BPEL process flow diagram.

  15. Double-click on the Receive activity in the BPEL process diagram and click the View XML document link to open the XML file. Note that the purchase order (number 5789) has been received.

    Verification of the Receive Event Name

    the picture is described in the document text

  16. Examine the Assign and Invoke activities as well for the event raised and document number.

  17. Go to the directory you specified for the write operation, for example outputDir (typically c:\temp). Open the output file (for example PO_1.xml), and confirm that the order number is the same as that of the approved purchase order.

    Confirmation of the Output Order Number

    the picture is described in the document text