The Mapping Context
Mapping components are hierarchical structures that may contain many levels of depth. On the other hand, a mapping may have multiple source and components, plus any intermediary components such as functions, filters, value-maps, and so on. This adds complexity to the mapping algorithm, especially when multiple unrelated components are connected. To make it possible to execute the mapping in portions, one step at a time, a current context must be established for each connection.
We could also say that multiple "current contexts" are established for the duration of the mapping execution, since the current context changes with each processed connection.
MapForce always establishes the current context starting from the target root item (node). This is where the mapping execution actually begins. The connection to the target root item is traced back to all source items that are directly or indirectly connected to it, including via functions or other intermediary components. All the source items and results produced by functions are added to the current context.
After it finishes processing the target node, MapForce works down the hierarchy. Namely, it processes all mapped items of the target component from top to bottom. For each new item, a new context is established that initially contains all items of the parent context. Thus, all mapped sibling items in a target component are independent of each other, but have access to all source data of their parent items.
Let's see how the above applies in practice, based on an example mapping, PersonListByBranchOffice.mfd. You can find this mapping in the <Documents>\Altova\MapForce2024\MapForceExamples\ directory.
In the mapping above, both the source and the target component are XML. The source XML file contains two Office elements.
As mentioned previously, the mapping execution always begins from the target root node (PersonList, in this example). By tracing back the connection (via the filter and the function) to a source item, you can conclude that the source item is Office. (The other connection path leads to an input parameter and its purpose is further explained below).
Had there been a straightforward connection between Office and PersonList, then, according to the general mapping rule, the mapping would have created as many PersonList instance items as there are Office items in the source file. However, this does not happen here, because there is a filter in between. The filter supplies to the target component only data that satisfies the Boolean condition connected to the bool input of the filter. The equal function returns true if the office name is equal to "Nanonull, Inc.". This condition is satisfied only once, because there is only one such office name in the source XML file.
Consequently, the connection between Office and PersonList defines a single office as the context for the entire target document. This means that all descendants of the PersonList item have access to data of the office "Nanonull, Inc." office, and no other office exists in the current context.
The next connection is between Contact and Person. According to the general mapping rule, it will create one target Person for each source Contact. On each iteration, this connection establishes a new current context; therefore, the child connections (first to First, last to Last) supply data from the source to the target item in the context of each Person.
If you left out the connection between Contact and Person, then the mapping would create only one Person with multiple First, Last, and Details nodes. In such cases, MapForce issues a warning and a suggestion in the Messages window, for example:
Finally, the mapping includes a user-defined function, LookupPerson. The user-defined function is also executed in the context of each Person, because of the parent connection between Contact and Person. Specifically, each time when a new Person item is created on the target side, the function is called to populate the Details element of the person. This function takes three input parameters. The first one (OfficeName) is set to read data from the input parameter of the mapping. The source data for this parameter could as well be provided by the Name source item, without changing in any way the mapping output. In either case, the source value is the same and it is taken from a parent context. Internally, the look-up function concatenates the values received as arguments and produces a single value. For more information about how the LookupPerson function works, see the Example: Look-up and Concatenation.