Mapping data in the local environment tree

Use the Graphical Data Mapping editor to transform data graphically in the local environment tree.

Before you begin

Create a message map. For more information, see Creating a message map.

About this task

The local environment tree is a part of the logical message tree in which you can store information while the message flow processes the message. You use the local environment tree to store 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 destinations (that are internal or external to the message flow) to which a message is sent.

When you add the local environment tree to a message map, you must provide transforms for all of its elements so that the input values of each element are not lost. You can copy the input field unchanged or modified by a transform. Many IBM Integration Bus nodes depend on information in the local environment tree being copied along the message flow.

The variables folder in the local environment tree is defined as xsd:any. When you add the local environment tree, you can see the structure of the destination folders with all its elements, and a Variables folder with a single element defined with a generic type.

This figure shows graphically how the variables folder is defined with type any.

You manually define the elements that are included in the Variables folder by using the Cast or Add User Defined functions. There is no predefined structure for the Variables folder. Each message flow node has an input and an output local environment tree. There is a Variables folder in the input local environment tree and a Variables folder in the output local environment tree.
Note: You should not access attributes or other non-element field types in the local environment tree. The data in the local environment tree is stored by using a generic parser and does not have specific field types set, (see XMLNSC: Using field types). In particular, if you copy data from an XMLNSC tree into the local environment tree, the field type that defines the element or attribute type is not preserved. If you model the data to be an attribute, the map attempts to access the data by using an XPath expression that matches data elements that have the field type that is specified in the XMLNSC tree, and so the data is not read.

When you create a top level message map, only the Properties folder is initially included in the map, and a default transformation from input to output properties is created in a local map.

You can then use the Message Assembly properties page in the Graphical Data Mapping editor to modify the message assembly components transformed in the map and include the local environment folders in the mapping. For more information, see Customizing a message map to include a message assembly component.

Procedure

Complete the following steps to transform data in the local environment tree by using a message map:

  1. Decide whether you need the local environment tree in the input message assembly, the output message assembly, or both. You may want to copy, initialize, or modify LocalEnvironment elements. For more information, see Choosing a mapping action.
    Note: The Mapping node copies the LocalEnvironment tree from input to output, unchanged, when they are not included in the message map.
  2. Add the local environment to the input message assembly, the output message assembly, or both. For more information, see Customizing a message map to include a message assembly component.
  3. Optional: Define a Move transform between the input local environment tree and the output local environment tree to copy all the input values onto the output values. Create a connection between the input local environment tree and the output local environment tree.
    Note: If you need to modify only some fields in the local environment tree, you can use a Move transform to copy the local environment tree unchanged, and then use the Override function to modify the elements you must update. For more information, see Applying mapping overrides.

    You can do this in any of the following ways:

    • In the message map, right-click LocalEnvironment on the input message assembly, and select Add Connection. Move the mouse to the output local environment tree, and click LocalEnvironment to define the Move transform.
    • In the message map, right-click LocalEnvironment on the input message assembly, and select Quick Link. A new window appears where you can select the output element LocalEnvironment. Use this option when you have a long list of output elements. You can filter the list in Quick link too.

    The following figure shows graphically how the Move transform is defined between the input local environment tree and the output local environment tree.

    This figure shows graphically how the Move transform is defined between the input local environment tree and the output local environment tree.

  4. Optional: Define the Variables folder in the local environment tree. The Variables folder contains an xsd:any element, that you can redefine by using a Cast function and a schema file describing the variables. Alternatively, you can use the Add User Defined function to define dynamically the variables that you require in the message map.
  5. Define transforms between the input local environment tree and the output local environment tree. For more information, see Specifying a transform (mapping operation) and Transform types in the Graphical Data Mapping editor.

    You must provide transforms to copy or modify all fields that are required on the output. Many message flow nodes depend on information in LocalEnvironment being copied along the message flow. If you need to modify only some fields, use a Move transform to copy LocalEnvironment and then use the Override function to modify the elements you must update. For more information, see Applying mapping overrides.