Mapping - Records and paths
Starting from the source tree, we have two crucial design mechanisms.
Records
The first design mechanism is implicit and simply given by the records themselves. The target structure is traversed once per record of the source tree. This determines the structure of the target data at the highest level. Each (partial) source tree of a record on the source side thus always generates a record with a (partial) target tree on the target side.
More abstractly, the records order repeating structures of the input data on the top-level. How this is done, is determined by the respective parser rules and how you built your source structure. You have already seen a simple example.
Paths
The second design mechanism is used in the records on the target side.
When generating the source tree from the source structure and the input data, a node of the source structure in a record can be generated multiple times.
As we mentioned above, each (partial) source tree of a record on the source side always generates exactly one record with a (partial) target tree on the target side. However, repeat structures (nodes occurring multiple times) within the source tree are not transferred directly to the target tree! By default, only the first node is transferred!
You must explicitly initiate a repetition of a node in the target tree by giving that node in the target structure a path. This is done by setting the target structure node attribute "Path". Specifically, you set the path of a node of the target structure to a node of the source structure. The node in the target tree is then repeated exactly as often as the node in the source tree to which the path is set.
Example
That sounds a bit complicated at first, but basically, it is very simple. Let us look at the slightly modified source structure (and almost identical target structure) of the previous example and slightly adapted input data.
ADR;Randy;Random;Mainstreet 1TEL;00498157488364TEL;00491723374222ADR;Sharon;Fillerup;Treeway 3TEL;00498157483221If everything works as we want, then we get the same number of records as in the first example, but we should get two nodes "phone_number_in" in the first record.
Let us take a look at the result of a mapping test with the above input data.
As you can see, it works in the source structure, but in the target structure, we only get one node "phone_number_out". And the reason for this is, as you may already suspect, that we have not set a path from the node "phone_number_out" to the node "phone_number_in".
We now do that in the attribute "Path" of the target node "phone_number_out". Enter value "phone_number_in" there.
We review the result in the mapping test and see that we now have what we wanted. The twice repeated node "phone_number_in" from the source tree now causes the node "phone_number_out" in the target tree to repeat twice as well.
Summary
So you have two mechanisms to model repeating parts of the input data on the way to your output data. First, the splitting into records during parsing and then the setting of paths to model repeated data within a record (e.g. the multiple occurrences of "node X" in the diagram above). In our concrete example, we first split our input data into addresses (one address per record). Then we used a path from our telephone number node in the target structure to the telephone number node in the source structure to make sure the target structure node will be repeated as often in target tree as the source structure node in the source tree.
The next step is the filling of a record of the target tree.