Altova MapForce 2024 Enterprise Edition

This example shows you how to combine data from two XML structures conditionally, by using a join component. The example is accompanied by a mapping sample which is available at the following path: <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\JoinPeopleInfo.mfd.

The purpose of this mapping is to collect people data (name, surname, address, email, and phone) from two source XML files into a single target XML file.

The first XML file stores the name and surname of each person, as well as their email and phone, as shown in the sample code listing below (note that the XML declaration, namespaces, and some records have been omitted, for simplicity):

People.xml

The second XML file stores the name and surname of each person, as well as their address details:

Addresses.xml

The goal of the mapping is to combine the <Person> information from the first file with <Address> information from the second file, wherever the first and last names match. Specifically, for each <Person> in the first file, and for each <Address> in the second file, the FirstName and LastName must be compared. If both values are the same, then the corresponding <Person> and <Address> records refer to the same person, and must be joined. The target XML structure should look like this:

PeopleInfo.xml

This mapping goal can be easily achieved by adding a Join component to the mapping. Note that it is also possible to achieve the same result using other component types; however, in the steps below, you will be using a Join component, which is the subject of this example.

To create the required mapping, follow the steps below.

Step 1: Add the source XML files to the mapping

1.On the Insert menu, click XML Schema/File, and browse for the following source file: <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\People.xml.

2.Repeat the step above for Addresses.xml (the second source file).

Step 2: Add the target schema file to the mapping

•On the Insert menu, click XML Schema/File, and browse for <Documents>\Altova\MapForce2024\MapForceExamples\Tutorial\PeopleInfo.xsd (the target XSD schema file). When prompted to supply a sample XML file, click Skip. When prompted to select a root element, select PeopleInfo as root element.

Step 3: Add the Join component

1.On the Insert menu, click Join. (Alternatively, click the Join toolbar button). At this stage, the mapping should look as follows (you will need to drag and resize the components in order to make them look as illustrated below):

Observe the structure of the Join component. It has two nodes/rows items, which makes it possible to connect to it the two structures that need to be compared (in this case, the Person and the Address structures).

2.Draw a connection from Person to the first nodes/rows item of the Join component. Likewise, connect Address to the second nodes/rows item.

3.As mentioned earlier, the join should take place only if the FirstName and LastName values are equal in both structures. To define this condition, click the Define Join Condition button.

4.Select the pair of items that define the first join condition (FirstName under Structure 1, and FirstName under Structure 2).

5.Click Add Condition, and repeat the step above for LastName.

In some mappings, a condition consisting of one comparison may be sufficient to perform the join. However, in this example, it is important that two comparisons are created:

1)FirstName in Structure1 = FirstName in Structure 2

2)LastName in Structure 1 = LastName in Structure 2.

When multiple conditions are defined, all of them must be true in order for the join to take place. Therefore, in this example, a join will happen only when both comparisons are true (which is the intended behaviour). Otherwise, if only one of the comparisons above were defined, a join could happen for persons that have the same first name but different last names.

Step 4: Map the Join component to the target schema

Now that the two structures are joined, you can define which items of the joined structure should be mapped to the target. To do this, create connections from items of both joined structures to the target component, as shown below. The connection between joined and Row has the following purpose: whenever the join condition is satisfied, it creates a new Row item in the target.

To preview the mapping output, click the Output pane. As expected, each person record (<Row>) now includes the full address details, joined from two different sources.