About the Message Map sample

The sample maps demonstrate design patterns that implement a variety of brokering scenarios. The design of the message map tools allows these design patterns to be combined together as compound patterns. This allows message maps for complex scenarios to be authored by assembling design patterns for simpler scenarios together. The sample files are not intended to be deployable.

Handling complete message assemblies

The sample files for processing complete message assemblies are located in the message_assembly folder in the Message Map Sample Message Flows project.

A message assembly is the combination of all the headers and the body or payload of the message. The Mapping, DataInsert, DataUpdate, DataDelete, and Extract nodes in a message flow always handle a complete message assembly. This means mapping for these nodes always show a message assembly model as the sources and targets of a map.

There are two message assembly models in WebSphere Message Broker: the simplified Properties model and the full Headers model. Choosing either is a matter of selecting the model that matches your scenario requirements. The left picture shows the Properties model of a message assembly; the right shows the Headers message assembly model.

Properties Assembly

Properties Assembly

A WebSphere Message Broker message assembly includes four items, that are numbered in the picture:

  1. the LocalEnvironment folder;
  2. the Properties folder;
  3. transport layer Message Headers group;
  4. the message payload or body.

You can configure a message flow to perform a Route To Label jump after one of the mapping nodes; this is useful in intra-flow content-based routing scenarios.

Three common scenarios are implemented in this sample:

In all cases, the body or payload of the message comes as the last item in the message assembly.

Return to the top.

Controlling Message Flow Processing with a Map

Use the message assembly labelName element to control the routing of a message after a mapping node. This is useful in scenarios where you wish to select the next message flow nodes to continue processing from a map.

The following figure shows the sample message flow file RouteToLabelUsingMap.msgflow configured with a Mapping node, a Route To Label node, and several destination Label nodes. The target destination labels of the Label nodes are configured to be the same as their names.

Route To Label message flow

In order to select which Label node processes the output message, the map must specify the Label node Label Name property. The sample map file SetLabelNodeLabelName.msgmap handles this using an if row with 2 conditions and an else:

Route To Label message map

In this sample:

Return to the top.

Copy All Headers

Often a map focuses exclusively on the body of a message. In this scenario, all the headers are to be copied unchanged by the map.

Use the Properties model to copy all the headers unchanged. When you select the simplified Properties message assembly model, all the message headers except the Properties folder are copied, in-order and unchanged.

Once you have created a Properties message map, map the $source/Properties complex element to the $target/Properties complex element. This will cause the Properties folder to be copied unchanged from source to target, together with all the other unchanged headers.

The image below shows the sample file CopyAllHeaders.msgmap configured to copy all headers (including Properties) unchanged.

Copy All Headers

Return to the top.

Mapping Properties

The Properties model enables many broker scenarios without having to deal with the complexity of mapping several headers. Properties distills most of the important header attributes for MQ Series and the MRM parser, and presents them in a single package. In addition to the Copy All Headers scenario, use the Properties model in situations where MQ Series is the transport layer, and MRM is the message body parser. These attributes can be categorized as follows:

Properties Model

  1. Physical format of message
  2. Transport layer "Quality of Service"
  3. Reply path information
  4. Publish/subscribe topic

One point to keep in mind is that all fields in a Properties model must be set. If you need to set any single field, for example, MessageFormat to select the output message wire format, also set or copy the other values in the Properties folder. Any fields not explicitly set will not be copied to the output message.

Return to the top.

Mapping Headers

The Headers model provides the ability to map selected headers in addition to the properties. Note that the Headers model doesn't support the "copy all headers" capability: any headers that are not explicitly mapped will not be created as part of the target.

The Headers are categorized as MQMD, MQ, HTTP, and JMS headers. Use the Headers model for JMS, SOAP over JMS, and HTTP scenarios. Use the Headers model for MQ scenarios when the Properties model does not provide the control required.

  1. The MQ grouping includes the MQMD, and MQRFH2 headers. Note that this is the header structure definition; in the runtime a map handles source parsers automatically. For an MQRFH2 target the map dynamically selects the MQRFH2 parser in brokers version 5 and the higher performance MQRFH2C parser in brokers version 6.
    All ESQL downstream of a message map that maps the MQRFH2 header (as opposed to copies it using the copy all headers feature) needs to be configured with the correct parser name for the this header.
  2. The HTTP grouping includes all the standard headers; other HTTP headers are ignored. If you need to process custom HTTP headers you will need to configure an ESQL Compute node to call the map, as described below.
  3. The JMS grouping includes the standard JMS headers. To process custom versions you will need to define the custom JMS header in a message set, and configure an ESQL Compute node to call the map, as described below.
Headers Model

Return to the top.

Creating Multiple Output Messages

The sample files for multiple output message scenarios are located in the multiple_output folder in the Message Map Sample Message Flows project.

The basic rule for creating multiple output messages is to declare, implicitly or explicitly, multiple $target rows. Multiple rows can be implicitly declared using a for row. Using a for row, zero or more output messages will be created, one per source item provided as the for row source. Multiple output messages can also be created by explicitly adding more than one target using the Add Sources and Targets menu. Each such target will create one output message. You can even combine for rows with multiple targets, if each item in a source creates multiple output messages on its own.

There are several scenarios in which it is useful to configure a message map to output multiple messages. Some of these scenarios are:

The message map tools make it easy to generate multiple output messages: all that is required is to specify multiple target message assemblies, or to enclose a target message assembly in a for row.

Return to the top.

Creating Multiple Output Messages for a Repeating Field

The sample files for this scenario are located in the multiple_output folder in the Message Map Sample Message Flows project.

All that is required to create multiple output messages for a repeating source field is to enclose the target message assembly in a for row that operates on the repeating source.

The sample message map repeating_source.msgmap will convert a repeating field in a source message assembly into a stream of message assemblies in the calling message flow. repeating_source.msgmap wraps the $target row in a for row to create multiple output message assemblies, one per repeating input. For each assembly, the Properties folder is copied, which means the copy all headers behaviour is used. Then, in each output message assembly, a single rtl:body is copied.

Batch Repeating

Return to the top.

Creating Multiple Output Messages for a Multipart Input Message

The sample files for this scenario are located in the multipart_messages folder in the Message Map Sample Message Flows project.

As for repeating fields, all that is required to create multiple output messages for a repeating multi-part source message is to enclose the target message assembly in a for row that operates on the repeating multi-part message definition.

The key difference between a multi-part message and a regular repeating field is that a multi-part message is defined by a local content group with open or open-defined content model (a brokers extension to XML Schema), while a repeating field is defined by an element.

Rather than introduce a different message map construct for a multi-part message, the content group is treated as if its content were an XML schema wildcard. Creating a map for an XML Schema wildcard element requires the use of a called submap.

As the sample shows, wildcard elements are mapped through the use of a element specific submap. In effect, the wildcard or "unknown" element is converted to a "known" element by a submap call.

Batch Repeating

Return to the top.

Creating Multiple Output Messages for Non-repeating Input

The sample files for this scenario is nonrepeating_source.msgmap located in folder multiple_output under project Message Map Sample Message Flows.

The technique to produce multiple messages is the same regardless whether the source is repeating or not. In this case, multiple $target rows are explicitly declared by the map. Each declared target row will create an output message. In the repeating scenarios, the multiple assemblies were implicitly declared by the for rows that contained the target assemblies, and created one output assembly per item in the for.

Batch Repeating

Return to the top.

Sorting, Grouping, or Collating Fields in a Message

The sample files for this scenario are located in the sorting folder in the Message Map Sample Message Flows project. There are 2 variations on the theme:

Sorting With Keys Known in Advance

Sorting or grouping when the key values for sorting are known while authoring the map is illustrated by the file sorting.msgmap. Three possible field values are sorted into three separate messages using the Creating multiple output messages for non-repeating input design pattern.

Frequently it is necessary to compute total amounts or record counts after a single message is transformed into multiple messages. This needs to be handled by a second step, in file total.msgmap. Message flow sort.msgflow illustrates how to connect two mapping nodes to achieve this result.

Sorting With Keys From a Database

The sample file is sorting_dynamic.msgmap. This sample is much the same as Sorting with keys known in advance, the crucial difference is the map needs to go to a database to obtain the list of valid keys. The steps in the map are as follows:

As in the previous example, this isn't quite enough to have a correct output message, and the total.msgmap map will again need to be called to compute the totals per output message.

Return to the top.

Calling a Map from ESQL

The sample files are in folder esql_calling_msgmap in project Message Map Sample Message Flows.

The sample shows how to call a map from ESQL. Our expectation is that users will call submaps rather than main maps. A submap is any message map that is intended to be called from another map or from ESQL. You create a submap in the New Message Map Wizard (File>New>Message Map) by selecting the This map is called from another map... radio button:

Creating a submap in the New Message Map wizard

The expected ESQL signature for calling a submap is:

	submapName(
		sourcePath1, [sourcePath2, [...]]
		[targetPath, ]
		InputLocalEnvironment [, OutputLocalEnvironment])
	

At least one sourcePath parameter is always present; this represents the messaging input that is driving the message flow node. sourcePaths are ESQL REFERENCE variables that are initialized to reference the source tree node before calling the message map.

targetPath is an optional ESQL REFERENCE variable that references the target root tree node. It must be initialized before calling the message map. targetPath is optional, and if a message map has no target parameter then the map will not create any messaging output. This is used for message to relational database scenarios, where maps are called from ESQL Database nodes.

InputLocalEnvironment and OutputLocalEnvironment are ESQL REFERENCE variables initialized to the associated ESQL node correlation names. Message maps are implemented as schema-scope procedures, so they can't access the correlation names directly.

The sample code initializes the required parameters, and calls the map.

Return to the top.

Using a Message Map in an Aggregate Scenario

The sample files are in folder esql_calling_msgmap in project Message Map Sample Message Flows.

The basic pattern of ESQL calling a map has been implemented. The ESQL MODULE code has been written to initialize the Properties and Headers folders, create the necessary references, and call the map.

The map constructs a single output message from all the Aggregate node folders (Request1, Request2, etc). Since the ESQL MODULE took care of the properties and headers, all that's left to do is to copy the contents of the LocalEnvironment.Aggregate.AgregateRequestFolderName to the output message.

Return to the top.

XML Schema Scenarios

These sample scenarios show the design pattern for transforming XML Schema models that use wildcards, type extensions and restrictions, substitution groups, and content model groups in a message map.

Return to the top.

Wildcard Elements

The sample files for processing wildcard elements and attributes are located in the multipart_messages folder in the Message Map Sample Message Flows project.

Wildcard elements are handled by calling a submap. In the submap, the name of the element is hard-coded. To process different element names from the same wildcard, use if, condition, and else rows.

The sample implements a simple repeating field scenario, but in the slightly more complex case where the repeating source is modeled as a brokers multipart message. The multipart-message is handled as a wildcard element by the map tools. Wildcards are handled by calling a submap for the correct element name.

In the first map, the target message assembly is contained in a for row. The for row operates over the repeating multipart message contained by the single source message. The containment of the target assembly in the for row means complete target message assemblies will be output, one per input multipart message in the source. The first message map also contains a mapping for the wildcard message that supports multipart messages. This mapping calls a submap, that must return a complete definition of the element that the wildcard represents.

Multipart Envelope Message

In the second map, we see that the wildcard message element has been constrained to be an rtl:body element. In this submap, the source and target are the same, and the source is deep-copied to create the target.

Multipart Contained Message

Return to the top.

Type inheritance

The sample file for this scenario is type_to_substitutiongroup.msgmap located in the xmlschema folder in the Message Map Sample Message Flows project.

In the message map editor, special source and target tree 'folders' are used to show the valid type combinations. The name of the folder is specializations for base type. Inside the folder are shown the elements combined with every non-abstract derivation from the base type. Each of these concrete element representations contains its full content; with all the possible attributes followed by all the valid elements. Essentially, the tree shows the different XML elements that the XML schema model describes.

In the sample message map, the source is described using an XML Schema model that allows extensionType1 and extensionType2 alternatives. Each of these alternatives can be mapped individually to the target.

Type extension hierarchies can be combined with choice models, substitution groups, etc., though the sample avoids this complexity.

Return to the top.

Substitution groups

The sample file for this scenario is type_to_substitutiongroup.msgmap located in the xmlschema folder in the Message Map Sample Message Flows project.

In the message map editor, special source and target tree 'folders' are used to show the valid elements using the substitution group combinations. The name of the folder is substitutions for head element. Inside the folder are shown the different element names combined with every non-abstract derivation to the base type. Each of these concrete element representations contains its full content; with all the possible attributes followed by all the valid elements. Essentially, the tree shows the different XML elements that the XML schema model describes.

In the sample message map, the target is described using an XML Schema model that allows Substitute1 and Substitute2 alternatives to the abstract HeadElement element. Each of these alternatives can be mapped individually to the source.

Substitution groups can be combined with type hierarchies, though the sample avoids this complexity.

Return to the top.

Repeating Model Groups

The sample files for this scenario are located in the modelgroups folder in the Message Map Sample Message Flows project.

Return to the top.

Back to sample home