BPM Intoduction

1. Samples are provided as-is with no warranty Page 1 of 10
BPM 11g Samples
bpm-int-101-JMS-integration
Copyright  2011 Oracle Corporation
All Rights Reserved

2. Samples are provided as-is with no warranty Page 2 of 10
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

3. Samples are provided as-is with no warranty Page 3 of 10
History
Date Version Change Reference
Nov-06-2011 1.0 First release of sample

4. Samples are provided as-is with no warranty Page 4 of 10
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.

5. Samples are provided as-is with no warranty Page 5 of 10
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.

6. Samples are provided as-is with no warranty Page 6 of 10
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.

7. Samples are provided as-is with no warranty Page 7 of 10
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.

8. Samples are provided as-is with no warranty Page 8 of 10
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.

9. Samples are provided as-is with no warranty Page 9 of 10
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.

10. Samples are provided as-is with no warranty Page 10 of 10
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.