In the example provided in this article, you'll learn all the steps required to integrate a WebSohere MQ DataPower SOA Appliances (hereafter called DataPower) XI50 appliance with WebSphere MQ. In the example, you'll:
- Create and configure WebSphere MQ resources
- Create and configure DataPower resources
- Test the end-to-end scenario
Some familiarity with WebSphere MQ and DataPower is useful, but is not required to complete this exercise. The exercise does not include installation instructions for either product. The firmware revision of the X150 appliance used for this example is XI126.96.36.199.17 (Build 131012).
The scenario presented in this article (shown in Figure 1) demonstrates WebSphere MQ being used as both client and server with DataPower located between them. This allows us to demonstrate the specific configuration required for both DataPower and WebSphere MQ. Switching protocols from HTTP to WebSphere MQ and vice versa is a more likely real-world scenario to which DataPower would be applied.
Figure 1. The MQ to MQ multi-protocol gateway scenario that forms the basis for this article
The steps of the scenario are as follows:
- A message is placed in a queue.
- The input message is taken from the queue (FRONT.GET) by the DataPower XI50 appliance, which then applies a simple XSLT transformation to the message data.
- The message is written to an output queue (BACK.REQUEST). For simplicity, we use the same queue manager to integrate both sides of the DataPower appliance, but this is not required.
- The message is taken from the output queue (BACK. REQUEST) by a second instance of RFHUtil. This simulates the action of another WebSphere MQ enabled application. Typically, the message might be reformatted by a WebSphere MQ application before being sent on the "second leg" back through the XI50. In our example, RFHUtil simply writes the same message to a different queue (the Backend URL reply queue, BACK.REPLY), which is the input point for the second leg.
- Before sending the message back, we use the second instance of RFHUtil to switch the MsgId to the CorrelId property of the MQMD header, following the the classic Request/Reply model of WebSphere MQ. For those who are knowledgeable about WebSphere MQ, the DataPower XI50 carries out an MQGet using CorrelId in order to identify messages destined for the return leg from the reply queue of the backend URL.
- After picking up the message from the backend URL, the DataPower appliance applies the same stylesheet transformation to the data on its return leg. An alternative transformation could be applied on the return leg., but we use the same transformation for simplicity.
- The transformed message is written to the reply queue (FRONT.PUT) of the front side handler component. The first instance of RFHUtil is used to read this message.
For those who are skilled in WebSphere MQ but not so familiar with DataPower, Figure 2 may help you understand the options available with the multi-protocol gateway:
Figure 2. Options available through a multi-protocol gateway
A single multi-protocol gateway can support definitions of multiple front side handlers. Data can be input to the same gateway on the XI50 using different protocols or different input locations. The example in Figure 2 shows two MQ front side handlers and one HTTP front side handler.
Each MQ front side handler specifies a request queue and a reply queue, both on the same queue manager.
A single multi-protocol gateway can have either a "static-backend" or a "dynamic-backend":
- A static-backend URL specifies both a RequestQueue and a ReplyQueue for a single WebSphere MQ enabled backend resource. The static backend URL is configured on the multi-protocol gateway general properties.
- A dynamic-backend uses the
route-setAction, within the multi-protocol gateway policy. The
route-setAction is available from the Advanced Action icon, when configuring the processing policy. This setting utilizes either a DataPower variable, a stylesheet, or an Xpath expression to determine the backend URL with which the XI50 communicates. This means that a single processing policy can utilize multiple protocols and destinations dynamically decided at runtime.
Set up the environment
In order to complete this exercise the following, you'll need the following:
- Domain administration access to one DataPower appliance.
- WebSphere MQ Server installed. The screen captures in this article were taken on Windows XP.
- RFHUtil, available free of charge as part of an IBM support pac. RFHUtil simulates a WebSphere MQ enabled application. See Resources for more information.
For simplicity, we'll use the Web interface rather than the command line administration utility, to perform the DataPower configuration in this example. We'll use a script (runmqsc) from the WebSphere MQ command line for WebSphere MQ configuration. We'll use the WebSphere MQ Explorer to explore the resources created in this process.
Step 1: Create the WebSphere MQ resources
A script is provided that defines all the WMQ artifacts needed. You could use the WebSphere MQ user interface to do this, but a script is provided for your ease:
- Unzip the LabResources.zip file provided in the Download section.
- Open a command prompt and change to the directory where you unzipped the LabResources file.
- Execute the batch script setupQMDP.bat. This script does the following, as shown in Figure 3:
- Creates and starts a Queue Manager called QMDP.
- Creates four queues called:
- Creates and starts a listener called QMDP_LSTR that listens on port 3414.
- Creates a channel called DP.CHANNEL.
Figure 3. Running setupQMDP.bat creates the WMQ resources
- Open the WebSphere MQ Explorer and you should see that the queue manager has been successfully created with four local queues. Expand the Queue Managers folder in the left window, and expand the QMDP queue manager. Select Queues, and you should see the following queues displayed:
Figure 4. New queues shown in WebSpher MQ Explorer
- To view the WebSphere MQ listener configuration, expand Advanced and select Listeners. Note that our listener is running on Port 3414. We'll specify this later.
Step 2: Create a DataPower multi-protocol gateway
Next we'll create artifacts to demonstrate the integration between WebSphere MQ and DataPower:
- Log in to your DataPower box, using a domain you have access to.
- Select the Multi-Protocol Gateway icon (in the upper left of the control panel), as shown in Figure 5:
Figure 5. Create multi-protocol gateway
- Click Add add a new multi-protocol gateway.
Step 3: Create a DataPower processing policy
- In the Multi-Protocol Gateway Name field, specify
WMQ_MPGateway, and add an optional summary, as shown in Figure 6:
Figure 6. Specify multi-protocol gateway name
- To add a multi-protocol gateway policy, select the + button beside the Multi-Protocol Gateway Policy field, as shown in Figure 7:
Figure 7. Add a multi-protocol gateway policy
WMQ_ProcessingPolicyas the policy name and click OK. If you receive a warning message, click OK to dismiss it.
- To configure the match rule, double-click the Match icon (highlighted with a yellow box), as shown in Figure 8:
Figure 8. The initial multi-protocol gateway policy
- Click the + button to create a new match rule.
- On the Main tab, specify
Allas the rule name.
- Click the Matching Rule tab, then click Add, as shown in Figure 9:
Figure 9. Add matching rule
urlin the Matching Type field, and
*for the URL Match, then click Save, as shown in Figure 10:
Figure 10. Specify matching type
- Click Apply, as shown in Figure 11:
Figure 11. Apply matching rule
The Matching Rule should have been successfully modified.
- Click Close. Note that the new matching rule is now selected.
- Click Done. If you hover over the Match icon, you'll see that the rule has successfully been applied.
- Drag and drop a Transform icon onto the rule to the right of the Match icon, as shown in Figure 12:
Figure 12. Drag and drop Transform icon
- To edit the transform, double-click the yellow box around the new transform.
- In the Configure Transform Action dialog, do the following:
- For Use Document Processing Instructions, leave the default setting of Use XSLT specified in this action.
- Click Upload beside the Processing Control File field, as shown in Figure 13:
Figure 13. Upload processing control file
- In the next window, click Browse to navigate to the simple.xsl stylesheet supplied with this document. The file details will display in the window.
- Click Upload.
- Click Continue in the confirmation window. The previous window should display and show the XSL settings as shown in Figure 14:
Figure 14. XSL settings
- Click Done.
- In the Rule Action section, click Apply. The new rule should appear in the Configured Rules at the bottom of the screen, as shown in Figure 15:
Figure 15. New rule
- Click Close in the Select a Policy Name section at the top of the screen.
The following XSL has been uploaded:
<?xml version="1.0" encoding="UTF-8"?> <xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:dp="http://www.datapower.com/extensions" xmlns:dpconfig="http://www.datapower.com/param/config" extension-element-prefixes="dp" exclude-result-prefixes="dp dpconfig"> <xsl:output method="xml"/> <xsl:template match="/"> <Message> <Text>Simple XSL Transformation</Text> <OriginalMessage> <xsl:copy-of select="."/> </OriginalMessage> </Message> </xsl:template> </xsl:stylesheet>
Step 4: Configure the backend URL
- Under General Configuration settings there are two sections: Back side settings and Front side settings. These sections control the properties of both sides of the multi-protocol gateway. To add the backend URL, click MQHelper under Back side settings.
- Click the + next to the Queue Manager field, and select Create a New => MQ Queue Manager, as shown in Figure 16:
Figure 16. Create a queue manager
- Complete the fields in the Configure Queue Manager dialog, as follows:
QMDPas the Name.
- In the Comments field, enter
This is the DataPower representation of the WebSphere MQ queue manager.
- In the Host Name field, specifiy the host name or IP address of the machine on which the WebSphere MQ queue manager is located, followed by the WebSphere MQ listener port number (in this case, 3414), in the format:
QMDP, which is the name generated by the script, in the Queue Manager Name field.
- The Channel Name field is pre-filled with the text
SYSTEM.DEF.SVRCONN. This is a server connection channel that is created by default on a WebSphere MQ queue manager. To avoid confusion with other uses of the channel, the supplied script generates a server connection channel, called DP.CHANNEL, exclusively for DataPower communication. Update the Channel Name field to
- In the User Name field, specify a user ID that is authenticated for WebSphere MQ. This is typically a user ID that is a member of the local group "mqm" on the machine that hosts WebSphere MQ.
- Leave all the other settings as their defaults, and click Apply, as shown in Figure 17:
Figure 17. Configure Queue Manager dialog
- Back in the MQ URL Builder dialog, do the following, as shown in Figure 18:
URINotUsedin the URI field. This is not actually used for the WebSphere MQ connection, but is a mandatory property, so it must be filled in
- In the RequestQueue field specify
- In the ReplyQueuefield, specify
Click off for Transactionality.
Click the offUserIdentifier.
Figure 18. MQ URL Builder dialog
- The browser window will display again, and you'll see that your previous actions will have generated the following backend URL:
Step 5: Configure the front side handler
- Create a new front side protocol, by doing the following:
- In the Front Side Settings dialog, click Create new.
- Select MQ Front Side Handler from the list, as shown in Figure 19:
Figure 19. Create front side protocol
- Configure the MQ front side handler by doing the following, as shown in Figure 20:
WMQ_FrontSideHandleras the Name.
- In the Queue Manager field, select QMDP.
FRONT.GETfor the Get Queue.
FRONT.PUTfor the Put Queue.
- Click Apply.
Figure 20. Configure MQ front side handler
- Add the front side handler you just created by clicking Add to gateway, as shown in Figure 21. The front side handler should now be listed.
Figure 21. Add front side handler
Step 6: Complete the gateway configuration
All that's left is to configure is a couple of remaining pieces if the multi-protocol gateway.
- In the General section of the multi-protocol gateway configuration, select XML for Response Type and Request Type, as shown in Figure 22:
Figure 22. Select response and request type
- WebSphere MQ messages contain a header called an MQ Message Descriptor (MQMD). This must be suppressed in the back direction, because it can't be processed by the XSL transformation used in our example. To suppress the MQMD, click the Headers, then click Add under Header Suppression Parameters, as shown in Figure 23:
Figure 23. Supress MQMD
- Leave the default setting of back in the Direction field, and specify
MQMDas the Header Tag, the click Submit, as shown in Figure 24:
Figure 24. Add new header suppression parameter
- Click Apply to apply the configuration of the multi-protocol gateway.
- Click View Status to verify that all of the components are running. The op-state should be up for all of the components.
Figure 25. Verify status
- Once you're satisfied that all components are operational, you can close the window. However, you might want to take this opportunity to do some troubleshooting of the DataPower and MQ integration. Troubleshooting is beyond the scope of this article.
- When you're returned to the success window for the multi-protocol gateway, click Done.
- To save the configuration, click Save Config for your domain.
Step 7: Test using RFHUtil
To test the end-to-end scenario, do the following:
- To view the open input count of the queues, in the WebSphere MQ Explorer, select IBM WebSphere MQ => Queue Managers => QMDP => Queues, as shown in Figure 26. The open input count of the FRONT.GET queue should be 1, which indicates that the DataPower appliance has this queue open and is ready to receive a message.
Figure 26. FRONT.GET queue
- Launch RFHUtil, which is provided with IH03.
- On the Main tab, do the following:
QMDPin the Queue Manager Name field.
FRONT.GETin the Queue Name.
- Click Read File and browse to the location of Text.xml, supplied with this article.
Figure 27. Specify settings on Main tab
- Click the Data tab, and select XML. The following message is displayed:
Figure 28. Specify settings on Main tab
- Click the MQMD tab.
MQSTRfor MQ Message Format, as shown in Figure 29:
Figure 29. Specify MQ message format
- Go back to the Main tab and click Write Q to send a message.
- Return to WebSphere MQ Explorer and open the Queues window again. Notice that the message on FRONT.GET has been consumed, and that a message has been sent to BACK.REQUEST, as shown in Figure 30:
Figure 30. Test message
- Launch another instance of RFHUtil.
- On the Main tab, do the following:
QMDPin the Queue Manager Name field.
BACK.REQUESTin the Queue Name field.
- Click Read Q, as shown in Figure 31:
Figure 31. Main tab settings
- Select the Data tab, and select XML. You'll see that the original message that was written to FRONT.GET has been transformed by DataPower in accordance with the supplied style sheet:
Figure 32. Message from BACK.REQUEST
- Create a reply message, using the same message read from BACK.REQUEST for the response, by doing the following:
- Select the MQMD tab.
- So that DataPower can retrieve the reply, the Correlation ID needs to be set to the Message ID in the message it sent. Click Copy Msg Id to Correl Id, as shown in Figure 33:
Figure 33. Set Correlation ID
- Write the message to the reply queue, by doing the following from the Main tab:
- Select BACK.REPLY for the Queue Name.
- Click Write Q , as shown in Figure 34:
Figure 34. Write the message to the reply queue
- Return to WebSphere MQ Explorer and open the Queues window again. Notice that
the message sent to BACK.REPLY has been consumed and that a message has now been sent to FRONT.PUT:
Figure 35. Message to BACK.REPLY consumed
- Return to the first instance of RFHUtil and read the message, by doing the following:
- Select FRONT.PUT for the Queue Name.
- Click Read Q.
Figure 36. Read the message
- To view the data, do the following:
- Select the Data tab.
- Click XML.
- The return message that was written to BACK.REPLY has once again been transformed by DataPower in accordance with the supplied style sheet.
You've now finished testing.
In this exercise you have seen how to:
- Create a simple queue manager, with a number of queues and a channel that is then used by DataPower.
- Configure a multi-protocol gateway that included:
- A simple processing policy
- An MQ front side handler
- An MQ backend URL
- Test the end-to-end scenario.
You've seen firsthand how front- and back-end integration is possible with DataPower and WebSphere MQ. These capabilities extend the reach of WebSphere DataPower SOA Appliances into the award-winning WebSphere MQ messaging backbone.
- WebSphere MQ product information: WebSphere MQ features and specifications.
- WebSphere MQ product documentation: Complete production documentation for WebSphere MQ.
- DataPower product information: DataPower features and specifications.
- WebSphere DataPower documentation: Product documentation, whitepapers, and more.
- Patterns: SOA Design using WebSphere Message Broker and WebSphere ESB: This redbook discusses patterns for integrating WebSphere Enterprise Service Bus and WebSphere Message Broker and includes a scenario to help you design, develop and deploy these products. Chapters 7 and 10 deal specifically with DataPower topics.
- developerWorks WebSphere MQ zone: Get the latest technical information on WebSphere MQ.
- developerWorks WebSphere and SOA zone: Get the latest technical information on WebSphere and SOA.
Get products and technologies
- IH03: WebSphere Message Broker V6-Message display, test & performance utilities: Get RFHUtil, which is used to test the scenario in this article.
- DataPower Appliance firmware and documentation: Download the appliance firmware and documentation.
- Developerworks forum for WebSphere MQ users: Discuss MQ with other developers.