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.
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.
A WebSphere Message Broker message assembly includes four items, that are numbered in the picture:
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.
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.
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 condition
s and an
else
:
In this sample:
$source/rtl:body/content
equal to zero
will be processed by flow nodes downstream from Label node
Target1;$source/rtl:body/content
greater than
zero will be processed by flow nodes downstream from Label node Target2;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.
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:
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.
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.
Compute
node to call
the map, as described below.Compute
node to
call the map, as described below.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:
In this scenario, a single message is transformed into different messages targeting different enterprise information systems or otherwise contains multiple repeating fields that are best processed individually;
A multipart message is a message modeled using the brokers multipart message capability, that allows messages in different wire formats or even different dictionaries to be combined in a single batch message.
A source message contains data that needs to be transformed into separate messages for multiple EIS systems. Individual, not-repeating fields need to be combined to create multiple output messages;
A source message contains a repeating field (perhaps an invoice) that needs to be transformed into multiple output messages based on a value in the field (perhaps a trading partner identifier).
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.
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.
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.
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
.
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 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.
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:
$db:select
row is used to obtain the list of
keys from a database.for
row processes each item from
$db:select
in turn. for
row is another
for
row, this time choosing each record in the
source in turn.if
row and a condition
row filter the two for
rows, so that only rows
for which the keys match produce an output message.$target
row creates the output
messages, one per unique key value that is in both the database and
the source message.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.
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:
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.
sourcePath
s 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.
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.
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.
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.
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.
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.
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.
The sample files for this scenario are located in the modelgroups folder in the Message Map Sample Message Flows project.