Testing the Map
After you create a map, or after you modify an existing map, you will want to unit-test it before incorporating the new or changed map into your BizTalk Server processes. The Mapper will first compile the map into an executable form and can detect a number of mapping errors at that stage. Then you can test the execution of the map with automatically generated field values, with field values you define, or with an actual instance of the source document. There are also a number of option settings for the Mapper that affect the process of map testing.
Compiling the Map
The first step in testing your completed map is to compile the specifications, links, and functoids into an XSLT script that actually performs the work specified by the map definition. To illustrate the error checking and reporting capability of BizTalk Mapper, we deleted the links to two of the destination fields as shown in Figure 5.17. Note that the compiler can detect which destination fields are required to have values in a valid output document. The compiler also reports which functoids are not connected to any output.
Figure 5.17. Compile errors in the Warnings tab.
Make it a habit to compile the map every time after adding a new functoid and linking it to its inputs and output. Compile warning messages are often specific enough to pinpoint a problem, but sometimes they are not. If you compile the map right after making a change, and a new warning appears, you already know where to look to find the problem—it must be something about the changes you made since your last successful map compilation.
Testing with Generated Data
When the map is compiling successfully, you can perform a simple test of the mapping process by choosing Tools, Test Map, Generated XML to XML (see Figure 5.18). Simulated values based on the source field name are provided as map inputs, and the resulting output interchange is displayed on the Output pane. (If you are working through these examples yourself, you will need to uncheck Tools, Options, Validate Content After Map Test to successfully execute the map. See the section “Testing and Validation Options” later in the chapter for details.) The grade percentage and letter don't look too good, of course, because the generated data are not realistic numbers for the corresponding input fields.
Figure 5.18. Testing the map with generated data.
Testing with Entered Values
To provide more realistic values for the input fields, click the Values tab (on the lower pane) and click each source field in turn to enter a single value to use for the Generated test. The Values tab can also be used to specify constant values for destination fields that are required to appear in the output specification but do not have corresponding source fields that can be linked to provide values using the map. To test with entered values, you still choose the menu item Tools, Test Map, Generated XML to XML (see Figure 5.19). As you can see, any entered values are used in place of the automatically generated "FieldName_1" strings. The entered values are stored with the map and can always be used for a quick test after any change to the completed map.
Figure 5.19. Testing with field data entered on the Values tab.
Testing with a Source Instance
A new and excellent feature of the Mapper for BizTalk 2002 is the capability to read and process an actual source document file in the Mapper itself, without having to set up a BizTalk Messaging Channel as in earlier versions of BizTalk Server. In addition, as you can see on the menu in Figure 5.20, the Mapper can read or write “Native” documents if the source or destination format is not XML. (Those options are grayed out as appropriate if the source or destination is an XML-format document). You can create a test instance entirely by hand, or you can use the BizTalk Editor to generate either an XML or a Native instance; then edit the attribute values as shown in Listing 5.1 to produce a suite of useful test instances. Of course, if you have actual examples of source documents, the map can now be tested against those examples directly in the Mapper application.
Figure 5.20. Testing the map with a source instance.
Listing 5.1. A Source Instance Generated by BizTalk Editor, Edited with Test Values
<ScoreReport>
<StudentScores>
<CourseInfo CourseID="DET411" CourseTitle="Elementary Detection" />
<StudentInfo StudentID="010-32-7246" StudentLastName="Holmes"
|
StudentFirstName="Mycroft" />
<ScoreItem ScorePercent="100" ScoreWeight="0.20" />
<ScoreItem ScorePercent="90" ScoreWeight="0.20" />
<ScoreItem ScorePercent="80" ScoreWeight="0.20" />
<ScoreItem ScorePercent="95" ScoreWeight="0.40" />
</StudentScores>
</ScoreReport>
Testing and Validation Options
If you have been carrying out the preceding examples, you may already have encountered another new feature in the BizTalk 2002 Mapper: the capability to validate both incoming source test documents and the outgoing destination document resulting from the mapping. That is a terribly useful feature, especially for verifying that the output document fulfills the specification, but you don't always want it during initial testing of your map. One reason is that you may want to test a partial map, when you have mapped only a few fields—and not all the required output fields yet have values. To turn off validation temporarily, use the Tools, Options dialog (see Figure 5.21) and uncheck either or both of the Validate options as desired. Of course you will want to perform your final tests of the map with both validation options checked, so be sure to add that to your final-test checklist.
Figure 5.21. Source and destination validation options.
Note
To illustrate how simple it is to test and validate file types other than XML, the example code on the publisher's Web site contains a sample comma-delimited version of the Grade Report file named specGradeReportCSV.xml. It also contains a sample map file named mapScoresGradesCSV.xml that maps the inbound XML file to the CSV version.
Another option that affects testing (in a minor way) is Prompt to Save Before Testing the Map. When checked, that option offers to save any changes to the map file before beginning the test. Although that option is not as necessary as for a programming-language development environment—testing a BizTalk map is not likely to crash your machine—it is handy to have a reminder to save your map frequently, especially because the Mapper does not have an Undo function. However, all those Save changes dialogs can become a nuisance. Clearing the Prompt to save Before Testing the Map option stops the appearance of the Save dialog. Be aware that the Mapper does not automatically save the map without prompting; it simply does not save the map before beginning the test. You will need to save the map yourself at frequent intervals to guard your changes from being lost.