Contents


Integrate IBM MQ with your IBM Business Process Manager processes

Comments

IBM BPM V8.5 is a comprehensive business process management platform, providing full visibility and insight to managing business processes. IBM MQ is robust messaging middleware that simplifies and accelerates the integration of diverse applications and business data across multiple platforms. IBM MQ facilitates the assured, secure, and reliable exchange of information between applications and systems. If you need to send and receive data to other systems from within business processes, IBM MQ is usually the natural choice because of its track record of rapid and seamless connectivity.

This tutorial describes approaches to send data from a business process to IBM MQ and approaches to receive data from IBM MQ to drive the business process to move forward. The examples step through a simple use case to describe different scenarios. This tutorial assumes that you have a basic knowledge of IBM BPM and IBM MQ. To follow and run the code sample that is provided in the tutorial, you need the following software:

  • IBM Business Process Manager Standard or Advanced V8.5.x (This tutorial uses IBM BPM V8.5.6, available at the time of publishing.)
  • IBM MQ V8.x
  • An eclipse-based J2EE development environment

Business process use case overview

This tutorial uses a simple credit card application example business process to demonstrate various ways of integrating IBM BPM with IBM MQ. The first step in the process is to gather a customer's information, such as social security number (SSN) and customer name. Then, the customer SSN is sent through IBM MQ to a credit score service provider, and the provider sends back the credit score to the business process through IBM MQ. If the credit score is below 650, a manager approval is required. Figure 1 shows the example business process definition (BPD) in Process Designer.

Figure 1. Credit Card Application Process, an example process in IBM BPM
Screen                     capture of the Credit Card Application Process, an example process in IBM                     BPM
Screen capture of the Credit Card Application Process, an example process in IBM BPM

To simplify the process, a script activity is used to initialize the customer information. The Credit Check system service sends a message to IBM MQ with the customer information. Then, a message event is placed in the process to wait for the credit check result that is sent back through IBM MQ. The message event is attached to an undercover agent to wait for a message.

Sending messages to IBM MQ in IBM BPM processes

In a business process, you can send a message to IBM MQ in the following three ways:

  1. Use the teamworks.MQMessages Java™ service putMessage method that is available for immediate use in the integration.jar file. This option is the simplest approach, but it provides very limited customization. To allow access, you must add both the user ID that the IBM BPM Java process runs under and the IBM BPM host to the server-connection channel authorization in IBM MQ.
  2. If you are using IBM BPM Advanced, the Advanced Integration service (AIS) with the IBM MQ binding is a better option. The IBM MQ Binding offers a higher degree of customization of IBM MQ connectivity. To create an AIS service with the IBM MQ binding, see the WebSphere MQ binding topic in the IBM BPM documentation on IBM Knowledge Center.
  3. If you are using IBM BPM Standard, if the MQMessages class that is available for immediate use cannot meet your needs, consider a Java service that uses a custom Java Message Service (JMS) client to send messages to IBM MQ. Treat the custom JMS client like any JMS client. The JMS client class needs to be packaged in a .jar file and included in the business process application. IBM MQ resources must be defined in the IBM BPM service that is used by the JMS client.

The sample code that is provided with this tutorial illustrates how to use option 1, using the MQMessages class. See Figure 2.

Figure 2. MQMessages class example in the Credit Check Service diagram
Screen                     capture of MQMessages class example in the Credit Check Service                     diagram
Screen capture of MQMessages class example in the Credit Check Service diagram

The MQMessages class is packaged in the integration.jar file that is available for immediate use in the System Data toolkit. The putMessagemethod is used to PUT a message to IBM MQ. On the Properties tab, click Data Mapping to configure the customization that you need to connect to IBM MQ, as shown in Figure 3.

Figure 3. Example of putMessage data mapping
Screen                     capture of putMessage data mapping example
Screen capture of putMessage data mapping example

Receiving messages from IBM MQ in IBM BPM processes

When a business process needs to wait for an IBM MQ message to continue to the next step in the process flow, usually it is implemented with a message event in the BPD that is designed to wait for a message to arrive. The message event is attached to an undercover agent that needs to be triggered when the message is placed in the IBM MQ queue. The IBM BPM runtime environment uses an internal Event Manager JMS queue to receive the message event.

In a business process, you can receive messages from IBM MQ and trigger the undercover agent in the following three ways:

  1. You can use an integration service that uses the getMessage method that is available for immediate use in the MQMessages class. This method has the same limitation as the putMessage method that is available with limited customization. After the message is retrieved from IBM MQ, you can use an Invoke UCA activity to trigger the undercover agent that is attached to the waiting message event.
  2. Similarly, if you have IBM BPM Advanced, you can use an AIS that uses the IBM MQ binding with to receive IBM MQ messages. After the message is retrieved from IBM MQ, you can use an Invoke UCA activity to trigger the undercover agent that is attached to the waiting message event.
  3. You can use a message-driven bean (MDB) that listens to the IBM MQ queue and retrieves the IBM MQ message. Then, use the JMS application programming interface (API) to directly send messages to the internal JMS event manager queue to trigger the undercover agent.

The following examples in this tutorial illustrate options 1 and 3. Option 2 requires IBM BPM Advanced, which is not shown in the examples with this tutorial.

The benefit of option 1 is that you don't need to understand the internal Event Manager JMS queue details and message-format details. Disadvantages are you have limited customization options, and you must manually start or schedule the service (the IBM MQ Get Service show in the examples).

The benefit of using option 3 is the MDB can constantly monitor the IBM MQ queue. The MDB is run whenever the message arrives at the queue. Also, you can use the complete set of the API for MDB and JMS. The disadvantage is that additional effort is needed to send messages to the internal JMS event Manager queue to trigger the undercover agent.

Using the >MQMessages class and the Invoke UCA activity

Figure 4 and Figure 5 show how you can use an integration service that uses the getMessage method in the MQMessages class. After the message is retrieved from IBM MQ, you use an Invoke UCA activity to trigger the undercover agent that is attached to the waiting message event.

Figure 4. The getMessage method in the MQMessage class
Screen                     capture of the getMessage method in the MQMessage class
Screen capture of the getMessage method in the MQMessage class
Figure 5. The getMessage method data mapping
Screen                     capture of data mapping for the getMessage method
Screen capture of data mapping for the getMessage method

As you can see from Figure 4 and Figure 5, after the MQMessages.getMessage method is called, the message is saved in the tw.local.mqMessage return value and is parsed to retrieve the credit score information. Then, the Invoke UCA activity is called to trigger the undercover agent.

The code sample that is available to download with this tutorial uses a credit card application scenario that has a credit score check provider. With the code sample, you can mimic the credit score service provider by directly putting a message to the reply queue with the comma-separated message format of customerSSN,creditScore. Parse the message script as shown in Listing 1.

Listing 1. Example of how to parse an IBM MQ message
var splittedString = tw.local.mqMessage.split(",");
tw.local.customerSSN = splittedString[0];
tw.local.creditScore = Number(splittedString[1]);

After the message is parsed, the undercover agent is started with the mapping shown in Figure 6.

Figure 6. Undercover agent input
Screen                     capture of undercover agent input
Screen capture of undercover agent input

The same undercover agent implementation is attached to the message event in the BPD, and the customerSSN string is used as the correlation key, as shown in Figure 7.

Figure 7. Undercover agent data mapping for the message event
Screen                     capture of undercover agent data mapping for the message
Screen capture of undercover agent data mapping for the message

Using an MDB to trigger an undercover agent

Another option to receive messages from IBM MQ is to use an MDB. Figure 8 shows the event flow of using an MDB to trigger an undercover agent.

Figure 8. Triggering an undercover agent with an MDB
Illustration                     of the event flow for triggering an undercover agent with an MDB
Illustration of the event flow for triggering an undercover agent with an MDB

The MDB runs in a separate J2EE application, which runs on the IBM BPM server and acts as a bridge between IBM MQ and the business process. The bean receives the message from IBM MQ, processes the message, and sends another message through JMS to the internal IBM BPM Event Manager queue. The message triggers the undercover agent for the message event, and moves the process along.

The undercover agent definition needs to specify a unique Event Message name (for example, creditScoreMessage, shown in Figure 9).

Figure 9. Undercover agent definition
Screen                     capture of an example undercover agent definition
Screen capture of an example undercover agent definition

An example of the JMS resources definition for the internal IBM BPM Event Manager queue is shown in the administrative console example in Figure 10. The Event Manager queue is an internal IBM BPM queue.

Figure 10. The JMS resources definition for the IBM BPM Event Manager queue
Screen                     capture of the JMS resources definition for the IBM BPM Event Manager
Screen capture of the JMS resources definition for the IBM BPM Event Manager

To send a message to the Event Manager, you send a message through an undercover agent to the Event Manager queue. Encapsulate the message data in a predefined XML structure with eventmsg as the root, as shown Listing 2:

Listing 2. Event message format
<eventmsg>
  <event processApp="MQAPP" ucaname="Credit Check UCA">creditScoreMessage</event> 
  <parameters>  
	<parameter> 
           <key>customerSSN</key> 
           <value>123456789</value> 
     </parameter>
     <parameter>
           <key>creditScore</key> 
           <value>620</value>
    </parameter>
 </parameters>
</eventmsg>

For more information about the message structure, see Posting a message to IBM Business Process Manager Event Manager in the IBM BPM documentation on IBM Knowledge Center.

Listing 3 shows the example MDB code that reads from IBM MQ, processes the message, and then sends it to the Event Manager queue.

Listing 3. Example MDB code
public void onMessage(Message message) {
    	try {
           TextMessage textMessage = (TextMessage) message;
           String mqMessageText = textMessage.getText();
          
           String[] splittedString = mqMessageText.split(",");
           String ssn = splittedString[0];
           String creditScore = splittedString[1];
         
	      String data="<eventmsg><event processApp=\"MQAPP\" ucaname=\"Credit Check
               UCA\">creditScoreMessage</event><parameters><parameter><key>customerSSN</key><value>" 
		 	+ ssn + "</value></parameter><parameter><key>creditScore</key><value>"  
               + creditScore + "</value></parameter></parameters></eventmsg>";
		 		 
		 System.out.println(" to send data" +"\n"+data);
		 InitialContext ctx=new InitialContext();
		 QueueConnectionFactory ucaqcf=(QueueConnectionFactory)ctx.lookup
					("javax.jms.QueueConnectionFactory");
		 Queue ucaqueue=(Queue)ctx.lookup("jms/eventqueue");
		 QueueConnection connection=ucaqcf.createQueueConnection
                        ("bpmdeadmin", "bpmdeadmin");
		 Session session = connection.createSession(false,Session.AUTO_ACKNOWLEDGE);
           MessageProducer producer = session.createProducer(ucaqueue);
           TextMessage sendUCAMessage = session.createTextMessage();
           sendUCAMessage.setText(data);
           producer.send(sendUCAMessage);
            
           System.out.println("UCAMessage Sent");		 		 		 		 
    		} catch (Exception e) {
              e.printStackTrace();
          }
      }

Running the sample code

The sample code contains a business process .twx file that you can import into Process Designer and an .ear file with MDB source code that you can install on the application server for IBM BPM. From the Download section of this tutorial, download the code_sample.zip file and extract the files.

Configuring IBM MQ

The sample code uses the MyQM as the IBM MQ queue manager name, OutgoingQ as the queue name to send the message to IBM MQ, and IncomingQ as the queue to receive the message from IBM MQ. These IBM MQ resources must be created before you run the test. If you named anything differently, update the configuration in the business process and in the MDB settings. Use Figure 11 as an example.

Figure 11. IBM MQ configuration
Screen                     capture of IBM MQ configuration
Screen capture of IBM MQ configuration

Installing the MDB application

The J2EE application contains the MDB in the .ear file in the code_sample.zip file that available in the Download section. Before you install the file, you must create the IBM MQ JMS queue resource, pointing to the IncomingQ queue that was defined in IBM MQ and the MDB activation specification for the application server, as shown in Figure 12.

Figure 12. IBM BPM server configuration for the IBM MQ JMS queue resource
Screen                     capture of the IBM BPM sever configuration for the IBM MQ JMS queue                     resource
Screen capture of the IBM BPM sever configuration for the IBM MQ JMS queue resource

Figure 13 shows the MDB activation specification configuration for installing the sample code with MDB.

Figure 13. MDB activation specification
Screen                     capture of the MDB activation specification
Screen capture of the MDB activation specification

Then, install the .ear file by using the setting for the MDB that is shown in Figure 14.

Figure 14. MDB listener bindings
Screen                     capture of MDB listener bindings
Screen capture of MDB listener bindings

The enterprise archive (EAR) application is installed, but do not start it yet.

Testing how a message is sent to IBM MQ

In Process Designer, import the .twx file and click Start to start an instance of the Credit Card Application Process process. In the inspector, you can see that the message is sent to IBM MQ, and the token is waiting at the message event for the incoming IBM MQ message.

Figure 15 shows the point in the business process that waits for the IBM MQ message to arrive.

Figure 15. Process waiting at the message event
Diagram of a                     process waiting at the message event
Diagram of a process waiting at the message event

In the IBM MQ Explorer, check the OutgoingQ queue to view the sent message.

Testing how a message is received from IBM MQ

Now you can test how IBM MQ messages are received, for both options (if you use the MQMessages class and if you use the MDB).

Testing the MQMessages Java service option

First, put a message in the IncomingQ queue with IBM MQ Explorer to mimic a Credit Score service provider that places a message in the queue. Remember, a comma-separated message format is used, so put a 123456789,620 message in the queue. In this example, 123456789 is the customer SSN and 620 is the credit score. The customer SSN is set in the Gather Customer Info script in the beginning of the process. You can update the script to provide a different SSN, but then, make sure to use a different message to IBM MQ when testing.

Next, run the IBM MQ Get Service service from Process Designer. You can see the token for the process instance moved to the Approval human service because the business rule determines that if the credit score is less than 650, a manager approval is needed.

Testing the MDB option

You need to start a new BPD instance for the testing. First, update the Gather Customer Info script to provide a different customerSSN, for example, 987654321. Then, start the new BPD instance. The process instance waits at the Wait for Credit Score message event.

Next, put a message in the IncomingQ queue as 98765432,700, and the message waits to get picked up the MDB. In the administrative console, start the JMSUCATest application that you installed earlier. Back in Process Designer, you see that the process instance moved through the flow to the end node. Because the credit score is 700, the manager approval step is not needed.

Conclusion

You learned advantages and disadvantages of ways to send and receive messages from a business process to other systems through IBM MQ. After an explanation of three ways to send messages to IBM MQ, the next section stepped through an example of sending messages to IBM MQ with the MQMessages class. And after an explanation of three ways to receive messages from IBM MQ, the tutorial demonstrated two examples: using the MQMessages class and the Invoke UCA activity, and using an MDB to trigger an undercover agent.

The sample code that you can download with this tutorial gives you more opportunities to test sending and receiving messages through IBM MQ from a business process.

You now have the knowledge to determine which option is best for your applications as you plan how to integrate IBM BPM with IBM MQ.

Acknowledgements

The author would like to thank Madhu Channapatna for providing a valuable technical review of this tutorial.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=1016931
ArticleTitle=Integrate IBM MQ with your IBM Business Process Manager processes
publish-date=10072015