Choosing message assembly components to include in a message map

You can add the message tree components, that is, the Properties tree, the headers, and the message body into a message map. You can also add the local environment tree into a message map, and the Environment tree.

About this task

In IBM® Integration Bus, the logical tree structure is the internal representation of a message. The logical tree structure is created by the parser when the message is received by an input node. It is also known as the Message tree and makes up part of the message assembly. The message assembly consists of four trees:
  • Message tree: This tree includes the Properties folder, the message body, and headers.
  • Environment tree
  • Local environment tree: This tree includes multiple destination folders, and a variables folder.
  • Exception list tree

When you create a message map, the Properties folder and the message body are automatically included in your Graphical Data Mapping editor.

Note: You can remove the properties folder and the message body in the message map if you only want to modify the local environment tree. This will accelerate your message transformation since the message properties and the message body will be copied over without the need to bring them into the transformation engine.

You cannot add the exception list tree to the message map. The exception list is included automatically, and the entire contents of the input exception list is retained in the output.

Procedure

Choose one or more message assembly components to include in a message map:

  • Header folders: You can add one or more headers to a message map, in addition to the Properties folder and the message body.

    When an input message is received by an input node, the input node invokes the correct parser for each header, and includes in the message tree the corresponding headers. You can then access these headers by using message maps.

    The message tree always includes the following components:
    • All the headers that are present in the message.
    • The message body.
    • The Properties folder. The Properties folder (sometimes referred as the Properties tree) is the first element of the message tree and holds information about the characteristics of the message. When the input node receives the input message, it creates and completes the Properties folder.

    If you need to access information available in an element of a header or if you need to modify it, then you must add the header to the message map. For more information, see Mapping transport headers.

  • Local environment tree: You can add the local environment tree to the message map. The local environment is divided into two parts:
    • Standard folders that are automatically defined for each of the destination folders available in IBM Integration Bus.
    • A variables folder that is added automatically. You can use the Cast function to include a variable into your message map. You can add variables by using the Add User Defined function.

    The local environment tree stores variables that can be referred to and updated by message processing nodes that occur later in the message flow.

    You can also use the local environment tree to define where a message is sent. The destination can be internal or external to the message flow.

    IBM Integration Bus also stores information in the local environment tree in some circumstances, and references it to access destination values that you might have set.

    If you need to access information available in an element of the variables folder or if you need to modify a variable, then you must add each individual variable to the message map. For more information, see Configuring a generic type in the local environment tree by using the Cast function.

  • You can add the environment tree to the input message assembly of the message map.

    If you do not include the environment tree in the input message assembly, the entire contents of the environment tree are retained in the output.

    If you add the environment tree, you can define both its content and structure by using the Add User Defined function.

    Note: The environment tree differs from the local environment tree in that a single instance of it is maintained throughout the message flow.

Results

The following table summarizes the message assembly tree folders that you can include into your message map:
Table 1. Message assembly trees that can be included in a message map
Message assembly trees Folders in a message assembly tree Can be configured in a message map as an input to the map and as an output to the map? Status in a message map
Message tree Properties folder Yes Required
Message tree Header folders Yes Optional
Message tree Message body Yes
Note: You must cast parts of the SOAP message body to be able to define transforms between its input and output elements.
 Required
Local environment tree Variables folder Yes (You must cast a variable to define transforms between its input and output elements.) Optional
Local environment tree Destination folders Yes Optional
Environment tree   Yes Optional
Exception list tree   No  

What to do next

Identify the configuration of the different message assembly components. For more information, see Choosing a mapping action.