Module 3: Creating MapsTime 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.

OverviewUsing 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 OverviewWhen 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 CasesIn 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 ToolThe 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 ViewsThe 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 ImprovementsWith 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 MapBefore 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 TimeDuring 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 LinksYou 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 TypesThe 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.

OverviewThe 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 MappingBasic 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 MappingComplex 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 MapBefore 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 Map1. 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 Map1. In Windows Explorer, navigate to C:\AllFiles\DemoCode\Module3, and then double-

click 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 OverviewWhereas 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 FunctoidsA 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 FunctoidsIn 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 FunctoidsThere 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 FunctoidsTo 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 PropertiesThe 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 PagesMaps 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 Map1. 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 Functoid1. 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 Functoid1. 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 Functoid1. 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 Map1. 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 OverviewAdvanced 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 business-specific tasks.

Using Advanced Functoids

Perform data manipulation by using advanced functoids.

OverviewAdvanced 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 FunctoidsLooping 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 FunctoidsIn 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 DevelopmentSome 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

OverviewThe 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 Functoid1. 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 Map1. 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

ScenarioMaps 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 MachineProcedure 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 MapOverviewA 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 SolutionProcedure 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 MapProcedure 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 SchemasProcedure 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 FieldStoreNumber StoreNumber

OrderNumber OrderNumber

Employee Employee

Link Nodes Automatically by Node NameProcedure 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 StructureProcedure 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 MapProcedure 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 MapProcedure 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 MapOverviewIn 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 PageProcedure 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 UppercaseProcedure 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 OrderProcedure 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 SchemaProcedure 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 TermProcedure 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 MapOverviewIt 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 FunctoidsProcedure 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 FunctoidsProcedure 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 ValueInput[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 MapProcedure 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.