Integrating WebSphere DataPower SOA Appliances with WebSphere MQ

Learn how you can configure Websphere® MQ to send and receive WebSphere DataPower SOA Appliances messages, thus providing WebSphere MQ apps with rich DataPower capabilities and providing DataPower with access to a WebSphere MQ network.

Peter Crocker (peter_crocker@uk.ibm.com), Senior IT Specialist, EMC

Photo of Peter CrockerPeter Crocker is an Accredited Senior IT Specialist working for the Software Services team in the IBM Hursley Software Lab in the UK. He specializes in WebSphere Message Broker and works with customers to provide consultancy on design and implementation. Peter moved to this role from the Message Broker development team, bringing a deep technical knowledge of the internals of this product. He was part of the team that delivered the WebSphere Message Broker Version 6 beta program and has also developed and delivered education to the services teams in this area. You can reach Peter at peter_crocker@uk.ibm.com.



Ben Thompson, Senior IT Specialist, EMC

Photo of Ben ThompsonBen Thompson is an Accredited Senior IT Specialist in IBM Software Group's EMEA Laboratory Services in Hursley, UK. He has worked with distributed transactional middleware for seven years and has extensive experience designing and implementing solutions using the WebSphere product portfolio with IBM customers worldwide. You can reach Ben at bthomps@uk.ibm.com.



21 March 2007

Also available in Japanese

Introduction

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 XI50.3.5.0.17 (Build 131012).

The scenario

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
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:

  1. A message is placed in a queue.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.

Alternative scenarios

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
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-set Action, within the multi-protocol gateway policy. The route-set Action 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:

  1. Unzip the LabResources.zip file provided in the Download section.
  2. Open a command prompt and change to the directory where you unzipped the LabResources file.
  3. 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:
      • FRONT.GET
      • FRONT.PUT
      • BACK.REQUEST
      • BACK.REPLY
    • 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
    Figure 3. Running setupQMDP.bat creates the WMQ resources
  4. 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
    Figure 4. New queues shown in WebSpher MQ Explorer
  5. 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:

  1. Log in to your DataPower box, using a domain you have access to.
  2. 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
    Figure 5. Create multi-protocol gateway
  3. Click Add add a new multi-protocol gateway.

Step 3: Create a DataPower processing policy

  1. 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
    Figure 6. Specify multi-protocol gateway name
  2. 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
    Figure 7. Add a multi-protocol gateway policy
  3. Enter WMQ_ProcessingPolicy as the policy name and click OK. If you receive a warning message, click OK to dismiss it.
  4. 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
    Figure 8. The initial multi-protocol gateway policy
  5. Click the + button to create a new match rule.
  6. On the Main tab, specify All as the rule name.
  7. Click the Matching Rule tab, then click Add, as shown in Figure 9:
    Figure 9. Add matching rule
    Figure 9. Add matching rule
  8. Specify url in the Matching Type field, and * for the URL Match, then click Save, as shown in Figure 10:
    Figure 10. Specify matching type
    Figure 10. Specify matching type
  9. Click Apply, as shown in Figure 11:
    Figure 11. Apply matching rule
    Figure 11. Apply matching rule
    The Matching Rule should have been successfully modified.
  10. Click Close. Note that the new matching rule is now selected.
  11. Click Done. If you hover over the Match icon, you'll see that the rule has successfully been applied.
  12. 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
    Figure 12. Drag and drop Transform icon
  13. To edit the transform, double-click the yellow box around the new transform.
  14. 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
      Figure 13. Upload processing control file
  15. 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.
  16. Click Upload.
  17. 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
    Figure 14. XSL settings
  18. Click Done.
  19. 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
    Figure 15. New rule
  20. 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

  1. 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.
  2. 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
    Figure 16. Create a queue manager
  3. Complete the fields in the Configure Queue Manager dialog, as follows:
    • Specify QMDP as 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: x.x.x.x(3414).
    • Specify 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 DP.CHANNEL.
    • 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
      Figure 17. Configure Queue Manager dialog
  4. Back in the MQ URL Builder dialog, do the following, as shown in Figure 18:
    • Specify URINotUsed in 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 BACK.REQUEST.
    • In the ReplyQueuefield, specify BACK.REPLY.

      Click off for Transactionality.

      Click the offUserIdentifier.

      Click Build.

      Figure 18. MQ URL Builder dialog
      Figure 18. MQ URL Builder dialog
  5. The browser window will display again, and you'll see that your previous actions will have generated the following backend URL:
    dpmq://QMDP/URINotUsed?RequestQueue=BACK.REQUEST;ReplyQueue=BACK.REPLY

Step 5: Configure the front side handler

  1. 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
      Figure 19. Create front side protocol
  2. Configure the MQ front side handler by doing the following, as shown in Figure 20:
    • Specify WMQ_FrontSideHandler as the Name.
    • In the Queue Manager field, select QMDP.
    • Specify FRONT.GET for the Get Queue.
    • Enter FRONT.PUT for the Put Queue.
    • Click Apply.
      Figure 20. Configure MQ front side handler
      Figure 20. Configure MQ front side handler
  3. 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
    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.

  1. 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
    Figure 22. Select response and request type
  2. 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
    Figure 23. Supress MQMD
  3. Leave the default setting of back in the Direction field, and specify MQMD as the Header Tag, the click Submit, as shown in Figure 24:
    Figure 24. Add new header suppression parameter
    Figure 24. Add new header suppression parameter
  4. Click Apply to apply the configuration of the multi-protocol gateway.
  5. 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
    Figure 25. Verify status
  6. 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.
  7. When you're returned to the success window for the multi-protocol gateway, click Done.
  8. 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:

  1. 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
    Figure 26. FRONT.GET queue
  2. Launch RFHUtil, which is provided with IH03.
  3. On the Main tab, do the following:
    • Specify QMDP in the Queue Manager Name field.
    • Specify FRONT.GET in 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
      Figure 27. Specify settings on Main tab
  4. Click the Data tab, and select XML. The following message is displayed:
    Figure 28. Specify settings on Main tab
    Figure 28. Specify settings on Main tab
  5. Click the MQMD tab.
  6. Specify MQSTR for MQ Message Format, as shown in Figure 29:
    Figure 29. Specify MQ message format
    Figure 29. Specify MQ message format
  7. Go back to the Main tab and click Write Q to send a message.
  8. 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
    Figure 30. Test message
  9. Launch another instance of RFHUtil.
  10. On the Main tab, do the following:
    • Specify QMDP in the Queue Manager Name field.
    • Specify BACK.REQUEST in the Queue Name field.
    • Click Read Q, as shown in Figure 31:
      Figure 31. Main tab settings
      Figure 31. Main tab settings
  11. 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
    Figure 32. Message from BACK.REQUEST
  12. 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
      Figure 33. Set Correlation ID
  13. 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
      Figure 34. Write the message to the reply queue
  14. 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
    Figure 35. Message to BACK.REPLY consumed
  15. 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
      Figure 36. Read the message
  16. To view the data, do the following:
    • Select the Data tab.
    • Click XML.
  17. 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.

Conclusion

In this exercise you have seen how to:

  1. Create a simple queue manager, with a number of queues and a channel that is then used by DataPower.
  2. Configure a multi-protocol gateway that included:
    • A simple processing policy
    • An MQ front side handler
    • An MQ backend URL
  3. 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.


Download

DescriptionNameSize
Required materialsLabResources.zip1KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=203070
ArticleTitle=Integrating WebSphere DataPower SOA Appliances with WebSphere MQ
publish-date=03212007