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 executed 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 repository 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 BPEL process in Oracle JDeveloper to include the subscribed event at design time and update application data if needed at run time.

To better understand how the subscription model works for business events, detailed tasks at design time and run time are included in this chapter. For the example described in the following sections, we use Oracle JDeveloper 10.1.3.3.0 as a design-time tool to create the BPEL process and use Oracle SOA Suite BPEL server 10.1.3.3.0 for the process deployment.

Using a Business Event in Creating a BPEL Process at Design Time

BPEL Process Scenario

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

When a purchase order is created and approved, a Purchase Order Approved business event oracle.apps.po.evnt.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 will be written in XML file as an output file.

If the BPEL process is successfully executed after deployment, you should get the same purchase order information from the output file once a purchase order is approved.

Prerequisites to Create a BPEL Process Using a Business Event

Integration repository administrators 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 is successfully created.

Business Event Details Page

the picture is described in the document text

To subscribe to a business event, the administrators 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.

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 BPEL project

    Use this step to create a new BPEL project 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.

Example of a BPEL Project Using Business Events

the picture is described in the document text

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

  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, GetPurchaseOrder.bpel).

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.evnt.xmlpo event.

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

  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 GetPurchaseOrder. You can also add an optional description of the service.

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

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

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

    Queue Name Dialog

    the picture is described in the document text

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

    Queue Parameters Dialog

    the picture is described in the document text

    Enter the following information:

    • Enter an 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.evnt.xmlpo').

  9. 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 to open the Type Chooser window to select APPS_WF_EVENT_T.xsd as the Schema Location and WF_EVENT_T as the Schema Element.

    Messages Dialog with Selected Message Schema

    the picture is described in the document text

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

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

    Create Partner Link Dialog

    the picture is described in the document text

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

    Create Variable Dialog

    the picture is described in the document text

  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 then 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 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 WritePurchaseOrder. You can add an optional description of the service.

  4. Click Next and the Operation dialog box appears.

    Operation Dialog

    the picture is described in the document text

  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

    the picture is described in the document text

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

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

  8. Select Native format translation is not required (Schema is Opaque) check box.

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

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 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 WritePurchaseOrder service. The Invoke activity will send event data to the partner link. The Edit Invoke dialog box appears.

    Edit Invoke Dialog

    the picture is described in the document text

  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.

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 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 dialog box appears.

    Create Copy Operation Dialog

    the picture is described in the document text

  4. In the From navigation tree, select type Variable. Navigate to Variable > Process > Variables > Receive_PO_DEQUEUE_InputVariable > WF_EVENT_T and select ns3:WF_EVENT_T element. The XPath field should contain your selected entry.

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

  6. Click OK to close the Create Copy Operation dialog box.

    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 a BPEL process with the subscribed event, you can deploy it to a BPEL server if needed. 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 initiate 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 GetPurchaseOrder 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.

    Compilation and Deployment Message Logs

    the picture is described in the document text

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. Therefore, the validation starts with the BPEL console to ensure that you can find the deployed BPEL process listed in the console. Then, you can log on 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:

  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 Control console, confirm that GetPurchaseOrder has been deployed.

    Oracle Enterprise Manager BPEL Control Console

    the picture is described in the document text

  4. 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 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: For example, 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 Order window:

    • 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, note 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 BPEL Process Manager, and return to the BPEL Console to confirm that the GetPurchaseOrder process has been completed.

    To verify, select the instance of your deployed process which opens up in the Instances tab of your selected BPEL process.

    Instances Tab with the Selected BPEL Process Flow

    the picture is described in the document text

  14. Double-click 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.

    Receive XML File to Verify the Purchase Order Number

    the picture is described in the document text

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

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

    Output XML File to Confirm the Order Number

    the picture is described in the document text