Mapping node

This topic contains the following sections:

Purpose

Use the Mapping node to construct one or more new messages and populate them with new information, with modified information from the input message, or with information taken from a database. You can modify elements of the message body data, its associated environment, and its exception list.

When you first open or create a message map for the node, if you specify the option This map is called from a message flow node and maps properties and message body, the headers in the input message are always copied to the output message without modification.

If you want to modify the message headers in a Mapping node, you must select the option This map is called from a message flow node and maps properties, headers, and message body. When you do this, the map that is created allows additional elements, including MQ, HTTP, and JMS headers, to be mapped.

These 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 associated with this node in the mapping file associated with this node by mapping inputs (message or database) to outputs. You can optionally 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.

Use the Mapping node to:

  • Build a new message
  • Copy messages between parsers
  • Transform a message from one format to another

The Mapping node is represented in the workbench by the following icon:

Mapping node icon

Using this node in a message flow

Look at the following sample to see how you can use this node:

Configuring the Mapping node

When you have put an instance of the Mapping node into a message flow, you can configure it. Right-click the node in the editor view and click Properties. The node's basic properties are displayed.

All mandatory properties for which you must enter a value (those that do not have a default value defined) are marked with an asterisk on the properties dialog.

Configure the Mapping node as follows:

  1. Specify in Data Source the name by which the appropriate database is known on the system on which this message flow is to execute. The broker connects to this database with user ID and password information that you have specified on the mqsicreatebroker, mqsichangebroker, or mqsisetdbparms command.

    On z/OS systems, the broker uses the broker started task ID, or the user ID and password that were specified on the mqsisetdbparms command JCL, BIPSDBP in the customization data set <hlq>.SBIPPROC.

  2. Select the Transaction setting from the drop-down menu. The values are:
    • Automatic (the default). 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.
    • Commit. If you want to commit any uncommitted actions performed in this message flow on the database connected to this node, irrespective of the success or failure of the message flow as a whole, select Commit. The changes to the database are committed even if the message flow fails.
  3. In Mapping Routine, identify the mapping routine that is to be executed in this node. By default, the name assigned to the mapping routine is identical to the name of the mappings file in which the routine is defined. The default name for the file is the name of the message flow concatenated with the name of the node when you include it in the message flow (for example, MFlow1_Mapping.mfmap for the first Mapping node in message flow MFlow1). You cannot specify a value that includes spaces.

    If you click Browse next to this entry field, a dialog is displayed that lists all available mapping routines accessible by this node. Select the routine that you want and click OK. The routine name is set in Mapping Module.

    To work with the mapping routine associated with this node, right-click the node and select Open Mappings. If the mapping routine does not exist, it is created for you with the default name in the default file. If the file already exists, you can also open file <flow_name>_<node_name>.mfmap in the Navigator view.

    A mapping routine is specific to the type of node with which it is associated; you cannot use a mapping routine that you have developed for a Mapping node with any other node that uses mappings (for example, a DataInsert node). 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 Developing message mappings.

  4. In Mapping Mode, specify the mode that you want to use to process information being passed through the Mapping node. You can choose any combination of Message, LocalEnvironment, and Exception components to be generated and modified by the Mapping node.

    You must set this property to correctly reflect the output message format that you require. If you select an option (or accept the default value) that does not include a particular component of the message, that component is not included in any output message that is constructed.

    (In releases prior to Version 2.1, the associated environment (LocalEnvironment) was known as DestinationList. DestinationList is valid and can be used for compatibility.)

    (The Environment component of the message tree is not affected by the mode setting. Its contents, if any, are passed on from this node.)

    The options are explained in the table below.

    Mode Description
    Message (the default) The message is generated or passed through by the Mapping node as modified within the node.
    LocalEnvironment The LocalEnvironment tree structure is generated or passed through by the Mapping node as modified within the node.
    LocalEnvironment And Message The LocalEnvironment tree structure and message are generated or passed through by the Mapping node as modified by the node.
    Exception The Exception List is generated or passed through by the Mapping node as modified by the node.
    Exception And Message The Exception List and message are generated or passed through by the Mapping node as modified by the node.
    Exception and LocalEnvironment The Exception List and LocalEnvironment tree structure are generated or passed through by the Mapping node as modified by the node.
    All The message, Exception List, and LocalEnvironment are generated or passed through by the Mapping node as modified by the node.
  5. Select Basic in the properties dialog navigator and set or clear the two check boxes:
    • If you want database warning messages to be treated as errors and want the node to propagate the output message to the failure terminal, select the Treat Warnings as Errors check box. The box is initially cleared.

      When you select the box, the node handles all positive return codes from the database as errors and generates exceptions in the same way as it does for the negative, or more serious, errors.

      If you do not select the box, the node treats warnings as normal return codes, and does not raise any exceptions. The most significant warning raised is not found, which can be handled as a normal return code safely in most circumstances.

    • If you want the broker to generate an exception when a database error is detected, select the Throw Exception on Database Error check box. The box is initially selected.

      If you clear the box, you must handle the error in the message flow to ensure the integrity of the broker and the database: the error is ignored if you do not handle it through your own processing, because you have chosen not to invoke the default error handling by the broker. For example, you could connect the failure terminal to an error processing subroutine.

  6. Select Validation in the properties dialog navigator if you want the MRM parser to validate the body of messages against the dictionary generated from the message set. (If a message is propagated to the failure terminal of the node, it is not validated.)

    For more details refer to Validating messages and Validation properties for messages in the MRM domain.

  7. Select General Message Options in the properties dialog navigator. Parse Timing is, by default, set to On Demand. This causes validation to be delayed until it is parsed by partial parsing. If you change this to Immediate, partial parsing is overridden and everything in the message is parsed and validated, except those complex types with a Composition of Choice or Message that cannot be resolved at the time. If you change this to Complete, partial parsing is overridden and everything in the message is parsed and validated; complex types with a Composition of Choice or Message that cannot be resolved at the time cause a validation failure.

    Select the Use MQRFH2C Compact Parser for MQRFH2 Domain check box if you want the MQRFH2C Compact Parser to be used instead of the MQRFH2 parser for MQRFH2 headers.

  8. Select the XMLNSCparser options in the properties dialog navigator and select the Use XMLNSC Compact Parser for XMLNS Domain check box if you want to use the XMLNSC parser for messages in the XMLNS Domain.

    Other properties control whether the XMLNSC parser is used for mixed text, comments and processing instructions in the input message.

  9. Select Description in the properties dialog navigator to enter a short description, a long description, or both.
  10. Click Apply to make the changes to the Mapping node without closing the properties dialog. Click OK to apply the changes and close the properties dialog.

    Click Cancel to close the dialog and discard all the changes that you have made to the properties.

Terminals and properties

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 outputs the message following the execution of the mappings.

The following tables describe the node properties; the column headed M indicates whether the property is mandatory (marked with an asterisk on the properties dialog 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 Basic properties are described in the following table.

Property M C Default Description
Data Source No Yes   The ODBC data source name of the database in which reside the tables to which you refer in the mappings associated with this node (identified by the Mapping Module property).
Transaction Yes No Automatic The transaction mode for the node. Valid values are Automatic or Commit.
Mapping Routine Yes No Mapping The name of the mapping routine that contains the statements to execute against the database or the message tree. The routine is unique to this type of node.
Mapping Mode Yes No Message Select one of the following:
  • Message
  • LocalEnvironment
  • LocalEnvironment And Message
  • Exception
  • Exception And Message
  • Exception And LocalEnvironment
  • All
If you want to construct a map that propagates multiple target messages, set this property to Local Environment and Message to ensure the node executes correctly.
Treat Warnings as Errors Yes No Cleared Treat database SQL warnings as errors. If you select the check box, this action is performed.
Throw Exception on Database Error Yes No Selected Database errors cause the broker to throw an exception. If you select the check box, this action is performed.

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

Property M C Default Description
Validate Yes Yes None Whether validation takes place. Valid values are None, Content and Value, Content, and Inherit.
Failure Action Yes No Exception 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.
Include All Value Constraints Yes No Selected This property cannot be edited. The default action, indicated by the check box being selected, is that all value constraints are included in the validation.
Fix Yes No None This property cannot be edited. Minimal fixing is provided. Valid values are None, and Full.

The properties of the General Message Options for the Mapping node are described in the following table:

Property M C Default Description
Parse Timing Yes No On Demand This property controls when an input message is parsed. Valid values are On Demand, Immediate, and Complete.

Refer to Parsing on demand for a full description of this property.

Use MQRFH2C Compact Parser for MQRFH2 Domain No No False This property controls whether the MQRFH2C Compact Parser, instead of the MQRFH2 parser, is used for MQRFH2 headers.

The XMLNSC parser options for the Mapping node are described in the following table.

Property M C Default Description
Use XMLNSC Compact Parser for XMLNS Domain Yes Cleared No Start of changeSetting this property causes the outgoing MQRFH2 to specify the XMLNS instead of XMLNSC parser, allowing an external application to remain unchanged. If outgoing messages do not contain MQRFH2 headers this property has no effect.End of change
Mixed Content Retain Mode Yes No None This property controls whether the XMLNSC parser creates elements in the message tree when it encounters mixed text in an input message. Valid values are None and All. Selecting All means that elements are created for mixed text. Selecting None means that mixed text is ignored and no elements are created.
Comments Retain Mode Yes No None This property controls whether the XMLNSC parser creates elements in the message tree when it encounters comments in an input message. Valid values are None and All. Selecting All means that elements are created for comments. Selecting None means that comments are ignored and no elements are created.
Processing Instructions Retain Mode Yes No None This property controls whether the XMLNSC parser creates elements in the message tree when it encounters processing instructions in an input message. Valid values are None and All. Selecting All means that elements are created for processing instructions. Selecting None means that processing instructions are ignored and no elements are created.

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

Property M C Default Description
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.