In the previous installment of this series on refactoring BizTalk maps I discussed how you could take the easy road to ensure your maps work when the target namespace of your schema changes, or if the schema is moved to a different project or had it’s .NET type name changed. In this new entry to the series we will explore further variations on scenarios that could force you to tread down the refactoring path.

A question was posed to me on the previous installment on how best one should identify when a map needs to be refactored. In most cases when a schema changes and you open a map you will see a warning message advising that some links might have been lost as the referenced nodes do not exist in the schema (make sure you don’t save the map after seeing this dialog box or you will lose out on your chance to refactor). However if your map makes use of an external XSLT file then you will not get such an obvious indication that refactoring is necessary. I would suggest that regression unit testing is the way to go to identify that a map needs to be refactored, and I suggest you read my previous post discussing the BizTalk Map Testing Framework (keep in mind that there are alternative means to test your maps but this is my favorite) if you want a primer on this.

Disclaimer : when manually editing any BizTalk artifacts (only recommended for schemas and maps) you should always make sure that you have checked in a prior working version of your source code to a source control repository or made a copy of the components in a safe location. Proceed with caution.


Refactoring for changes to root node names in one of your schemas

This is one of the most common refactoring scenario faced when dealing with BizTalk maps, especially in the early stages of development while specifications are still more fluid than a developer might like them to be. Let’s assume that to start with the map looks like the below (note that while the root node on the source and destination messages are both called source, these are based on different schemas and have different target namespaces).


Now what if the root node name on the destination schema is changed from source to destination. If you try to open the map using the default map designer then you will see that all the links to the destination message have broken. As in the previous examples you will want to open the map in XML view (using your favorite XML editor or by right clicking on the map in Visual Studio and choosing Open With -> XML (Text) Editor), paying particular attention to the sections I have highlighted in the below screenshot.


The first section you will want to pay attention to will be the TrgTree node (it would have been SrcTree if the change was to our source schema), changing the value of the RootNode_Name attribute to the new root node name. The next thing you will want to do is to do a find/replace all searching for the XPath statements to the root node contained within the LinkTo (it would be LinkFrom if the change was to our source schema). In this case we would be performing a find/replace as below.


Once the above has been done you should once again be able to open the map using the default map designer.


Refactoring for changes to record/element/attribute names in one of your schemas

Refactoring for changes to record/element/attribute names in schemas is definitely the most common refactoring scenario that one would encounter. While a change to the name of a single element that is only used once in a simple map might not cause many problems to the developer and he should opt to fix up his map using the designer, oftentimes maps can be very complex and there might be many links to or from the same element which the developer does not want to revisit. Of course if a record name were to change then that would cause all the links to/from underlying elements to break as well and most developers will want to avoid this scenario at all costs.

Lets start by exploring changes to a record name using the below starting point (note that AnAttribute in the source schema is an aptly named attribute).


If we have changed the name of the Dates record in the source schema to RelevantDates then we would once again have to open up the map in an XML Viewer.


In this case we can be pretty confident that there is only one node named Dates so we could theoretically even just do a find/replace which replaces all instances of the word Dates with RelevantDates and that would get us going. It would be a lot safer to run the below find/replace (replacing the XPath contained within the LinkFrom attribute to the changed record), after which we could once again open our map in the map designer and all our links would be preserved.


To demonstrate refactoring to cater for a changed element name lets assume that the name of the destination element called Element2 has changed to Age. Once again lets open the map in an XML view.


Once again we could simply do a search for Element2 and replace it with Age, but the safer way to approach this is to do a find/replace on the XPath statement in the LinkTo attribute right from the root element to the changing node as below.


If we wanted to change the attribute called AnAttribute in the source schema to DateOfMarriage then we would see that the process is not much different from that encountered while refactoring for changed element names. The below find/replace would do the trick.



As would be evident to anyone who reads the blog posts in these series, maps are heavily based on XPath and the better you understand XPath syntax the more power you will have when dealing with BizTalk maps, and XML in general. I would definitely recommend using the DanSharp XmlViewer tool which is probably the #1 tool I could not live without while doing BizTalk development.