Using Business Events of Oracle Application Server Adapter

This chapter covers the following topics:

• Overview of Business Events
• Design-Time Tasks for Outbound Business Events
• Creating a New BPEL Project
• Creating a Partner Link
• Configuring the Receive Activity
• Adding a Partner Link for the File Adapter
• Configuring the Invoke Activity
• Configuring the Assign Activity
• Run-Time Tasks for Outbound Business Events
• Deploying the BPEL Process
• Testing the BPEL Process
• Troubleshooting and Debugging

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:

• Executing custom code on the event information

• Sending event information to a workflow process

• Sending event information to other queues or systems

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:

• System integration messaging hubs - Oracle Workflow with the Business Event System can serve as a messaging hub for complex system integration scenarios. The Event Manager can be used to ”hard–wire” routing between systems based on event and originator. Workflow process event activities can be used to model more advanced routing, content–based routing, transformations, error handling, and so on.

• Distributed applications messaging - Applications can supply Generate and Receive event message handlers for their business entities. For example, message handlers can be used to implement Master/Copy replication for distributed applications.

• Message-based system integration - You can set up subscriptions, which cause messages to be sent from one system to another when business events occur. In this way, you can use the Event Manager to implement point–to–point messaging integration.

• Business–event based workflow processes - You can develop sophisticated workflow processes that include advanced routing or processing based on the content of business events.

• Non-invasive customization of packaged applications - Analysts can register interesting business events for their Internet or intranet applications. Users of those applications can register subscriptions to those events to trigger custom code or workflow processes.

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

OracleAS 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 OracleAS Adapter for Oracle Applications to create business event outbound subscriptions. It describes the tasks required to configure OracleAS Adapter for Oracle Applications using the Adapter Configuration Wizard in Oracle JDeveloper.

Prerequisites to Configure Outbound Business Events

• The agentListener must be running on WF_Deferred queue.

• The event should be enabled for BPEL to subscribe to it. The event should not be in the disabled mode.

Following is a list of the procedures required to accomplish the design-time tasks.

1. Create a new BPEL project.
2. Create a partner link.
3. Configure the Receive activity.
4. Add a partner link for the file adapter.
5. Configure the Invoke activity.
6. Configure the Assign activity.

Creating a New BPEL Project

To create a new BPEL project

1. Open JDeveloper BPEL Designer.

2. From the File menu, select New. The New Gallery dialog box appears.

   Creating a New BPEL Process Project

   

3. Select All Items from the Filter By box. This produces a list of available categories.

4. Expand the General node, then select Projects.

5. Select BPEL Process Project from the Items group.

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

   Specifying Settings for the New BPEL Process Project

   

7. In the Name field, enter a descriptive name; for example, BusinessEventOutbound.

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

9. Click Finish.

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

Creating a Partner Link

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

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 create a partner link

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

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

   Specifying the Service Name

   

3. Enter a service name; for example, ListenToPOAckEvent. You can also add an optional description of the service.

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

   Specifying a Database Service Connection

   

5. Do one of the following:

   • Use an existing database connection - Select a database connection from the Connection list, and skip to Step 6 of the current procedure.

   • Define a new database connection - Click New. The Create Database Connection Wizard appears. Continue with the following procedure to create a database connection.

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

   To create a database connection

   1. In the Create Database Connection Wizard welcome dialog, click Next. The Type dialog box appears.

      Specifying the Database Connection Type

      

   2. Enter a unique connection name, then select a connection type for the database connection.

   3. Click Next. The Authentication dialog box appears.

      Authenticating the Database Connection

      

   4. Enter an appropriate username and password to authenticate the database connection, then click Next. The Connection dialog box appears.

      Providing Database Connection Details

      

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

      • From the Driver list, select Thin.

      • Enter the host name for the database connection; for example, myhost01.example.com.

      • Enter the JDBC port number 1521 for the database connection.

      • Select SID and specify a unique SID value for the database connection; for example, sid01.

   6. Click Next. The Test dialog box appears.

   7. Click Test Connection to determine whether the specified information establishes a connection with the database. The status message "Success!" indicates a valid connection.

   8. Click Next. The Service Connection dialog box reappears, providing a summary of the database connection.

      Verifying the Database Service Connection

      

      You can now continue with step 6 of the procedure to create a partner link.

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.

   Note: When you specify a JNDI name, the deployment descriptor of the Oracle Applications adapter must associate this JNDI name with configuration properties required by the adapter to access the database.

   The JNDI name acts as a placeholder for the connection used when your service is deployed to the BPEL server. This enables you to use different databases for development and later for production.

7. Click Next to open the Applications Module Browser.

   Oracle Applications Module Browser

   

   • The Oracle Applications Module Browser lists the various product families that are available in Oracle Applications. For example, the Marketing Suite and the Order Management Suite are product families in Oracle Applications.

   • The product families contain the individual products. For example, the Order Management Suite contains the Order Management product.

   • Each product contains the business entities associated with that product. For example, the Order Management product contains the Sales Order business entity.

   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.

8. Expand the navigation tree to Product Families > Other Interfaces > Business Events > Outbound. The direction outbound is from the 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.

9. Click Next in the Operation dialog box. The WF Event Schema Definition dialog box for business event payload appears.

   Selecting Business Event Payload Schema

   

10. 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 in the Import Schema File dialog box.

       Selecting a Schema File

       

    3. In the Import Schema dialog box, navigate to the schema file APPS_WF_EVENT_T.xsd and open it. The Type Chooser reappears with the selected schema in the Imported Schemas section.

       Choosing the Schema

       

    4. Select the schema element WF_EVENT_T for the business event and click OK. The WF Event Schema Definition dialog box reappears with your selected schema location and element information populated. Click Next.

       Populating Selected Business Event Payload Schema

       

11. The Finish dialog box 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 box appears, specifying the new WSDL file.

    Completing the Partner Link Configuration

    

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

    BPEL Project with an Applications Partner Link

    

Configuring the Receive Activity

The next task is to configure a Receive activity to receive XML data from the partner link that you configured for the Oracle Application adapter service for business events.

To configure the 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.

   Adding the Receive Activity

   

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

   Editing the Receive Activity

   

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

   Creating a Variable

   

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

5. Select Create Instance, then click Apply and OK to finish configuring the Receive activity.

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 be returned to an XML file.

To add a partner link for the 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. Click Next. The Service Name dialog box appears.

   Specifying the Service Name

   

3. Enter a name for the file adapter service; for example, WriteEventData. You can also add an optional description of the service.

4. Click Next. the Operation dialog box appears.

   Specifying the Operation

   

5. Specify the operation type; in this example, Write File. This automatically populates the Operation Name field. Click Next to access the File Configuration dialog box.

   Configuring the Output File

   

6. For Directory specified as, select Logical Name. Enter outputDir as the Directory for Outgoing Files, and specify a naming convention for the output file; for example, PO_%SEQ%.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.

7. Click Next, and the Messages dialog box appears. For the output file to be written, you must provide a schema.

8. Click Browse to access the Type Chooser.

   Choosing the Message Schema

   

9. In the Type Chooser, navigate to and select the WF_EVENT_T schema from the Project Schema Files section, then click OK to return to the Messages dialog box.

   Specifying the Message Schema

   

10. Click Next, 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

    

11. Click 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 and configuring the partner link, the next task is to configure the BPEL process itself. You can start by configuring the Invoke process activity to write the business event information to the file.

To configure the 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, below the Receive activity.

   Adding the Invoke Activity

   

2. Link the Invoke activity to the WriteEventData file adapter service. The Invoke activity will send event data to the partner link. The Edit Invoke dialog box appears.

   Editing the Invoke Activity

   

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

   Creating a Variable

   

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

Configuring the Assign Activity

The next task is to add an Assign activity to the process map. This activity is configured to assign the values to the variables to invoke activity.

To configure the 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 acivity.

   Adding the Assign Activity

   

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

   Specifying a Copy Operation Action

   

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

   Defining the Copy Operation

   

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

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, then click OK in the Edit Assign dialog box to complete the configuration of the Assign activity.

   Completed Outbound Business Event BPEL Process Project

   

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 need to deploy the BPEL process before you can run it. The BPEL process is first compiled and then deployed to the BPEL server.

To deploy the BPEL process

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

   Deploying the BPEL Process

   

2. Right-click the project and select Deploy > LocalBPELServer > Deploy to Default Domain from the menu.

   The Password Prompt dialog box appears.

3. Enter the password for the default domain in the Domain Password field and click OK.

   The BPEL project is compiled and successfully deployed.

   Compilation and Deployment Message Logs

   

   

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 into Oracle BPEL Process Manager, then select BPEL Console. The BPEL console login screen appears.

2. Select Default in the Domain box. Enter the password for the default domain in the Password field and click Login to access the console.

3. In the BPEL console, confirm that BPELProcess_eng_wf_bpel_qtab has been deployed.

   Deployed BPEL Processes

   

4. Open up Oracle Applications and log in. The Oracle Applications home page appears, with the list of responsibilities.

   Accessing the Oracle Applications Home Page

   

5. Select the responsibility Purchasing, Vision Operations (USA), then click Purchase Orders within that responsibility.

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

6. Close the Forms and select File > Switch Responsibility, then select the XML Gateway responsibility.

   Selecting XML Gateway Functions

   

7. Select Define Trading Partner to access the Trading Partner forms.

   Press to access the Trading Partner Setup form.

   Setting up Trading Partners

   

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

   • Trading Partner Type - Supplier

   • Trading Partner Name - for example, Advanced Network Devices

   • Trading Partner Site - trading_partner_site_address

   • Company Admin Email - valid_email_id

9. Enter a data row with the following values:

   • 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 - HTTP

   • Username - username

   • Password - password

   • Protocol Address - valid_protocol_address

   • Source Trading Partner Location Code - valid_location_code

10. Save the trading partner details and switch responsibility back to Purchasing, Vision Operations (USA).

    Selecting Purchasing Functions

    

11. Select Purchase Orders to access the Purchase Order forms.

    Press to access the Purchase Order Setup form.

    Setting up a Purchase Order

    

12. Create a purchase order with header values reflecting the trading partner you previously defined:

    • Supplier - Advanced Network Devices

    • Site - SANTA CLARA-ERS

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

    • Item - CM13139

    • Quantity - 1

    • Promised - some_future_date

14. Save the purchase order. The Approve Document form appears.

    Approving the Purchase Order

    

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

    Click OK to approve the purchase order. The Purchase Order Setup form reappears. The status of the purchase order is now Approved. For future reference, note the value of the PO, Rev field. Once the purchase order is approved, the business event oracle.apps.po.event.xmlpo is raised.

    Next, you should ensure that the WF_Deferred agent listener is running on the target database.

16. Log into Oracle Applications as System Administrator.

    Accessing the Oracle Applications Home Page

    

17. On the Oracle Applications home page, select the Workflow Administrator Web Applications responsibility, then Oracle Applications Manager > Workflow Manager.

    Managing Oracle Applications

    

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

    

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

20. Log into Oracle BPEL Process Manager, and return to the BPEL Console.

    Confirming Completed BPEL Processes

    

21. Confirm that the BusinessEventOutbound process has completed, then select the instance, which opens up in the Instance tab. Select the Audit secondary tab.

    Auditing the BusinessEventOutbound Instance Receive Activity

    

22. Open the xml file for the Receive activity, and note the name of the event raised - oracle.apps.po.event.xmlpo.

    Examining the Receive Event Name

    

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

24. 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 same as that of the approved purchase order.

    Confirming the Output Order Number

    

Troubleshooting and Debugging

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

• Confirm that WF_Listener is up and running.

• Ensure that business events are raised only after the BPEL process is deployed.

• If the BPEL process is created on one instance of Oracle Applications and deployed on another instance, ensure the following:

  • WF_BPEL_Q, WF_BPEL_QTab, and WF_BPEL_QAgent should be present on the target database.

  • A custom subscription for the raised business event should be present on the target database.

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.