Sequences
Understanding sequences is essential for mastering mapping techniques in MapForce. The main rule for sequences runs as follows:
If a sequence of more than one node is connected to a target node, a loop is created that generates as many target nodes as there are source nodes.
If there is a filter on the way, MapForce checks if there is at least one Boolean condition in the sequence that evaluates to true and maps the data that satisfies this condition to the target.
If a sequence is empty, nothing is generated on the target side. For example, if the target is an XML document and the source sequence is empty, no XML elements would be created in the target at all.
Exceptions
Note some exceptions to the rule about sequences (see below).
Exception 1
If the target item is an XML root element, it is created only once. If you connect a sequence to it, the result might not be schema-valid. If attributes of the root element are also connected, the XML serialization will fail at runtime. Therefore, avoid connecting a sequence to the root XML element.
Exception 2
If the target item accepts only one value, it is created only once. Examples of items that accept only one value are as follows: XML attributes, database fields, simple output components. For example, the mapping below generates a sequence of three integers (1, 2, 3) with the help of the generate-sequence function. Nevertheless, the output will contain only one integer, because the target is a simple-output component that accepts a single value. The other two values are ignored.
Exception 3
If the source schema specifies that a specific item occurs only once, but the instance file contains many items, MapForce may extract the first item from the source (which must exist according to the schema) and create only one item in the target. To disable this behavior, clear the check box Enable input processing optimizations based on min/maxOccurs from the component settings.
Functions
If a non-sequence function gets a sequence as input, the function is called as many times and produces as many results as there are items in the sequence. If a function gets an empty sequence as input, it returns an empty result and, consequently, produces no output at all.
Functions that return a value even if they get an empty sequence
However, there are some categories of functions that, by virtue of their design, return a value even if they get an empty sequence as input:
•exists, not-exists, substitute-missing
•is-null, is-not-null, substitute-null (these three functions are aliases of the previous three)
•aggregate functions (sum, count, and so on)
•user-defined functions that accept sequences and are regular (not inlined) functions
If you need to replace a missing value, add the substitute-missing function to the mapping and replace the missing value with a substitute value of choice. Alternatively, you can achieve the same result by using defaults and node functions.
Functions with multiple inputs
Functions may have multiple inputs. If a sequence is connected to each input, this produces a Cartesian product of all inputs (a set of all ordered pairs that can be created by combining elements from two or more sets), which is typically not the desired outcome. To avoid this, connect only one sequence to a function with multiple parameters; all other parameters must be connected to "singular" items from parents or other components.