Path types (repetition of target structure nodes)

Relative and non-relative path

The number of repetitions of a target structure node can be controlled by the source structure with the target node attributes "Path" and "Is relative path".

Node attribute "Path"

The following screenshot shows the effects of the node attribute "Path" using two examples.

(1) Source structure. The target structure refers to this structure.

(2) Target structure. Controls the creation of the target tree.

(3) The node attribute "Path" has been set to the source structure node of the same name ("OrderHeader"). The names of the nodes are freely assignable and do not have to be identical. However, the path value must be a node name from the source structure.

(4) As an alternative to (3), the path of the node has been set to "Position". Of course, only one path can be specified.

(5) The source tree created from the source structure (1).

(6) The target tree created from the source tree using the target structure and (3). Since the assigned node in the source tree occurs only once, the node in the target tree is also created only once.

(7) The target tree created from the source tree using the target structure and (4). The assigned node in the source tree ("Position") occurs several times, in the target tree the node is repeated just as often.

Node attribute "Is relative path"

As mentioned earlier, the node attribute "Path" works in conjunction with the node attribute "Is relative path", which determines from which direction (top or bottom) the occurrences of the assigned path are counted. Depending on the value of this node attribute, different numbers of occurrences of the assigned node are found.

The illustrations below contain examples for clarification. Since the previous examples are not complex enough to show the possibilities of the mapper, an additional level of complexity has been added in the following examples.

The following screenshot shows the source and target structure for the following examples.

(1) Source structure. An order position consists of one position and any number of texts for this position.

(2) Target structure. "OrderHeader" and "OrderPosition" are mapped as before with a relative path to the nodes of the same name in the source structure. The mapping of "Position" and "PositionText" will be changed in the following examples and the effects will be shown there.

(3) Mapping from "OrderHeader" to "OrderHeader" with a relative path (1:1 mapping).

(4) Mapping from "OrderPosition" to "OrderPosition" with a relative path (1:1 mapping).

The following figure shows the result of the mapping if the node property "Is relative path" has the value "No" (i.e. the absolute path is used).

(1) Mapping of "Position" and "PositionText" with a path to the respective source structure node with the same name and "Is relative path" with the value "No".

(2) Source tree. For clarity, the fields are not displayed.

(3) Target tree. For clarity, the fields are not displayed.

(4) The node "Position" is repeated as often as the node occurs in the source tree (controlled by the path). The algorithm looks for all nodes named "Position" in the source tree and finds two occurrences. Therefore, the node in the target tree is also repeated twice.

(5) The node "PositionText" is repeated as often as the node occurs in the source tree (controlled by the path). The algorithm looks for all nodes named "PositionText" in the source tree and finds four occurrences. Therefore, the node in the target tree is also repeated four times.

You can imagine the target nodes as a program loop. These nodes are simply repeated as many times as the corresponding source nodes are found. The number of occurrences depends on the node attribute Is relative path, as shown in the following figure.

(1) Mapping of "Position" and "PositionText" with path value "PositionText" and node attribute "Is relative path" with the value "Yes".

(2) Source tree. For clarity, the fields are not displayed.

(3) Target tree. For clarity, the fields are not displayed.

(4) The node "Position" is repeated as often as the node "PositionText" in the source tree under the parent node ("OrderPosition") (controlled by the path). The algorithm looks for all nodes named "PositionText" under the parent and finds one occurrence. Therefore, the node in the target tree is also repeated once.

(5) The node "Position" is repeated as often as the node "PositionText" in the source tree under the parent node ("OrderPosition") (controlled by the path). The algorithm looks for all nodes named "PositionText" under the parent and finds three occurrences. Therefore, the node in the target tree is also repeated three times.

For a relative path (attribute "Is relative path" with value "Yes"), the algorithm searches like this.

• Search for nodes with the same name in the source tree below (and including) the parent node. If nodes are found, count them and repeat the node on the target side as many times. If nothing is found, execute the next step.

• Go up one level and look for nodes with the same name below (and including) the parent node. If nodes are found, count them and repeat the node on the target side as many times. If nothing is found, repeat the step until you find something or until the root of the record is reached.

The following figure shows the algorithm based on a schematic target tree.

(1) The starting point of the search. Within the marked area, the occurrence of the specified node (path) is searched for.

(2) If nothing is found in (1), the algorithm expands its search range one node up and looks below the new starting point for all occurrences of the specified node (path).

(3) If nothing is found in (2), the algorithm expands its search range one node up and looks below the new starting point for all occurrences of the specified node (path).

(4) If nothing is found in (3), the algorithm expands its search range one node up and looks below the new starting point for all occurrences of the specified node (path). The marked area here corresponds to the absolute path setting since all occurrences of the node are found. The search is not extended beyond the limits of the record.

Node attribute "Optimize path"

If attribute "Optimize path" has value "No", the usually active path optimisation will be deactivated. If a child node in the target structure has the same path as its parent node and its attribute "Is relative path" has value "No", this node will only appear once in the target tree if the optimisation is enabled. If the optimisation is disabled, the node appears in the target structure as often as it appears in the source tree.

Self calculated path

You have already seen how to repeat target structure nodes by the source structure. But the number of times a node appears in the target tree can also be calculated/specified in the mapping. To do so, attribute "Path" does not contain the name of a source structure node, but instead a variable of type "Integer". The value of the variable, e.g. "@var__COUNTER@", will then determine the number of repetitions of the node.

The value of the variable is read when the mapper processes the node in the target structure for the first time. Later changes to the variable have no effect on the number of repetitions. Anywhere else, however, the current value of the variable is used.

Often, a node should be executed as many times as a list has values, or a map has keys. Therefore, you can use the following path definitions.

Note: The spelling of the prefixes "List:" and "Map:" is case-sensitive. You can also insert a string variable for this type of specifying paths. To do so, the variable has to contain a value "List:list_name" or "Map:map_name" (without the surrounding @ characters).

Note: It is also possible to specify only the list name or map name with a string variable. So if the variable "var__NAME" contains the name of the list or map object, the syntax is "@List:@var__NAME@@" or "@Map:@var__NAME@@".