Skip Headers

Oracle Fusion Middleware Adapter for Oracle Applications User's Guide
11g Release 1 (11.1.1)
Part Number E10537-02
Go to Table of Contents
Contents
Go to previous page
Previous
Go to next page
Next

Using Business Events

This chapter covers the following topics:

Overview of Business Events

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 contains a registry of business events, systems, named communication agents within those systems, and subscriptions indicating that an event is significant to a particular system. 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.

Subscriptions can include the following types of processing:

Business events are represented within workflow processes by event activities. By including event activities in a workflow process, you can model complex processing or routing logic for business events beyond the options of directly running a predefined function or sending the event to a predefined recipient.

Each business event represents a ready to use integration or extension point. Oracle E-Business Suite currently ships preconfigured with over 900 business events.

The uses of the Business Event System include:

Business Events Concepts

Event

A business event is an occurrence in an Internet or intranet application or program that might be significant to other objects in a system or to external agents. For instance, the creation of a purchase order is an example of a business event in a purchasing application.

Event Key

A string that uniquely identifies an instance of an event. Together, the event name, event key, and event data fully communicate what occurred in the event.

Event Message

A standard Workflow structure for communicating business events, defined by the datatype WF_EVENT_T. The event message contains the event data as well as several header properties, including the event name, event key, addressing attributes, and error information.

Event Activity

A business event modeled as an activity so that it can be included in a workflow process.

Event Data

A set of additional details describing an event. The event data can be structured as an XML document. Together, the event name, event key, and event data fully communicate what occurred in the event.

Event Subscription

A registration indicating that a particular event is significant to a system and specifying the processing to perform when the triggering event occurs. Subscription processing can include calling custom code, sending the event message to a workflow process, or sending the event message to an agent.

Deferred Subscription Processing

If you do not want subscriptions for an event to be executed immediately when the event occurs, you can defer the subscriptions. In this way you can return control more quickly to the calling application and let the Event Manager execute any costly subscription processing at a later time.

Agent

An agent is a named point of communication within a system. Communication within and between systems is accomplished by sending a message from one agent to another. A single system can have several different agents representing different communication alternatives. For example, a system may have different agents to support inbound and outbound communication, communication by different protocols, different propagation frequencies, or other alternatives.

Design-Time Tasks for Outbound Business Events

Adapter for Oracle Applications is deployed at design-time using Oracle JDeveloper and at run-time using the BPEL Process Manager.

This section discusses the process of configuring Adapter for Oracle Applications to create business event outbound subscriptions. It describes the tasks required to configure Adapter for Oracle Applications using the Adapter Configuration Wizard in Oracle JDeveloper.

Multiple BPEL Processes Consuming the Same Business Event

Please note that Adapter for Oracle Applications can handle multiple BPEL processes consuming the same business event. Adapter for Oracle Applications creates only single subscription for a particular business event regardless of the number of BPEL process consuming it. Internally, this subscription forwards business event message to a multi-consumer AQ. Since each BPEL process is an unique consumer for the event, when the message is placed in the queue, all BPEL processes are notified. Therefore, as a user you do not need to create a separate subscription for each BPEL process. All you need to do is to create the service for the event, and Adapter for Oracle Applications will take care of message delivery to each BPEL process.

For example, if there are three BPEL processes (BPEL1, BPEL2, and BPEL3) that want to consume the same business event (such as BE1 event). For each BPEL process, you create a service for the BE1 event using Adapter for Oracle Applications. Adapter for Oracle Applications in turn creates a single subscription for all the three BPEL processes - BPEL1, BPEL2, and BPEL3. This subscription puts BE1 event message in multi-consumer AQ.

At run time, when a BE1 event is raised, since the subscription is applicable to all the three BPEL processes, all these three deployed BPEL processes will be activated and would receive the same BE1 event message.

BPEL Process Scenario

Take a PO XML Raise business event as an example.

When a purchase order is created and approved, a purchase order approved business event oracle.apps.po.evnt.xmlpo is raised. The subscription to this event is created in the background to listen to the business event and get event details. The event data will be passed through BPEL process activities and then 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 Configure Outbound Business Events

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.

  2. Create a partner link.

  3. Configure a Receive activity.

  4. Add a partner link for the file adapter.

  5. Configure an Invoke activity.

  6. Configure an Assign activity.

Creating a New BPEL Project

To create a new BPEL project

  1. Launch Oracle JDeveloper.

  2. Click New Application in the Application Navigator.

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

    The Create SOA Application - Name your application Page

    the picture is described in the document text

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

    The Create SOA Application - Name your project Page

    the picture is described in the document text

  5. In the Project Technologies tab, 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.

    The Create SOA Application - Configure SOA settings Page

    the picture is described in the document text

  6. Click Finish. You have created a new application, and an SOA project. This automatically creates an SOA composite.

    The Create BPEL Process page is displayed.

    The Create BPEL Process Page

    the picture is described in the document text

  7. Enter an appropriate name for the BEPL process in the Name field. For example, GetPOAckBusinessEvent.

    Select Define Service Later from 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, GetPOAckBusinessEvent.bpel and GetPOAckBusinessEvent.wsdl) and composite.xml are also generated.

    An Empty BPEL Process

    the picture is described in the document text

Creating a Partner Link

Configuring an outbound business event requires creating a partner link to allow the outbound event to be published.

This task adds a partner link to the BPEL process. A partner link defines the link name, type, and the role of the BPEL process that interacts with the partner service.

To add a partner link

  1. Click BPEL Services in the Component palette.

    Drag and drop Oracle Applications from the BPEL Services list into the right Partner Link swim lane of the process diagram. The Adapter Configuration Wizard Welcome page appears. Click Next.

  2. Enter a service name in the Service Name field. For example, GetPOApprovalEvent.

    Enter the Service Name

    the picture is described in the document text

    Click Next. The Service Connection dialog appears.

    Specifying a Database Service Connection

    the picture is described in the document text

  3. You can perform either one of the following options for your database connection:

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

  4. Once you have completed creating a new connection for the service, you can add a business event by browsing through the list available in Oracle Applications.

    Click Next.

    For Oracle E-Business Suite Release 12:

    If you are connecting to Oracle E-Business Suite Release 12, then the IREP File not present dialog appears indicating that Adapter could not find the Oracle Integration Repository data file corresponding to the database you are connecting in your workspace. Absence of the data file would make browsing or searching of Integration Repository tree considerably slow. You can choose to extract the data file and create a local copy of the Integration Repository data file. Once it is created successfully, Adapter will pick it up automatically next time and retrieve data from your local Integration Repository.

    You can select one of the following options:

    For Oracle E-Business Suite pre-Release 11.5.10:

    If you are connecting to a pre-11.5.10 Oracle Applications instance, you must select the interface type in the Adapter Configuration Wizard. Select Workflow Business Event System to proceed.

    Click Get Object in the Application Interface dialog to open the Oracle Applications Module Browser.

  5. The Oracle Applications Module Browser combines interface data from Oracle Integration Repository with information about the additional interfaces supported by Oracle Application Adapter, organized in a tree hierarchy.

    Oracle Applications Module Browser

    the picture is described in the document text

    The Oracle Applications Module Browser includes the various product families that are available in Oracle Applications. Each product family contains the individual products. Each product contains the business entities associated with the product. Business entities contain the various application modules that are exposed for integration. These modules are grouped according to the interface they provide.

    Note: Business Events can be found in the Other Interfaces node, which is at the product family level. For more information, see Using the Oracle Applications Module Browser.

  6. Expand the navigation tree to Product Families > Other Interfaces > Business Events > Outbound. The direction outbound is from the Oracle E-Business Suite perspective, in this case listening to business events from Oracle Applications. Select the appropriate business event, for example, oracle.apps.po.event.xmlpo, and click OK. The Application Interface page is displayed with selected business event.

    Adapter Configuration Wizard - Application Interface Page

    the picture is described in the document text

  7. Click Next in the Application Interface page. The WF Event Schema Definition page for business event payload appears.

    Selecting Business Event Payload Schema

    the picture is described in the document text

  8. You must specify one of the following options to be used for the business event payload:

    No Schema

    If you select the No Schema option, then the payload data would be available in the form of string. This option also allows you to receive non-XML event payload.

    Any Schema

    If you select the Any Schema option, then XML payload of any schema could be attached to event payload. You should select this option if you know the payload is XML, but not sure of its schema.

    Note: When you select either the 'No Schema' or 'Any Schema' option, there is no need to further specify the schema information for your business event service, and you will proceed to the next step.

    Specify Schema

    If you select the Specify Schema option, then the Schema Location and Schema Element fields become visible. You must specify the location of schema file and then select the schema element that defines the payload of outbound business event.

    To specify schema location and element

    1. Click Browse to search for an existing schema definition in the Type Chooser.

    2. Click the Import Schema File icon at the upper right of the Type Chooser, then click the Browse File System icon to open the Import Schema File dialog.

      Selecting a Schema File

      the picture is described in the document text

    3. Click the Browse icon to open the SOA Resource Browser dialog.

    4. In the Location field, select the 'xsd' file from the schema folder.

      Specifying Schema URL

      the picture is described in the document text

      Select the schema file APPS_WF_EVENT_T.xsd. Click OK in the SOA Resource Browser dialog. Click OK in the Import Schema File dialog. The Type Chooser reappears.

      Choosing the Schema

      the picture is described in the document text

    5. Select the schema element WF_EVENT_T for the business event and click OK. The WF Event Schema Definition page reappears with your selected schema URL and element information populated.

      Populating Selected Business Event Payload Schema

      the picture is described in the document text

      Click Next.

      The Finish page appears indicating that you have finished defining the business event service. The wizard generates the GetPOApprovalEvent WSDL file corresponding to the oracle.apps.po.event.xmlpo business event service.

      The main Create Partner Link dialog appears with the new WSDL file.

  9. Click Apply and then OK to complete the partner link configuration.

    Partner Link Information

    the picture is described in the document text

    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.

Configuring the Receive Activity

The next task is to configure a Receive activity to receive event details from the partner link that you just configured for the Oracle Application adapter service as an input to the Assign activity.

To configure the Receive activity

  1. In JDeveloper BPEL Designer, click BPEL Services and Components in the Component palette.

    Drag and drop Receive from the BPEL activity list into the center swim lane of the process diagram.

  2. Link the Receive activity to the partner link GetPOApprovalEvent that you just created earlier.

    Associating the Receive Activity with the Partner Link

    the picture is described in the document text

    The Receive dialog appears.

    Configuring the Receive Activity

    the picture is described in the document text

  3. Enter an appropriate name for the Receive activity.

    The Dequeue Operation is automatically selected since the partner link has been configured with an outbound business event.

  4. Specify a Variable to receive the message data from the partner link by clicking the Create icon to the right of the Variable field. The Create Variable dialog box appears.

  5. Click OK to accept the default name.

  6. Click Apply in the Receive dialog, then click OK.

Adding a Partner Link for the File Adapter

If you are configuring an outbound business event, you need to add another partner link for the file adapter. This allows the outbound business event to write the data to the XML file.

To add a partner link for the file adapter

  1. In JDeveloper BPEL Designer, click BPEL Services in the Component palette.

    Drag and drop File Adapter from the BPEL Services list into the right Partner Link swim lane of the process diagram. The Adapter Configuration Wizard Welcome page appears.

    Click Next.

  2. In the Service Name page, enter a name for the file adapter service. For example, enter WriteEventData.

    Specifying the Service Name

    the picture is described in the document text

  3. Enter a name for the file adapter service, for example, WriteEventData.

  4. Click Next. The Adapter Interface page appears.

    Specifying the Adapter Interface

    the picture is described in the document text

    Select the Define from operation and schema (specified later) radio button and click Next.

  5. In the Operation page, specify the operation type. For example, select the Write File radio button. This automatically populates the Operation Name field.

    Specifying the Operation

    the picture is described in the document text

  6. Click Next to access the File Configuration page.

    Configuring the Output File

    the picture is described in the document text

  7. For the Directory specified as field, select the Logical Name radio button. Enter outputDir as the Directory for Outgoing Files (logical name) and specify a naming convention for the output file, such as EventAck%yyMMddHHmmss%.xml.

    Tip: When you type a percent sign (%), you can choose from a list of date variables or a sequence number variable (SEQ) as part of the filename.

    Confirm the default write condition: Number of Messages Equals 1.

  8. Click Next, and the Messages page appears. For the output file to be written, you must provide a schema.

  9. Click Browse to access the Type Chooser.

  10. Expand the node by clicking Project Schema Files > WF_EVENT_T.xsd. Select WF_EVENT_T as the element and click OK.

    The selected schema information will be automatically populated in the URL and Schema Element fields.

    Populating the Selected Message Schema

    the picture is described in the document text

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

    Completing the Partner Link Configuration

    the picture is described in the document text

  12. Click Apply and then OK to complete the configuration and create the partner link with the required WSDL settings for the File Adapter service.

Configuring the Invoke Activity

After adding the File Adapter partner link, you need to configure an Invoke activity to associate it with the File Adapter link.

Through the Invoke activity, the business event information can be written to the XML file you specified as the output directory.

To configure the Invoke activity

  1. In JDeveloper BPEL Designer, select BPEL Activities and Components in the component palette.

    Drag and drop an Invoke activity into the center swim lane of the process diagram after the Receive activity.

  2. Link the Invoke activity to the WriteEventData File Adapter service.

    Associating Invoke with the File Adapter Link

    the picture is described in the document text

    The Invoke activity will send event data to the partner link. The Edit Invoke dialog appears.

  3. Enter a name for the Invoke activity, then click the Create icon next to the Input Variable field to create a new variable. The Create Variable dialog appears.

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

    Editing the Invoke Activity

    the picture is described in the document text

    Click Apply and then OK to finish configuring the Invoke activity.

Configuring the Assign Activity

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

To configure the Assign activity

  1. In JDeveloper BPEL Designer, select BPEL Activities and Components in the component palette.

    Drag and drop the Assign activity into the center swim lane of the process diagram, between the Receive activity and the Invoke activity.

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

    Click the General tab to enter a name for the Assign activity. For example, setEventData.

  3. Select the Copy Operation tab, click the 'Plus' sign icon and select Copy Operation from the menu. The Create Copy Operation window appears.

    Specifying a Copy Operation Action

    the picture is described in the document text

  4. In the From navigation tree, select type Variable, then navigate to Variable > Process > Variables > Receive_DEQUEUE_InputVariable > WF_EVENT_T and select ns4:WF_EVENT_T. The XPath field should contain your selected entry.

    Defining the Copy Operation

    the picture is described in the document text

  5. In the To navigation tree, select type Variable, then navigate to Variable > Process > Variables > Invoke_Write_InputVariable > WF_EVENT_T and select ns3:WF_EVENT_T. 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.

    Completed Outbound Business Event BPEL Process Project

    the picture is described in the document text

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

    Note: Click the Source tab of composite.xml to enter a value for the physical directory outputDir for the reference WriteEventData (such as /usr/tmp).

    <property name="outputDir" type="xs:string" many="false" override="may">/usr/tmp</property>

    Specifying the Physical Directory for the Property

    the picture is described in the document text

    Oracle JDeveloper Composite Diagram

    the picture is described in the document text

Run-Time Tasks for Outbound Business Events

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

  1. Deploy the BPEL process.

  2. Test the BPEL process.

Deploying the BPEL Process

You must deploy the BPEL process before you can run it. The BPEL process is first compiled, and then deployed to the application server (Oracle WebLogic Server) that you have established the connection.

Prerequisites

Before deploying the BPEL process using Oracle JDeveloper, you must ensure the following:

To deploy the BPEL process

  1. Select your BPEL project in the Applications Navigator.

    In the Applications Navigator of JDeveloper BPEL Designer, select your BPEL project (such as GetPOAckBusinessEvent) project.

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

    Deploying the BPEL Process

    the picture is described in the document text

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

Once the BPEL process is deployed, you can manage and monitor the process from the Oracle Enterprise Manager Fusion Middleware Control Console. You can also test the process and the integration interface by manually initiating the process.

To test the BPEL process

  1. Navigate to Oracle Enterprise Manager Fusion Middleware Control Console (http://<servername>:<portnumber>/em). The composite you deployed is displayed in the Applications Navigation tree.

    the picture is described in the document text

  2. Enter username (such as weblogic) and password and click Login to log in to a farm.

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

  3. From the Farm base domain, expand the SOA > soa-infra to navigate through the SOA Infrastructure home page and menu to access your deployed SOA composite applications running in the SOA Infrastructure for that managed server.

    Note: The Farm menu always displays at the top of the navigator. When you expand the SOA folder in the navigator and click the links displayed beneath it, the SOA Infrastructure menu becomes available at the top of the page.

  4. Log on to Oracle Applications with the XML Gateway responsibility.

    This is to ensure that the XML Gateway trading partner is set up correctly so that a purchase order can have a valid 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:

  7. Enter the following trading partner details:

    Trading Partner Setup Form

    the picture is described in the document text

    Save the trading partner details.

  8. Switch responsibility by selecting the Purchasing, Vision Operations (USA) and select Purchase Order from the navigation menu.

    The Oracle Applications Forms open up with the Purchase Order forms.

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

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

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

    Setting Up a Purchase Order

    the picture is described in the document text

  12. Click Approve. The Approve Document form appears.

    Approving the Purchase Order

    the picture is described in the document text

    Click OK to confirm the approval.

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

    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 4449 in this case).

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

  13. Use the following steps to ensure that the WF_Deferred Agent Listener is running on the target database.

    1. Log in to Oracle Applications with the System Administrator responsibility.

    2. On the Oracle Applications home page, select the Workflow Administrator Web Applications responsibility. Select Oracle Applications Manager > Workflow Manager from the menu.

      Managing Oracle Applications

      the picture is described in the document text

    3. On the Applications Manager page, click the Agent Listeners icon. The Service Components page appears, containing a list of the installed agent listeners.

      Reviewing Agent Listener status

      the picture is described in the document text

    4. Confirm that the Workflow Deferred Agent Listener is in Running status.

  14. At this time, your deployed your BPEL project is listening for oracle.apps.po.event.xmlpo business event. Please allow 2-3 minutes for the BPEL process to activate after the event is raised.

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

    Confirming the Output Order Number

    the picture is described in the document text

Troubleshooting and Debugging

If you experience problems with your Business Event System integration, you can take the following troubleshooting steps:

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

Enabling Debugging

You can enable debugging for business events using the BPEL Process Manager.

To enable debugging:

  1. Log into your BPEL Process Manager domain.

  2. Select yourdomain.collaxa.cube.ws

  3. Select Debug.

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