Tutorial- Maps

Module 4: Creating BizTalk Maps

• Introduction of BizTalk Map
• Creating a BizTalk Map
• Manipulating Data Using Functoids
• Test Mapping

Introduction of BizTalk Map:

BizTalk maps are graphical representation of XSLT to perform transformation between XML messages in simple & visual manner.

BizTalk Mapper is a tool that runs within the Microsoft Visual Studio environment. BizTalk Mapper can be used to create and edit maps, which are used for translating or transforming xml messages. Maps are used in orchestrations, receive port, and send port(s). Maps enable you to translate and to transform messages. Translation is the process of converting a message from one format to another format.

Part of BizTalk Mapper:

The following figure shows various parts of BizTalk Mapper within Visual Studio.

The functionality of each of the views is as follows:

• Visual Studio Mapper Utility Ribbon. The BizTalk Server Mapper provides a utility ribbon to surface Mapper-related commands. The ribbon provides source schema information, toggle button for relevance view for source and destination schemas, toggle button to show or hide totally out of scope links, toggle switch to turn auto-scrolling on or off, button to pan the Mapper surface, controls to zoom in or zoom out, and the search text box. The following figure shows the utility ribbon you can see at the top of the grid page.

Source schema tree view. This is the tree view of the source message and is found on the left side of the main window

Destination schema tree view. This is the tree view of the target message and is found on the right side of the main window. The links that define the mapping lead into the destination schema tree view from the grid view, and ultimately from the source schema tree view.

Grid view.  this view plays a critical role in the definition of maps, containing the links and functoids that control how data in a source instance message is transformed into an instance message that conforms to the destination schema.

The grid view can have multiple layers, called grid pages, allowing you to organize complex maps into logical subdivisions of mappings. Grid pages generally use more space than can be displayed at one time, and there are several effective ways to scroll within a grid page.

Visual Studio Toolbox window. You use this view to display the functoids available for use in BizTalk maps, and as the source of the drag-and-drop operations to place functoids in a grid page. The functoids shown in the Toolbox are organized according to their categories.

Property view: In this window, we can view and modify the properties of a selected object on the mapper grid or in the schemas. This is usually available on the right of the destination schema.

Creating a BizTalk map:

There are two types of mapping in BizTalk for message transformation.

1. One-To-One Mapping: this is most commonly used. In this there is one source schema & one destination schema. Below is the sample picture for the same. This map can be applied in Orchestration, receive & send ports.

In this map you need to add source & destination schema and apply link in between them. Also, you can use functoid for data manipulation.

2. Many to One Mapping: This mapping can only apply in orchestration. There will be multiple Input message and one output in this mapping, and it is not applicable for receive port or send port.     

• Create all the message types you need (all the input messages and the output message)
• Create an orchestration.
• Drag a construct message shape and a transform shape onto there.
• Configure the transform shape and add all your input messages to the Transform Source list

• Set the output message as usual and click OK
• A map file should appear in your project. Open it
• You will see on the left-hand side all you input messages are now available in the mapper (under Root/InputMessagePart_1, _2, etc)

Now you can start linking source to destination in mapping.

Manipulating Data Using Functoids

BizTalk mapping provides toolbox for better and advance mapping. Which are helpful to create mapping or transformation in easy way without knowledge of XSLT. For functoid details, you need to drag & drop functoid into grid and open that by double click. Functoid work details will be mentioned. In below screenshot Script functoid is defined.

the Functoids are organized into nine categories based on their intended purpose:

• Advanced Functoids: used to create various types of data manipulation, such as implementing custom script (C#, Visual Basic .NET, XSLT), value mapping, and managing and extracting data from looping records.

• Conversion Functoids: used to convert data, such as: convert ASCII to characters or to convert numbers from one base to another (hex, decimal).

• Cumulative Functoids: used to perform various types of accumulation operations for values that occur multiple times within an instance message.

• Database Functoids: used to look up data from a database and to perform simple cross-referencing operations (sometimes called ID mapping).

• Date and Time Functoids: this is a set of operations applicable on dates like, add date, time, date and time, or add days to a specified date, in output data.

• Logical Functoids: used to conditionally control the behavior of other Functoids and to determine whether output data is created.

• Mathematical Functoids: used to perform specific numeric calculations such as addition, multiplication, and division.

• Scientific Functoids: used to perform specific scientific calculations such as logarithmic, exponential, and trigonometric functions.

• String Functoids: used to manipulate data strings (text alphanumeric) by using well-known string functions such as concatenation, length, find, and trim.

If you have deleted the functoid by mistake or need to add custom functoid, then you can resume them back as below:

Right click on toolbox and select Choose Items as below:

And select as below:

If you want to know more about Functoids, please refer the following resources:

• Functoid Reference (http://msdn.microsoft.com/en-us/library/aa561783.aspx)
• Functoids in Maps (http://msdn.microsoft.com/en-us/library/aa547582.aspx)
• Developing Custom Functoids (http://msdn.microsoft.com/en-us/library/aa560879.aspx)
• BizTalk Mapper Extensions Utility Pack (http://btsmapextutilitypack.codeplex.com/)

Test Mapping:

Microsoft has provided great feature in mapping. We can test mapping before deployment that everything is running fine or not.

Right click on map in solution explorer. There are three tabs showing as below:

1. Test Map: it will test the map. You can provide input xml path in TestMap input instance tab into Test Map section in properties. And change the TestMap input from General Instance to XML. Below is the output when we run the Test Map.

2. Validate Map: it willgenerate the xsl file for the mapping. You can use this file as reference whenever require creating custom xslt for mapping. Sometimes we use custom scripts (C# and XSLT) inside our maps and sometimes we make use of external XSLT files to perform the transformation. In these cases, Validate Map is an important operation that will allow us to validate the structure and syntax of the map. It will also provide us with another way to inspect and analyze the XSLT code generated by the compiler, thereby providing us with more information on how the maps work and with an option to debug maps inside the XSLT code.

3. Debug Map: BizTalkmapping background is xslt. So, you can debug and check the mapping This option allows us to debug a map, thereby facilitating the identification and correction of complex mapping problems at design time. Debugging a map is straightforward and can be useful in many situations.

Note: Some time the input message xml files BizTalk receive and the schema which has already developed, may not match due to schema prefix or element data type that why it failed in map mostly it happens in development environment. And we face issue when we test xml file into map. Mapping does not success and fails due to some schema validation. Before testing the xml file into test map. Just verify the xml files in schema via validate instance. If verification success, then proceed for mapping test.