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.
- 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 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 in the Graphical Data Mapping editor toolbar. Alternatively, you can right-click anywhere in the map and select Remove environment mapping.
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.
- 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.
- 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.
- 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.
Procedure
You can complete any of the following mapping tasks when you add the environment tree to a message map:
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).