Transforms/Maps Best Practices

 

Important

Microsoft Azure BizTalk Services (MABS) is being retired, and replaced with Azure Logic Apps. If you currently use MABS, then Move from BizTalk Services to Logic Appsprovides some guidance on moving your integration solutions to Logic Apps.

If you're brand new to Logic Apps, then we suggest getting started here:

• What are logic apps

• Create your first logic app, or quickly get started using a pre-built template

• View all the available connectors you can use in your logic apps

Label and Comment Properties	When configuring a Map Operation, modify the Label property to name each Map Operation. Populate the Comment property with specific details, especially the MapEach and ForEach Map Operations: See Image 1, below This Label name is used in the breadcrumb trail. It is very important to change the Label name. Also, the Search feature can be used to find a specific Map Operation by the Label name or text within the Comment property.
Breadcrumb Trail	When creating links and adding Map Operations, use the Breadcrumb trail to determine the current scope container. At the bottom of the Transform Design surface, the scope hierarchy is displayed in the breadcrumb trail. The current scope is the last item in the breadcrumb trail. When a MapEach Loop scope is set, the breadcrumb trail is updated to reflect the current hierarchy. In the example below, the Employee Mapping MapEach Loop is the last item in the breadcrumb trail so it is the current set scope. Any Map Operations added or links created are under the Employee Mapping scope: See Image 2, below Using Scope in a Loop - How To provides more specific details.
Sample Input File	Before starting to create a Transform, have a sample input.xml file ready to test the Transform.
Build in Increments	Build the Transform incrementally. Once portions of the Transform are built, save it and fix any errors. Test the Transform using the Test Map feature.
Set Scope	Set the correct working scope container when creating a Transform. Remember, working scope is indicated by the last item in the breadcrumb trail at the top of the Transform Designer surface. To set scope, refer to Using Scope in a Loop - How To.
Creating Links	Creating a link from a source to a target is left to right. Any link made from right to left considers left as the source and right as the target. Any link made from left to right considers left as the source and right as the target.
Direct Links	To link source and target nodes with similar node structure or node names, use the Direct Link feature. Direct Linking can be used with repeating records and non-repeating records. See Loop Map Operations - Usage and Examples for more information.
Test the Transform	Use the Test Map Input File and Test Map Output File properties of the Transform in Visual Studio: Select the Transform (.trfm) file in Solution Explorer. In Properties, click Test Map Input File and browse to the sample input.xml. Click Open. In Properties, click Test Map Output File and browse to the sample output.xml. Click Open. Right-click the Transform in Solution Explorer and select Test Map. The Output window displays the result. Tip If a Transform contains a Get Context Property Map Operation, a Test Data for context property window displays. In this window, you can enter a temporary value for the context property to test the Transform.

Image 1

Image 2

SCOPE/LOOP BEST PRACTICES

Containing Scope	Every Map Operation and link has a Containing Scope property. The Containing Scope property indicates the parent scope container. Use this property to help determine the current parent scope container.
Container	Each container can be minimized and expanded. Setting scope on a MapEach Loop can be done when the container is expanded. Modifying links are done when the container is minimized or expanded. Minimizing the container automatically unsets the scope. Minimizing the container also provides a larger design surface.
Ambiguous Links	If the Transform Designer determines that the scope of a link or a Map Operation is ambiguous when the link or Map Operation is created, an error is flagged when compiled. All errors are flagged during Transform compilation and when loading a fresh Transform.
Error & Data Handling	Error Handling and Null/Empty Data Handling behavior is configurable for the Transform Runtime. To customize how your application handles these scenarios, configure these settings in the individual Map Operations in the Visual Studio project.
Home Link	Selecting Home in the breadcrumb trail puts the Transform at the Home (Page) scope. No scope is set and the Containing Scope property displays None.
Move To Working Scope	When moving links and Map Operations, refer to the highlight propagation and the Containing Scope property to determine the parent and child scope containers.
Sibling and Children	Operations in a scope can use the source elements and Map Operations available in its scope and its parent hierarchy. Elements and Map Operations in a sibling or child scope cannot be used.
Ctrl + Select	To move Map Operations and their links, use Ctrl + Click to select the items to move. Ctrl + Click cuts the items and then you paste to the desired location.
Repeating Record with Direct Linking	Draw a link from a repeating record in the source document to the repeating record in the target document. When doing this, you can create direct links by node name and structure. For other options, go to Loop Map Operations - Usage and Examples.

More Transforms topics

Convert a BizTalk map to a BizTalk Services Transform

Use standard XSD constructs in your maps

Loop and Scope Examples in map or transforms

Azure BizTalk Services Resources on the TechNet Wiki