Altova MapForce 2025 Basic Edition

Context is one of the most crucial aspects in mapping execution. Understanding context is key to achieving the desired result in the output. Context determines what data is available for the current target node and its descendants and which source items are actually selected and copied from the source to the target component.

MapForce always establishes the current context starting from the target root item (node). This is where mapping execution actually begins. After processing the target node, MapForce progresses down the hierarchy. For each target node, the connections are traced back to the sources, through any functions in between.

For each target node, a new context is established that initially contains all the current source nodes of the parent and all function results. While MapForce evaluates the connections leading directly or indirectly to the target node, additional sources and function results are added to the context. Target sibling nodes are thus independent of each other but have access to all the sources of their parents.

For a recap of the fundamental rules of mapping execution, see Basic Rules and Strategies.

Example

To put the principles described above into practice, we will discuss the following mapping: MapForceExamples\PersonListByBranchOffice.mfd (illustrated below). The main objective of the mapping is to get a list of employees with their details from a particular office.

Source and target structures

In our example, the mapping contains a source XML component and a target XML component. Besides, there is a simple-input component that also acts as a source and supplies the name of the office in whose employees we are interested. The mapping also features various transformation components such as a filter and some functions.

It is important to note that MapForce always displays only schema hierarchies in structural components (e.g., XML). For example, the BranchOffices component shows only one Contact element despite the fact that the source instance file BranchOffices.xml contains multiple Contact nodes with different content and in different Office parent nodes. An extract from BranchOffices.xml is shown below.

Context and processing order

In our mapping, processing begins from the target root node called PersonList. We can trace back the connection via the filter and the equal function to its source item - the Office element.

Single office as context for the target

Since our mapping has a filter, only the data that satisfies the Boolean condition will be mapped to the target. This condition is satisfied only once, because there is only one office called Nanonull, Inc. in the source XML file. Consequently, the connection from the PersonList list through the filter to the Office node defines a single office as the context for the entire target document. This means that all further connections to the descendants of the root element will be affected by the filter and will have access only to the data of the Nanonull, Inc. office, and no other office will exist in the current context.

One Person for each Contact

The next connection is between the Contact and Person nodes. According to the general mapping rule, this connection will create one target Person for each source Contact. On each iteration, this connection establishes one current Contact for the connections to the children of the Person element. Therefore, the child connections (first to First, last to Last) will select the first and last names of the current Contact element and write them to the target.

User-defined function

The mapping also includes a user-defined function called LookupPerson. The user-defined function is also executed in the context of each Person because of the parent connection between Contact and Person. Each time a new Person item is created on the target side, the function is called to populate the Details element of the person.

The function takes three input parameters. The OfficeName parameter reads data from the simple-input component. 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 taken from the 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 is configured, see Look-up Implementation.

If parents are not connected

If there were no connection between Contact and Person, the mapping would create only one Person with multiple First, Last, and Details nodes. In such cases, MapForce displays a warning in the Messages window (screenshot below) and suggests connecting the parent nodes to resolve the issue.