Troubleshooting Maps

This section provides troubleshooting strategies and problem detail and resolution information for maps.

Validate your map

This may sound obvious, but you should always validate your map at different points throughout its development. This will help identify design, logic, and schema problems early in the development cycle when it is easier to fix them or find an alternative solution.

To validate a BizTalk map
  1. In Solution Explorer, open the map that you want to validate.

  2. In Solution Explorer, right-click the map, and then click Validate Map.

  3. In the Output window, verify the results

When you validate a map, your test instance data is not checked to see if it violates any data types defined in the schemas. You can check the instance data when you test the map or validate the instance data in BizTalk Editor.

Review the XSLT generated for the map

It is often useful to inspect the XSLT generated by the map compiler. Some of the benefits of inspecting XSLT include:

  • If you are using looping or custom functoids, you will better understand how the looping is performed and how the custom functoid is invoked.
  • If you have a complicated map, reviewing the XSLT will enable you to see how the map is translated into a transform and may give you insight about how to better structure, replace, or streamline one or more parts.
  • If you are using custom scripts or other artifacts, reviewing the XSLT will enable you to see how the scripts, artifacts, and other parts of the map interact.

Fortunately, viewing the XSLT for a map is an easy process.

To view the XSLT generated by the map compiler
  1. From a Visual Studio BizTalk project, click the Solution Explorer tab, right-click a map, and then click Validate Map.

  2. Scroll the Output window to find the URL for the XSL file. Press CTRL and click the URL to view the file.

If you decide to customize your map by hand, you can modify the version produced by the map compiler. Changes will not be reflected by the Mapper and will be lost the next time you build your solution.

Tune your map for specific scenarios using <mapsource>

You can modify some default behaviors of the Mapper by modifying attributes of the mapsource element directly in a map source (.btm) file. There are currently three behaviors that you can modify:

  • Optimize Value Mapping functoid code generation. You can modify the behavior that controls when a variable is used with if statements.
  • Accommodate schemas with large footprints. You can change the way internal compiler nodes are used in large maps.
  • Manage for-each usage with Looping, Conditional, and Value Mapping functoids. You can control where the xsl:for-each statement is used within the destination schema.

For more information about modifying mapsource, see Managing Default Mapping Behavior Using <mapsource>.

This section contains a set of questions and answers designed to help you resolve issues with BizTalk Mapper.

How do I specify XSLT output settings?

You can use BizTalk Mapper to omit or include XML declarations and control the encoding used for output instance data.

To include or exclude an XML declaration
  1. In the Grid view, click the mapper grid.

    The Properties window shows the Grid properties.

  2. In the drop-down list for the Omit XML Declaration property, select Yes to omit an XML declaration, or select No not to omit an XML declaration.

To set encoding for output instance data
  1. In the Grid view, click the mapper grid.

    The Properties window shows the Grid properties.

  2. In the drop-down list for the Encoding property, select the character set you want used for the output instance data.

How do I create multipart mappings?

If you have multiple maps that are used together, you will need to combine them in an orchestration by using the Transform shape to test them together. BizTalk Mapper can test only one map at a time.

Why isn't my database functoid working?

The database functoids Database Lookup and Value Extractor do not directly return error information; rather, they capture the information and supply it to the Error Return functoid for use by your map. You can use the Error Return functoid for error detection as in the following scenarios:

  • When your map has a Database Lookup or Value Extractor functoid that is not behaving as expected. To see the error message, temporarily map the functoid to a field in the output schema.
  • If your application expects different message content when database operations fail. You can use the Error Return functoid to detect an error and map the error message to an alternate structure so that downstream applications can react in a controlled manner.

To avoid errors that are detected only at run time, make sure that the parameter 1 to the Error Return functoid is the output of a Database Lookup functoid and not the output of any other functoid in the Database category.

For more information about using the Error Return functoid (including a sample), see Error Return Functoid.

Why is my map failing when calling my custom functoid?

Custom functoids must be installed into the global assembly cache (GAC) on the BizTalk Server computer before they can be invoked by a map. Verify that the assembly containing your custom functoid has been signed and placed into the GAC.

For more information about installing assemblies to the GAC, see Assembly Installation in the GAC. To view assemblies installed in the GAC, navigate to the Assembly directory of your Windows installation directory.

You receive error event ID 324 when parsing dates


When you use the Database Value Extractor functoid in a map to extract a date field, your document may fail validation against the outbound document definition. BizTalk Server may log a validation error similar to the following in the event log:

Event Source: BizTalk Server

Event Category: Document Processing

Event ID: 324


An error occurred in BizTalk Server.



The XML document has failed validation for the following reason: Error parsing '10/12/1995' as date datatype.

Suspended Queue ID: "{A1127909-CA36-4359-B672-7CBA8B60BDAF}"


The date format (as it is returned from the data source) is not in ISO 8601 format, which is the format required by XML.


To resolve this issue, do one of the following:

  • Edit your outbound document definition to use a string datatype instead of a date datatype.
  • Create a custom Microsoft Visual Basic Script functoid that will convert the output of the Database Value Extractor functoid into the ISO 8601 format.

For more information, see KB article 278737.