How to migrate BizTalk maps to Windows Azure BizTalk Services (WABS) maps

Unlike Schemas, that you will be able to directly take your BizTalk Server schemas and use them in you WABS solution, BizTalk Maps needs to be migrated because despite the Transform Designer (mapping tool used for WABS) and the BizTalk Mapper Designer looks mostly the same in terms of layout and user experience, they are quite different and the underlying map format is different. Basically, when we are using BizTalk Mapper Designer the transformation are created using XSLT, however with Transform Designer the transformation are created using Extensible Application Markup Language (XAML).

Also, the available functoids, that are now called Operations, are different as well. Not all the functoids available in BizTalk Server are available as map operations in Azure BizTalk Services and there are new Operations that don’t exist in BizTalk Server like several List Operations, DateTimeReformat, GetContextProperty and so on. And despite XSLT and custom C# are supported the concept of “Scripting” map operation in Azure BizTalk Services Transforms are limited comparing to BizTalk Service for example:

• You cannot use custom inline XSLT, you only can custom XSLT code directly to override WABS map, similar to the “Custom XSLT Path” map grid properties in BizTalk Server.
• You can only use CSharp Scripting inside WABS maps.

Because of all these reasons, you cannot directly use a BizTalk map in Azure BizTalk Services.

Basically, you have two options that you can use to migrate BizTalk maps:

• By using custom XSLT code gathered from your BizTalk Maps (…the easy way)
• Or by using the BizTalk Map Migration Tool provided by Microsoft.

Using BizTalk Map Migration Tool

This is a command-line tool, provided by Microsoft that takes a BTM File as input and that will try to produce the new mapper (.trfm) file as an output.

I’m saying “that will try” because there are many limitations present like:

• Certain functoids may not get converted by this tool, for example, some Scripting and Custom functoids from BTM way cannot be converted. In this case, they are converted to arithmetic expression functoid in the TRFM map with the expression value as empty.
• Links to functoids, which cannot be converted successfully, are denoted as empty inputs in the new TRFM functoids.
• Certain features that are not supported, yet, in TRFM, will not be converted properly. For example, links from xs:extension node(s) are not converted to TRFM
• Certain conditional mapping are not converted as expected as these features are not yet implemented in the Transforms
• And so on.

In the end, this tool will generate a conversion process report (Report.txt) listing out the failed conversions.

Also in terms of Organizing and Documenting Maps, there are two drawbacks presents:

• Labels and comments from the BTM functoids are not mapped onto the TRFM functoids
• The multiple pages from BTM are translated to a single page in the TRFM map to ensure all operations within scope are within a page.

The BizTalk Map Migration Tool is available on Codeplex at BTM Migration Tool, but before you use this tool you need to know that:

• This tool expects that the machine on which it’ll run would have both products installed: BizTalk 2010 or above and Windows Azure Biztalk Services.
• And the Schemas should be present as expected by the BTM map (in the relative folders).

The BTM Migration Tool is a command-line tool that uses the following parameters:

• A BizTalk map (.btm)
• Optional. Resulting BizTalk Service project Transform (.trfm)

Let’s look at one very easy example and analyze the end result. In this scenario, we have two different records, Client and Employee, and we want to map all the man’s clients and employees to Person (Sex == M). This is the look of the BizTalk Server maps:

When we apply the BTM Migration Tool it will generate this nice WABS map for us:

And the good news in this case, if we try the map it will successfully work and it will produce the right output! (Yes I looked for a good sample). However is this the perfect output?

So let’s try to change this to get only the female sex present in the input message. It seems an extremely easy change to make… we just need to go to the Logical Operation present in each MapEach Loop Operation and change the condition

However surprisingly the output instance after this change is empty

So why this happens? In this case, after looking at all the shapes, I found out that the MapEach Loop operation also like the same condition that is present in the Logical Operation that we need to change, as you can see in the picture below:

Can this map be improved?

The aim here is not to explain the functionalities of the new map and how the new operations work, however, if you look at the map generated by the compiler, at least in this case, you can easily identify that we can simplify the map to be more easy to read and to maintain, by:

• Maintaining the condition in the MapEach Loop operation
• Suppress all the Logical and Conditional Assignment Operations that are inside the MapEach Loop operation
• And use direct links to map the Name and Sex

So as a final note, even if the migrator tool did a decent job, you should always try to identify some bottlenecks, problems or overlaps and simplify it

Using Custom XSLT Code

Migrating maps from BizTalk Server solutions to Azure BizTalk Services could be one of the more complex artifacts to migrate (depending on map complexity)… or not!

The good news is that, you don’t necessarily have to remake or migrate our BizTalk map to WABS map. As I mention earlier WABS maps support custom XSLT code, you can use a custom external XSLT file, similar to the “Custom XSLT Path” map grid properties in BizTalk Server to override WABS map and use custom XSLT to make the entire map transformation.

I try to avoid using Custom XSLT files for solving a mapping problem, for many reasons, however, there are always exceptions. I do recommend using custom XSLT files:

• If you are dealing with huge message and High Performance is one of the primary requirements (and even then this maybe can be avoided)
• Or if you already have a custom XSLT file provided by another team, or from another system that you can re-use in your map. In this case, don’t try to reinvent the wheel!

And because we are migrating a BizTalk Server map we already have the XSLT, so for me, there is no point spending a few and in some case many hours trying to remake the same transformation in a different editor.

To extend your WABS maps to use custom XSLT code you must:

• Go to the grid properties (or also call Transform design surface properties) in the Transform Designer, where you can see that there is an XSLT property in which we can extend the map to use custom XSLT code

Note: This time Microsoft did a nice job and if you notice in the grid page there is a message that will help you.

• In Properties, click XSLT, and click the ellipses (…). A Configure XSLT dialog window is opened.

• To import an existing XSLT file, click Import XSLT. Browse to the .xslt or .xsl file and click Open. The imported XSLT populates the Configure XSLT dialog window. OR, enter the XSLT syntax in the Specify the XSLT below … window.

• Optional. To import an existing XML extension file, click Import EXTXML. Browse to the XML file and click Open. The imported XML populates the Specify the extension objects … dialog window. OR, enter the XML syntax in the Specify the extension objects … window.
• Optional. Click Use XslCompiledTransform for better performance to transform XML data by compiling XSLT stylesheets and executing XSLT Transforms. When the style sheet is compiled, it can be cached and reused. Otherwise, the XslTransform class is used; which is best when executing a Transform on one occurrence.
• Click OK.

When XSLT is used, the Transform design surface is grayed out. XSLT can be specified for every Transform file (.trfm).

How do I generate XSL output from the BizTalk Mapper Designer?

To generate an XSLT file that represents you BizTalk Map you just need to:

• Open the BizTalk map in Visual studio
• Right-click on the map and select “Validate Map” option, this operation will generate the XSLT and you can see the path of generated XSLT in the output window.

You can use this XSLT, without change it in most of the cases, to add in your WABS Maps.

Code Samples

All of this sample can be found and downloaded in Microsoft Code Gallery:

• BizTalk Maps can be found here:  BizTalk Server – Basics principles of Maps
• BizTalk Services map samples can be found here: Migrating BizTalk Server maps to Windows Azure BizTalk Services (WABS) maps