bpminto

Samples are provided as-is with no warranty of 10

BPM 11g Samples

bpm-int-101-JMS-integration

Copyright 2011 Oracle Corporation

All Rights Reserved


Contents

1. Introduction ............................................................................................................4

2. Environment Requirements ..................................................................................5

3. Installation and Configuration .............................................................................6

3.1 JMS Queue on the SOA/BPM Server .................................................................................... 6

3.2 Update the UIConnectionName in the Adapter JCA Configuration File (Optional) ............. 6

3.3 Deploy the Two Composite Projects ...................................................................................... 7

4. Sample Overview ...................................................................................................8

5. Sample Scenarios ...................................................................................................9

5.1 Start Process Using Process “Start” Message ........................................................................ 9

5.2 Start Process Using an “Event” Message ............................................................................... 9

6. Running the Samples ...........................................................................................10


History

Date Version Change Reference

Nov-06-2011 1.0 First release of sample


1. Introduction

A frequently asked question is whether BPM processes can be started by the arrival of a JMS

message on a Topic or Queue. The short answer is yes, and this sample provides an example of a

BPM process that is started via a JMS message in two common scenarios:

1. The arrival of a message that matches the WSDL of the Service endpoint for the BPM

process. In this case the XML message is exactly the same as would be delivered in the Body

of a SOAP/HTTP message. The root element is typically in the target namespace of the

process, and named after the name of the operation that starts the process. This scenario is

essentially a Web Service call using JMS as the transport.

2. The arrival of a message that is just the payload portion of the message that would be used in

the first scenario, typically a message that describes a business event. This scenario is more

like publishing events over JMS, rather than invoking a Web Service operation over JMS.

In both cases the BPM process is insulated from the type of transport used to deliver messages that

start instances of the process. The process design only specifies the “shape” of the message. The

composite is configured with adapters that are the sources of those messages. In cases where the

“shape” of the adapter message does not match that of the process, a Mediator can be used to

transform the message into the correct “shape”

While the primary objective of this sample is to show how to start processes from JMS messages,

the sample also illustrates:

Use of configuration plans to override Destination JNDI names.

Use of Service Properties to set and get JMS Messages Properties.

Use of JMS Message Selectors to use a shared Destination for multiple message types.


2. Environment Requirements

This sample requires JDeveloper version 11.1.1.5 (or higher) with the SOA Composite Editor and

BPM Studio extensions installed. A standalone server with BPM Suite 11.1.1.5 (or higher) and a

domain configured with BPM Suite is required for deploying and running the sample.

Note: This sample will run on 11.1.1.5 or 11.1.1.5 Feature Pack (11.1.1.5-FP). Some of the screen

shots in this document were created using 11.1.1.5-FP, however there are no 11.1.1.5-FP specific

features used in the sample. If you’re using 11.1.1.5-FP, you will be prompted to upgrade the

project when opening it. You will not need to make any other changes to run the sample.

The sample requires a single JMS Queue deployed to the SOA/BPM server to illustrate how BPM

Process can be started via JMS Messages. The JNDI destination name used by the JMS adapters

is jms/sampleQueue. However that value can be overridden by updating the configuration plan

provided in both the sending (BPMJmsSend) and receiving (BPMJmsReceive) projects.


3. Installation and Configuration

The sample is provided as a zipped JDeveloper application. The application can be unzipped into

any location where the path name does not include spaces. To open the application, use the

“Application Open” menu and locate the file: bpm-int-101-JMS-integration.jws.

The application contains 3 projects:

BpmJmsSend – BPM project that generates the JMS messages that start instances of a

process defined in the BpmJmsReceive project.

BpmJmsReceive – Contains the BPM process that is started by the arrival of messages on

a JMS Queue.

Resources – A generic project that contains documentation and ANT build targets to

package this sample.

3.1 JMS Queue on the SOA/BPM Server

Then sending and receiving BPM processes use the same JMS Queue. The Destination JNDI

name is defined in the composite.xml file to make it possible to override the JNDI name using a

configuration plan. A sample configuration plan is provided in each project as a sample of how to

override the name at deployment time. The options for configuring JMS are:

Create a Queue with the Destination JNDI name jms/sampleQueue in your SOA/BPM

domain

or …

Update the configuration plan in each project (BpmJmsSend_cfgplan.xml,

BpmJmsReceive_cfgplan.xml) to specify the JNDI name of a Queue that already exists in

your SOA/BPM domain. The example configuration plans are configured to override the

default JNDI name with the value jms/q1.

Note: The connection factory name configured in the adapter configuration is eis/wls/Queue,

which is one of the default factories pre-configured during creation of a SOA/BPM domain. So

the connection factory name does not need to be changed.

3.2 Update the UIConnectionName in the Adapter JCA Configuration File (Optional)

The UIConnectionName is used whenever the JMS Adapter wizard is run. It specifies the name of

the application server where the JMS Destinations can be browsed. If you intend to make changes

to the JMS adapter by running the wizard, you will have to update this value to match the name of

an application server connection in your environment. However you do not need to change this

value to run the sample, or to update the Destination via configuration plan.


3.3 Deploy the Two Composite Projects

Use JDeveloper to deploy both composites:

BpmJmsReceive

BpmJmsSend

If you have updated the configuration plans to reference a Queue that already exists on you

BPM/SOA server, then be sure to select the configuration plan when deploying the projects. If

you created a Queue with the JNDI name jms/sampleQueue, then do not specify a configuration

plan.


4. Sample Overview

As noted in the introduction, a key goal of the sample is to show how processes can be started via

the receipt of JMS messages. The sample is designed to have one BPM process produce (send)

the JMS messages that then create instances of another BPM process in a separate project

(composite).

The “sending” composite. This composite contains a single BPM process that sends JMS

messages to the receiving composite via JMS adapters.

The “receiving” composite. This composite contains the BPM process where instances are

created on receipt of JMS messages. Note that a Mediator is used to transform JMS messages to

match the shape of the Message Start Event in the BPM process.

A single JMS Destination is used for communication between the processes. A message selector

is used in the receiving JMS adapter to distinguish between the two message types (i.e.

startProcess messages and NewOrderEvent message). In the sending process Service Properties

are used to set the “msgType” JMS Message property used in the message selector.


5. Sample Scenarios

The sending process (BpmJmsSend) produces two JMS messages via Service Activities that are

bound to outbound JMS adapters. Each message “send” represents one of the two scenarios

described in the introduction.

5.1 Start Process Using Process “Start” Message

In this scenario the sending process send a JMS message that has the same XML schema type as

the operation defined in the target process Message Start Event (i.e. the operation defined in the

process WSDL). Since the sender must have the remote service’s WSDL, this is a scenario that’s

often referred to as Web Service invocation over JMS.

5.2 Start Process Using an “Event” Message

In this scenario the sending process does not have the WSDL of the target service. It just has an

XML schema that represents a Business Event (e.g. NewOrderEvent). The receiving composite

includes a Mediator that will create the target process start message via transformation of the

incoming JMS message.

Note that this is similar to the use of EDN within SOA. However in this case the processes are

directly using JMS to send and receive messages.


6. Running the Samples

The sending composite (BpmJmsSend) includes a BPM process that exposes a web service

endpoint. That endpoint defines two parameters that are then used to create the outbound JMS

messages for both scenarios:

String – orderId

Integer – orderAmount

To run the sample, log into Enterprise Manager (EM) and navigate to the Test Page for the

BpmJmsSend project. Enter an orderId and orderAmount, then select “Test Web Service”.

If you select the Flow Trace you’ll see the following, which shows the two outbound JMS

messages that result in two instances of the BpmJmsReceive Process being created; one for each

of the scenarios:

If you select the BPMN components you’ll see (via the Log Handler output) the values from the

inbound JMS message, along with the message type that was set as a JMS Message Property by

the sender, and used in the JMS Message Selector to determine which adapter handles the

incoming message.

bpminto

Software