BizTalk 2010 Recipes : Document Mapping - Using the Value Mapping Functoids

3/27/2011 8:43:39 PM

1. Problem

You need to understand how and when to use the Value Mapping and the Value Mapping (Flattening) functoids.

2. Solution

BizTalk provides two Value Mapping functoids: Value Mapping and Value Mapping (Flattening). Both will cause a new record to be created in the destination for every record in the source. The Value Mapping (Flattening) functoid is used when the destination document has a flat structure.

Both functoids require two input parameters: a Boolean value and the node that is to be mapped. If the Boolean value is true, the value will be mapped; otherwise, it will not be mapped.

The following steps demonstrate the use of the Value Mapping functoid in a map, using the source document shown in Listing 1.

Example 1. Source Document for the Value Mapping Functoid Example

<ns0:NewHireList xmlns:ns0="http://UsingValueMappingFunctoids.NewHireList">
  <DateTime>DateTime_0</DateTime>
  <Person>
    <ID>1</ID>
    <Name>Jonesy</Name>
    <Role>.NET Developer</Role>
    <Age>47</Age>
  </Person>
  <Person>
    <ID>2</ID>
    <Name>Scott</Name>
    <Role>Database Developer</Role>
    <Age>40</Age>
  </Person>
  <Person>
    <ID>3</ID>
    <Name>Austin</Name>
    <Role>QA</Role>
    <Age>33</Age>
  </Person>
</ns0:NewHireList>

These steps refer to the Value Mapping functoid but are identical for the Value Mapping (Flattening) functoid.

Click the Toolbox, and click the Advanced Functoids tab. Drop the Value Mapping functoid on the map surface between the source and destination schemas.
The first parameter for the Value Mapping functoid needs to be a Boolean value. For this example, a Not Equal functoid will be used to generate the Boolean value. In the Toolbox, click the Logical Functoids tab, and drop a Not Equal functoid to the left of the Value Mapping functoid. The first input parameter for the Not Equal functoid should be the value from the Role element. The second input parameter should be a constant value. Set this value to QA. This will ensure that only those records that are not in this role will be mapped across. See Figure 1.

Figure 1. Configuring the Not Equal functoid
The second parameter for the Value Mapping functoid in this example is the Name element from the source document. Ensure that a line exists between this node and the functoid.
Drop the output line from the Value Mapping functoid on the target node in the destination document.

Figure 2. Using the Value Mapping functoid

At this point, the map can be tested. Using the source document shown in Listing 1, output of the map is the document shown in Listing 2.

NOTE

If the Value Mapping (Flattening) functoid does not map a value across, the node is not created on the destination schema, whereas if the Value Mapping functoid does not map a value, an empty destination node will be created. To change this behavior, you will need to use additional functoids or scripting.

Example 2. Output Document Using the Value Mapping Functoid

<ns0:Company xmlns:ns0="http://UsingValueMappingFunctoids.Company">
 <Employees>
  <Employee>
   <Name>Jonesy</Name>
  </Employee>
  <Employee>
   <Name>Scott</Name>
  </Employee>
  <Employee>
  </Employee>
 </Employees>
</ns0:Company>

If the Value Mapping functoid is replaced with the Value Mapping (Flattening) functoid (as shown in Figure 3), the document in Listing 3 will be output.

Figure 3. Map with Value Mapping (Flattening) functoid

Example 3. Output Document Using the Value Mapping (Flattening) Functoid

<ns0:Company xmlns:ns0="http://UsingValueMappingFunctoids.Company">
 <Employees>
  <Employee>
   <Name>Jonesy</Name>
   <Name>Scott</Name>
  </Employee>
 </Employees>
</ns0:Company>

3. How It Works

This example showed the default behavior of the Value Mapping functoid. However, the default output of the Value Mapping functoids can be altered through the use of additional functoids and scripting. For example, notice that the output in Listing 3 is flat instead of nested (two Person nodes within the Employee node). By adding a Looping functoid to the Name element in the source document and attaching it to the Employee root node in the destination document (see Figure 4), you can obtain nested output, as in Listing 4. The output is identical to using the Value Mapping functoid as shown in Listing 2.

Figure 4. Using the Value Mapping (Flattening) and Looping functoids

Example 4. Output Using Value (Mapping) Flattening and Looping Functoids

<ns0:Company xmlns:ns0="http://UsingValueMappingFunctoids.Company">
 <Employees>
  <Employee>
   <Name>Jonesy</Name>
  </Employee>
  <Employee>
   <Name>Scott</Name>
  </Employee>
  <Employee>
  </Employee>
 </Employees>
</ns0:Company>

One of the most common situations in XML document mapping is working with nonexistent elements. By default, if an element does not exist in an incoming document but is mapped to the destination document in a BizTalk map, the node on the destination document will be created with a null value (<Node/>). The use of a Value Mapping (Flattening) functoid causes the node to be created in the destination document only if the source node exists in the source document.