Scope and Context of Variables
Every variable has a compute-when input item (see screenshot below), which allows you to control the scope of the variable. This means that you can control when and how often the variable value is computed when the mapping is executed. You do not have to connect this input in many cases, but it can be essential to override the default context or to optimize the mapping performance.
The following terms are relevant to the discussion of the scope and context of variables: subtree and variable value. A subtree is a set of an item/node in a target component and all of its descendants: for example, a <Person> element with its <FirstName> and <LastName> child elements.
A variable value is the data that is available at the output side of the variable component.
•For simple variables, it is a sequence of atomic values that have the datatype specified in the component properties.
•For complex variables, it is a sequence of root nodes (of the type specified in the component properties), each one including all its descendant nodes.
The sequence of atomic values (or nodes) may contain one or even zero elements. This depends on what is connected to the input side of the variable, and to any parent items in the source and target components.
Compute-when is not connected (default)
If the compute-when input item is not connected to an output node of a source component, the variable value is computed whenever it is first used in a target subtree directly via a connector from the variable component to a node in the target component or indirectly via functions. The same variable value is also used for all target child nodes inside the subtree.
The actual variable value depends on any connections between parent items of the source and target components. This default behavior is the same as that of complex outputs of regular user-defined functions and Web service function calls. If the variable output is connected to multiple unrelated target nodes, the variable value is computed separately for each of them. This can produce different results in each case, because different parent connections influence the context in which the variable's value is evaluated.
Compute-when is connected
By connecting an output connector of a source component to compute-when, the variable is computed whenever that source item is first used in a target subtree.
The variable actually acts as if it were a child item of the item connected to compute-when. This makes it possible to bind the variable to a specific source item. That is, at runtime the variable is re-evaluated whenever a new item is read from the sequence in the source component. This is related to the general rule governing connections in MapForce: For each source item, one target item is created. In this case, compute-when instructs MapForce to compute the variable value for each source item. For more information, see Mapping Rules and Strategies.
Compute-once
If necessary, you can choose to compute the variable value once before each of the target components, making the variable essentially a global constant for the rest of the mapping. To do this, right-click the compute-when item and select Compute Once from the context menu:
When you change the scope of a variable to compute-when=once, the input connector is removed from the compute-when item, since such a variable is only evaluated once. In a user-defined function, the compute-when=once variable is evaluated each time the function is called before the actual function result is evaluated.
Parent-context
The parent-context argument is an optional argument in some MapForce core aggregation functions (e.g., min, max, avg, count). In a source component which has multiple hierarchical sequences, the parent context determines the set of nodes on which the function should operate.
Adding a parent-context item may be necessary, for example, if your mapping uses multiple filters and you need an additional parent node to iterate over. For details, see Example: Changing the Parent Context. To add a parent-context to a variable, right-click the root node (in this example, PersonList) and select Add Parent Context from the context menu. This adds a new node, parent-context, to the existing hierarchy.
The parent context adds a virtual parent node to the hierarchy within the component. This allows you to iterate over an additional node in the same or in a different source component.