Create a Transform or Map


Updated: November 27, 2015

You can define relationships between an input XML document, add Map Operations to modify the data, and then output an XML document. A Transform or map is part of the BizTalk Services SDK template in Visual Studio. See Install Azure BizTalk Services SDK.

In this topic:

Choose your Project type

Add your Schemas

Add your map operations

Design Area Tips and Tricks

More Map Stuff

There are two ways to create a new Transform: Add a map to the BizTalk Service project or create a new BizTalk Service Artifacts project.

When a map is added or created in the BizTalk Service project, it’s part of the project and is meant to be used in the XML One-Way Bridge or the XML Request-Reply Bridge. When you create a BizTalk Service Artifacts project, you are creating a map independent of any other project. When the Transform is complete, it can be saved, added to a business to business agreement, or added to an existing BizTalk Service project.

Many developers prefer to keep their schemas in a central location. In this situation, you can use BizTalk Service Artifacts project to store your schemas and your maps. Then, you save/backup one project and its resources. When you need those schemas or maps, you can simply add them to other projects.

Add a map to an existing BizTalk Services project

  1. Open Visual Studio as Administrator and open your BizTalk Service project.

  2. In the BizTalk Services project, go to Solution Explorer.

  3. Right-click the project, select Add, and select New Item or Existing Item.

  4. Enter your map details and select Add.

After you’re done creating the map, you can add the map to the Transform Stage of the XML bridge. See Create an XML One-Way Bridge or Create an XML Request-Reply Bridge. Uses and Stages of Bridges provides more information on the Transform Stage.

Create a new BizTalk Service Artifacts project

  1. Open Visual Studio as Administrator.

  2. Select New Project.

  3. Expand the Visual C# template and select BizTalk Services.

  4. Select BizTalk Service Artifacts.

  5. Enter the project Name, project Location, Solution name properties, and Create directory for solution preference.

  6. Select OK.

When the project is opened, Map.trfm, Schema1.xsd, and Schema2.xsd are created automatically. These files are blank so you can change them, delete them, or add your own. BizTalk Services Transforms have a .trfm extension and opening a .trfm file opens the Transform designer where you can add schemas, add Map Operations, and draw your links.

You can create and modify schemas using the built-in Schema Editor. After the map is added, add your Source schema (input) and Target schema (output):

  1. Open a BizTalk Services or BizTalk Service Artifacts project in Visual Studio as Administrator.

  2. Add an existing schema (.xsd) or add a new schema (.xsd) to the project:

    1. Right-click the project and select Add.

    2. Select Existing Item to add a schema that is already created. Select New Item, Schema to create a new schema.

  3. Select Add.

  4. Double-click the schema (.xsd) to open the Schema Editor.

Developing EDI Schemas provides information on creating and modifying existing schemas.

After the schemas are added, you can use the built-in Map Operations to change or manipulate the incoming data to match the output schema:

  1. From the Toolbox, click and drag the Map Operation to the Transform designer:

    Double-click the Map Operation to configure the inputs.

  2. Click and drag items from your input schema to the map operations or output schema to create the links. Map Operations support three input source types:

    • Link from a tree node

    • Link from a Map Operation

    • Constant value

  • If a link from a tree node or a Map Operation is not allowed, a message stating the reason is displayed in the Status Bar.

  • Some Map Operations have a Type property in the Configure dialog window. This Type property is read-only.

Cut, Copy & Paste

Map Operations are movable using Cut/Copy and Paste. Links are not movable using Cut/Copy and Paste. If you move a Map Operation using Cut/Copy and Paste, the links are removed.

Map Operations and links cannot be dragged and dropped. 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.

XSLT Support

In a BizTalk Services or BizTalk Service Artifacts project, a Transform (.trfm) file can use XSLT. XSLT options include entering XSLT syntax and importing exiting XSLT files, including XML extension files (EXT XML).

To import an existing XSLT file, select the Transform design area. In Properties, select Import XSLT. You can select a file or directly enter XSLT syntax.

To import an existing XML extension file, select the Transform design area. In Properties, select Import EXTXML. You can select a file or directly enter XML syntax.

Select 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. When this option is not enabled, the XslTransform class is used; which is best when a Transform executes once.

Direct Links with Repeating Records

When linking a repeating record in the source document to a repeating record in the target document, a MapEach Loop is needed. Creating these links from each source node to the target node is often time consuming. As a result, BizTalk Services includes Direct Link functionality.

Direct Linking is simply copying from an input node to an output node, with no other processing. Direct Linking is also used when linking non-repeating records; which does not require a MapEach Loop.

Loop Map Operations - Usage and Examples describes the Direct Link functionality.


Scrolling vertically in the Transform Designer can be done in two ways:

  • Scroll the mouse wheel

  • Using the Up and Down arrow keys

Scrolling horizontally in the Transform Designer can be done in two ways:

  • Hold down the SHIFT key + scroll the mouse wheel

  • Using the Left and Right arrow keys

Drawing Surface

The drawing surface in the Transform Designer has a default size of 200*200 cells. To modify the size:

  1. Go to the Tools menu and select Options.

  2. Expand Transforms Designer and click General.

  3. Modify the Number of Grid Cells on the X axis of the Grid Surface and the Number of Grid Cells on the Y axis of the Grid Surface values. Values range from 100 to 1000.

  4. Click OK.


Pages can be added, deleted and renamed within the Transform design surface. Map Operations and their scope containers are per page.

To add, remove, or rename a page, right-click the Page 1 tab at the bottom of the design surface to view the available options.