32 Integrating Oracle BAM with SOA Composite Applications

Oracle BAM provides an adapter available in the SOA Composite Editor in Oracle JDeveloper. This chapter provides information about using the Oracle BAM Adapter and Oracle BAM sensor actions to integrate SOA composite applications with Oracle BAM.

This chapter contains the following topics:

• Section 32.1, "Introduction to Integrating Oracle BAM with SOA Composite Applications"

• Section 32.2, "Configuring Oracle BAM Adapter"

• Section 32.3, "Creating a Design Time Connection to an Oracle BAM Server"

• Section 32.4, "Using Oracle BAM Adapter in an SOA Composite Application"

• Section 32.5, "Using Oracle BAM Adapter in a BPEL Process"

• Section 32.6, "Integrating BPEL Sensors with Oracle BAM"

32.1 Introduction to Integrating Oracle BAM with SOA Composite Applications

The Oracle BAM Adapter is a Java Connector Architecture (JCA)-compliant adapter which can be used from a Java EE client to send data and events to the Oracle BAM Server. The Oracle BAM Adapter supports the following operations on Oracle BAM data objects: inserts, updates, upserts, and deletes.

The Oracle BAM Adapter can perform these operations over Remote Method Invocation (RMI) calls (if they are deployed in the same farm), direct Java object invocations (if they are deployed in the same container), or over Simple Object Access Protocol (SOAP) (if there is a fire wall between them)

Oracle BAM Adapter is configured in Oracle WebLogic Server Administration Console to provide any of these connection pools. Oracle BAM Adapter provides three mechanisms by which you can send data to Oracle BAM Active Data Cache from an SOA composite application.

The Oracle BAM Adapter supports the active Oracle BAM Server migration automatically, and always communicates with the active server, without losing any messages.

Oracle BAM Adapter provides three mechanisms by which you can send data to an Oracle BAM Server in your SOA composite application:

• The Oracle BAM Adapter can be used as a reference binding component in an SOA composite application. For example, Oracle Mediator can send data to Oracle BAM using the Oracle BAM Adapter.

• The Oracle BAM Adapter can also be used as a partner link in a Business Process Execution Language (BPEL) process to send data to Oracle BAM as a step in the process.

• Oracle BAM sensor actions can be included within a BPEL process to publish event-based data to the Oracle BAM data objects.

32.2 Configuring Oracle BAM Adapter

The Oracle BAM Adapter Java Naming and Directory Interface (JNDI) connection pools must be configured when you use the adapter (also used with Oracle BAM sensor actions in BPEL) to connect with the Oracle BAM Server at runtime. For information about configuration see "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite.

Make note of the JDNI name that you configure in the Oracle BAM Adapter properties, so that you can use them in the Oracle BAM Adapter wizard and the Oracle BAM sensor action configuration in Oracle JDeveloper.

32.3 Creating a Design Time Connection to an Oracle BAM Server

You must create a connection to an Oracle BAM Server to browse the available data objects and construct transformations while you are designing your applications in Oracle JDeveloper.

Notes:

Do not create an Oracle BAM Server connection through the Resource Palette that is displayed when you select View > Resource Palette. The connection must be created in the application scope.

32.3.1 How to Create a Connection to an Oracle BAM Server

You create a connection to an Oracle BAM Server to browse data objects available on that server and to publish data to those data objects.

To create a connection to an Oracle BAM Server:

1. From the File main menu in Oracle JDeveloper, select New.

   The New Gallery dialog box opens.

2. From the General category, choose Connections.

3. From the Items list, select BAM Connection, and click OK.

   The BAM Connection wizard opens.

4. Ensure that Application Resources is selected.

5. Provide a name for the connection.

6. Click Next.

7. Enter the connection information about the Oracle BAM Server host described in Table 32-1.

   Table 32-1 Oracle BAM Server Connection Information

   Field	Description
   BAM Web Host	Enter the name of the host on which the Oracle BAM Report Server and web applications are installed. In most cases, the Oracle BAM web applications host and Oracle BAM Server host are the same.
   BAM Server Host	Enter the name of the host on which the Oracle BAM Server is installed.
   User Name	Enter the Oracle BAM Server user name.
   Password	Enter the password of the user name.
   HTTP Port	Enter the port number or accept the default value of 9001. This is the HTTP port for the Oracle BAM web applications host.
   JNDI Port	Enter the port number or accept the default value of 9001. The JNDI port is for the Oracle BAM report cache, which is part of the Oracle BAM Server.
   Use HTTPS	Select this checkbox to use secure HTTP (HTTPS) to connect to the Oracle BAM Server during design time. Otherwise, HTTP is used.

   
   

8. Click Next.

9. Test the connection by clicking Test Connection. If the connection was successful, the following message appears:

   Passed.
   

10. Click Finish.

32.4 Using Oracle BAM Adapter in an SOA Composite Application

The Oracle BAM Adapter is used as a reference that enables the SOA composite application to send data to an Oracle BAM Server external to the SOA composite application.

32.4.1 How to Use Oracle BAM Adapter in an SOA Composite Application

You can add Oracle BAM Adapter references that enable the SOA composite application to send data to Oracle BAM Servers external to the SOA composite application.

To add an Oracle BAM Adapter reference:

1. In the Component Palette, select SOA.

2. Drag the BAM Adapter to the right swim lane.

   This launches the Adapter Configuration wizard.

3. In the Service Name page, provide a Service Name and an optional Description.

4. In the Data Object Operation and Keys page,

   1. Select a Data Object using the BAM Data Object Chooser dialog box.

      When you click Browse the Data Object Chooser dialog box opens allowing you to browse the available Oracle BAM Server connections in the BAM Data Object Explorer tree. Select a data object and click OK.

   2. Choose an Operation from the list.

      Insert adds a row to the data object.

      Upsert inserts new data into an existing row in a data object if the row exists. If the row does not exist a new row is created. You must select a key from the Available column to upsert rows in a data object.

      Delete removes a row from the data object. You must select a key from the Available column to delete rows in a data object.

      Update inserts new data into an existing row in a data object. You must select a key from the Available column to update rows in a data object.

   3. Provide an appropriate display name in the Operation Name field for this operation in your SOA composite application.

   4. To select Enable Batching select the checkbox.

      The data cached in memory by the Oracle BAM Adapter of the Oracle BPEL Process Manager runtime is flushed (sent) to Oracle BAM Server periodically. The Oracle BAM component may decide to send data before a batch timeout if the cache has some data objects between automatically defined lower and upper limit values.

      Batching properties are configured in BAMCommonConfig.xml. See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for more information.

5. In the JNDI Name page, specify the JNDI Name for the Oracle BAM Server connection.

   The JNDI name is configured in the Oracle WebLogic Server Administration Console. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for more information.

6. Click Finish.

32.5 Using Oracle BAM Adapter in a BPEL Process

The Oracle BAM Adapter is used as a partner link in a BPEL process to send data to Oracle BAM as a step in the process.

See Section 5.3, "Introduction to Partner Links." for more information.

32.5.1 How to Use Oracle BAM Adapter in a BPEL Process

You can add the Oracle BAM Adapter to a BPEL process to send data to Oracle BAM as a step in the process. The Oracle BAM Adapter is used as a partner link and connected to an activity in the BPEL process.

To add an Oracle BAM partner link:

1. In the SOA Composite Editor in Oracle JDeveloper, double-click the BPEL process icon to open it in the BPEL Process Designer.

2. In the Component Palette, expand the BPEL Services panel.

3. Drag and drop the Oracle BAM Adapter into the Partner Links swim lane on the right side of the BPEL Process Designer.

4. In the Adapter Configuration wizard, enter a display name in the Service Name field and click Next.

   When the wizard completes, a Web Services Description Language (WSDL) file by this name appears in the Application Navigator for the BPEL process or Oracle Mediator message flow. This file includes the adapter configuration settings you specify with this wizard.

5. In the Data Object Operation and Keys page,

   1. Select a Data Object using the BAM Data Object Chooser dialog box.

      When you click Browse the Data Object Chooser dialog box opens allowing you to browse the available Oracle BAM Server connections in the BAM Data Object Explorer tree. Select a data object and click OK.

   2. Choose an Operation from the list.

      Insert adds a row to the data object.

      Upsert inserts new data into an existing row in a data object if the row exists. If the row does not exist a new row is created.

      Delete removes a row from the data object.

      Update inserts new data into an existing row in a data object.

   3. Provide an appropriate display name in the Operation Name field for this operation in your SOA composite application.

   4. To select Enable Batching select the checkbox.

      The data cached in memory by the Oracle BAM Adapter of the Oracle BPEL Process Manager runtime is flushed (sent) to Oracle BAM Server periodically. The Oracle BAM component may decide to send data before a batch timeout if the cache has some data objects between automatically defined lower and upper limit values.

      Batching properties are configured in BAMCommonConfig.xml. See Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for more information.

6. In the JNDI Name page, specify the JNDI Name for the Oracle BAM Server connection.

   The JNDI name is configured in the Oracle WebLogic Server Administration Console. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for more information.

7. Click Finish.

8. Create a new Process Variable in the BPEL process of type Message Type, and browse the Type Chooser dialog box to select the WDSL for the data object you want to write to on the Oracle BAM Server.

   For more information about using the Oracle BPEL Process Manager see Chapter 5, "Getting Started with Oracle BPEL Process Manager."

9. In the BPEL Process add an activity that you can use to map the source data to the new variable you created.

10. In the BPEL Process add an Invoke activity to send data to the Oracle BAM Adapter partner link you created. Add the variable you just created as the Input Variable.

11. Save all of the project files.

32.6 Integrating BPEL Sensors with Oracle BAM

You can create sensor actions in Oracle BPEL Process Manager to publish sensor data into existing data objects on an Oracle BAM Server. When you create the sensor action, you can select an Oracle BPEL Process Manager variable sensor or activity sensor to get the data from and the data object in Oracle BAM Server in which you want to publish the sensor data.

The Oracle BAM Adapter supports batching of operations, but behavior with batching is different from behavior without batching. As the Oracle BAM Adapter is applied to BPEL sensor actions, the Oracle BAM sensor action is not part of the BPEL transaction. When batching is enabled, BPEL does not wait for an Oracle BAM operation to complete. It is an asynchronous call.

When batching is disabled, BPEL waits for the Oracle BAM operation to complete before proceeding with the BPEL process, but it does not roll back or stop when there is an exception from Oracle BAM. The Oracle BAM sensor action logs messages to the same sensor action logger as BPEL. See "Configuring Oracle BAM Batching Properties" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for information about batching behavior.

These instructions assume you have installed and configured Oracle BAM.

Notes:

Connection factory configuration must be completed before using Oracle BAM sensor actions. Also, if the Oracle BAM Adapter is using credentials rather than a plain text user name and password, in order for the Oracle BAM Adapter (including Oracle BAM sensor actions used in BPEL) to connect to the Oracle BAM Server the credentials must also be established and mapped. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for more information.

32.6.1 How to Create a Sensor

Before you can create an Oracle BAM sensor action, you must first create a sensor in the BPEL process. You must create a sensor before creating a Oracle BAM sensor action.

• Variable sensor

  Restrictions: A Variable sensor's variable must be defined in a standalone XSD. This variable must not be defined inline in the WSDL file. If the variable has message parts, then there must be only one message part.

• An Activity sensor containing exactly one sensor variable

  Restrictions: Because you map the sensor data to a single Oracle BAM Server data object, the Activity sensor must contain only one variable. All of the Variable sensor restrictions also apply.

Note:

Any sensor that does not conform to these rules are be filtered from the Oracle BAM sensor action configuration dialog box. Also, if a sensor is created conforming to the restrictions, but the variable is deleted (rendering the sensor invalid), it does not appear in Oracle BAM sensor action configuration dialog box.

For more information about creating sensors, see Section 17.2, "Configuring Sensors and Sensor Actions in Oracle JDeveloper."

32.6.2 How to Create an Oracle BAM Sensor Action

When you create the Oracle BAM sensor action, you select the BPEL variable sensor or activity sensor from which to get data, and you select the data object in Oracle BAM Server to which you want to publish the sensor data.

To create an Oracle BAM sensor action:

1. Go to your BPEL process in Oracle JDeveloper.

2. In the Structure window, right-click Sensor Actions.

   If the Structure window is not open, select View > Structure Window to open it.

3. Select Create > BAM Sensor Action.

   The Create Sensor Action dialog box appears.

   Figure 32-1 Oracle BAM Sensor Action Creation Dialog Box

   
   Description of "Figure 32-1 Oracle BAM Sensor Action Creation Dialog Box"
   
   

4. Enter the details described in Table 32-2:

   Table 32-2 Create Sensor Action Dialog Box Fields and Values

   Field	Description
   Action Name	Enter a unique and recognizable name for the sensor action.
   Sensor	Select a BPEL sensor to monitor. This is the sensor that you created in Section 32.6.1, "How to Create a Sensor" for mapping sensor data to a data object in Oracle BAM Server.
   Data Object	Click the Browse icon to open the BAM Data Object Chooser dialog box to select the data object in Oracle BAM Server in which you want to publish the sensor data. If you have not created a connection to Oracle BAM Server to select data objects, click the icon in the upper right corner of the BAM Data Object Chooser dialog box.
   Operation	Select to Delete, Update, Insert, or Upsert a row in the Oracle BAM Server database. Upsert first attempts to update a row if it exists. If the row does not exit, it is inserted.
   Available Keys/Selected Keys	If you selected the Delete, Update, or Upsert operation, you must also select a column name in the Oracle BAM Server database to use as a key to determine the row with which this sensor object corresponds. A key can be a single column or a composite key consisting of multiple columns. Select a key and click the > button. To select all, click the >> button.
   Map File	Provide a file name to create a mapping between the sensor data (selected in the Sensor list) and the Oracle BAM Server data object (selected in the Data Object list). You can also invoke a mapper dialog box by clicking the Create Mapping icon (second icon) or Edit Mapping icon (third icon).
   BAM Connection Factory JNDI	Specify the JNDI name for the Oracle BAM Server connection factory. The JNDI name is configured in the Oracle WebLogic Server Administration Console. See "Configuring the Oracle BAM Adapter" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for more information.
   Enable Batching	The data accumulated by the Oracle BAM component of the Oracle BPEL Process Manager runtime is flushed (sent) to Oracle BAM Server periodically. The Oracle BAM component may decide to send data before a batch timeout if the queue has some data objects between automatically defined lower and upper limit values. If batching is enabled, performance is dramatically improved, but there is no transaction guarantee. The BPEL process continues to run without waiting for the data to get to the Oracle BAM Server. If batching is not enabled, the BPEL process waits until the Oracle BAM Server confirms that the record operation was completed; however, if there is a failure, the exception from Oracle BAM Server is logged and the BPEL process continues. BPEL does not roll back the operation or stop when there is an exception from Oracle BAM. See "Configuring Oracle BAM Batching Properties" in Oracle Fusion Middleware Administrator's Guide for Oracle SOA Suite for information about batching behavior.

   
   

   Figure 32-1 shows the Create Sensor Action dialog box with a selected data object.

   WARNING:

   If you restart Oracle BPEL Server, any messages currently being batched are lost. Ensure that all messages have completed batching before restarting Oracle BPEL Server.

   Notes:

   After you click the Create Mapping or Edit Mapping, or the OK button on the Create Sensor Action dialog box, you must explicitly save the BPEL file.

5. Click OK to close the Create Sensor Action dialog box.

32.6.3 How to Disable an Oracle BAM Sensor Action

BPEL sensor actions are typically disabled using the Oracle Enterprise Manager Fusion Middleware Control Console; however, Oracle BAM sensor actions are not manageable from the Fusion Middleware Control Console.

To disable an Oracle BAM sensor action:

1. Open the project containing the Oracle BAM sensor action in Oracle JDeveloper.

2. Open the BPEL_PROCESS_NAME_sensorAction.xml file in the editor (refresh the project tree if you cannot see the file).

   
   Description of the illustration bam_sensor_disable.gif
   
   

3. Locate the sensor action you want to disable. You can search on the publishType="BAM" attribute to find only the Oracle BAM sensor actions.

4. In the <action> element for the sensor action you want to disable, set the enabled attribute to false.

   
   Description of the illustration bam_sensor_disable_xml.gif
   
   

5. After the file is updated and saved, you must redeploy the application.