Multi-protocol Gateway

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

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

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

   
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

   
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

   
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

   
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

   
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

   
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

   
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

   
9. Click Apply, as shown in Figure 11:

   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

    
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

      
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

    
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

    
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

   
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

     
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

     
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

     
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

     
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

   

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

   
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 underHeader Suppression Parameters, as shown in Figure 23:

   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

   
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

   
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

   
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

     
4. Click the Data tab, and select XML. The following message is displayed:

   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

   
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

   
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

      
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

    
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

      
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

      
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

    
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

      
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.