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

Posted: February 23, 2014 in BizTalk, BizTalk as PaaS, Integration
Tags: , , , , , , , ,

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 doesn’t exist in BizTalk Server like: several List Operations, DateTimeReformat, GetContextProperty and so on. And despise 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 this 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 produces 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.

At 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 a 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)

BTM-Migration-Tool-cmd

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 look of the BizTalk Server maps:

BizTalk-Server-map-sample-to-WABS

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

BizTalk-Services-map-sample-from-BTS

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

So let’s try 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

BizTalk-Services-Logical-Operation-WABS-Condition

However surprisingly the output instance after this change is empty

WABS-map-empty-result

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

BizTalk-Services-MapEach-Loop-Operation-WABS-Condition

Can this map be improved?

The aim here is not to explain the functionalities of the new map and how the new operations works, 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

BizTalk-Services-map-improved-from-BTS

BizTalk-Services-MapEach-Loop-Operation-WABS-Condition-2

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 necessary 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 exception. 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 avoid)
  • 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 a XSLT property in which we can extend the map to use custom XSLT code

BizTalk-Services-WABS-map-Transform-design-surface

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

Transform-design-surface-message

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

BizTalk-Services-configure-XSLT

  • 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.

BizTalk-Services-configure-XSLT-import

  • 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 style sheets 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).

BizTalk-Services-WABS-map-Transform-design-surface-XSLT

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

To generate a XSLT file that represent 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 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:

Comments
  1. Hi Sandro,

    This blog is amazing. Thanks for sharing all this for the resources being very scarce on BizTalk.

    A FAN
    Regards
    Singh

  2. Biz Daniel says:

    Hi Sandro,
    the Extension Object XML doesn’t work! I have tried to use an xml associated to a DLL referenced to project, but during the build phase, I receive Always the same message of failure “The assembly ‘xxxxxx’ referenced in the Extension Objects XML is not present in the project references”.
    The assembly xxxx is referenced to project (it is included among the project references).
    This simple thing is versy frustrating!😦

    Can you suggest me anything ?
    Tnxs in advance

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s