Module 3: Creating Maps
Time estimated: 90 minutes
Module objective:
In this module, you will learn how to:
Create a BizTalk map and configure functoids to manipulate data within a map.
Overview
Using the Microsoft BizTalk Mapper, you define the relationship between an input and an
output schema using links and functoids. A link defines a direct data copy of a record or field.
Links may directly connect to items in the other schema, or they may form connections to
functoids. Functoids perform more complex data manipulations. This module discusses the role
played by Microsoft BizTalk maps in the BizTalk Server architecture and how to work with maps
and functoids.
Lesson 1: Creating a BizTalk Map
Lesson objective:
Create basic and complex BizTalk maps and validate a map.
Lesson Overview
When building enterprise application–integration solutions, it is usually necessary to convert
between different message types. This could be done by simply converting all of the data from a
trading partner’s format for a purchase order to your company’s internal messaging format. In
other cases, only some of the information from an incoming message may be required. For
example, the information from an incoming purchase order may be used to create a related
invoice. Maps can be applied during run time by the BizTalk messaging engine, or, as you will see
in later modules, within an orchestration.
In this lesson, students will learn how maps are used by BizTalk and how to use the BizTalk
Mapper to create a map. Students will also learn how to use shortcuts to simplify the map
creation process.
What Is a BizTalk Map?
Describe the purpose of a map and explain the difference between transformation and translation.
Terminology

Map. You create a map when you want to transform or translate data between message
formats.

BizTalk Mapper. A visual tool, hosted within Microsoft Visual Studio®, for constructing
BizTalk maps, which define data transformations.

Data transformation. The process of converting an XML document that conforms to one
schema into an XML document that conforms to another schema. A transformation can
simply change the formatting applied to the data, but more often, data transformation
results in some kind of structural change to the document. For example, a system that
automates purchase order processing will typically transform purchase order records
into one or more invoices.

BizTalk map. A file that defines the correspondence between the records and fields in
one schema and the records and fields in another schema. BizTalk maps are
implemented in XML Extensible Stylesheet Language Transformations (XSLT).

Extensible Stylesheet Language Transformations (XSLT). An industry-standard
specification defined by the World Wide Web Consortium (WC3) for expressing
transformations between two documents. The XSLT generated by BizTalk is fully W3C
compliant.

Data translation. A special case of data transformation that involves changing the
format of an instance message, typically from non-XML (EDI or flat-file) to XML format,
or vice versa. For example, if your internal processes utilize XML data, but your trading
partner needs to receive messages in a flat-file format, you can perform the necessary
translation before you send such messages to the trading partner. Data translation can
be especially helpful in solving enterprise application integration problems by rendering
a given type of message into alternative formats required by existing systems.

Functoid. An executable module that performs a specific calculation or data
manipulation. Functoids provide BizTalk map developers with the ability to create richer
transformations than what is provided by XSLT on its own.
Use Cases
In addition to simple value mapping, the transformation process can include such operations as:

Flattening records received in a message that has a hierarchical format to one with a
flatter design.

Averaging data from multiple input nodes and sending the output to a single field in the
destination message.

Applying mathematical functions on values in the source message and then writing the
result to the destination message.

Concatenating multiple elements from the source message into a single field in the
destination message.

Looking up a value from the source message in a database or an in-memory table and
extracting new values to be written to the destination message.
Creating a Map by Using the BizTalk Mapper
Explain how the BizTalk Mapper works to create maps and how maps are compiled as XSLT files.
Starting the BizTalk Mapper Tool
The BizTalk Mapper tool, which is integrated into Visual Studio 2010, starts automatically when
you either add a new map to a BizTalk project or open an existing map (a .btm file). To create a
map, you must specify the source schema and the destination schema. The source and
destination schemas must either be part of the current BizTalk project or be in a referenced
assembly.
BizTalk Mapper Views
The BizTalk Mapper view consists of three panes within the Visual Studio interface:

Source schema pane. Displays the schema of incoming instance messages. The links that
define the mapping originate from the source schema tree view, passing through the
map zone and ultimately to the destination schema tree view.

Map grid view pane. Shows the links and functoids that control how data in a source
instance message is transformed to the destination schema. You work actively in this
view to construct your map. The map grid can have multiple pages, which can also be
named. This is helpful as maps become more complex.

Destination schema pane. Provides a tree view of an instance message as it will look
after being processed by a BizTalk Server destination schema.
Mapper Improvements
With the release of Microsoft BizTalk Server 2010, the BizTalk Mapper has been improved with a
new user interface that eases development of large. The new BizTalk Mapper improves
productivity by adding cut, copy, paste, move and undo functions and improved support for
search and readability. The new search feature highlights source and destination schema nodes,
and functoids containing text that match the search criteria.
Readability improvements include new pan and zoom features, and automatic panning that
brings all of the relevant links and functoids in to view when a user clicks on schema node. The
new mapper also hides or dims background schema nodes, links and functoids that are not
relevant to the user’s current selection.
Generating XSLT from a Map
Before the map can be used by BizTalk, the project containing the map needs to be built
(compiled) into an assembly. As you develop a map, BizTalk will generate compiler errors if it
encounters any type mismatches between the source and destination schemas. XSLT is
generated from the map when the project is built, and the XSLT code is executed when the map
is applied during run time.
Validation Considerations During Run Time
During run time, because maps do not perform validation on the inbound or outbound
messages, a map could potentially generate an invalid outbound message. For this reason,
source data should be validated against an XSD schema prior to being inserted into any process
that uses maps.
Creating Links
Use the BizTalk Mapper to automate the process of linking nodes within a map.
How to Specify Links
You can specify each individual link between two schemas yourself, or you can allow the BizTalk
Mapper to specify links automatically. When you allow the BizTalk Mapper to automatically
specify links, you must still choose between two options: Link by Name, or Link by Structure.
BizTalk Mapper Link Types
The BizTalk Mapper supports the following types of linking:

Simple linking. Use simple linking between individual nodes. To create a simple link,
drag a node from the source schema, and then drop it onto the target node in the
destination schema.

Structure linking. Use structure linking when the structure of the records being linked in
your source and destination schemas are the same or very similar. Structure linking can
be applied to the entire schemas or just to parts of each. By performing a structure link
from a record in a source to a record in a destination schema, the subordinate nodes
will automatically be linked. To create a structure link between portions of your source
and destination schemas that have matching structures, hold the SHIFT key while linking
the relevant records. After you link the records, links are automatically created for all of
the subordinate records and fields for which a match is found.

Name-matching linking. Use name-matching linking when the structure of the records
being linked in your source and destination schemas are somewhat similar and have
matching record and field names, but have more structural exceptions than would be
practicable for structure linking. The new BizTalk 2010 Mapper employs a new
predictive name matching algorithm that creates links between nodes that have similar
names, and are likely matches, even though the names may not be exact matches.
Any links created by using complex linking are no different from links that are created manually.
They can be deleted and relinked.
Basic and Complex Map Links
Identify the differences between a basic and a complex map.
Overview
The BizTalk Mapper provides a solution for a variety of mapping scenarios, ranging from simple
parent-child tree-type operations to detailed operations that are complex and involve looping
records and hierarchies. Almost all mapping scenarios can fit into one of two categories: basic
mapping and complex mapping.
Basic Mapping
Basic mapping is the most common type of mapping. It involves copying a value from an
element or attribute that occurs once in an input instance message to an element or attribute
that occurs once in an output instance message. In the corresponding source and destination
schemas, the record or field node that corresponds to the element or attribute and all of its
ancestors will be specified such that the element or attribute appears in the instance messages
once and only once.
Complex Mapping
Complex mapping involves records or fields that can occur multiple times for a single instance of
the Record or Field Element node in the schema tree. This type of variable count mapping is
called looping. You create this type of mapping by linking a field in a looping record in the source
schema to a field in a looping record in the destination schema. The number of corresponding
elements in an input instance message will then dictate the number of elements created in the
output instance message. Another type of complex mapping occurs when a record or element
occurs only once in the source schema but must be mapped to repeating nodes in the
destination schema.
Validating, Testing and Debugging a Map
Validate and test a map.
Validating a Map
Before a map is deployed, it should be tested to ensure that the resulting message contains the
desired results. The BizTalk Mapper provides the tools for validating a map and testing a map
with sample data, much as can be done with schemas.
In BizTalk Server 2010, the mapping of small messages occurs in memory. For performance
reasons, by default, mapping (which is a very memory-intensive operation) does not perform
data validation when executed in a pipeline. However, you can create a custom pipeline and use
the XML validator component to perform validation before and after mapping within the
pipeline. A new feature in BizTalk Server 2010 enables the ability to perform large message
mapping, which uses disk cache in addition to memory.
To validate a map, simply right-click the map in Solution Explorer, and then click Validate Map.
The Output pane will display a link with an .xsl extension that displays the actual XSTL output
generated by the map. This can be useful for troubleshooting execution problems with the map.
Testing a Map
Before you can test a map, you need to specify the type and location of an instance message to
be used for testing. Several properties need to be configured, which are set in the .NET
properties for the map. The .NET properties, as distinguished from the BizTalk properties, are
accessed by right-clicking the map in Solution Explorer, and then clicking Properties.

Validate TestMap Input. Specifies that the input message should be validated.

Validate TestMap Output. Specifies that the output message should be validated.

TestMap Input Instance. This is the message that you will use as the source message
instance for the map. This instance should be validated using the schema validation
steps described in Module 2, “Creating Schemas.”

TestMap Input. This specifies the format of the test message (XML, Native, or
Generated Instance). Native specifies that Visual Studio must convert the input file from
flat file format to XML before executing the map.

TestMap Output. This specifies the format of the test message (XML or Native).

TestMap Output Instance. Specifies the file location for the message to be written to. If
the file exists in the same location, it will be overwritten.
After configuring the test properties, right-click the map in Solution Explorer, and then click Test
Map. A link to the input and output message will be shown.
Demonstration: Creating and Testing a BizTalk Map
Learn how to create a map by using the BizTalk Mapper tool and how to create simple and
automated links. You will then see how to test and validate a map.
Create a BizTalk Map
1. In Microsoft Windows Explorer, navigate to C:\AllFiles\DemoCode\Module3\Demo,
and then double-click Demo.sln.
The following demonstration is not dependent upon completion of the previous
demonstrations. This solution provides artifacts and file paths that differ from those
used in the previous demonstrations.
2. In Solution Explorer, right-click the Messaging project, point to Add, and then click New
Item.
3. In the Add New Item dialog box, in the center pane, click Map, in the Name box, type
PurchaseOrderFF_to_PurchaseOrder.btm, and then click Add.
The map opens in the BizTalk Mapper.
4. Click the Open Source Schema link.
5. In the BizTalk Type Picker dialog box, expand Messaging, expand Schemas, and then
double-click Demo.Messaging.PurchaseOrderFF.
6. Click the Open Destination Schema link.
7. In the BizTalk Type Picker dialog box, expand Messaging, expand Schemas, and then
double-click Demo.Messaging.PurchaseOrder.
8. In the BizTalk Mapper, right-click the <Schema> node of the Source Schema, and then
click Expand Tree Node.
9. In the BizTalk Mapper, right-click the <Schema> node of the Destination Schema, and
then click Expand Tree Node.
10. While holding the SHIFT key, drag and drop the Address node from the Source Schema
to the Address node in the Destination Schema, then click Link by Structure.
The nodes are mapped according to the structure of the nodes.
11. While holding the SHIFT key, drag and drop the Item node from the Source Schema to
the Item node in the Destination Schema, then click Link by Name
Only the nodes with identical names are mapped.
12. Drag the ISBN node from the Source Schema to the SKU node in the Destination
Schema.
Test a BizTalk Map
1. In Windows Explorer, navigate to C:\AllFiles\DemoCode\Module3, and then doubleclick Message1.xml.
2. Examine the structure and content of the message. The new map will create messages
similar to this one. Close Microsoft Internet Explorer.
3. In Solution Explorer, right-click PurchaseOrderFF_to_PurchaseOrder.btm, and then click
Properties.
4. In the Properties window, in the TestMap Input list, click Native.
5. In the Properties window, click TestMap Input Instance, and then click the ellipsis (…)
button.
6. In the Select Input File dialog box, navigate to C:\AllFiles\Democode\Module3, click
Message1FF.txt, and then click Open.
7. On the File menu, click Save All.
8. On the In Solution Explorer, right-click PurchaseOrderFF_to_PurchaseOrder.btm, and
then click Test Map.
9. In the Output window, scroll to the right, and then while holding the CTRL key, click the
link to the right of The output is stored in the following file.
Ignore the warnings and errors you receive. They will be resolved when the map is
completed in the upcoming demonstrations.
10. Examine the message that appears, and then close it.
11. Pause the bt10d-demos virtual machine.
Lesson 2: Configuring Basic Functoids
Lesson objective:
Create and configure functoids to manipulate data within a map
Lesson Overview
Whereas linking provides for copying values from one message to another, functoids allow the
manipulation of the data contained in the message. There are approximately 70 functoids that
provide simple mathematical functions, string manipulation and date and time insertion, and
complex scientific calculations.
Data Manipulation with Functoids
Identify the types of data manipulations that can be performed by a functoid.
About Functoids
A functoid is an executable module that performs a specific calculation or data manipulation. A
functoid can be used graphically when constructing BizTalk Server maps to provide the basis for
richer transformations than what is provided by XSLT on its own.
The BizTalk functoids allow you to extend the functionality of the map to perform a variety of
operations on data as the data is being transformed from the source message to the destination
message.
The most common use of a functoid is to perform numeric calculations, such as summing the
total number of products ordered. Functoids that can have zero or more inbound links can be
chained to provide additional functionality.
Writing Custom Functoids
In addition to using the predefined functoids, you can also write your own functoid as a script
file or a .NET assembly. The BizTalk SDK has examples on how to use both scripting functoids
and how to create custom functoids.
Note: Many functoids require input parameters, so if a parameter is not valid, a default value
will be passed to the functoid in its place. The default value for numeric input parameters is zero
(0), and for all other inputs, the default is blank.
The output of a map validation will result in a link that will show the XSLT code generated by the
map. This will include the manipulations being performed by the functoids.
Using Basic Functoids
Perform data manipulation by using a basic functoid.
Basic Functoids
There are over 70 predefined functoids included with the BizTalk Mapper. These functoids can
perform such operations as calculations including multiplication and division, adding the current
date and time to an output instance message, and concatenating multiple strings together to
form one node in the destination side of the map. The basic functoid categories for predefined
functoids include:

Conversion. Use the Conversion functoids to perform conversions between numeric
bases, such as from hexadecimal to decimal.

Cumulative. Use the Cumulative functoids to perform accumulation operations for
values that occur multiple times within an instance message.

Date and Time. Use the Date and Time functoids to introduce the current date, time, or
both into the message or to add days to a specified date, in output data. This enables
you to insert the processed date (and time) into a message or calculate an anticipated
ship date.

Logical. Use the Logical functoids either to perform specific logical tests at run time or
determine whether output instance data is created at run time. Returns a string (True or
False).

Mathematical. Use the Mathematical functoids to perform calculations by using specific
values (arguments) in a specified order or structure.

Scientific. Use the Scientific functoids to convert a numeric value to a scientific value.
For example, the Cosine functoid takes a value in radians from a field or record and
returns the value of the cosine.

String. Use the String functoids to manipulate data strings by using string functions. The
String Concatenate functoid combines two or more inputs (nodes, constants, or other
functoids) and builds a string. The String Find functoid finds one text string within
another text string and returns the position of the first character of the found string.
Adding Functoids to a Map
Use the BizTalk Mapper to add and configure a functoid.
Adding Functoids
To add functoids to a map, drag a functoid from the Toolbox to the map grid, link a node in the
source schema to the functoid, and then link the functoid to a node in the target schema. You
can also chain functoids to provide a more complex result. For example, a multiplication
functoid could obtain the product of Quantity times Price for each instance of a product in an
inbound message and then add the total to a node in a destination message.
Note: Functoid linking works only from left to right. That is, you cannot link from a functoid back
to a source schema node nor to another functoid that is located to the left of the source
functoid; you can link only from the source schema node to the functoid.
Functoid Properties
The properties of each functoid are displayed in the Visual Studio Properties window when that
functoid is selected in the map zone layer. All functoid properties are categorized as general
properties and are listed in the order in which they appear in the Properties window, regardless
of whether they are being displayed alphabetically or by category.
Functoid properties can be categorized as follows:

Label. The Label property available for links and functoids provides a mechanism for
assigning a descriptive name, which can be extremely useful in map maintenance.

Input Parameters. The Input Parameters property provides access to the Configure
Functoid dialog box, which provides access to all of the functoid properties, including
inputs, label, comments and a functoid description which explains the usage of the
functoid, and lists required inputs.

Name, Help, Maximum Input Parameters, and Minimum Input Parameters. These
properties are always read-only and are informational in nature.
Note: For more information, see the Functoid Reference, provided in BizTalk Server 2010 Help.
Using Map Grid Pages
Use map grid pages to manage large and complex maps.
Map Pages
Maps for many types of business documents can require large numbers of links and functoids,
rendering the map grid complex and difficult to understand. For improved readability, you can
create separate map grid pages to isolate logical groupings of mapping operations into separate
pages. You can then view and work with each grouping individually.
You can add new pages, rename pages, delete pages, reorder pages, and move between and
within them. Map execution is non-deterministic with map pages. In other words, the mapping
will not occur in a top-down or bottom-up order. Similarly, functoids on page 1 are not
necessarily executed before the ones on page 2.
Note: All functoids that are connected together must reside on the same page. Also, if you
delete a grid page, you delete all the links and functoids on that page. The new BizTalk 2010
Mapper allows you to cut/copy and paste links and functoids from one map page to another.
Demonstration: Adding Functoids to a Map
Learn how to add a map page and functoids to a map. You will then see how to test the map to verify
that the functoids are behaving properly.
Add a New Page to a Map
1. Resume the bt10d-demos virtual machine.
2. If it is not open already, in Solution Explorer, double-click
PurchaseOrderFF_to_PurchaseOrder.btm to open the map.
3. Right-click the Page 1 tab at the bottom of the map grid, and then click Rename Page.
4. Rename the page to Links.
5. Right-click next to the Links tab at the bottom of the map grid, and then click Add Page.
6. Right-click the Page 1 tab at the bottom of the map grid, and then click Rename Page.
7. Rename the page to Functoids.
Having multiple map pages helps to keep the map organized.
Add a String Concatenate Functoid
1. From the Toolbox, drag a String Concatenate functoid to the map grid of the Functoids
page.
2. Double-click the String Concatenate functoid on the map grid.
3. In the Configure String Concatenate Functoid dialog box, read the Functoid description,
and then click OK.
4. Connect the LastName node from the Source Schema to the String Concatenate
functoid.
5. Connect the FirstName node from the Source Schema to the String Concatenate
functoid.
6. Double-click the String Concatenate functoid.
7. In the Configure String Concatenate Functoid dialog box, click the Insert new
parameter button (second button from the left).
8. In the parameter, type a comma and then a space (, ).
9. Click OK, then click on the map grid to deselect the String Concatenate functoid.
10. Connect the String Concatenate functoid to the Name node in the Destination Schema.
Add a Multiplication Functoid
1. From the Toolbox, drag a Multiplication functoid to the map grid.
2. Connect the Price node in the Source Schema to the Multiplication functoid.
3. Connect the Qty node in the Source Schema to the Multiplication functoid.
4. Connect the Multiplication functoid to the ExtendedPrice node in the Destination
Schema.
Add a Cumulative Sum Functoid
1. From the Toolbox, drag a Cumulative Sum functoid to the map grid.
2. Connect the Multiplication functoid to the Cumulative Sum functoid.
3. Connect the Cumulative Sum functoid to the OrderTotal node of the Destination
Schema.
Test the Map
1. In Solution Explorer, right-click PurchaseOrderFF_to_PurchaseOrder.btm, and then click
Test Map.
2. In the Output window, scroll to the right, and then while holding the CTRL key, click the
link to the right of The output is stored in the following file.
3. Examine the output message.
Notice that the Customer Name is displayed as Harris, Keith, the ExtendedPrice for
each line item is the product of Price and Quantity, and the OrderTotal is the
cumulative sum of the line items.
4. On the File menu, click Save All.
5. Pause the bt10d-demos virtual machine.
Lesson 3: Configuring Advanced Functoids
Lesson objective:
Create and configure advanced functoids for complex mapping operations
Lesson Overview
Advanced functoids allow more complex types of mapping. For example, you can look up
information in a database or you can call a custom .NET component to accomplish businessspecific tasks.
Using Advanced Functoids
Perform data manipulation by using advanced functoids.
Overview
Advanced functoids allow more complex types of mapping. Advanced functoids allow you to:

Manage looping records. The Index, Iteration, Looping, Record Count, Table Extractor,
and Table Looping functoids are used in various combinations to achieve appropriate
results when the input instance message contains sections that have an unpredictable
number of repeating elements.

Create conditional mapping. The Value Mapping and Value Mapping (Flattening)
functoids are used to provide conditional mapping from an input instance message to an
output instance message.

Define arbitrary scripting. The Scripting functoid is used to run arbitrary script or
compiled code when an input instance message is being mapped to an output instance
message.

Copy entire elements of data. The Mass Copy functoid, which implements the XSLT
<xsl:copy select=”..” /> function, can be used to copy an entire record, including its
subelements, to an arbitrary depth, from an input message to an output message.
Using Looping Functoids
Configure looping and table-driven functoids
Looping Functoids
Looping functoids are used when the input instance message contains sections that have a
number of repeating elements that need to be mapped to the destination message.
There are several functoids that allow you to loop through records:

Looping functoid. This functoid is used to combine multiple records or fields in the
source schema into a single record in the destination schema. For example, if you have
an unknown number of line items in an inbound message, and you want to set a grand
total in the destination message, you use the looping functoid. There is no limit to the
number of inputs a looping functoid can accept, but only links from the source schema
are allowed as input parameters.

Index functoid. This functoid enables you to select a specific value or set of values in a
source message to be copied to the destination message. This functoid must have at
least one input parameter that is a link from a record or field in the source schema. The
second and succeeding input parameters specify the record. See Help for more
information.

Record Count functoid. This functoid is used to count the number of records in the
input instance message. This functoid takes one input parameter that is the link from a
looping record in the source schema. The output of this functoid is the count of the
looping record in the source instance message. For example, you may need to create a
purchase order summary message that has only the total number of unique items
purchased as indicated in the PO details. This functoid would count the number of line
items in the purchase order details and copy the total results to the purchase order
summary destination message.
Table-Driven Functoids
In a map, you can use a table looping functoid in conjunction with one or more table extractor
functoids when you need an input instance structure to produce multiple output instance
structures. For example, if you have a single address in your source schema that needs to be
entered in both the BillTo and ShipTo address along with a node that indicates the address type
in the destination message, you can use the Table Looping and the Table Extractor functoids to
create these records in the destination schema.

Table Looping functoid. This functoid enables you to create a table of output values to
use in creating the output instance message. The data in the table can consist of links
and constants. This functoid must have at least two input parameters. The first input
parameter configures how many times the table will loop, and the second input
parameter determines how many columns are in the table. Additional parameters
define possible cell values for the table.

Table Extractor functoid. This functoid is used to output the data associated with a
specified column for each row of the table looping grid of the Table Looping functoid.
This functoid must have two input parameters. The first parameter is an output link
from a Table Looping functoid, and the second parameter is the column number of the
table looping grid from which this functoid is meant to retrieve data. You must use the
Table Extractor functoid in conjunction with the Table Looping functoid.
Using Database Functoids
Configure database functoids
Functoids of Special Interest in Database Development
Some of the most useful functoids for accessing data in a database include:

Database Lookup. Performs a database lookup and stores the result in an ActiveX® Data
Objects (ADO) dataset. This functoid might be used for mapping older product codes to
newer product codes. This functoid requires four input parameters: lookup value
(typically a node from the source message), a connection string, a table name, and a
column name in the table to be looked up.

Value Extractor. Extracts the value from a specified column in an ADO dataset. The first
parameter of the Value Extractor functoid should be the Database Lookup functoid. For
example, if you need to query a database for multiple columns from a table, you can use
value extractor functoids to pull out a single value from the result set to populate a
value in the destination instance message. Multiple value extractor functoids can be
used with a single database lookup functoid.

Error Return. Captures error information, such as database connection failures, that
occurs during run time. This functoid returns any Open Database Connectivity (ODBC)
errors from a Database Lookup functoid.

Format Message. Returns a formatted and localized string. For example, if a string such
as Operation %1 failed with the code %2, you could replace the %1 and %2 with actual
string values.
Using a Scripting Functoid
Create and configure a scripting functoid
Overview
The Scripting functoid is used to run arbitrary script or compiled code when an input instance
message is being mapped to an output instance message. The script or compiled code can be
created so that it accepts input parameters from the source instance message, configured
constant values, the output of another functoid, or some combination thereof.
You can call a .NET assembly at run time by using the Scripting functoid. For example, if you
need to calculate the tax for an invoice, you can create a .NET assembly by using Visual Studio
and then calling a method in the assembly to calculate the tax. This can be very useful when you
are performing calculations multiple times on multiple systems and want to minimize the
amount of code to write.
BizTalk Server 2010 supports the following languages and technologies for the Scripting
functoid:

Microsoft Visual Basic®

C#

JScript

Extensible Stylesheet Language Transformations (XSLT) and XSLT Call Templates.
Occasionally it may be easier or more manageable to write your own XSLT to map multiple
nodes or to perform complex computations. For example, a couple lines of well-written XSLT
may replace several functoids.
Any external assemblies called by the Scripting functoid must be located in the global assembly
cache (GAC) of the BizTalk server. By placing the assembly in the GAC, support for multiple
versions of the assembly is provided.
Demonstration: Configuring Advanced Functoids
Learn how to use the looping functoid in a map.
Add a Looping Functoid
1. Resume the bt10d-demos virtual machine.
2. If the PurchaseOrderFF_to_PurchaseOrder.btm map is not already open, open it in
Solution Explorer.
3. From the Toolbox, drag a Looping functoid to the map grid of the Functoids page.
4. Double-click the Looping functoid on the map grid.
5. In the Configure Looping Functoid dialog box, read the Functoid description, and then
click OK.
6. Connect the Item node from the Source Schema to the Looping functoid.
7. Connect the Looping functoid to the Item node of the Destination Schema.
8. From the Toolbox, drag a Greater Than functoid to the map grid of the Functoids page.
9. Connect the Qty node from the Source Schema to the Greater Than functoid.
10. Double-click the Greater Than functoid. In the Configure Greater Than Functoid dialog
box, double-click the Condition2 row, enter the value 0, and then click OK.
11. Click anywhere on the map grid to deselect the Greater Than functoid.
12. Connect the Greater Than functoid to the Item node of the Destination Schema.
With this loop condition in place, the map will only copy Items that have a Qty value
greater than zero.
Test the Map
1. In Solution Explorer, right-click PurchaseOrderFF_to_PurchaseOrder.btm, and then click
Test Map.
2. In the Output window, scroll to the right, and then while holding the CTRL key, click the
link to the right of The output is stored in the following file.
3. Notice that the map copied only the Item records from the input message that had Qty
greater than zero.
4. On the File menu click Save All, and then close the Visual Studio solution and all other
open windows.
5. Shut down the bt10d-demos virtual machine.
Lab: Creating a BizTalk Map
Time estimated: 30 Minutes
Scenario
Maps are typically used to convert messages from one format to another. In this lab, you will
create a map that is used to transform data from the flat file format generated by the Adventure
Works stores to the internal sales order format used by the sales order application. You will
configure the map with several functoids to manipulate and modify the message data. You will
also configure the map to retrieve information from a Microsoft® SQL Server™ database and
insert it into the destination message.
Start the Virtual Machine
Procedure List
1. If the Server Manager window is not already open, click on the Server Manager icon
located in the task bar next to the Start button.
2. Expand Roles, Hyper-V, Hyper-V Manager. The last node to appear displays the
machine name. Click on it to see the list of virtual machines available.
3. Double-click the virtual machine bt10d-01 to open a Virtual Machine Connection
window.
4. Click on the Action menu in the Virtual Machine Connection window and choose Start.
5. Once the virtual machine starts, press CTRL+ALT+END.
6. Log on using the user name Administrator and the password pass@word1.
7. At the Windows Activation prompt, click Ask Me Later, and then click OK.
Exercise 1: Creating a Map
Overview
A BizTalk map is used to convert message data between XML formats. In this exercise, you will
use the BizTalk Mapper to create a map that transforms data from the SalesOrder_FF schema to
the SalesOrder schema format. This map will contain links that associate the data fields between
these two schemas.
Open an Existing Solution
Procedure List
1.
On the Start menu, click All Programs, click Microsoft Visual Studio 2010, and then
click Microsoft Visual Studio 2010.
2. In Visual Studio, on the File menu, point to Open, and then click Project/Solution.
3. In the Open Project dialog box, browse to C:\AllFiles\LabFiles\Lab3\AdvWorks, click
AdvWorks.sln, and then click Open.
The existing project opens in Solution Explorer.
Create a New BizTalk Map
Procedure List
1. In Solution Explorer, right-click the Messaging project, point to Add, and then click New
Item.
2. In the Add New Item dialog box, click the Map icon.
3. In the Name box, type SalesOrder_FF_to_SalesOrder_XML.btm to name the map.
Notice the naming convention of the map. It is a good idea to incorporate the source
and destination schemas when naming a map.
4. Click Add to start the BizTalk Mapper.
Selecting the Map template causes the BizTalk Mapper to start after the map is
added to the project.
5. In the BizTalk Mapper, click the Open Source Schema, expand Messaging, then
Schemas, select AdvWorks.Messaging.SalesOrder_FF, and then click OK.
6. In the BizTalk Mapper, click the Open Destination Schema, expand Messaging, then
Schemas, select AdvWorks.Messaging.SalesOrder, and then click OK
Link Nodes Manually Between Schemas
Procedure List
1. Below the map grid, right-click the Page 1 tab (at the bottom of the map), and then click
Rename Page.
2. Rename the page to Links.
Renaming the map page makes map management easier. It does not affect the XSLT
in any way.
3. In the Source Schema, right-click Schema, and then click Expand Tree Node.
4. In the Destination Schema, right-click Schema, and then click Expand Tree Node.
5. Using only the pairings in the following table, click and drag a link from each source field
from the Source Schema across the Map grid to the associated destination field in the
Destination Schema.
Source Field
Destination Field
StoreNumber
StoreNumber
OrderNumber
OrderNumber
Employee
Employee
Link Nodes Automatically by Node Name
Procedure List
1. In the Source Schema, click the CustomerInfo node, and then while holding the SHIFT
key, click and drag a link from the CustomerInfo node to the CustomerInfo node in the
destination schema. Choose Link by Name in the menu that appears when you release
the mouse button.
Notice how fields with the same name were automatically mapped. You will have to
manually map fields from the source schema that do not have matching names in
the destination schema.
2. In the Source Schema, click the CustomerInfo node, and then while holding the SHIFT
key, drag a link from the CustomerInfo node to the Residence node in the Destination
Schema. Choose Link by Name in the menu that appears when you release the mouse
button.
Notice that the Address, Town, Region, and ZipCode fields are not automatically
mapped to the Residence node. Because the names of these fields do not match in
the source and destination schemas, you will have to map these manually.
3. Using the pairings in the following table, click and drag a link from each source field
from the Source Schema across the Map grid to the associated destination field in the
Destination Schema.
Use the Residence record on the Destination Schema for the mappings to Street,
City, State, and PostalCode. The BillingAddress record mappings will be made in a
later exercise.
Source Field
Destination Field
Address
Street (Residence)
Town
City (Residence)
Region
State (Residence)
ZipCode
PostalCode (Residence)
Employer
Employer
MonthsEmployed
MonthsEmployed
PrimaryIncome
Primary
OtherIncome
Other
Link Nodes Automatically by Structure
Procedure List
1. In the Source Schema, click the Product node, and then while holding the SHIFT key,
drag a link from the Product node to the Item node in the Destination Schema. Choose
Link by Structure in the menu that appears when you release the mouse button.
Notice how nodes with the same node structure were automatically mapped. The
nodes that haven’t yet been mapped will be mapped in later exercises.
2. In the Source Schema, drag a link from the Comment node to the Comment node in the
Destination Schema.
3. On the File menu, click Save All.
Validate the Map
Procedure List
1. In Solution Explorer, right-click SalesOrder_FF_to_SalesOrder_XML.btm, and then click
Validate Map.
The results of the map validation are displayed in the Output window. Notice that
there are several warnings on the Error List stating that there are required fields that
are missing values. These validation warnings will be resolved with the additional
mappings made in a later exercise.
Test the Map
Procedure List
1. Right-click SalesOrder_FF_to_SalesOrder_XML.btm, and then click Properties.
2. In the SalesOrder_FF_to_SalesOrder_XML.btm properties window, configure the
following properties:
Property
Value
TestMap Input Instance
C:\AllFiles\LabFiles\Lab3\SalesOrder_FF_Sample.txt
TestMap Input
Native
3. Right-click SalesOrder_FF_to_SalesOrder_XML.btm, and then click Test Map.
The errors displayed in the Error List window are expected since the mapping process
isn’t complete. If you do not see the Error List window, click on the View menu and
click Error List.
4. In the Output window, while holding the CTRL key, click the link to the XML instance to
open the resulting XML file (bottom right link following “The output is stored in the
following file:”).
Information from the sample instance has been mapped from the SalesOrder_FF
message type to the SalesOrder message type.
5. Close the XML output message.
Exercise 2: Adding Basic Functoids to a Map
Overview
In addition to copying data between message nodes, maps can contain functoids that perform
data manipulation. In this exercise, you will add functoids to the map to manipulate data from a
source message to a destination message.
Create a New Map Page
Procedure List
1. Below the Map grid, right-click the Links tab (at the bottom of the map), and then click
Add Page.
2. Rename Page 2 to Functoids.
Convert a String to Uppercase
Procedure List
1. If the Toolbox is not already docked on the left side, on the View menu, click Toolbox.
2. From the String Functoids section of the Toolbox drag, the Uppercase functoid on to the
Map grid.
To move the functoid to a different position on the map grid, click the functoid to
select it (it will be highlighted with a blue box), then drag and drop it to the new
position. Click anywhere else in the mapper to unselect the functoid.
3. In the Source Schema, click the Cash_Cred field, and then drag a link to the Uppercase
functoid in the Map grid.
4. In the Map grid, click the Uppercase functoid, and then drag a link to OrderType node in
the Destination Schema.
The functoid must not be selected (i.e. it must not be highlighted with a blue box)
when dragging it to create a new link.
Specify the Current Date for the Order
Procedure List
1. From the Date/Time Functoids section of the Toolbox, drag the Date functoid on to the
Map grid.
2. In the Destination Schema, click the OrderDate field, and then drag a link to the Date
functoid in the Map grid.
Multiply Two Fields from the Source Schema to a Single Field in the Destination
Schema
Procedure List
1. From the Mathematical Functoids section of the Toolbox, drag the Multiplication
functoid on to the Map grid.
2. From the Cumulative Functoids section of the Toolbox, drag the Cumulative Sum
functoid on to the Map grid.
Because functoids must link left to right, you must drag the Cumulative Sum functoid
to the right of the Multiplication functoid.
3. In the Source Schema, click the Quantity field, and then drag a link to the Multiplication
functoid in the Map grid.
4. In the Source Schema, click the PriceEach field, and then drag a link to the
Multiplication functoid in the Map grid.
5. In the Map grid, click the Multiplication functoid, and then drag a link to the
ExtendedPrice node in the Destination Schema.
6. In the Map grid, click the Multiplication functoid, and then drag a link to the
Cumulative Sum functoid.
7. In the Map grid, click the Cumulative Sum functoid, and then drag a link to the Order
Total node in the Destination Schema.
Specify a Constant Value for the Loan Term
Procedure List
1. From the String Functoids section of the Toolbox, drag the String Concatenate on to the
Map grid.
2. In the Map grid, click the String Concatenate functoid, and then drag a link to the
TermOfLoan node in the Destination Schema.
3. In the Map grid, double-click the String Concatenate functoid.
4. In the Configure String Concatenate Functoid dialog box, click “Edit the selected
constant input” (the button with the pencil icon), and enter 6 as the value.
5. Click OK.
Exercise 3: Adding Database Functoids to a Map
Overview
It is often necessary to insert data into a message from an outside data source, such as a SQL
Server database. In this exercise, you will use functoids to retrieve information from a SQL
database and insert it in the destination message.
Create Links to the Database Lookup and Value Extractor Functoids
Procedure List
1. Drag the Uppercase functoid from the Toolbox to the Map grid.
2. In the Source Schema, click the ID field, and then drag a link to the Uppercase functoid
in the Map grid.
3. From the Database Functoids section of the Toolbox, drag the Database Lookup
functoid on to the Map grid.
Because functoids must link left to right, you must drag the Database Lookup
functoid to the right of the Uppercase functoid.
4. Drag a link between the Uppercase functoid and the Database Lookup functoid.
5. Right-click the link between the Uppercase and Database Lookup functoids, and then in
the Properties window, in the Label box, type CustomerID.
6. Drag four Value Extractor functoids, and then line them up vertically to the right of the
Database Lookup functoid.
7. Drag a link between the Database lookup functoid and each of the Value Extractor
functoids (four separate links).
8. Drag a link between the first Value Extractor functoid to the Street field under the
Billing Address record.
9. Drag a link between the second Value Extractor functoid to the City field under the
Billing Address record.
10. Drag a link between the third Value Extractor functoid to the State field under the
Billing Address record.
11. Drag a link between the fourth Value Extractor functoid to the PostalCode field under
the Billing Address record.
Configure the Database Lookup and Value Extractor Functoids
Procedure List
1. Double-click the Database Lookup functoid.
2. In the Configure Database Lookup Functoid dialog box, notice that Input[0] is the link
from the Uppercase functoid. Double-click on each of the following Input Parameters,
and enter the following values:
Input Parameter
Value
Input[1]
Provider=SQLOLEDB.1;Integrated Security=SSPI;Persist Security Info=False; Initial
Catalog=AdvWorks;Data Source=(local)
Input[2]
CUSTOMER
Input[3]
CUSTID
The first parameter is the SQL connection string to access the AdvWorks database.
The Second parameter specifies the database table you’re looking up. The third
parameter specifies the column in the table you’re looking up.
3. Click OK.
4. Double-click each Value Extractor functoid, notice that Input[0] is the link from the
Database Lookup functoid, then set the appropriate value for Input[1], as shown in the
table below:
Functoid
Value for Input[0]
First Value Extractor Functoid
ADDRESS
Second Value Extractor Functoid
CITY
Third Value Extractor Functoid
REGION
Fourth Value Extractor Functoid
ZIP
Each one of these parameters specifies the column from the database from which
the data will be mapped. These functoids will look up the CUSTID field in the source
schema in the AdvWorks database. If the CUSTID exists, the associated values in the
ADDRESS, CITY, REGION, and ZIP columns will be mapped to the Street, City, State,
and PostalCode fields in the destination schema.
Validate and Test the Map
Procedure List
1. In Solution Explorer, right-click SalesOrder_FF_to_SalesOrder_XML.btm, and then click
Validate Map.
The results of the map validation are displayed in the Output window. Notice, in the
Error List window, the validation errors you received earlier are no longer returned.
2. Right-click SalesOrder_FF_to_SalesOrder_XML.btm, and then click Test Map.
A link to the XML instance is shown in the Output window.
3. In the Output window, while pressing the CTRL key, click the link to open the output
XML file (bottom right link).
4. Examine and then close the order.
The Street, City, State, and PostalCode fields are retrieved from the database and
inserted in the destination message.