Mapping node

Use the Mapping node to graphically construct one or more new messages and populate them with various types of information, to transform messages, to route messages, or to modify database records.

The Mapping node is available in the following operation modes:

Developer
Application Integration Suite
Standard
Advanced
Express
Scale

For more information, see Operation modes.

This topic contains the following sections:

Purpose

Use the Mapping node to complete the following actions:

Build a new message
Copy messages between parsers
Transform a message from one format to another
Route messages
Modify database content

Overview

The Mapping node is contained in the Transformation drawer of the palette, and is represented in the IBM® Integration Toolkit by the following icon:

The Mapping node requires a message map. The message map can be in the same container as Mapping node (such as an application), or it can be in a referenced shared library. If multiple solutions are likely to use the same message map, store the map in a shared library.

When you create a message map for the node, the map can contain message and database tables as inputs and outputs. Properties, and optionally headers (WebSphere® MQ, HTTP, and JMS headers) and the local environment tree can also be mapped.

The components of the output message can be defined using mappings that are based on elements of both the input message and data from an external database. You create the mappings that are associated with this node, in the mapping file that is associated with this node, by mapping inputs (message or database) to outputs. You can modify the assignments made by these mappings using supplied or user-defined functions and procedures; for example, you can convert a string value to uppercase when you assign it to the message output field.

By using a Mapping node, you can modify elements of the message body data, the local environment tree and the properties folder.

The Mapping node passes through the exception list tree of the input message unchanged.

You can populate the new messages with the following types of information:

New information
Modified information from the input message
Information taken from a database

The Mapping node supports a local environment override for the mapping script, which enables you to dynamically select the map that will be run. The map name that is specified in the input message is used in place of the one that is set in the Mapping node. The override is in the following format:

SET OutputLocalEnvironment.Mapping.MappingRoutine = '{brokerSchemaName}:mapName';

For example:

SET OutputLocalEnvironment.Mapping.MappingRoutine = '{default}:mapperFlow_poNode';

where mapperFlow_poNode.map is in the default Broker schema.

If you store your message map file in a shared library, the override has the following format:

SET OutputLocalEnvironment.Mapping.MappingRoutine='{{mbsharedlib:sharedLibraryName}brokerSchemaName}:mapName';

For example:

SET OutputLocalEnvironment.Mapping.MappingRoutine='{{mbsharedlib:shlib1}default}:mapperFlow_poNode';

Terminals and properties

When you have put an instance of the Mapping node into a message flow, you can configure it; see Configuring a message flow node. The properties of the node are displayed in the Properties view. All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk.

The Mapping node terminals are described in the following table.

Terminal	Description
In	The input terminal that accepts a message for processing by the node.
Failure	The output terminal to which the input message is propagated if a failure is detected during the computation. If you have selected Treat Warnings as Errors, the node propagates the message to this terminal if database warning messages are returned, even though the processing might have completed successfully.
Out	The output terminal that propagates the message following completion of the mappings.

The following tables describe the Mapping node properties.

The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined).
The column headed C indicates whether the property is configurable (you can change the value when you add the message flow to the BAR file to deploy it).

The Mapping node Description properties are described in the following table.

Property	M	C	Default	Description
Node name	No	No	The node type	The name of the node.
Short Description	No	No		A brief description of the node.
Long Description	No	No		Text that describes the purpose of the node in the message flow.

The Mapping node Basic properties are described in the following table.

Property M C Default Description mqsiapplybaroverride command property

Transaction

Yes

Property	M	C	Default	Description	mqsiapplybaroverride command property
Transaction	Yes	No	Automatic	The transaction mode for the node. The supported value for the node is Automatic. The message flow, of which the Mapping node is a part, is committed if it is successful; that is, the actions that you define in the mappings are performed and the message continues through the message flow. If the message flow fails, it is rolled back. If you choose Automatic, the ability to commit or rollback the action of the Mapping node on the database depends on the success or failure of the entire message flow.
Mapping Routine	Yes	No	Mapping	The name and location of the mapping routine that contains the statements to execute against the database or the message tree. By default, the name that is assigned to the mapping routine is: `{default_broker_schema}:default_map_file name with no extension` Where `default_broker_schema` is the broker schema where the message flow file is located, and where `default_map_file_name_with_no_extension` is the name of the message flow, concatenated with the name of the mapping node. For example, `{your.broker.schema}:yourFlowName1_yourNodeName1`. Note that you cannot specify a value that includes spaces. If you store the map file in a shared library, the name of that shared library is specified; for example: `{your.broker.schema}:yourFlowName1_yourNodeName1 in Shared Library sharedLibraryName` If you click Browse next to this entry field, a dialog box is displayed that lists all available mapping routines that this node can access. Select the routine that you want and click OK; the routine name is set in the Mapping Routine property. This property can be overridden dynamically by setting a mapping route in the local environment. See Dynamically selecting a message map. To work with the mapping routine that is associated with this node, double-click the node, or right-click the node and click Open Map. If the mapping routine does not exist, the New Message Map wizard opens, with some default values entered. If the mapping routine already exists, it is opened in the Graphical Mapping editor. You can also open the mapping routine in the Application Development view, and double-click it to open the routine in the Graphical Mapping editor. If you create a mapping routine, you cannot call it from any other mapping routine, although you can call it from an ESQL routine. For more information about working with mapping files, and defining their content, see Using message maps.

Automatic

The transaction mode for the node. The supported value for the node is Automatic.

The message flow, of which the Mapping node is a part, is committed if it is successful; that is, the actions that you define in the mappings are performed and the message continues through the message flow. If the message flow fails, it is rolled back. If you choose Automatic, the ability to commit or rollback the action of the Mapping node on the database depends on the success or failure of the entire message flow.

Mapping Routine

Yes

Mapping

The name and location of the mapping routine that contains the statements to execute against the database or the message tree. By default, the name that is assigned to the mapping routine is:

{default_broker_schema}:default_map_file name with no extension

Where default_broker_schema is the broker schema where the message flow file is located, and where default_map_file_name_with_no_extension is the name of the message flow, concatenated with the name of the mapping node. For example, {your.broker.schema}:yourFlowName1_yourNodeName1. Note that you cannot specify a value that includes spaces.

If you store the map file in a shared library, the name of that shared library is specified; for example:

{your.broker.schema}:yourFlowName1_yourNodeName1 in Shared Library sharedLibraryName

If you click Browse next to this entry field, a dialog box is displayed that lists all available mapping routines that this node can access. Select the routine that you want and click OK; the routine name is set in the Mapping Routine property. This property can be overridden dynamically by setting a mapping route in the local environment. See Dynamically selecting a message map.

To work with the mapping routine that is associated with this node, double-click the node, or right-click the node and click Open Map. If the mapping routine does not exist, the New Message Map wizard opens, with some default values entered. If the mapping routine already exists, it is opened in the Graphical Mapping editor. You can also open the mapping routine in the Application Development view, and double-click it to open the routine in the Graphical Mapping editor.

If you create a mapping routine, you cannot call it from any other mapping routine, although you can call it from an ESQL routine.

For more information about working with mapping files, and defining their content, see Using message maps.

You can configure the Validation properties in a Mapping node for the output messages. These properties are acted upon when the message is serialized, that is, when the logical tree representing the message is formatted into its physical bitstream format.

These properties do not cause the input message to be validated. It is expected that, if such validation is required, the validation has already been performed by the input node or a preceding validation node. For more details about validating messages and validation properties, see Validating messages and Validation properties.

The Validation properties of the Mapping node are described in the following table:

Property	M	C	Default	Description
Validate	No	Yes	None	This property controls whether validation takes place. Valid values are None, Content and Value, Content, and Inherit.
Failure Action	No	No	Exception	This property controls what happens if a validation failure occurs. You can set this property only if Validate is set to Content or Content and Value. Valid values are User Trace, Local Error Log, Exception, and Exception List.

If a message is propagated to the Failure terminal of the node, it is not validated.