So You Want To Write A Map?

  • Article

Looking for information about writing a map in BizTalk Server 2006? This post is a modest attempt to catalog some of the many useful tidbits of information out on the web.

  • Legend
    • blog = blog post
    • core = BizTalk Server 2006 core documentation hosted on MSDN.
    • lib = non-core docs at Microsoft
    • other = general resource out on the vast interweb
    • wp = BizTalk Server 2006 whitepaper

Nice legend. Maybe I don't need it. In any case, here is the material:

  •  General Material
    • Planning to Create Maps (core) - provides a short list of questions you should consider before undertaking a map. On the downside, the questions are a bit obvious..."What maps do I need to create?".
    • About Maps (core) - describes what maps do, components of maps, and touches on functoids. If you are interested in this type of material, review child topics as well.
    • Links in Maps (core) - this is a subtopic under About Maps is useful because it describes how elements between two different schemas (map source and map destination or target) are related and what BizTalk Server lets you do with the relationships (links).
    • Using BizTalk Mapper (core) - this topic and its children take you on a whirlwind tour through the BizTalk Server mapper UI. Do you have a hankering to play with the Grid View? Do you yearn to express your individuality by changing colors and fonts used in the mapper? This topic and its children dish the dirt.
    • Managing Maps (core) - describes how to use the BizTalk Server Administration console to manage maps. You ma need to review this if you are updating map versions and performing other maintenance operations.
    • Functoids in Maps (core) - gives an overview of what Functoids are. Child topics go into more detail.
    • Creating Schemas Using BizTalk Editor (core) - you can't have a map without at least one schema (you could map a message back onto the same schema).
  • Functoids (and Custom Functoids)
    • Developing Custom Functoids (core) - explains the ins and outs of BaseFunctoid and writing your own custom functoids.
    • DBFunktoids (blog) - I wrote a set of funktoids to enable stored procedure execution and data retrieval from within a BizTalk Map. Check it out.
    • Custom Funtoid (core) - this SDK sample demonstrates how to write a custom functoid for BizTalk Mapper. Not as funky as DBFunktoids but a solid example.
  • Testing Maps
    • How to Generate Instance Messages (core) - the first step down the road to Map Testing Goodness is a creating a test file (aka "instance message"). Visual Studio can generate an instance message for you; this topic shows you how.
    • How to Validate Instance Messages (core) - the second step down the road to Map Testing Goodness is having a valid test file (instance message). This topic tells you how to validate your instance message and contains an important link to Known Issues with Schema Generation and Validation.
    • Map File Properties (core) - the third step down the road to Map Testing Goodness is mucking about with map file properties so that your input and output instance file location, format and validation desires are known to the BizTalk Mapper.
      • TestMap Input Instance - configures the location of the input instance message file to be used while testing the map.
      • TestMap Input - specifies the format of the input instance message.
      • TestMap Output - specifies the format for the output instance message.
      • Validate TestMap Input - specifies whether you want to validate input instance messages against the source schema before you test the map.
      • Validate TestMap Output - specifies whether you want to validate output instance messages against the destination schema after you test the map. 
    • How to Test Maps (core) - the fourth step down the road to Map Testing Goodness; this topic tells you how to right-click on the map you want to test in the Solution Explorer, click Test Map, then verify the results in the Output window. Did I spoil it for you? No, because it also tells you how to sniff about the XSLT code generated to actually do the transformation. Maybe you can spot an error.
    • Developers Troubleshooting Guide to BizTalk Server 2006 (wp) - the last step down the road to Map Testing Goodness, the troubleshooting guide provides different debugging and testing strategies along with general BizTalk Server tips, tricks and traps all wrapped up in a Word document.
    • Using the XSLT Debugger (I really love whidbey + BizTalk) (blog) - one of the side-streets on the road to Map Testing Goodness, this post by Jon Flander's describes debugging a map with the XSLT debugger. Interesting stuff.
    • Map is Too Big (other) - an interesting thread about error "Internal Compiler Error (0xc0000005 at address 53624FD6): likely culprit is 'CODEGEN'." 
  • Examples, How-To's, etc.
    • How to Add Maps to Send Ports for Outbound Normalization Using BizTalk Explorer (core) - describes how you can use a map to transform the schema of a message at the send port without processing the message through an orchestration. 
    • How to Configure Outbound Maps for a Send Port (core) - explains the steps required to configure a send port to use an outbound map.
    • How to Remove a Map from an Application (core) - describes how to use the BizTalk Server Administration console to remove a map from a BizTalk application. You might want to remove a map after deploying a new version of the map.
    • Extending Mapper (core) - shows how to have external code impact a transformation. Take a look if you want to see how to provide external methods called through the scripting functoid, or want to perform other processing not supported by a custom functoid.
    • Using the Mass Copy Functoid (lib) - this SDK sample demonstrates the use of the Mass Copy Functoid to map a source hierarchy to a destination hierarchy without mapping each individual element by hand.
    • Using the Looping Functoid (lib) - this SDK sample transforms catalog data from one format to another by using the Looping functoid.
    • Mapping to a Repeating Structure (lib) - this SDK sample demonstrates how to map multiple recurring records in an inbound message to their corresponding records in the outbound message in the BizTalk Mapper.
    • Using the Table Looping Functoid (lib) - this SDK sample demonstrates the use of the Table Looping functoid in gated and non-gated configurations.
    • Using the Value Mapping and Value Mapping (Flattening) Functoids (lib) - wondering about the difference between these two functoids? This SDK sample demonstrates the use of the Value Mapping and Value Mapping (Flattening) functoids to transform data between different message formats.
    • BizTalk, Another Custom XSLT Example (blog) - as Matt Meleski shows, sometimes it may be easier to roll your own map using XSLT rather than use the Mapper UI. 
  • Interesting Technical Material
    • XSLT Reference (lib) - provides information about XSLT Elements, XSLT Syntax, and XSLT Functions so that you too can create maps from scratch to solve problems not expressible in the Mapper and edit XSLT generated by the Mapper. And impress your friends, confuse your enemies, and amuse your pets.
    • Production Debugging (blog) - Scott Colestock describes how to use the Windows debugging tools to perform old-school debugging of a BizTalk application. This is some serious debugging smack-down; I'm not sure when a map would be so heinously naughty that you'd have to open this can of whup-butt but its there if you need it.

Suggestions? Addtions? Drop me a line.