Mapping the environment tree

In a message map, you can update, delete, or create data in the environment tree Variables folder. You can use the environment tree as input data to your transformations.

About this task

The environment tree is a single global set of data that is available to all nodes in a message flow. The Mapping node accesses the single instance of the environment tree at both the input and output side of the map.

The Graphical Data Mapping editor displays the environment tree by showing the same component on the input and in the output connected via a banner to highlight the fact that it is a single global object.

This figure shows how the environment tree is represented in a message map.

In the Graphical Data Mapping editor, you can add the environment tree to the input message assembly of a message map or to the output message assembly of a message map.
  • When you add the environment tree to the input message assembly, you automatically get the environment tree included in the output message assembly.
  • When you add the environment tree to the output message assembly, you automatically get the environment tree included in the input message assembly.
  • When you define the content of the environment tree, changes are automatically applied to both the input and the output message assembly.

To add the environment tree, select the icon This figure shows the add environment tree icon. in the Graphical Data Mapping editor toolbar.

Add environment tree icon in the Graphical Data Mapping editor toolbar.

Alternatively, you can right-click anywhere in the map and select Add environment mapping.

To remove the environment tree, select the icon This figure shows the add environment tree icon. in the Graphical Data Mapping editor toolbar. Alternatively, you can right-click anywhere in the map and select Remove environment mapping.

Note: When you use the environment tree in your integration solutions, you should create your own information in the provided folder called Variables.

You define the structure of the environment tree by using the Add User-Defined function or the Cast function. For more information, see Adding and renaming a user-defined element or Casting elements in a message map.

The following rules apply when you map the environment tree in the Graphical Data Mapping editor:
  • If you do not include the environment tree in your message map, the entire contents of the environment tree are retained unchanged.
  • If you only need to read and update the environment tree, you define a map that only contains the Environment tree.
  • If you only need to read from the input assembly and update the environment tree, you define a map that includes the input message assembly and the environment tree.
  • If you only need to read from the environment tree and build a new output message, you define a map that includes the output message assembly and the environment tree. You can optionally update the environment tree.
  • If you have multiple output message assemblies, or the output message assembly is propagated multiple times, for example when you split an input message with a repeating structure into multiple messages, the environment tree will only be mapped once.
  • You cannot wire an output message assembly and the environment tree to a transform that allows multiple outputs, that is, an If transform, a For each transform, and any of the database transforms. When you need to populate both Environment and the output message assembly, you must have two instances of the transform.

When you add for the first time the environment tree in your message map, the entire contents of the environment tree are retained unchanged. This is indicated visually in the banner with the word Transferred located between the input and the output environment structures.

If you include the environment tree in your message map, then the entire contents of the input environment tree are retained in the output environment tree, subject to any modifications that you make in the map.
  • Any element present in the environment tree that is not transformed in the map remains unmodified.
    Note: Yon only need to define the elements that you need to map to or from the environment tree. All other elements that might be present in environment tree will remain and be transferred unmodified by the map. You can use the Remove transform to delete data from the environment tree.
  • When you add transformations that modify the environment tree, there will be a visual change to indicate that the environment tree will be updated after being transferred. As soon as you modify an element in the environment tree, the word Transferred changes to Updates.

    This figure shows how the environment tree changes from status Transferred to status Updates in a message map.

  • When you define a transform to modify an element in the environment tree, the value of the input element is not transferred. The outcome of the transform determines the existence, state, and content of the element in the environment tree output element.
Note: For each element in the environment tree, you cannot have different transforms that use the element as a both a source and a target.

Procedure

You can complete any of the following mapping tasks when you add the environment tree to a message map:

  1. Use Environment elements to define conditional expressions that determine if a transform can be applied. For more information, see Defining an XPath conditional expression for a transform.
  2. Use the value of elements defined in the Variables folder of the environment tree to calculate or set the value of an output message element. Use the value of elements from other parts of the message to calculate the value of an environment tree element.
    • Use the Assign transform to set a fixed value without the use of input data.
    • Use the Create transform to create an empty element, or a nil element without the use of input data.
    • Use the Move transform to copy an input element value to the output element.
    • Use the If transform, a custom transform, or the XPath transform to define the condition that determines the value of an output element.
    • Use the Append transform, the Group transform, the ForEach transform, the Join transform, a custom transform, or the XPath transform to set the value of a repeating element.
    • Use the Select transform or the Database Routine transform to set the value with data available in a database system.
    • Use the xs:type transforms to cast the value of a simple input element to a specific data type.
    • Use the fn:type transforms to set the value by using XPATH 2.0 functions.

    In the same map, you cannot access and update an element in the environment tree. For example, you cannot define a Move transform and an Assign transform to the same environment element in a map. Maps do not allow you to control the order of transforms. In this example, you cannot control whether the access or the update of the element occurred first. You will get an error if you access and update an element in the environment tree in the same map.

    Note: You can define a custom transform, Custom XPath, Custom Java, or Custom ESQL, to read the value of an environment element, and then increment its value. The Graphical Data Mapping editor reads the environment variable first, and then updates its value. For example, you can use it to implement a counter action.
    The following transforms are not permitted in environment tree mappings:
    • Local Map transform.
    • Submap transform.

    When you use a Custom ESQL transform or a Custom Java transform to modify the environment tree in a message map, check that the transform does not make modifications to environment data that might conflict with other transforms in the map.

    If you use a mapping to add a child to a complex element which already exists in the environment tree, it will be added as the last child.

    If you wish to modify a child element of an existing repeating parent, you should iterate over each parent using the ForEach transform, and include child mappings.

    If you need to read and update an element of the Environment tree, you must use two sequential Mapping nodes.

  3. Use the value of elements defined in the Variables folder of the environment tree to insert, update, or delete data in a database. You can also use the value of an environment element in the definition of a Where clause of a Select transform.
    • Use the transform Insert to add new data to one or more tables in a database.
    • Use the transform Delete to delete data in one or more tables in a database.
    • Use the transform Update to update data in one or more tables in a database.
    • Use the Database Routine transform to update, insert, or delete data in a database by using stored procedures.
  4. Use the Remove transform to remove elements from the environment tree.

    You do not need to define a Move transform between the input and the output environment structures, data will be retained. If you want to remove data from the environment tree, you can use the Remove transform. For more information, see Remove.

What to do next

Define transforms in the message map to set the value of the output elements. For more information, see Specifying a transform (mapping operation).