Skip to main content

Using WebSphere MQ bindings in WebSphere ESB, Part 1: Manipulating MQ headers in WebSphere ESB using the XSL transformation primitive and WebSphere Integration Developer

Philip Norton (nortonp@uk.ibm.com), Software Engineer, WebSphere ESB development team, IBM
Philip Norton photo
Philip Norton is a software engineer at IBM Hursley Lab. He works on the WebSphere ESB Development team. His expertise includes Java and JMS for Websphere MQ. He is a certified Java Programmer and he has a degree in Computer Science from Canterbury University.
Alex Wood (wooda@uk.ibm.com), Software Developer, IBM United Kingdom
Alex Wood
Alex Wood works at IBM Hursley Lab in England as a software developer for the IBM WebSphere Business Integration suite of products. He has extensive experience in development on many of the WebSphere products, including WebSphere MQ, WebSphere Message Broker, WebSphere Enterprise Service Bus, and WebSphere Process Server. He received a BSc in Physics with Astrophysics from Birmingham University in the UK in 1998.

Summary:  The WebSphere MQ binding provided with WebSphere ESB and WebSphere Process Server allows communication between native MQ applications and a Service Component Architecture (SCA) environment. The WebSphere MQ bindings make receiving and sending MQ messages simple, but sometimes additional manipulation of the message is required to map from one application to another. This article describes the MQ header and shows you how to modify it to create the message format required by your native MQ application. It includes sample code that uses an XSL transformation mediation primitive to set required fields in the MQ header.

View more content in this series

Date:  21 Jan 2009
Level:  Intermediate
Activity:  749 views

Introduction

IBM® WebSphere® Enterprise Service Bus (WebSphere ESB) exposes MQ headers in a mediation component as part of the Service Message Object (SMO) structure. Therefore, MQ headers can be manipulated, added, and removed using the transformation capabilities of the Websphere ESB mediation component. This article shows you how the MQ headers are exposed in the SMO, and how you can manipulate the MQ headers that appear in an outbound MQ message sent from an MQ import, including controlling the properties of the MQMD and adding an MQRFH2 header.

Products used in this article:

  • WebSphere Integration Developer V6.1
  • WebSphere ESB V6.1 Integrated Test Environment (included with WebSphere Integration Developer)
  • WebSphere MQ V6.0.2.2

Overview of the MQHeader structure in the Service Message Object

It is important to understand how the MQ headers are exposed in the Service Message Object (SMO) and how this structure differs from the way the headers are structured on the wire by Websphere MQ.

The key difference is that in the SMO, the chain of headers is unraveled and the control information (encoding, CCSID, and format) describing each header is placed within that header's structure in the SMO. On the wire, by contrast, each header carries the control information of the next header or payload in the sequence. Therefore headers in the SMO can be manipulated more easily because they can be added and removed from the sequence without the need to modify control information in other headers. The control information associated with the payload of the MQ message is kept in the control structure at the top level of the MQHeader structure in the SMO.


Figure 1. Mapping of MQ headers to the System Message Object
Figure 1. Mapping of MQ headers to the SMO

Although all fields in the MQMD, RFH2, and RFH headers are exposed in the SMO with the exception of StrucID, Version, and StrucLength, not all fields will be propagated into the outbound MQ Message as they are overridden by system values.

Fields that are not propagated to the outbound MQ message

  • MQMD
    • MsgType
    • MsgID
    • BackoutCount
    • ReplyToQ
    • ReplyToQMgr
    • UserIdentifier
    • AccountingToken
    • ApplIdentityData
    • PutApplType
    • PutApplName
    • PutDate
    • PutTime
    • ApplOriginData
    • GroupId
    • MsgSeqNumber
    • Offset
    • OriginalLength

Manipulating MQMD, MQControl, and MQRFH2 using an XSL transformation

The MQ headers exposed in the SMO can be manipulated by a number of the transformation primitives in a mediation module. This section will guide you through manipulating the MQMD, MQRFH2, and control information of the MQ message payload using the XSL transformation primitive.

In this example, the JMSTextBody business object and the MQ unstructured text data binding are being used, so the message payload will be treated a a single block of unstructured text. The example will focus on manipulating the headers and not the body.

Building the module

First, create a library and mediation module that will contain the XSL transformation:

  1. Create a new Library called MQHeaderExampleLibrary.
  2. Open the dependencies on the library, and under Predefined Resources, tick the Schema for simple JMS Data Bindings and click Save. The JMS body types are now available.
  3. In the library, create a new interface called MQHeaderExampleService.
  4. Create a one-way operation named writeMQNativeMessage.
  5. Change the type of input1 to JMSTextBody and click Save to save the interface.
  6. Create a new mediation module called MQHeaderExample1. Ensure that Create mediation component is ticked and click Next.
  7. Tick the MQHeaderExampleLibrary and click Finish.
  8. Add an import to the assembly diagram.
  9. Wire the mediation component to the import, and when asked to add a reference, select MQHeaderExampleService.
  10. Right-click on Import1 and select Generate Binding: Messaging Binding: MQ Binding.
  11. Specify the queue manager name, send destination, host name, server channel, and port of your WebSphere MQ installation.
  12. Under Data Configuration, click Browse.
  13. Select Show predefined data bindings.
  14. Select MQ unstructured text message and click OK, then click OK again.
  15. Right-click on the mediation component, select Add: Interface, select the MQHeaderExampleService, and click OK.

Your assembly should now look like this:


Figure 2. MQHeaderExample1 assembly
Figure 2. MQHeaderExample1 assembly

Building the mediation flow

Next, create the mediation flow and add an XSL transformation primitive to do the MQ headers mapping:

  1. Double-click on the mediation component MQHeaderExample1 to generate an implementation.
  2. In the mediation flow editor, wire writeMQNativeMessage to writeMQNativeMessage to create a flow.
  3. In the Palette, select Transformation: XSL Transformation.
  4. Add the XSL transformation primitive to the canvas.
  5. Wire the input node to the input terminal of the XSL transformation.
  6. Wire the output terminal of the XSL transformation to the callout node.

Your mediation flow should now look like this:


Figure 3. MQHeaderExample1 mediation flow
Figure 3. MQHeaderExample1 mediation flow

Mapping MQ header fields in the XSL transformation

  1. Double-click the XSLTransformation1 primitive to open the New XML Mapping wizard.
  2. Click Next to accept the default mapping name and namespace.
  3. Select Message Root and set it to /headers from the drop down list.
  4. Click Finish to accept the default input and output message types.

The mapping editor will now open. Because a root of /headers was selected, only the header part of the SMO will be shown. On the left side of the editor are the input fields representing all the possible header structures that may be found in the SMO entering the XSL transformation primitive. Depending on the origin of the SMO message at this point, these headers may not all be present and may not contain values. On the right side of the editor are the output fields representing all the possible headers structures that can be set in the SMO by the XSL transformation.

  1. Right-click on the input SMOHeader, select Create Connection, and drag the wire to the output SMOHeader.
  2. Right-click on the output MQHeader, and select Create Transform.

Your mapping should now look like this:


Figure 4. XSLT Mapping /headers
XSLTMapping/headers

  1. Double-click on the Inline Map box to open the MQHeader map.
  2. Right-click on the output md, and select Create Transform to create an Inline Map.
  3. Right-click on the Inline Map for header, and select Show in Properties.
  4. In the Cardinality section, set the Output array indices of header to 0.

Setting the cardinality of the header map to 0 means that this map will act on the first MQ header in the output array. You can create further transforms wired to header, and for each one set the cardinality property to act on a different instance. In this way you can build up a sequence of different MQ headers in the output message.

  1. Double-click on the Inline Map box for md to open the MQMD map.
  2. Right-click on the output Expiry, and select Create Transform to create an Assign map. Set the value in the properties panel to 600 (60 seconds).
  3. Repeat the previous step, creating assignments for the following additional properties and values:
    • Priority: 7
    • Persistence: 0 (Non-Persistent)
    • CorrelId: 4D5920434944 (ASCII for "MY CID").

Your MQMD mapping should now look like this:


Figure 5. Mapping of MQMD
Figure 5. Mapping of MQMD

  1. Right-click anywhere in the Mapping Editor and select Up a level to return to the higher level mapping.
  2. Repeat the process of building an inline map for the control structure, setting assignments for the following properties:
    • Encoding: 0
    • CodedCharSetId: 819
    • Format: MQSTR
  3. Repeat the process of building an inline map for the header structure, setting assignments for the following properties:
    • Encoding: 0
    • CodedCharSetId: 819
  4. Whilst still in the header map, create an Inline Map for rfh2.
  5. Inside the rfh2 map, create an Inline Map for folder with a Cardinality of 0.
  6. In the folder map, set the Name property to ExampleGroup, and create an Inline Map for property with a Cardinality of 0.
  7. Finally, in the property map, set assignments for the following properties:
    • Name: ExampleProperty
    • Type: String
    • Value: testValue
  8. Save all changes.

Figure 6 shows the process of building up the multilevel mapping of the RFH2 header:


Figure 6. Mapping the RFH2 header
Figure 6. Mapping the RFH2 header

The mapping and the mediation module are now complete.

Testing the module

You can use the universal test client to test the module:

  1. Right-click on the MQHeaderExample1 mediation component and select Test component.
  2. In the Component Test Events view, enter any value for the value field of input1.
  3. Click on the Continue(run) button to start the test.
  4. In the Deployment Location window, select WebSphere ESB Server and click Finish.

The server will start and the application will be deployed and invoked. Once the component test is complete, you will see the invoke returned, as shown below:


Figure 7. Invoke Returned
Figure 7. Invoke Returned

  1. Using WebSphere MQ Explorer, right-click on the send queue and select Browse Messages.
  2. Double-click on the message and you will see the properties that were set in the mediation component:

Figure 8. MQMessage
>Figure 8. MQMessage

Congratulations, you have successfully created a mediation module that adds a MQHeader to a message.


Back to top

Download

DescriptionNameSizeDownload method
Project Interchange containing MQHeaderExample1PIMQHeaderExample1PI.zip29KBHTTP

Information about download methods


Resources

About the authors

Philip Norton photo

Philip Norton is a software engineer at IBM Hursley Lab. He works on the WebSphere ESB Development team. His expertise includes Java and JMS for Websphere MQ. He is a certified Java Programmer and he has a degree in Computer Science from Canterbury University.

Alex Wood

Alex Wood works at IBM Hursley Lab in England as a software developer for the IBM WebSphere Business Integration suite of products. He has extensive experience in development on many of the WebSphere products, including WebSphere MQ, WebSphere Message Broker, WebSphere Enterprise Service Bus, and WebSphere Process Server. He received a BSc in Physics with Astrophysics from Birmingham University in the UK in 1998.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Close [x]

Help: Update or add to My dW interests

What's this?

This little timesaver lets you update your My developerWorks profile with just one click! The general subject of this content (AIX and UNIX, Information Management, Lotus, Rational, Tivoli, WebSphere, Java, Linux, Open source, SOA and Web services, Web development, or XML) will be added to the interests section of your profile, if it's not there already. You only need to be logged in to My developerWorks.

And what's the point of adding your interests to your profile? That's how you find other users with the same interests as yours, and see what they're reading and contributing to the community. Your interests also help us recommend relevant developerWorks content to you.

View your My developerWorks profile

Return from help

Close [x]

Help: Remove from My dW interests

What's this?

Removing this interest does not alter your profile, but rather removes this piece of content from a list of all content for which you've indicated interest. In a future enhancement to My developerWorks, you'll be able to see a record of that content.

View your My developerWorks profile

Return from help

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=365976
ArticleTitle=Using WebSphere MQ bindings in WebSphere ESB, Part 1: Manipulating MQ headers in WebSphere ESB using the XSL transformation primitive and WebSphere Integration Developer
publish-date=01212009
author1-email=nortonp@uk.ibm.com
author1-email-cc=ramaker@us.ibm.com
author2-email=wooda@uk.ibm.com
author2-email-cc=

Table of contents

Next steps from IBM

My developerWorks community

Interact, share, and communicate with developers worldwide.

My developerWorks overview

Tags

Help
Use the search field to find all types of content in My developerWorks with that tag.

Use the slider bar to see more or fewer tags.

Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).

My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).

Use the search field to find all types of content in My developerWorks with that tag. Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere). My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).

 

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Rate a product. Write a review.

Write a review for Rational products today!

Special offers

No-cost WebSphere Application Server development

Free trial IBM TXSeries for Multiplatforms

Cloud computing for developers

More offers