BizTalk 2010 Recipes : Document Mapping - Testing Maps

3/30/2011 7:10:53 PM

1. Problem

You have developed a map and are ready to test and view its output.

2. Solution

For the purposes of testing, there are two basic types of maps:

Simple maps, which consist of a single source schema and single destination schema
Complex maps, which consist of two or more source schemas and/or two or more destination schemas

This solution will work through both types, illustrating several techniques for creating the necessary input documents and obtaining the test results. Figure 1 shows a simple map, with a Company schema being mapped from a combination of a Person schema and hard-coded values in two String Concatenate functoids.

Figure 1. A simple map

Use the following steps to test a simple map:

In the Solution Explorer, right-click the map to test and select Properties. The Property Pages dialog box contains the properties listed in Table 1.

Table 1. Map Properties
Property	Description
Validate TestMap Input	Boolean value indicating whether the source document will be validated against the source schema. For testing, it is often easiest to leave this to False in the early stages of development.
Validate TestMap Output	Boolean value indicating whether the output document should be validated against the destination schema. For testing, it is often easiest to leave this to False in the early stages of development.
TestMap Input Instance	Path to the file that contains an instance of the source schema. Used when the TestMap Input property is not set to Generate Instance.
TestMap Input	Indicates the origin of the source document. If set to Generate Instance, BizTalk will generate an instance in memory that contains values for all attributes and elements in the source schema. If set to XML or Native, BizTalk will look for an instance of the document in the location specified in the TestMap Input Instance property. Native indicates a non-XML file, such as a flat file.
TestMap Output	Indicates the format of the output document. The document will be output to a file stored in a temporary directory on Windows and accessible through Visual Studio.

NOTE

All test map output files are stored in the following directory: $\Documents and Settings\[current user]\Local Settings\Temp\_MapData.

If you're testing with the TestMap Input property set to Generate Instance, right-click the map, and select Test Map (see Figure 2 ). This will cause BizTalk to write to the Output window in Visual Studio and display any errors that may exist. If no errors exist in the map, a link to the test's output XML file will be made available.

Figure 2. The context menu of a map
If you're testing with the TestMap Input property set to XML or Native, and no instance currently exists, follow these steps:
1. Right-click the source schema in the Solution Explorer, and select Properties. Set the path where an instance of the output document should be written. Click OK when the properties have been set appropriately.
2. Right-click the source schema, and select Generate Instance.
3. Open the document created in the previous step. BizTalk will give default values to all of the elements and attributes in the schema. Edit these with appropriate values for your testing needs. When you're generating instances from schemas, all Any elements and Any attributes will be created. These will fail validation when a map is tested. Either delete these from the generated instance or replace them with a value that would be expected.
4. Right-click the map in the Solution Explorer, and select Properties.
5. Set the TestMap Input Instance property to the path of the instance created in step 3c. Set the Test Map Input property to the appropriate type. Click OK.
6. Right-click the map, and select Test Map. This will produce an output document that can be validated for accuracy. Check the Output window in Visual Studio for details in case of failure.

Testing complex maps requires several more steps to create a valid input instance. The main difference in testing the two types of maps lies in how the input instances are generated.

When a map has multiple source schemas, they are wrapped in a hierarchy created by BizTalk. This hierarchy must be matched if using anything other than Generate Instance for the TestMap Input. In cases where nodes such as Any elements or Any attributes exist in the source documents, generated instances will fail during testing. It then becomes a requirement to create by hand an instance of the multipart input document.

A map can have two or more source documents specified through the use of a Transform shape in a BizTalk orchestration (as shown in Figure 3).

Figure 3. Specifying two source schemas on a map in a Transform shape

Figure 4 shows a complex map with a Company schema being mapped from a combination of two source schemas, Person and SourceCompanyInfo.

Figure 4. A complex map

There is never a time in which multiple native instances can be set as source, since the only place that a map with multiple source schemas can be created is in a Transform shape within an orchestration. Therefore, the following steps are specific to creating XML instances that match the multipart input instance needed and can be taken to aid in producing a valid source instance:

To generate an instance of the source schema, create a temporary map that is the inverse of what you are trying to produce. In the case of the example shown in Figure 3-67, the map would consist of the Company schema being the single source schema, with the Person and SourceCompanyInfo being the two destination schemas. The intention is to have BizTalk generate an output message that closely resembles the needed input instance. When namespaces are involved, this is all the more important, as prefixes will be added by BizTalk when creating the multipart message. Figure 5 illustrates the inverse mapping.

Figure 5. Inverse complex map used to generate an input instance
Once a temporary map has been created, right-click the map in the Solution Explorer, and select Properties. Check that the TestMap Input property is set to Generate Instance.

Right-click the map in the Solution Explorer, and select Test Map. This will produce an output document. The output of the map shown in Figure 2-69 is shown in Listing 1.

Example 1. Output of the Inverse Map

<ns0:Root xmlns:ns2="http://TestingMaps.SourceCompanyInfo"
xmlns:ns0="http://schemas.microsoft.com/BizTalk/2003/aggschema"
xmlns:ns1="http://TestingMaps.Person">
 <OutputMessagePart_0>
  <ns1:Person>
   <ID>ID_0</ID>
   <Name>Name_0</Name>
   <Role>Role_0</Role>
   <Age>Age_0</Age>
  </ns1:Person>
 </OutputMessagePart_0>
 <OutputMessagePart_1>
  <ns2:SourceCompanyInfo>
   <ID>ID_0</ID>
   <CompanyName>Name_0</CompanyName>
  </ns2:SourceCompanyInfo>
 </OutputMessagePart_1>
</ns0:Root>

Copy the output document into a text editor, and manually change the names of the OutputMessage nodes to InputMessage nodes so that the outcome is a valid instance of the input document for the true map. In this case, you want a document that can be used as the input for the map shown in Figure 3-66, as shown in Listing 2 . The bold elements in the example are the only elements that need to be modified.

Example 2. Input Instance Produced by Modifying Output from Listing 1

<ns0:Root xmlns:ns2=http://TestingMaps.SourceCompanyInfo
xmlns:ns0="http://schemas.microsoft.com/BizTalk/2003/aggschema"
xmlns:ns1="http://TestingMaps.Person">
<InputMessagePart_0>
<ns1:Person>
<ID>ID_0</ID>
<Name>Name_0</Name>
<Role>Role_0</Role>
<Age>Age_0</Age>
</ns1:Person>
</InputMessagePart_0>
<InputMessagePart_1>
<ns2:SourceCompanyInfo>
<ID>ID_0</ID>
<CompanyName>Name_0</CompanyName>
</ns2:SourceCompanyInfo>
</InputMessagePart_1>
</ns0:Root>

Once the modifications have been made to the document, save it to a file. This document can now be used as a valid input instance for the valid map (you can delete the temporary map at this time). Right-click the valid map in the Solution Explorer, and select Properties. Set the TestMap Input property to XML and TestMap Input Instance to the file that you just created.
Right-click the map in the Solution Explorer, and select Test Map. This will produce an output document that can be validated for accuracy. Check the Output window in Visual Studio for details in case of failure.

3. How It Works

The difficulty in testing maps lies in the creation of the source schema instances. There are a number of ways in which these instances can be created. The objective of this solution was to provide the steps necessary for creating documents that would allow for the testing of both simple maps and complex maps. Additionally, the steps necessary for producing the test output were described.