Integrating IBM Business Process Manager Standard with synchronous and asynchronous applications using IBM Integration Bus V9

Introduction

IBM IB provides new integration with IBM BPM that makes it easier for BPM users to access synchronous services. IBM IB lets IBM BPM developers focus on the human-related tasks, and delegate the connectivity issues to IBM IB developers. The Synchronous integration section below describes this process.

Many companies also have asynchronous applications that they would like to access from IBM BPM business process flows. IBM IB can help bridge the gap between IBM BPM and asynchronous applications by providing asynchronous access to the back-end service, and then constructing the appropriate event message to instruct IBM BPM to collect the response. The Asynchronous integration section below deals with this aspect of connectivity.

Synchronous integration

Integration process

The integration process for synchronous interaction between IBM BPM and IBM IB follows a top-down flow from the perspective of the IBM BPM user:

1. The IBM BPM developer defines an integration service and its inputs and outputs in a toolkit.
2. The IBM BPM developer creates and exports a snapshot of the toolkit as a .TWX and gives it to the IBM IB developer.
3. The IBM IB developer creates, tests and deploys an IBM IB integration service based on the inputs and outputs of the IBM BPM integration service.
4. The IBM IB developer exports the IBM IB integration service as a .TWX. A new snapshot of the original toolkit is created. The IBM BPM integration service in the original .TWX is updated with a web service integration step.
5. The IBM BPM developer imports the .TWX, updates the process app that references the toolkit, and tests the process app on the playback server.

IBM BPM BPD

In this example, IBM BPM users require credit check information about customers. So they create a toolkit and define the business objects that will be needed to transport and hold that information:

Business objects

They then create an integration service with the relevant input and output business objects defined. However, the IBM BPM user does not attempt to implement the service:

Integration service definition

A snapshot is created of this toolkit and the snapshot is exported as a TWX file.

Export TWX from IBM BPM

The TWX file is then passed to an IBM IB developer, who implements the integration service. The IBM BPM user then creates a BPD within a process application and designs a simple flow where:

1. The GetCustomerDetails human task uses a coach to obtain input from a user.
2. The RequestCreditCheck system task invokes an integration service to send the customer data as a web service request and receive the response.
3. The DisplayResponse human task shows the credit status.

Synchronous IBM BPM BPD

To provide the integration service and business objects, the relevant toolkit is added to the process application. The business objects are assigned to variables at the BPD level and are used in the human tasks GetCustomerDetails and DisplayResponse to set the request values and display the response values. The implementation of the system task RequestCreditCheck is assigned to be the integration service from the toolkit:

Select the integration service from the toolkit

For each of the activities the BPD level variables should be mapped to the task level variables.

Map business objects

Generating a service from the TWX file

When an IBM BPM user provides the TWX file containing an unimplemented IBM BPM integration service, the IBM IB developer uses the following steps to generate an IBM IB integration service:

1. Start the IBM IB Toolkit.
2. From the Quick Starts page, select Start by creating an integration service.
3. Enter a name for the integration service.
4. Select Create a new service interface from an IBM BPM integration service and then click Next.
5. Browse to the TWX file that was saved from IBM BPM and click Open.
6. In the Select the Integration Service area, click on the integration service and then click Finish:

   Select the integration service

   
7. A service is generated with an interface to match the BOs from IBM BPM:

   Generated interface

   

Implementing the service

Next you need to implement and deploy the integration service so that it can be made available to the IBM BPM process. Normally the implementation involves invoking an external service and manipulating the return data into a form appropriate for the interface response type. For brevity this example will simply use a Mapping node:

1. Click on the Service tab at the bottom of the Service Editor.
2. Click on the operation name (grey link in the interface box):

   Service Editor

   
3. In the Flow Editor, implement the flow by putting a Mapping node between the input and output and mapping between the request and response BOs.
4. The implemented service should now be deployed to an integration service:

   Service implementation

   

Exporting the service definition

The required information about the implemented IBM IB integration service should now be exported as a new snapshot of the original TWX file:

1. Right-click the integration service description in the service project and select Export.
2. From the Export dialog, expand Integration Bus -- IBM Business Process Manager Integration, select Business Process Manager Export (.TWX), and then click Next.
3. Review the host name and port for the Integration node and then click Next,
4. Review the Snapshot name and Export Location path and then click Finish.

The TWX file containing the new snapshot can now be passed back to the IBM BPM user so a that the IBM IB integration service can be used by the IBM BPM BPD.

Importing the TWX

The IBM BPM user must import the new snapshot and update its reference to it:

1. Start IBM BPM Process Designer and log in with the administrator user name and password.
2. Go to the Process Center and click the Toolkits tab.
3. Select Import Toolkit at top right.
4. Browse to the location of the updated TWX file from IBM IB and click Open.
5. Click OK.
6. Review the Toolkit name and click Import.
7. Select the Process Apps tab and click Open in Designer next to your Process App.
8. Under Toolkits on the left, the Toolkit that has been updated will have a yellow triangle next to it. Right-click the Toolkit and select Upgrade dependency to ....
9. Open the Process Definition via the Processes menu.
10. Double-click the RequestCreditCheck activity. You should see that the Integration Service is now implemented with a Web Service Integration.
11. Return to the Process Definition via the Processes menu.

The IBM BPM integration service implementation consists of a web service Integration configured with the WSDL URI of the IBM IB integration service and its endpoint address, which uses variables for the host and port so that a BPC administrator can change them.

Exercising the BPD

The IBM BPM process definition is now ready to run. It can be tested using the Process Inspector (test environment). Ensure that the top level BPD is visible in designer, then:

1. Click the Run Process icon (Orange/white forward arrow at top right).
2. The Instance is started with the getCustomerDetails activity highlighted. Select getCustomerDetails at top right then click the Runs the selected task icon (Orange/white forward arrow at top right).
3. Choose a user to run as and click OK.
4. A browser will pop up containing the coach with input fields for the input BO. Fill in all of the fields and click OK.
5. Return to the IBM BPM Inspector and click the Refresh icon (Yellow circular arrows at top right).
6. The flow will move through RequestCreditCheck, and the DisplayResponse activity will be highlighted. Select DisplayResponse at top right, and then click the Runs the selected task icon (Orange/white forward arrow at top right).
7. Choose a user to run as and click OK.
8. A browser will open containing the output coach with the returned data displayed.
9. Click OK to complete the flow.

Asynchronous integration

Message flow

Integrating with asynchronous services from IBM BPM Standard is not straightforward because the callback mechanism that allows IBM BPM to respond to an event is very rigid. Using IBM IB can help with this by providing the asynchronous access to the back end service and then constructing the appropriate event message required by IBM BPM to instruct it to collect the response from the back end once it has arrived. The high level flow in this example is:

Example asynchronous message flow

1. The IBM BPM Process Application puts a request message to an MQ queue.
2. The IBM IB Application takes the request message from the MQ queue.
3. The IBM IB Application invokes the asynchronous service.
4. When the asynchronous service returns, the IBM IB Application puts the response message to an MQ queue.
5. The IBM IB Application puts an event message on the IBM BPM event queue.
6. The IBM BPM Process Application responds to the event and takes the response message from the MQ queue.

IBM BPM BPD

IBM BPM BPDs are characterised by human tasks interspersed with system tasks. The IBM BPM BPD in this example has two distinct parts:

1. Input customer information and send that to the service.
2. On receiving an appropriate event message obtain the service response and display the result

   IBM BPM BPD

   
   Here is the flow shown above:
   1. The GetCustomerDetails human task uses a coach to obtain input from a user.
   2. The RequestCreditCheck system task sends the customer data as an MQ message.
   3. The flow stops and waits for a response.
   4. The undercover agent attached to the StartMQGet start event responds to an event message.
   5. The CreditInfo system task gets the response message from an MQ queue.
   6. The CreditGood gateway checks a data value and branches to either the DisplayAcceptance human task, or to the DisplayRejection human task.

Putting to MQ

The RequestCreditCheck system task is implemented by an Integration Service which contains a server script, which serialises the Customer Business Object (BO) to an XML string, and a Java Integration which puts the string to an MQ queue.

IBM BPM put to MQ task

The script in the serialise node requires a private string variable (tomqMessage) to be defined and the Customer BO passed in from the main BPD is serialised to it using:

tw.local.tomqMessage=tw.system.serializer.toXml(tw.local.Customer).toString(true);

The XML resulting from tw.system.serializer.toXml(tw.local.Customer) is not one that conforms to the Customer schema. Rather, it's a generic XML that looks like this:

BPM serialized XML

<variable type="Customer">
  <FName type="String"><![CDATA[John]]></FName>
  <LName type="String"><![CDATA[Doe]]></LName>
  <Address type="Address">
    <HouseStreet type="String"><![CDATA[123 Some Street]]></HouseStreet>
    <City type="String"><![CDATA[A City]]></City>
    <PostCode type="String"><![CDATA[99999]]></PostCode>
  </Address>
</variable>

You have a choice to either put the data in "proper" XML format on the wire so that the MQInput node on IBM IB can use the XMLNSC message parser to parse it, or you can send the message as-is and transform it to the "proper" XML in IBM IB. In this example, we'll use the later approach.

In the putToMQ Java Integration Definition the putMessage method is selected from the MQMessages class in the provided integration.jar. It's Data Mapping is used to define the parameters to the putMessage method which include the string to send as a message and the MQ connectivity details.

IBM BPM Put to MQ parameters

For this example. the MQ queue manager to use is the one used by the IBM IB Integration node with a queue called APPINPUT. Ensure that the host and port values match those of your queue manager.

Setting up event handling

There are three main aspects to setting up event handling in IBM BPM:

1. Create a General System Service to be invoked when an event occurs.
2. Create an Undercover Agent to monitor the event queue for an appropriate message and invoke the General System Service when a message is found.
3. Create a Start Event to associate the Undercover Agent with.

The General System Service can be used to manipulate the actual data passed in the event message. In this example, the event message does not contain actual business data and is just being used as an invocation tool, so the General System Service just does a simple map of input data to output data. What is important, however, is the name of the input data, which is defined as an Input Variable of the General System Service and is used as an element value key in the event message responseFromMqIn.

IBM BPM General System Service

The Undercover Agent (UCA) should be created with an On Event Schedule Type. IBM BPM has a single asynchronous queue defined as a System Integration Bus (SIB) JMS queue with a JNDI name of jms/eventqueue. For the UCA to monitor this queue, set its Queue Name parameter to Async Queue. Its Implementation should be of type Service and the Attached Service should be selected as the previously created General System Service -- ResponseFromMq.

The final important parameter is the Event Message, which is a unique identifier that is the value of the event element in the event message. By default, IBM BPM creates a unique ID when the UCA is created, but in this example it is set to gotFromMQ.

IBM BPM Undercover Agent

Set the implementation of the Start Event in the main BPD to type Message, and select the Attached Message UCA as the newly created UCA,respondToMQ in this example. Also check Consume Message:

IBM BPM Start event

Getting from MQ

The CreditInfo system task is implemented by an Integration Service that contains a Java integration, which gets the response message as a string from an MQ queue, and a server script, which extracts the required information from the response message:

IBM BPM Get From MQ

In the GetFromMQ Java integration, the getMessage method is selected from the MQMessages class in the provided integration.jar file. Its data mapping is used to define the parameters to the getMessage method, which include the string variable to which to assign the returned message, and the MQ connectivity details. For this example, use the MQ queue manager used by the IBM Integration Bus Integration Node with a queue called APPOUTPUT. Ensure that the host and port values match those of your queue manager.

In the getStatus server script, the returned message is searched for the value of the Status element, and that value is assigned to an output variable to be passed back to the main BPD:

var posst = tw.local.getFromMq.indexOf("Status>");
var tstr = tw.local.getFromMq.substring(posst+7);
var posen = tstr.indexOf("</");
tw.local.Status = tstr.substring(0, posen);

IBM BPM values required for the event message

The UCA monitoring the Async Queue looks for certain values in the event message. They are:

• The short name (acronym) of the process application to which the event should be directed (the value of the processApp attribute)
• The name of the snapshot of that process application (the value of the snapshot attribute)
• The name of the Undercover Agent that the event message is to be processed by (the value of the ucaname attribute)
• The correlation value (Event Message) that the UCA uses to select the message from the event queue (the value of the event element)
• The name of the variable that the message payload is to be placed in (the value of the key element)

In this example those values are:

• Process application acronym = DWASYNC
• Snapshot name = DWSS
• UCA name = respondToMQ
• Event Message = gotFromMQ
• Return variable name = responseFromMqIn

This means that the IBM IB flow needs to create an event message with this structure to put on the IBM BPM Async Queue:

<eventmsg>
<event processApp="DWASYNC" 
       snapshot="DWSS"
       ucaname="respondToMQ">gotFromMQ</event>
  <parameters>
    <parameter>
      <key>responseFromMqIn</key>
      <value>...</value>
    </parameter>
  </parameters>
</eventmsg>

IBM IB Flow

In IBM IB, the example application (which you can download at the bottom of the article):

1. Gets the MQ message put by the IBM BPM application
2. Parses the IBM BPM XML into standard XML
3. Constructs a response message, this is in lieu of calling out to a back end service
4. Puts the response message to the MQ queue that IBM BPM can get from
5. Constructs the IBM BPM event message
6. Puts the event message to the IBM BPM Async Queue

   IBM IB Flow

   

Schemas

To facilitate the parsing of the input message, construction of the output message and construction of the event message the example contains schemas, in a library, for the IBM BPM BOs and the IBM BPM event message. The IBM BPM BO schemas were generated by creating a new Message Model of type Other XML based on schema files imported from IBM BPM. In IBM BPM, for any BO, there is an advanced property button called View XML Schema and the resulting schema can be saved to file to import into IBM IB. The event message schema can be generated by creating a new Message Model of type Other XML by using an XML document as an example and using something like the example in IBM BPM values required for the event message above.

MQ configuration

For this example, the queues accessed by the flow are assumed to be defined on the MQ queue manager used by the IBM IB Integration node:

1. Start WebSphere MQ Explorer.
2. Expand the queue manager used by the IBM IB Integration node.
3. Right-click Queues.
4. Select New => Local Queue.
5. Set the name as APPINPUT and click Finish and then OK.
6. Right-click Queues once more.
7. Select New => Local Queue.
8. Set the name as APPOUTPUT and click Finish and then OK.

To enable the IBM BPM process application to communicate with MQ, create and start a listener on the Integration Node queue manager:

1. Start WebSphere MQ Explorer.
2. Expand the queue manager used by the IBM Integration Bus Integration node.
3. Right-click Listeners.
4. Select New => TCP Listener.
5. Set the Name to BPMLSNR and click Next.
6. Set Control to Queue Manager Start.
7. Set the Port to a unique number, such as 1444.
8. Click Finish and then OK.
9. Select the new listener, right-click, and select Start and then OK,

To make it easier for IBM BPM to access the queue manager, enter the following commands from a console or terminal to turn off channel authorisation. On the first line, for IIBQM, substitute the actual name of the IBM Integration Bus Integration node queue manager:

runmqsc IIBQM   
alter qmgr chlauth(disabled)
end

Configuring the JMS output

The JMS Output node has its Destination queue set to jms/eventqueue, which is the JNDI name of the SIB JMS queue that the IBM BPM server uses as its Async Queue. Since the IBM BPM server is running on WebSphere Application Server, the JMS Connection parameters should use an appropriate Client for WebSphere Application Server values. For example:

JMS Output properties

On the Advanced tab, set the type of the JMS Message as TextMessage. Ensure that the host and port specified in the Location JNDI bindings field match those of your IBM BPM server.

IBM IB configurable properties

In addition to the properties set on the input node, a configurable service setting is required to point to the WebSphere Application Server client jar files. For example:

mqsichangeproperties IIB9NODE -c JMSProviders -o WebSphere_WAS_Client
    -n jarsURL -v C:\MQSI9000\wsrrclient\jms
    mqsireportproperties IIB9NODE -c JMSProviders -o WebSphere_WAS_Client -r

Configuring the IBM BPM profile

The connection factory name in the example (QCF) is not a default artifact in a IBM BPM server, so you must create it manually:

1. Start the Administrative console for the IBM BPM server and log in.
2. Select Resources => JMS => Queue Connection Factories.
3. Set the scope to Node=xx, server=yy.
4. Click New.
5. Select Default messaging provider and click OK.
6. Set a Name (QCF), JNDI name (QCF), and then select Bus (PROCSRV...).
7. Set the Provider endpoints to the appropriate host and port for your system. For example:

   bpmsrv:7276:BootstrapBasicMessaging,bpmsrv:7286:BootstrapSecureMessaging

8. Click OK.

For this example, remove the need to use SSL for the SIBus JMS connection. Still in the Administrative Console:

1. Select Security => Global security.
2. Expand RMI/IIOP security.
3. Select CSIv2 inbound communications.
4. Under CSIv2 Transport Layer, set Transport from the drop down to be SSL-supported.
5. Click OK and Save.
6. Expand RMI/IIOP security.
7. Select CSIv2 outbound communications.
8. Under CSIv2 Transport Layer, set Transport from the drop down to be SSL-supported.
9. Click OK and Save.
10. Stop and restart the IBM BPM server.

Testing the BPD

Ensure that the IBM Integration Bus application (dwasyncApp) is deployed to an Integration Server. You can now use the IBM BPM Inspector to test the process application:

1. In Process Designer, select the BPD.
2. Click the Run Process icon at top right (orange forward arrow).
3. The Inspector screen opens. In the main diagram, the GetCustomerDetails task is highlighted. At top right, select GetCustomerDetails and click the Run the selected task icon at top right (orange forward arrow).
4. Select a user to run the task and click OK.
5. A browser starts with the coach for supplying customer information. Enter the data and click OK.
6. Go back to Process Designer, and in the Inspector view, click Recycle at top right (circular yellow arrows).
7. A new instance of CreditRequest should be created at top left in Active state. Select this instance.
8. The DisplayAcceptance task will be highlighted in the diagram. At top right, select the DisplayAcceptance step and click the Run the selected task icon at top right (orange forward arrow).
9. Select a user to run the task and click OK.
10. A browser will start displaying the received status.

Conclusion

This article showed examples of configuring IBM BPM and IBM IB to work together to allow access from BPM process applications to both synchronous and asynchronous applications.