You would like to map one XML format to another using the BizTalk tool set. This may be for a variety of reasons, such as application mapping with an internal application, format specifics (such as flat file to database object), or an external business scenario where a business partner requires the core data for a business process in a different format (such as an industry standard) than your schema provides.

The BizTalk Mapper enables you to perform XML message transformation. The tool is shipped with the core BizTalk product and provides numerous capabilities to support message transformation and translation via straight mapping and functoids, as well as unit test support.

As an example, suppose that you have the following simple customer schema (Customer):

<Customer>
  <FirstName> </FirstName>
  <LastName> </LastName>
  <MiddleInit> </MiddleInit>
  <Age></Age>
  <Address>
  <AddrLine1> </AddrLine1>
  <AddrLine2> </AddrLine2>
  <AddrLine3> </AddrLine3>
  <Zip> </Zip>
  <State> </State>
  <Country></Country>
  </Address>
   </Customer>

And you want to map to another customer schema (CustomerRecord) that is slightly different in structure and format:

<CustomerRecord >
  <Name> </Name>
  <MiddleInit> </MiddleInit>
  <Address> </Address>
  <Zip> </Zip>
  <State> </State>
  <Country> </Country>
  <DateTime> </DateTime>
</CustomerRecord>

The example involves mapping values from a source to a destination schema that subsequently demonstrates different structure and invariably, message transformation. To create the BizTalk map for the example, follow these steps:

Here are the steps to follow in order to perform the concatenation.

To demonstrate functoid usage, you will now add a Date and Time functoid to the mapping example. In this instance, the destination schema requires a date/time stamp to be mapped. This value will be generated from the Date and Time functoid, not the source schema.

The map is now complete, as shown in Figure 3-8.

Figure 3.8. Completed customer map

The BizTalk Mapper is used to map XML messages (instances of XML schema at runtime) to an alternate format based on transformation and/or translation. It is built on XSLT and shields the user from complex XSLT transformation logic, by providing a GUI environment to facilitate the transformation. The tool comes with numerous functoids and mapping capabilities to support straight-through and deterministic transformation. In addition, the tool gives the built-in ability to perform unit testing.

The maps created within the BizTalk Mapper environment can be used within other BizTalk runtime environments. For example, they can be used with receive/send ports, for transforming a message to and from application end points. Port mapping might be advantageous when the mapping involves minimal process considerations or the need to apply multiple maps to a given message. Changes to maps on ports can be completed without recompilation of currently deployed BizTalk assemblies. Maps can also be used with transformation shapes, for message transformation within a BizTalk orchestration. Mapping within an orchestration might be preferred when the mapping process involves broad process considerations or process support via robust exception and error handling.

The choices for where and when to map vary depending on a number of factors. A number of these have to do with common development principals (such as consistency and readability) and standards enforced by the environment in which you are operating. However, a few common rules of thumb should be noted:

Like all good development processes, maps should be designed and tested for desired application operation conditions.

The example in this recipe showed a baseline solution of what can be performed with the BizTalk Mapper. Throughout this chapter, other mapping capabilities will be demonstrated, illustrating the use of functoids and mapping techniques for structure and transformation control.

Maps can become very complex and hence difficult to read and maintain.

BizTalk Sever provides a number of features to aid in the readability and maintainability of maps. One of these features is grid pages. BizTalk Server allows you to create, name/rename, and order grid pages. When you create links between source and destination elements, the links will appear on only the selected grid page. Therefore, you can segment groups of links onto different grid pages. By default, a map file is created with one grid page named Page 1. Once you have selected source and destination schemas, you can access the grid page menu by right-clicking the tab at the bottom of the grid page, as shown in Figure 3-9.

Figure 3.9. Click the tab at the bottom of the grid page to access the grid page menu.

From this menu, you can perform the following functions:

Figure 3.10. Reorder Pages dialog box

Another feature provided by BizTalk Server for facilitating the readability and maintainability of maps is the ability to label links. While the labels do not appear on the grid pages, they will be used to designate the input parameters for functoids. By default, a functoid will show the XPath designation if it is linked directly to a source field, or it will show the name of the previous functoid if it is linked from another functoid. However, if the input links to a functoid are labeled, and the Label property of the link will be shown. To label a link, follow these steps:

The ability to label and add comments to individual functoids is helpful in organization, especially when there are a large number of functoids on the page. To comment a functoid, simply double click the functoid, and click on the Label and Comments tab (as shown in Figure 3-11).

Figure 3.11. Commenting a functoid

There are many ways to segment a map into multiple grid pages. For example, you can create a grid page for each major node in a source schema that requires complex mapping. Regardless of how you divide the map, the goal of using multiple grid pages should be to improve the readability and maintainability of the map.

You would like to use constant values within a BizTalk map. This might be because of preset output map values within a destination schema (that do not exist in the source schema) to assist in general programming concepts when using functoids, or for other reasons.

To demonstrate how to add map constants using the BizTalk Mapper, suppose that you want to use a constant in conjunction with a String Extraction functoid. In this example, you would like to extract a specified number of characters (five) from the left of the source element value. In the source schema, Customer, you have Zip elements like this:

<Zip>98103-00001</Zip>

In the destination schema, CustomerRecord, you have Zip elements like this:

<Zip>98103</Zip>

To map constants, follow these steps:

Figure 3.15. Adding a new constant

You might use constant mapping for the following:

The best use of constant mapping depends on the situation and requirements you are developing against. Examine the likelihood of change within the scenario where you are looking to apply the functoid constant. If there is a high likelihood that values and their application will change, consistency should be the major factor to facilitate maintenance.

If constants are set via deterministic logic or complex or embedded business rules, it might be worth thinking about whether the constant should be applied in the map or applied within a scripting component or upstream/downstream BizTalk artifacts. The key is understanding where rules and deterministic values are set to support the specific situation. Apply the appropriate design principles to ensure the correct constant assignment technique is applied.

You might decide it would be best to map values outside the mapping environment. This could be a result of deterministic logic or business rules being the major requirement in the constants implementation. Furthermore, rules that derive constants may exist outside the BizTalk map. Constants may need to change dynamically, and it may be too cumbersome to perform a recompile/deployment for such changes within a BizTalk map.

You need to create a mapping between two schemas containing elements and attributes that are unknown when building the map, and you must include the unknown schema structures in your mapping.

You can include unknown schema structures in a map by using the <Any> element.

An <Any> element in a schema designates a specific location in the schema where new elements or attributes can be added. When BizTalk uses the schema to process a message containing unknown elements or attributes in the designated location, the schema will still consider the message valid. If this source message is mapped into a different schema that also has a location designated for extensibility with an <Any> element, then the information must be copied to that location with the Mass Copy functoid.

The contents of an <Any> element cannot be mapped with most of the default BizTalk functoids. Other functoids require establishing an explicit link from a source field, and that is not possible if the source field is not known at design time. The Mass Copy functoid can be linked only directly to an ancestor of the <Any> element, which may not give the granularity of control desired. Consider using an XSLT script with the Scripting functoid to achieve finer control. For example, if you know some element will be present at runtime but cannot predict the element name of its parent, an XSLT script can still perform the mapping.

Note that you can override the mapping of the mass copy on a line by line basis. For instance, if the Zip field needs to be mapped differently, simply add the appropriate functoid(s) and map it; this will override whatever the Mass Copy functoid has created (see Figure 3-19).

Figure 3.19. Overriding AddrLine2 within a Mass Copy functoid

Sometimes, the BizTalk development environment has difficulty validating schemas containing <Any> elements. It can incorrectly determine that elements and attributes appearing in the location designated by the schema should not be there, causing validation for the schema to fail. This complicates schema development because the developer must deploy the schema with a pipeline capable of validating the document structure to check if the schema is correct according to a sample source message. To avoid this deployment effort while developing the schema, wait to add <Any> elements until the rest of the schema is developed and verify that those other elements are defined correctly. Then, when adding the <Any> elements to the schema, there will be a baseline of what is working correctly.

The Mass Copy functoid allows source records and containing elements and attributes to be copied and mapped across to the destination schema. This in turn, allows large structures to be mapped quickly in design time, without the need of performing 1:1 detailed mapping on all subsequent schema nodes. The Mass Copy functoid performs the recursive copying by applying a wildcard (/*) XSLT template match on source to destination XML elements. This is of particular benefit when the destination is defined as an <xs:any> type.

When mapping from source to destination, only the structure under the destination parent XML record will be copied. This often results in having to re-create the parent record element to allow all subsequent children nodes to be mapped to the destination schema. For example, consider the following two schemas, Customer and Customers:

<Customer>
  <Name> </Name>
  <AccountID> </AccountId>
  <DOB> </DOB>
</Customer>


<Customers>
  <Customer>
  <Name> </Name>
  <AccountID> </AccountId>
  <DOB> </DOB>
  </Customer>
</Customers>

In this instance, the <Customers> record cannot be mapped to the <Customer> record on the destination schema. A containing element <Customer> will need to be defined on the destination schema to enable the correct operation of the Mass Copy functoid mapping.

When mapping source to destination elements, always be cautious of underlying XSD schema rules, such as cardinality, order, and data types. For example, the Mass Copy functoid will "blindly" copy all child elements specified to the destination schema. It will not copy elements out of order or check for required values in the destination schema.

Changes to the source and destination schema may result in the need to update your impacted maps leveraging the Mass Copy functoid. This, in turn, will mandate a recompile and deployment of your BizTalk solution.

Using the Mass Copy functoid within the BizTalk Mapper is one of a variety of ways to recursively copy elements. The following are three key approaches to recursively copy XML structures:

You need to understand how and when to use the Value Mapping and the Value Mapping (Flattening) functoids.

BizTalk provides two Value Mapping functoids: Value Mapping and Value Mapping (Flattening). Both will cause a new record to be created in the destination for every record in the source. The Value Mapping (Flattening) functoid is used when the destination document has a flat structure.

Both functoids require two input parameters: a Boolean value and the node that is to be mapped. If the Boolean value is true, the value will be mapped; otherwise, it will not be mapped.

The following steps demonstrate the use of the Value Mapping functoid in a map, using the source document shown in Listing 3-1.

<ns0:NewHireList xmlns:ns0="http://UsingValueMappingFunctoids.NewHireList">
  <DateTime>DateTime_0</DateTime>
  <Person>
    <ID>1</ID>
    <Name>Jonesy</Name>
    <Role>.NET Developer</Role>
    <Age>47</Age>
  </Person>
  <Person>
    <ID>2</ID>
    <Name>Scott</Name>
    <Role>Database Developer</Role>
    <Age>40</Age>
  </Person>
  <Person>
    <ID>3</ID>
    <Name>Austin</Name>
    <Role>QA</Role>
    <Age>33</Age>
  </Person>
</ns0:NewHireList>

These steps refer to the Value Mapping functoid but are identical for the Value Mapping (Flattening) functoid.

Figure 3.21. Using the Value Mapping functoid

At this point, the map can be tested. Using the source document shown in Listing 3-1, output of the map is the document shown in Listing 3-2.

<ns0:Company xmlns:ns0="http://UsingValueMappingFunctoids.Company">
 <Employees>
  <Employee>
   <Name>Jonesy</Name>
  </Employee>
  <Employee>
   <Name>Scott</Name>
  </Employee>
  <Employee>
  </Employee>
 </Employees>
</ns0:Company>

If the Value Mapping functoid is replaced with the Value Mapping (Flattening) functoid (as shown in Figure 3-22), the document in Listing 3-3 will be output.

Figure 3.22. Map with Value Mapping (Flattening) functoid

<ns0:Company xmlns:ns0="http://UsingValueMappingFunctoids.Company">
 <Employees>
  <Employee>
   <Name>Jonesy</Name>
   <Name>Scott</Name>
  </Employee>
 </Employees>
</ns0:Company>

This example showed the default behavior of the Value Mapping functoid. However, the default output of the Value Mapping functoids can be altered through the use of additional functoids and scripting. For example, notice that the output in Listing 3-3 is flat instead of nested (two Person nodes within the Employee node). By adding a Looping functoid to the Name element in the source document and attaching it to the Employee root node in the destination document (see Figure 3-23), you can obtain nested output, as in Listing 3-4. The output is identical to using the Value Mapping functoid as shown in Listing 3-2.

Figure 3.23. Using the Value Mapping (Flattening) and Looping functoids

<ns0:Company xmlns:ns0="http://UsingValueMappingFunctoids.Company">
 <Employees>
  <Employee>
   <Name>Jonesy</Name>
  </Employee>
  <Employee>
   <Name>Scott</Name>
  </Employee>
  <Employee>
  </Employee>
 </Employees>
</ns0:Company>

One of the most common situations in XML document mapping is working with nonexistent elements. By default, if an element does not exist in an incoming document but is mapped to the destination document in a BizTalk map, the node on the destination document will be created with a null value (<Node/>). The use of a Value Mapping (Flattening) functoid causes the node to be created in the destination document only if the source node exists in the source document.

You need to create a repeating structure in an output document with no equivalent repeating structure in an input document.

BizTalk Sever provides two functoids, the Table Looping functoid and the Table Extractor functoid, for creating a repeating node structure from a flattened input structure, from constant values, and from the output of other functoids. The Table Looping functoid is used to create a table of information based on inputs. The functoid will generate output for each row from this table. The Table Extractor functoid is used to direct data from each column in the table to a node in the destination document. Following are the basic steps for configuring these functoids.

The Table Looping and Table Extractor functoids are used together. As an example, suppose that you have the sample input document shown in Listing 3-5.

<AliasesFlat>
    <Names>
        <Alias1FirstName>John</Alias1FirstName>
        <Alias1LastName>Doe</Alias1LastName>
        <Alias2FirstName>Sam</Alias2FirstName>
        <Alias2LastName>Smith</Alias2LastName>
        <Alias3FirstName>James</Alias3FirstName>
        <Alias3LastName>Jones</Alias3LastName>
    </Names>
</AliasesFlat>

The goal is to use these two functoids to create an output document of the format shown in Listing 3-6.

<AliasesRepeating>
    <AliasNames>
        <FirstName>John</FirstName>
        <LastName>Doe</LastName>
    </AliasNames>
    <AliasNames>
        <FirstName>Sam</FirstName>
        <LastName>Smith</LastName>
    </AliasNames>
    <AliasNames>
        <FirstName>James</FirstName>
        <LastName>Jones</LastName>
    </AliasNames>
</AliasesRepeating>

Figure 3-24 shows the configuration for the input parameters for the Table Looping functoid. The first parameter is a reference to the node structure Names in the input schema. The second parameter is a constant value of 2 indicating there will be two columns in the table. The remaining parameters are the first and last name of each alias from the input document.

Figure 3.24. Table Looping input parameters

Figure 3-25 shows the completed Table Looping Configuration dialog box for the Table Looping functoid. It has been configured so that each row contains an alias first name in column 1 and an alias last name in column 2. There will be three rows in the table to process, one for each alias provided as input.

Figure 3.25. Table Looping Configuration dialog box

The output links from the Table Looping functoid are configured as follows:

Figure 3-26 shows the configuration for the Table Extractor functoid that will process column 1 from the table. The first parameter is a link from the Table Looping functoid, and the second parameter is a constant value of 1, which indicates it will process the first column from each row as it is processed.

Figure 3.26. Table Extractor functoid configuration for column 1

Figure 3-27 shows the configuration for the Table Extractor functoid that will process column 2 from the table. The first parameter is a link from the Table Looping functoid, and the second parameter is a constant value of 2, which indicates it will process the second column from each row as it is processed.

Figure 3.27. Table Extractor functoid configuration for column 2

Finally, each Table Extractor functoid must be linked to a node in the destination schema. The complete map is shown in Figure 3-28.

Figure 3.28. Final map for the Table Looping functoid example

Here is what the data table will look like when the map is processed:

Once the table is loaded, it will generate three sets of output: one set of output for each row in the table. This, in turn, will create three repetitions of the AliasNames node structure in the destination document: one for each row in the table. A repeating node structure has been created, even though one did not exist in the input document.

You need to map an incoming node to a database table column to reference a specific set of data via a BizTalk Server map. Specifically, for an inbound author ID, you need to retrieve the person attributes that are stored in a SQL based table. Additionally, the data that is stored in the database table is dynamic, and coding the values within the BizTalk map is not possible.

BizTalk provides the Database Lookup functoid, which can retrieve a recordset. For example, suppose that the inbound message specifies an author's Social Security number but no personal information. The map must retrieve the author's information and map the information to the outbound message. The Database Lookup functoid can retrieve the information from a specific SQL table using the author's Social Security number as the value for which to search. The inbound XML message may have a format similar to the following and a table with data as show in Figure 3-29.

<ns0:PersonSearch xmlns:ns0="http://DatabaseLookupFunctoid.PersonSearch">
  <ID>172321176</ID>
</ns0:PersonSearch>

Figure 3.29. Record data

You can use the Database Lookup functoid by taking the following steps:

Figure 3.32. The final mapping

The Database Lookup functoid requires four parameters as inputs, and it outputs an ActiveX Data Objects (ADO) recordset. Keep in mind that the recordset returns only the first row of data that matches the specific criteria provided to the Database Lookup functoid.

In addition to the input parameters, the Database Lookup functoid requires two helper functoids for optimal use:

Figure 3.33. An error has been generated

Whenever you use SQL authentication (SQL username and password), there is potential for a security risk. Consider using trusted security for access to the database rather than specifying the username and password in the connection string used by the Database Lookup functoid. For example, here is a connection string that uses SQL security:

Provider=SQLOLEDB;Server=localhost;Database=pubs;User ID=sa;Password=password;
  Trusted_Connection=False

And here is an example of a connection string that uses Trusted Security:

Provider=SQLOLEDB;Server=localhost;Database=pubs;Integrated Security=SSPI;

Keep in mind that if you choose Trusted Security for authentication, the account under which the BizTalk host instance is running must have appropriate access to the SQL Server, the SQL database, and the table in which the Database Lookup functoid is looking.

Another option to enclosing connection string information within the Database Lookup functoid is to make use of a Universal Data Link (UDL) file. A UDL is simply a text file with the file extension .udl. The connection string is included within the UDL file, and the connection string parameter in the Database Lookup functoid becomes a reference to that file, for example:

File Name=c:BizTalkConfigConnectionString.UDL

Once the UDL file is created, it can be made available on a secure file share.

Additionally consider the use of a SQL view, versus direct table access, and having the Database Lookup functoid point to the database view. A SQL view offers the ability to manage table security permissions or the abstraction of the physical table structure.

The Database Lookup functoid is convenient to implement in mappings. For straightforward data retrieval, this functoid performs adequately. However, the following items should be taken into consideration when evaluating when to use the Database Lookup functoid:

The BizTalk map translates the Database Lookup functoid information into a dynamic SQL SELECT statement. If you run a SQL Profiler trace during testing of the BizTalk map, you will see the SELECT call with the dynamic SQL. Knowing that dynamic SQL is created by the Database Lookup functoid allows you to use it to perform some relatively powerful database lookups. The Database Lookup functoid allows only a single value and single column name to be referenced in the query. However, with a bit of extra mapping, you can use this functoid to query against multiple columns. The map in Figure 3-32 generates the following SQL query code:

exec sp_executesql N'SELECT * FROM people WHERE ID= @P1', N'@P1 nvarchar(9)',
N'172321176'

This query performs a SELECT to retrieve all rows from the People table where the author ID is equal to the value in the inbound XML document (for example, 172321176).

Keep in mind that the Database Lookup functoid returns only the first row that it encounters in the recordset. If multiple authors had the same ID, you would potentially retrieve the incorrect author. For example, if the author ID is the last name of the author, you may retrieve multiple authors that share the same last name. One way to ensure uniqueness, aside from querying on a unique column, is to specify additional columns in the query. The Database Lookup functoid accepts only four parameters, so additional concatenation must occur before submitting the parameters to the Database Lookup functoid.

After configuring the inbound concatenated value, the next step is to specify multiple column names as the input parameter in the Database Lookup functoid. Figure 3-34 demonstrates a sample Database Lookup functoid configuration with multiple columns specified. The output from the Database Lookup functoid to the Value Extractor functoid does not change.

Figure 3.34. Database Lookup functoid with multiple columns

In this example, the inbound message specifies an author's first name and last name instead of a unique author ID. The map must still retrieve the author's information and map the information to the outbound message. The inbound XML message may have a format to the following message:

<ns0:PersonSearch xmlns:ns0="http://DatabaseLookupFunctoid.PersonSearch">
  <FirstName>Juan</FirstName>
  <LastName>Dos</LastName>
</ns0:PersonSearch>

The following is the dynamic SQL created in the map that accepts multiple columns:

exec sp_executesql N'SELECT * FROM authors WHERE FirstName+LastName= @P1', N'@P1
nvarchar(12)', N'JuanDos'

The dynamic SQL created shows the inbound author's first name and last name parameters as a concatenated parameter. The SQL statement also shows a combination WHERE clause with FirstName + LastName.

There are some limitations to specifying multiple columns through the concatenation approach. Specifically, string data types are the only data types that work reliably due to the concatenation operation that occurs in SQL. Integer data types may also be used, but in the case of integer (or other numeric data types), SQL will perform an additive operation versus a concatenation operation. Adding two numbers together, as what would happen when specifying numeric data types, and comparing the result to another set of numbers being added together may yield multiple matches and may not achieve the desired results. The mix of varchar and numeric fields will not work with this approach, as you will receive a data casting exception from your data provider.

You wish to dynamically cross-reference unique identifiers between two or more systems. The reference data already exists, so you wish to load the data into the BizTalk cross-reference tables before you use the cross-reference functoids or application programming interface (API).

Within an XML configuration file you name List_Of_App_Type.xml, insert the XML shown in Listing 3-7, and insert an appType node for each system that will have cross-references.

<?xml version="1.0" encoding="UTF-8"?>
<listOfAppType>
    <appType>
        <name>Oracle</name>
        <description/>
    </appType>
    <appType>
        <name>Siebel</name>
        <description/>
    </appType>
</listOfAppType>

Within an XML configuration file you name List_Of_App_Instance.xml, insert the XML shown in Listing 3-8.

<?xml version="1.0" encoding="UTF-8"?>
<listOfAppInstance>
        <appInstance>
            <instance>Oracle_01</instance>
            <type>Oracle</type>
            <description/>
        </appInstance>
        <appInstance>
            <instance>Siebel_01</instance>
            <type>Siebel</type>
            <description/>
        </appInstance>
        <appInstance>
            <instance>Siebel_12</instance>
            <type>Siebel</type>
            <description/>
        </appInstance>
</listOfAppInstance>

Since unique identifiers are often different for each unique instance of a system, you must create different cross-references for each system. Therefore, you must insert an appInstance node for each instance of an application you will cross-reference, inserting a common type value across instances that are of the same type of system, and which correspond to the appType you created in the List_Of_App_Type.xml configuration file. For instance, you may be running two instances of Siebel, so you would insert two appInstance nodes with a type of Siebel, but give each a unique value in the instance node (for example, Siebel_01 and Siebel_12).

Within an XML configuration file you name List_Of_IdXRef.xml, insert the XML shown in Listing 3-9.

<?xml version="1.0" encoding="UTF-8"?>
<listOfIDXRef>
    <idXRef>
        <name>Customer.ID</name>
        <description/>
    </idXRef>
    <idXRef>
        <name>Order.PONumber</name>
        <description/>
    </idXRef>
</listOfIDXRef>

For each ID field you plan to cross-reference, insert an idXRef node with a unique name child node. This value will be used to identify the ID field that you are cross-referencing. For instance, if you plan to cross-reference a customer that is in different systems, you would insert an idXRef with a name like Customer.ID.

Within an XML configuration file you name List_Of_IdXRef_Data.xml, insert the XML shown in Listing 3-10.

<?xml version="1.0" encoding="UTF-8"?>
<listOfIDXRefData>
    <idXRef name="Customer.ID">
        <appInstance name="Oracle_01">
            <appID commonID="100"> CARA345</appID>
        </appInstance>

        <appInstance name="Siebel_01">
            <appID commonID="100">99-4D976</appID>
        </appInstance>
        <appInstance name="Siebel_12">
            <appID commonID="100">44OL</appID>
        </appInstance>
    </idXRef>
</listOfIDXRefData>

For each field you create in the List_Of_IdXRef.xml file, insert an idXRef node. For each system you create in the List_Of_App_Instance.xml file, insert an appInstance node. Insert one or more appID nodes for each unique identifier. Insert a commonID attribute to store a common identifier, and set the application-specific value within the node. The common ID will be repeated for each appID that is cross-referenced.

Within an XML configuration file you name Setup-Config.xml, insert the XML shown in Listing 3-11.

<?xml version="1.0" encoding="UTF-8"?>
<Setup-Files>
    <App_Type_file>C:List_Of_App_Type.xml</App_Type_file>
    <App_Instance_file>C:List_Of_App_Instance.xml</App_Instance_file>
    <IDXRef_file>C:List_Of_IDXRef.xml</IDXRef_file>
    <IDXRef_Data_file>C:List_Of_IDXRef_Data.xml</IDXRef_Data_file>
</Setup-Files>

Each node should point to the physical location where you have created the corresponding XML configuration files.

Seed the BizTalk cross-reference tables by opening a command-line window and running the BizTalk cross-reference import tool, BTSXRefImport.exe (found in the BizTalk installation directory), passing in the path to the cross-reference XML file created in Listing 3-11:

BTSXRefImport.exe -file=C:Setup-Config.xml

During installation of BizTalk, several cross-reference tables are created in the BizTalkMgmtDb database. All the cross-reference tables begin with the prefix xref_, and the BTSXRefImport tool imports the data from the XML files provided into the table structure for access at runtime. It is not necessary to use the BTSXRefImport.exe tool to insert data into the cross-reference tables. You may insert data directly into the following tables:

After running the BTSXRefImport tool, and if the data were in a denormalized form, the data would look like this:

There are subtle differences between ID and value cross-referencing. Value cross-references, as the name implies, deal with static values, while ID cross-references deal with cross-referencing unique identifiers. Since most value cross-references are not updated at runtime, a functoid and API method are not provided to update the references at runtime. ID cross-references, though, may be updated using the Set Common ID functoid or API method.

You wish to statically cross-reference state values between two or more systems. The reference data already exists, but you must load the data into the BizTalk cross-reference tables before you may use the cross-reference functoids or API.

Within an XML configuration file you name List_Of_App_Type.xml, insert the XML shown in Listing 3-12, and insert an appType node for each system that will have static cross-references.

<?xml version="1.0" encoding="UTF-8"?>
<listOfAppType>
    <appType>
        <name>Oracle</name>
        <description/>
    </appType>
    <appType>
        <name>Siebel</name>
        <description/>
    </appType>
</listOfAppType>

Within an XML configuration file you name List_Of_ValueXRef.xml, insert the XML shown in Listing 3-13.

<?xml version="1.0" encoding="UTF-8"?>
<listOfValueXRef>
    <valueXRef>
        <name>Order.Status</name>
        <description/>
    </valueXRef>
</listOfValueXRef>

For each field you plan to statically cross-reference, insert a valueXRef node with a unique child node name. This value will be used to identify the static field. For instance, if you plan to map between order status codes, you might create a common value of Order.Status.

Within an XML configuration file you name List_Of_ValueXRef_Data.xml, insert the XML shown in Listing 3-14.

<?xml version="1.0" encoding="UTF-8"?>
<listOfValueXRefData>
<valueXRef name="Order.Status">
    <appType name="Oracle">
        <appValue commonValue="Open">OP</appValue>
        <appValue commonValue="Pending">PD</appValue>
        <appValue commonValue="Closed">CD</appValue>
    </appType>
    <appType name="Siebel">
        <appValue commonValue="Open">1:Open</appValue>
        <appValue commonValue="Pending">2:Pending</appValue>
        <appValue commonValue="Closed">3:Closed</appValue>
    </appType>
</valueXRef>
</listOfValueXRefData>

For each static field you create in the List_Of_ValueXRef.xml file, insert a valueXRef node. For each system you create in the List_Of_App_Type.xml file, insert an appType node. Insert one or more appValue nodes for each value that is permissible for this valueXRef field. Insert a commonValue attribute to store the common name for the value, and set the application-specific value within the node. The common value will be repeated for each appType that is cross-referenced.

Within an XML configuration file you name Setup-Config.xml, insert the XML shown in Listing 3-15.

<?xml version="1.0" encoding="UTF-8"?>
<Setup-Files>
<App_Type_file>c:List_OF_App_Type.xml</App_Type_file>
<ValueXRef_file>c:List_Of_ValueXRef.xml</ValueXRef_file>
<ValueXRef_Data_file>c:List_Of_ValueXRef_Data.xml</ValueXRef_Data_file>
</Setup-Files>

Each node should point to the physical location where you have created the corresponding XML configuration files.

Seed the BizTalk cross-reference tables by opening a command-line window and running the BizTalk cross-reference import tool, BTSXRefImport.exe (found in the BizTalk installation directory), passing in the path to the Setup-Config.xml cross-reference file:

BTSXRefImport.exe -file=C:Setup-Config.xml

During installation of BizTalk, several static cross-reference tables are created in the BizTalkMgmtDb database. All the cross-reference tables begin with the prefix xref_, and the BTSXRefImport tool imports the data from the XML files provided to the table structure for access at runtime. It is not necessary to use the BTSXRefImport.exe tool to insert data into the cross-reference tables. You may insert data directly into the following tables:

In a denormalized form, the table would look like this after running the BTSXRefImport tool:

Within a map, you wish to dynamically cross-reference unique identifiers between two or more systems, and the identifier cross-references have already been loaded into the cross-reference tables. For example, a source system publishes an Account with a unique identifier of 1234, and you want to cross-reference and dynamically translate that identifier to the unique identifier in a destination system of AA3CARA.

To cross-reference the identifiers within a map, take the following steps:

Identifier cross-referencing allows entities to be shared across systems. Although cross-referencing functionality is often not required in small integration projects, as usually there is a single system for a given entity type, in larger organizations, it is common to find several systems with the same entities (for example, Account, Order, and Invoice). These entities are often assigned a unique identifier that is internally generated and controlled by the system. In other words, from a business perspective, the entities are the same, but from a systems perspective, they are discrete. Therefore, in order to move an entity from one system to another, you must have a way to create and store the relationship between the unique identifiers, and to discover the relationships at runtime.

BizTalk Server provides this functionality through cached cross-referencing tables, API, an import tool, and functoids. Using the import tool, you can load information about systems, instances of those systems, the entities within those systems you wish to cross-reference, and the actual cross-reference data into a set of cross-reference tables that are installed with BizTalk in the BizTalkMgmtDb database. Then, using the functoids or API at runtime, you access the tables to convert an identifier from one recognized value to another. The basic steps for converting from one system to another are as follows:

This recipe has focused on accessing identifier cross-referencing functionality through BizTalk functoids, but an API is also available. The cross-referencing class may be found in the Microsoft.Biztalk.CrossRreferencing.dll, within the namespace Microsoft.BizTalk.CrossReferencing. This class has several members that facilitate storing and retrieving identifier cross referencing relationships, as listed in Table 3-1.

Within a map, you wish to statically cross-reference state values between two or more systems, and the value cross-references have already been loaded into the cross-reference tables. For example, a source system publishes an Order with a status of 1:Open, and you want to cross reference and translate the static state value to the static value in a destination system of OP.

To cross-reference the static values within a map, take the following steps:

Identifier and value cross-referencing are similar in concept, with the following differences:

The basic steps for converting from one system to another are as follows:

This recipe has focused on accessing value cross-referencing functionality through BizTalk functoids, but an API is also available. The cross-referencing class may be found in the Microsoft.Biztalk.CrossRreferencing.dll, within the namespace Microsoft.BizTalk.CrossReferencing. This class has several members that facilitate storing and retrieving value cross-referencing relationships, as listed in Table 3-2.

The structure of a message from a source system you are integrating with contains multiple repeating record types. You must map each of these record types into one record type in the destination system. In order for the message to be imported into the destination system, a transformation must be applied to the source document to consolidate, or standardize, the message structure.

Create a map that utilizes the BizTalk Server Looping functoid, by taking the following steps:

An example of a map that uses the Looping functoid is shown in Figure 3-35.

Figure 3.35. Using the Looping functoid

In this example, multiple types of plane flight reservations are consolidated into a single list of records capturing passengers and their associated seats. The XML snippet in Listing 3-16 represents one possible instance of the source schema.

<ns0:PassengerReservations xmlns:ns0="http://LoopingFunctoid.PassengerReservations">
  <FlightNumber>666</FlightNumber>
  <OnlineReservation>
    <Name>Lucifer Smith</Name>
    <Seat>13A</Seat>
    <Website>www.greatdeals.com</Website>
    <Confirmed>True</Confirmed>
  </OnlineReservation>
  <OnlineReservation>
    <Name>Beelzebub Walker, Jr.</Name>
    <Seat>13B</Seat>
    <Website>www.hellofadeal.com</Website>
    <Confirmed>False</Confirmed>
  </OnlineReservation>
  <TravelAgentReservation>
    <PassengerName>Jim Diablo</PassengerName>
    <Seat>13C</Seat>
    <AgentName>Sunny Rodriguez</AgentName>
  </TravelAgentReservation>
  <AirlineReservation>
    <Name>Imin Trouble</Name>
    <Seat>13D</Seat>
    <BookingDesk>Chicago</BookingDesk>
  </AirlineReservation>
</ns0:PassengerReservations>

Based on this source XML, the looping map displayed in Figure 3-35 will produce the XML document shown in Listing 3-17, containing a single passenger seat assignment list.

<ns0:Manifest FlightNumber="666" xmlns:ns0="http://LoopingFunctoid.Manifest">
  <Passenger Name="Lucifer Smith" SeatNumber="13A" />
  <Passenger Name="Beelzebub Walker, Jr." SeatNumber="13B" />
  <Passenger Name="Jim Diablo" SeatNumber="13C" />
  <Passenger Name="Imin Trouble" SeatNumber="13D" />
 </ns0:Manifest>

This example displays a simplistic but useful scenario in which the Looping functoid can be used. Essentially, this functoid iterates over the specified repeating source records (all those with a link to the left side of the functoid), similar to the For...Each structure in coding languages, and maps the desired elements to a single repeating record type in the destination schema.

Based on this simple principle, you can develop much more complex mappings via the Looping functoid. One example of a more advanced use of the Looping functoid is conditional looping. This technique involves filtering which source records actually create destination records in the resulting XML document. The filtering is done by adding a logical functoid to the map, which produces a true or false Boolean value based on the logic. Common examples of filtering are based on elements that indicate a certain type of source record, or numeric elements that posses a certain minimum or maximum value.

The previous flight reservation example can be extended to implement conditional looping, in order to map only those online reservations that have been confirmed. This can be accomplished via the following steps:

An example of the enhanced map is shown in Figure 3-36.

Figure 3.36. Conditional looping

Based on the same source XML outlined earlier in Listing 3-16, the looping map displayed in Figure 3-36 will produce the following XML document, containing a single passenger seat assignment list with only three passengers (Lauren Jones's reservation, which was not confirmed, is filtered out by the conditional looping logic):

<ns0:Manifest FlightNumber="666" xmlns:ns0="http://LoopingFunctoid.Manifest">
  <Passenger Name="Lucifer Smith" SeatNumber="13A" />
  <Passenger Name="Jim Diablo" SeatNumber="13C" />
  <Passenger Name="Imin Trouble" SeatNumber="13D" />
 </ns0:Manifest>

In this example of conditional looping, the second input parameter of the logical Equal functoid is a hard-coded constant set to True. In real-world scenarios, it may not be ideal for this value to be hard-coded. You may prefer to have it driven off a configurable value. Several alternatives exist:

When implementing a map that uses the Looping functoid, it is important to understand how BizTalk Server inherently handles repeating records in the source schema. If a record in the source schema has a Max Occurs property set to a value greater than 1, BizTalk Server handles the record via a loop. No Looping functoid is required for the map to process all appropriate source records. A Looping functoid is needed only to consolidate multiple repeating source records into a single repeating destination record.

You need to implement a map that handles certain records within a repeating series in an intelligent fashion. The map must be able to determine the sequential order, or index, of each repeating record, and perform customized logic based on that index.

Develop a BizTalk Server map, and leverage the Iteration functoid by taking the following steps.

An example of a map that uses the Iteration functoid is shown in Figure 3-37.

Figure 3.37. Using the Iteration functoid

In this example, all the peak hourly energy values from the source XML are mapped over to the destination XML. The Iteration functoid is used to determine the index of each HourlyUsage record, with those having an index value of 3 or higher being flagged as peak hours. Additionally, the output from the Iteration functoid is also used to create the Hour element in the destination XML, defining to which hour the energy reading pertains. The XML snippet in Listing 3-18 represents one possible document instance of the source schema.

<ns0:HourlyUsage xmlns:ns0="http://IterationFunctoid.HourlyUsage">
  <Date>09/06/2010</Date>
  <Usage>
    <Hour>01</Hour>
    <EnergyUsage>2.4</EnergyUsage>
    <Adjustments>0</Adjustments>
  </Usage>
  <Usage>
    <Hour>02</Hour>
    <EnergyUsage>1.7</EnergyUsage>
    <Adjustments>1</Adjustments>
  </Usage>
  <Usage>
    <Hour>03</Hour>
    <EnergyUsage>3.9</EnergyUsage>
    <Adjustments>0</Adjustments>
  </Usage>
  <Usage>
    <Hour>04</Hour>
    <EnergyUsage>12.4</EnergyUsage>
    <Adjustments>3</Adjustments>
  </Usage>
  <Usage>
    <Hour>05</Hour>
    <EnergyUsage>15</EnergyUsage>
    <Adjustments>0</Adjustments>
  </Usage>
  <Usage>
    <Hour>06</Hour>
    <EnergyUsage>3.2</EnergyUsage>
    <Adjustments>1</Adjustments>
  </Usage>

</ns0:HourlyUsage>

When passed through the map displayed in Figure 3-37, this XML will produce the XML document shown in Listing 3-19, containing all the peak hourly energy usage values with their associated Hour value.

<ns0:PeakHourUsage xmlns:ns0="http://IterationFunctoid.PeakHourUsage">
 <Date>09/06/2010</Date>
 <Usage>
  <Hour>4</Hour>
  <Amount>12.4</Amount>
 </Usage>
 <Usage>
  <Hour>5</Hour>
  <Amount>15</Amount>
 </Usage>
 <Usage>
  <Hour>6</Hour>
  <Amount>3.2</Amount>
 </Usage>
</ns0:PeakHourUsage>

The Iteration functoid can be a crucial tool for those business scenarios that require the current index number of a looping structure within a map to be known. In the energy usage example, it allows a generic list of chronological usage values to be mapped to a document containing only those values that occur in the afternoon, along with adding an element describing to which hour that usage pertains. As the map processes the repeating HourlyUsage records in the source XML in a sequential fashion, the index from the Iteration functoid is passed to the logical Greater Than functoid, which compares the index with a hard-coded value of 3. If the index value is 4 or greater, the element is created in the destination XML, and its hour ending value is set.

This example works well for the purposes of our simple scenario, but those who have dealt with hourly values of any kind know that days on which daylight saving time (DST) falls need to be handled carefully. Since the time change associated with DST actually occurs early in the morning, there are 13 morning (before afternoon) hourly values in the fall occurrence of DST, and 11 morning hourly values in the spring occurrence.

The map in Figure 3-37 can easily be enhanced to account for this by adding logic based on the record count of hourly values in the source XML document. You can accomplish this via the following steps:

In this modified example, the repeating source record's count has 12 subtracted from it to adjust for the two DST days of the year (this works since we are interested in only the afternoon energy usage values, which are always the final 12 readings for a day). This adjusted value is then passed through the same logical Greater Than functoid as in the previous example, and the DST issue is effectively handled.

The use of the Iteration functoid is common in a number of other scenarios. One such scenario is when dealing with a document formatted with comma-separated values (CSV). Often, the first row in a CSV document contains column header information, as opposed to actual record values. The following flat file snippet shows one possible representation of energy usage values in CSV format:

EnergyUsage,Adjustments
2.4,0
2.5,0
2.8,0

In cases like these, it is likely that you do not want to map the column headers to the destination XML document. You can use an Iteration functoid to skip the first record of a CSV document. The index from the Iteration functoid is passed to a logical Not Equal functoid, which compares the index with a hard-coded value of 1. If the index is anything other than 1 (the record at index 1 contains the column header information), the values are mapped to the destination XML.

Another common use of the Iteration functoid is to allow the interrogation of records preceding or following the currently processed record. This can be helpful when mapping elements in a repeating record in the source schema that require knowledge of the next or previous record.

You have a mapping need that requires the repeated use of complex functionality.

Rather than writing the same inline code (C#, XSLT, and so on) and pasting it in multiple shapes, or using a combination of multiple existing functoids, you can develop your own custom functoid.

As an example, we'll describe the process to develop, deploy, and use a custom functoid that replaces the ampersand (&), greater than (>), and less than (<) symbols with their HTML/XML equivalents. The functoid will have one input parameter and one output parameter, representing the string on which to run the replacement. This functoid would be used primarily with XML that may be returned from an external source, such as a .NET assembly, where the XML may not have been validated and contains characters that must be escaped.

Use the following steps to create, deploy, and use a custom functoid. Refer to the sample solution SampleCustomFunctoid.sln included with this book.

Figure 3.38. Adding a custom functoid to the Toolbox

This completes the steps for creating a custom functoid. You can now add the functoid to a BizTalk map and test it. When a map is ready for deployment, the functoid will need to be copied to the Mapper Extensions folder (see step 6) and the GAC on the production server. Figure 3-39 shows the new functoid with custom bitmap in the toolbox in Visual Studio.

Figure 3.39. The new functoid in the toolbox

One of the biggest benefits to using custom functoids is that you have full access to the .NET libraries. Inline code within maps gives only limited access to libraries, and coding is often primitive. Custom functoids are created as .NET class libraries, and they have all of the related coding benefits.

The example shown in this recipe is very simple. Custom functoids do not have to be limited to the two functions shown in the code. For example, assume that you need a functoid that does some sort of interaction with a database. You may need to include an Init() function and a deconstructor to terminate a connection, all of which can be included in the class library.

Additionally, you may need multiple input parameters for your functoid. Additional parameters can be added very easily. See Listing 3-21 for an example of a functoid with three input parameters.

SEE CODE FROM Listing 3-20.

            // three parameters in, one parameter out
            this.SetMinParams(3);
            this.SetMaxParams(3);

            ...

            // add one of the following lines of code for every input

// parameter. All lines would be identical.
            AddInputConnectionType(ConnectionType.All); // input parameter 1
            AddInputConnectionType(ConnectionType.All); // input parameter 2
            AddInputConnectionType(ConnectionType.All); // input parameter 3

        }

        // Actual function which does the replacement of symbols
        public string EncodeChars(String strInputValue, strReplace1, strReplace2)
        {
            strInputValue = strInputValue.Replace("&",strReplace1);
            strInputValue = strInputValue.Replace("<",strReplace2);

            return strInputValue;
        }

You are mapping a message in BizTalk Server and need to manipulate date and time fields. Specifically, you must use the current date in order to determine a required date and time in the future, which is added to the outbound message during mapping. Additionally, you must apply the processing time for each document during mapping.

Within a map, use the Date and Time functoids provided with BizTalk Server. To apply the current processing time to the outbound document within the map, take the following steps:

To determine a future date based on the current date, take the following steps:

An example of a map that uses the Date and Time functoids is shown in Figure 3-40.

Figure 3.40. Using the Date and Time Functoids

This example captures the current date and time in the TransactionProcessingDateTime element, which is supplied by the Date and Time functoid. The format of the date and time produced by the Date and Time functoid is YYYY-MM-DDThh:mm:ss, which is ISO 8601-compliant. The time values are notated in 24-hour format.

The future date that the deposited funds will be available is captured in the FundsAvailableDateTime element. This value is based off the current date, supplied by the Date functoid, with a single day added to it to provide tomorrow's date, which is supplied by the Add Days functoid. The format of the Date functoid's output is YYYY-MM-DD, while the Add Days functoid accepts dates formatted as YYYY-MM-DD or YYYY-MM-DDThh:mm:ss. The format of the Add Days functoid's output is YYYY-MM-DD. All date formats used by these two functoids are ISO 8601–compliant. The time values are notated in 24-hour format.

The XML in Listing 3-22 represents one possible instance of the source schema.

<ns0:ATMDeposit xmlns:ns0="http:// DateTimeFunctoids.ATMDeposit">
  <ATMNumber>00111</ATMNumber>
  <AccountNumber>123456</AccountNumber>
  <Amount>100.00</Amount>
  <Currency>USD</Currency>
</ns0:ATMDeposit>

When passed to the map in Figure 3-40, this XML message will produce the outbound XML document shown in Listing 3-23.

<ns0:BankDeposit xmlns:ns0="http://Mapping.BankDeposit">
  <TransactionSourceNumber>00111</TransactionSourceNumber>
  <Account>123456</Account>
  <Amount>100.00</Amount>
  <Currency>USD</Currency>
  <TransactionProcessingDateTime>2010-09-06T16:32:05</TransactionProcessingDateTime>
  <FundsAvailableDateTime>2010-09-07</FundsAvailableDateTime>
</ns0:BankDeposit>

The Date and Time functoids provide a baseline set of functionality when needing to interrogate and manipulate date and time values. In the bank account example, the Date and Time functoid provides the current date and time, allowing a timestamp to be applied to the outbound document, indicating the time that the message was processed. Often, messages include an element or elements detailing the time that the message pertains to, or the time at which a message was created. The Date and Time functoid is useful when the actual processing time (in this example, the time a deposit is processed within a bank's integration system) is required, which will likely be different from any time value embedded in the source document. The difference between date and time values within a source instance message and the actual processing time of the message can be particularly important when dealing with batched or time-delayed processes.

This example also shows how you can use the Date and Add Days functoids in conjunction to calculate a future date based on the day a message is processed. The current date is provided by the Date functoid, which is used by the Add Days functoid to come up with a date that is a specified number of days in the future. In the bank account scenario, this functionality is used to determine the day on which deposited funds are available. Business rules like this can be common among financial institutions, as validation procedures are often required when dealing with monetary transactions.

This bank account example can be extended to illustrate how the Time functoid can be used to add a time component to the data capturing the date at which deposited funds are available. Currently, the example simply calculates a date for this value, but it is likely that a financial institution would additionally need to know the time at which deposited funds should be made available for use. Since the Add Days functoid produces only date values (without a time component), you must use a Time functoid, in addition to a String Concatenate functoid. To implement this enhancement, take the following steps:

Figure 3-42 shows an example of a map implementing these changes.

Figure 3.42. Using the Time functoid

Based on the same source XML used in the preceding example, the map in Figure 3-42 will produce the XML document shown in Listing 3-24, with a time component included in the FundsAvailableDateTime element.

<ns0:BankDeposit xmlns:ns0="http://Mapping.BankDeposit">
  <TransactionSourceNumber>00111</TransactionSourceNumber>
  <Account>123456</Account>
  <Amount>100.00</Amount>
  <Currency>USD</Currency>
  <TransactionProcessingDateTime>2010-09-06T16:32:04</TransactionProcessingDateTime>
  <FundsAvailableDateTime>2010-09-07T16:32:05</FundsAvailableDateTime>
</ns0:BankDeposit>

One common challenge when dealing with datetime values is standardizing on a common format. This issue can be seen with dates adhering to the MM-DD-YYYY (common in the United States) or DD-MM-YYYY (common in Europe and other areas) format. Unfortunately, BizTalk Server does not have any Date and Time functoids that do complex datetime formatting. There are a number of ways to handle this issue. The simplest way is to use string functoids provided with BizTalk Server to manipulate and standardize the order of year, month, and day values. Specifically, you can use String Extract functoids to pull out values within a date (in this scenario, you would pull out the DD, MM, and YYYY values in three separate String Extract functoids), and then a String Concatenate functoid to combine the individual values in the correct format (in this scenario, you would append the three values in an order of YYYY-MM-DD).

There are also more robust ways of implementing complex date/time formatting. One option is to use the Scripting functoid, which provides access to the libraries of C#, VB .NET, and JScript .NET (either via inline code embedded in the map, or by referencing external assemblies written in one of the .NET-compliant languages). Additionally, you could use a custom functoid (which would leverage the datetime functionality of a .NET language).

You need to map values from the source to the destination message depending on whether a logical condition evaluates to true or false.

Define the logical condition that the mapping actions should be based on by dragging logical functoids from the toolbox onto the map surface. Any functoid or combination of functoids that returns a Boolean value can establish the logical condition, but these functoids can return only true or false.

In this example, the logical condition will check whether the amount of a sale is greater that 1,000, as shown in Figure 3-43.

Figure 3.43. Creating the logical operator

Only large sales should appear under the <BigSales> element in the destination message, so the logical condition will check if the Amount in the source message is greater than 1,000. The following steps define the logical operation that determines mapping actions, as shown in Figure 3-44.

Figure 3.44. Defining the comparison value

Next, define the mapping actions that depend on the evaluation of the logical condition. In this example, the contents of the <Sales> elements should map to different parts of the destination message, so the map must use the Boolean outcome of the logical comparison as input to a Value Mapping functoid.

The Value Mapping functoid defines the action the map should take when the logical condition evaluates to true. Both the amount of the big sale and the name of the sales representative must appear in the destination message in this example, so the map must use two Value Mapping functoids, as shown in Figure 3-45.

Figure 3.45. Defining conditional mapping actions

BizTalk must also know that it should create only the <RepSales> element in the destination message when the amount is greater that 1,000. Establishing a link from the logical operator to the RepSales element will ensure that BizTalk creates this parent to the actual values mapped.

When the logical condition evaluates to false, BizTalk should map the sale to the <SmallSales> part of the destination message. The map can check this directly by placing a Not Equal functoid on the mapping surface and comparing to the result of the logical comparison established earlier with a constant value equal to true, as shown in Figure 3-46.

Figure 3.46. Defining the else condition

Finally, define the mapping actions that BizTalk should take when the logical comparison is not true. In this example, the Value Mapping functoids simply need to map under the <SmallSales> element in the destination message.

Figure 3.47. Completed If-Then-Else map

Working with the BizTalk Mapper can be an unfamiliar process, even to experienced programmers. Business rules defined in source code can be procedural and explicit, but the graphical depiction of a BizTalk map can abstract the runtime behavior.

The link to the logical condition defines the information on which the map will perform the logical operation. BizTalk will evaluate the logical condition for each occurrence of the information in the source message, and remember the context of the logical condition when performing the output actions dependent on it. This means that the Value Mapping functoid will automatically know the right Amount and RepName values to map when the map executes.

The order of the Value Mapping functoid inputs is critical. The first input parameter must be either true or false. The second input parameter specifies the value that the functoid will return when the first parameter is true. While the order is established based on the order in which the inputs are connected to the Value Mapping functoid, sometimes the order can get mixed up when modifying the functoid links. There is no indication of the input parameter order on the mapping surface, but fortunately, it is easy to check. Open the Configure Functoid Inputs window, and the Boolean value should appear first in the list. Modify the order here by selecting one of the input parameters and clicking the up and down arrows.

This example establishes a logical condition and defines mutually exclusive mapping actions that are directly determined from the evaluation of the logical conditions. Alternatively, a map can define separate logical conditions independently. With this alternative approach, the developer must carefully define the logical conditions to ensure that every input message will map to some outcome, and never both. This becomes an increasingly important consideration as the logical comparison becomes more and more complex.

When there are more than two mutually exclusive outcomes, the Not Equal functoid in this example can be combined with additional logical comparisons by linking its result to the Logical AND functoid. The result of the Logical AND functoid also evaluates to true or false, and the developer can define actions to take based on this result, as with any other logical operator.

You need to access logic contained within an external assembly while transforming a message via a BizTalk Server map. The logic contained within the assembly cannot and should not be embedded within the map.

Create a map that uses the BizTalk Server Scripting functoid's ability to call external assemblies. The following steps outline the procedure:

In this example, the functoid in the map determine whether there is enough time before the event for the tickets to be mailed to the purchaser. The XML snippet shown in Listing 3-25 represents one possible instance of the source schema.

<ns0:TicketRequest xmlns:ns0="http://Mapping.TicketRequest">
  <EventName>Chelsea vs. Arsenal</EventName>
  <EventDate>08/06/2010</EventDate>
  <Venue>Stamford Bridge</Venue>
  <NumberOfTickets>2</NumberOfTickets>
  <PurchasedBy>George Murphy</PurchasedBy>
  <MailTicketFlag>True</MailTicketFlag>
</ns0:TicketRequest>

Based on this source XML, the map will produce the XML document (assuming that the current date is prior to August 4, 2010) shown in Listing 3-26, with the MailedTicketFlag appropriately set.

<ns0:TicketOrder xmlns:ns0="http://Mapping.TicketOrder">
  <Title>Chelsea vs. Arsenal</Title>
  <Date>08/06/2010</Date>
  <Venue>Stamford Bridge</Venue>
  <NumOfTickets>2</NumOfTickets>
  <TicketHolder>George Murphy</TicketHolder>
  <MailedTicketFlag>True</MailedTicketFlag>
</ns0:TicketOrder>

This example demonstrates one of the many reasons why external assemblies may need to be called from a BizTalk Server map. Here, the external assembly provides access to a configuration value. This value is held in a configuration file (but alternatively could be held in a database or other data store), which is updated over time by system administrators and business analysts. For the purposes of this example, the following configuration value was used.

<add key="MinimumDaysAdvanceForMailedTickets" value="-2" />

The value of −2, which represents the minimum number of days required to mail tickets to a purchaser, is added to the EventDate element (by the Add Days functoid), resulting in a date value two days prior to the event (08/04/2006 in this example). The current date (supplied by the Date functoid) is then compared to the calculated date value (by the Less Than logical functoid) to determine if there is enough time to mail the purchased tickets. Finally, if there is ample time to mail the tickets, and the source document indicates the purchaser requested tickets to be mailed, the MailedTicketFlag element in the destination message is set to true.

The benefit of having the MinimumDaysAdvanceForMailedTickets value stored in a file external to BizTalk, as opposed to being hard-coded within the actual map, is that a change to the value does not require a redeployment of BizTalk Server artifacts for the modification to be applied. Additionally, by encapsulating the custom logic in an external assembly, any changes to that logic will require only that the external assembly is rebuilt and redeployed to the GAC. No changes to the BizTalk Server environment (aside from a BizTalk service restart to immediately apply the changes in the redeployed custom assembly) are required. Implementing this logic in an external assembly has the additional benefits of allowing reuse of the logic, minimizing code maintenance, and providing access to the debugging utilities within Visual Studio.

In addition to using a generic external assembly, a custom functoid could also have been used to implement the configuration value retrieval logic. It is important to consider the differences between the two options prior to selecting your design. The main benefit of using a custom functoid is that the assembly is hosted within the BizTalk Server environment. The actual assembly file is located within the BizTalk Server program file directory, and the functoid can be added to the Functoid Toolbox within the development environment. Using generic external assemblies is sometimes a requirement, however, such as when the existing logic contained within them needs to be accessed directly (without modification to the source code or assembly location). This may be the case when using third-party or proprietary assemblies, where you do not have access to the source code.

Other common examples of logic contained in external assemblies are complex database-retrieval mechanisms, calculations above and beyond what is possible with the out-of-the-box mathematical functoids, and complex date and string formatting.

You are mapping a message in BizTalk Server and must implement custom logic via an inline C# code snippet. The custom logic should be embedded within the map.

Create a map that uses the BizTalk Server Scripting functoid's ability to call inline C#. The following steps outline the procedure:

An example of a map that uses the BizTalk Server Scripting functoid's ability to call inline C# is shown in Figure 3-51.

In this example, auction bids from the United States are transformed into European Union (EU) bids. The Scripting functoids used in the map format the date and datetime values common in the United States to those that are common in the EU. The XML snippet in Listing 3-28 represents one possible instance of the source schema.

<ns0:AuctionBidUS xmlns:ns0="http://Mapping.AuctionBidUS">
  <BidID>12345</BidID>
  <LotID>123-456</LotID>
  <BidDate>09/25/2010</BidDate>
  <LotCloseDateTime>09/18/2010 23:59:59</LotCloseDateTime>
</ns0:AuctionBidUS>

Figure 3.51. Using the Scripting functoid to call inline C#

Based on this XML snippet, the map displayed will produce the XML document shown in Listing 3-29. Notice that the format of the BidDate and LotClosedDateTime values have been changed from MM/DD/YYYY and MM/DD/YYYY hh:mm:ss format to DD/MM/YYYY and DD/MM/YYYY hh:mm:ss format, respectively.

<ns0:AuctionBidEU xmlns:ns0="http://Mapping.AuctionBidEU">
  <BidID>12345</BidID>
  <LotID>123-456</LotID>
  <BidDate>25/09/2010</BidDate>
  <LotCloseDateTime>18/09/2010 23:59:59</LotCloseDateTime>
</ns0:AuctionBidEU>

Date formatting like this is one of countless examples where custom logic could be needed within a BizTalk Server map. In the auction bid example, date and datetime values were formatted with inline C# to account for regional differences. Additionally, in the first Scripting functoid, two variables were defined that specify the date and datetime format for the EU. This illustrates another helpful use of Scripting functoids: the ability to create global variables that can be used by any other functoid within the map. In the example, the UStoEUDateFormatter method in the second Scripting functoid referenced the EUDateTimeFormat variable that was defined in the first Scripting functoid.

You can format dates in a number of different ways within a BizTalk Server map. In our example, we used inline C#, but we could have used either of the other available script languages (VB .NET or JScript .NET), an external assembly, or a custom functoid.

Inline scripting is a good option when a simple implementation of custom logic is needed, and the logic is unlikely to be leveraged outside the map. It is important to recognize a key limitation of inline scripting: debugging utilities. Because the inline script is embedded into the map's XSLT, stepping into the code at runtime is not possible. One possible way to allow easier debugging of an inline script is to first create and test it in a separate executable or harness. This will allow you to use the robust debugging utilities of Visual Studio. Once the code has been fully tested, it can be placed into a Scripting functoid.

The fact that the inline script is saved in the XSLT of the map has another important consequence: only those libraries available to XSLT style sheet scripts may be leveraged. The following are available namespaces:

You need to include information from variables in an orchestration in the destination message of a BizTalk mapping.

Begin by creating a new message schema with fields for capturing the information from the orchestration, as shown in Figure 3-52. The information from the orchestration variables must be set in a separate message from the input message, referred to here as a context message. In this recipe, the mapping will transform a customer purchase message for the customer support department, and the orchestration will define the support information with the business process. BizTalk will use the new message schema to capture the support information.

Figure 3.52. Defining the context message schema

Follow these steps to set up the orchestration.

xmlXmlDoc.LoadXml("<ns0:MapContext xmlns:ns0=
'http://PassingOrchestrationVariablesIntoMaps.MapContext'>
<SupportCode>SupportCode_0</SupportCode> <SupportExpires>SupportExpires_0</SupportExpires>
</ns0:MapContext>");

msgContext = xmlXmlDoc;

Figure 3.56. The Message Assignment

Once instantiated, the values in MapContextMsg can be set anywhere in the orchestration. For simplicity in this example, they are created and set in the same Message Assignment shape, and the expiration is the same day that the context message is created, as shown in Listing 2-31 and Figure 3-57.

msgContext.SupportCode = "R-2";
msgContext.SupportExpires = System.DateTime.Now.ToString("yyyy-MM-dd");

Figure 3.57. Setting the values of the context message

Once the context message contains the required orchestration information, the BizTalk orchestration must create the mapping. The orchestration must create mappings that have more than one source or destination message.

BizTalk will generate a new transformation with two input messages and one output message. One of the input messages will be the MapContextMsg message containing the values from the orchestration. The developer can choose to either drive mapping logic from these values or map them directly to the destination message as in this example, as shown in Figure 3-59.

Figure 3.59. Defining mapping logic from the source messages

BizTalk developers often think about translation among message types when defining integration processes in an orchestration. They can place a Transform shape directly within an orchestration to transform a message into different formats, so it seems that the transformation and orchestration are integral to each other. However, the BizTalk mapper cannot directly access the contextual information of the business process and the logic existing in the orchestration.

The BizTalk Mapper can natively access many resources outside the map with the default functoids. For example, the Database Lookup functoid can access records in a database, and the Scripting functoid can invoke an external assembly. However, the most direct way to access information about the context of the business process is by creating a message specifically for capturing the state of the business process. Add the information required in the mapping to this additional message, and then add the context message as an additional input message to the map.

The possible reasons for passing information from an orchestration into a mapping with a second message are as varied as the capabilities of BizTalk orchestrations. However, in all cases, the mapping destination message must contain information that cannot or should not be added to the schema of the input message. Here are some examples:

You need to map an incoming document with a node containing a document that matches exactly the destination schema. All of the nodes in the source document need to be mapped in their entirety to the destination document. Both the source and the destination schemas have target namespaces, and the namespaces must be preserved.

By using inline XSLT within a Scripting functoid, you can create the target document with the appropriate nodes and the correct namespace. Listing 3-32 shows a sample input document.

<ns0:SampleSource xmlns:ns0="http://Sample.Source">
  <ID>ID_0</ID>
  <Payload>
    <SampleDestination>
      <Name>Name_0</Name>
      <Address>Address_0</Address>
      <Company>Company_0</Company>
    </SampleDestination>
  </Payload>
</ns0:SampleSource>

The inline XSLT is written to parse the incoming document as a whole; there is no need to have an input to the Scripting functoid. The output of the Scripting functoid occurs under the node that the output is tied to—in this case, the XSLT output will be directly below the SampleDestination element. When XML documents contain namespaces, use the local-name() qualifier to reference a specific node by name. Because of the requirement that the namespaces be preserved, it is necessary to copy each of the nodes in the source document's Payload node (which consists of an Any element that can contain any XML structure) separately to the destination document.

Figure 3-60 shows the configuration for the Scripting functoid with the inline XSLT for the <Name> element. Additional nodes (such as Address and Company) can be added using the same code pattern. See Listing 3-33 for the XSLT code.

<xsl:if test="//*[local-name()='SampleDestination'])/*[local-name()='Name']">
 <xsl:element name="Name">
 <xsl:value-of select="//*[local-name()='SampleDestination']/*[local-name()='Name']"/>
</xsl:element>
</xsl:if>

Figure 3.60. Configuring the Scripting functoid to use inline XSLT

This XSLT script will produce the desired XML document on output, as shown in Listing 3-34.

<ns0:SampleDestination xmlns:ns0="http://Sample.Dest">
  <Name>Name_0</Name>
  <Address>Address_0</Address>
  <Company>Company_0</Company>
</ns0:SampleDestination>

The two expected solutions to this, the Mass Copy functoid or the <xsl:copy-of> function, both end up requiring additional logic and code outside the map due to the presence of the namespaces. These can be solved in orchestration mapping but not in maps outside orchestrations. An additional approach would be to reference an external XSLT file where more complex functions are available.

The Mass Copy functoid, designed specifically to copy entire documents to a destination node, is a graphic representation of the XSLT <xsl:copy-of> function. Both of these copy the entire source document to the destination document. The problem is that the source document namespace will be copied to the target document, regardless of the node level being copied. There is no simple way in XSLT to remove the source document namespace. For instance, if in the given solution for this recipe, the inline XSLT was changed to simply read:

<xsl:copy-of select="//*[local-name()='Payload']"/>

The following document would be created on output of the map (note that the root node contains the namespace of the source schema):

<Payload xmlns:ns0="Sample.Source">
  <SampleDestination>
    <Name>Name_0</Name>
    <Address>Address_0</Address>
    <Company>Company_0</Company>
  </SampleDestination>
</Payload>

If a Mass Copy functoid were used on the Payload node, the following document would be produced (note that the root node repeats itself and that it contains the namespace of the source schema):

<ns0:SampleDestination xmlns:ns0="http://Sample.Dest">
  <SampleDestination xmlns:ns0="http://Sample.Source">
    <Name>Name_0</Name>
    <Address>Address_0</Address>
    <Company>Company_0</Company>
  </SampleDestination>
</ns0:SampleDestination>

The output document for both of these approaches is not the desired outcome. However, if the mapping is being done in an orchestration, the output document will be in a message that can now be accessed and corrected in a Message Assignment shape, using the code in Listing 3-35.

// xmlDoc is a variable of type System.Xml.XmlDocument()
// msgSampleDestination contains the output of the map

// xpath will access the contents of the SampleDestination node
xmlDoc = xpath(msgSampleDestination, "/*/*");

// populate the message
msgSampleDestination = xmlDoc;

Another option would be to move the entire solution to an external XSLT document, where more complex functions such as templates are available, and reference it in the map directly rather than using the mapping functions. This can be done by selecting properties on the map being developed and indicating the path to the XSLT file in the Custom XSLT Path property.

In summary, a number of approaches can be taken to map an incoming document with a node containing a document that matches exactly the destination schema. The cleanest and most viable approach is described in this recipe's solution. Quicker and more convoluted solutions involve using the Mass Copy functoid and <xsl:copy-of> function. An additional approach is to move the mapping completely out of the map into a separate XSLT document. The appropriate solution must be decided by the developer.

You want to use the inline XSLT call template functionality within the Scripting functoid and understand the difference between inline XSLT and an inline XSLT call template.

Use the following steps to add an Inline XSLT Call Template functoid call to a map. The steps assume the schemas shown in the map in Figure 3-61 are being used.

Figure 3.61. Scripting/XSLT call template in a map

<ns0:Person xmlns:ns0="http://UsingCallTemplate.Person">
  <ID>1</ID>
  <Name>S. Brekalo</Name>
  <Role>Acupuncturist</Role>
  <Age>33</Age>
</ns0:Person>

<Company>
 <ID>Default Company ID</ID>
 <Name>Default Company Name</Name>
 <Employees>
  <Employee>
   <ID>1</ID>
   <Name>S. Brekalo</Name>
   <Role>Acupuncturist</Role>
   <Age>33</Age>

</Employee>
 </Employees>
</Company>

Calling an XSLT template is very similar to using inline XSLT. The main difference is the way in which values within the source document are passed and accessed. With inline XSLT, node values in the source document are accessed through XSL methods, whereas with called XSLT templates, the values are passed in as parameters.

In the case where code may need to be reused for multiple nodes, it may be more advantageous to create a template that can be reused without modifying the code. Templates will also allow for more traditional programming techniques, such as setting and updating variables dynamically within the template (for example, the ability to update a variable to store the number of loops that have occurred within a for-each loop).

Listing 3-39 demonstrates the use of inline XSLT rather than a called XSLT template. The output of Listing 3-39 will produce the same output as that of the XSLT template code shown earlier in Listing 3-36.

<xsl:element name="Company">
 <xsl:element name="ID">Default Company ID</xsl:element>
 <xsl:element name="Name">Default Company Name</xsl:element>
 <xsl:element name="Employees">
  <xsl:element name="Employee">
   <xsl:element name="ID">
    <xsl:value-of select="//*[local-name()='ID']" />
   </xsl:element>
   <xsl:element name="Name">
    <xsl:value-of select="//*[local-name()='Name']" />
   </xsl:element>
   <xsl:element name="Role">
    <xsl:value-of select="//*[local-name()='Role']" />
   </xsl:element>
   <xsl:element name="Age">
    <xsl:value-of select="//*[local-name()='Age']" /></xsl:element>
   </xsl:element>
  </xsl:element>
 </xsl:element>
</xsl:element>

You need to define mapping from an input message with a flat structure to an output message grouping elements by the values of fields in the input message.

The input message must have records containing a field on which the grouping should be performed, as well as the information that needs to be grouped together. The output message needs to define records for each group and a field containing the aggregated information. The input message may have a structure similar to the XML in Listing 3-40.

<ns0:Sales xmlns:ns0="http://tempURI.org">
  <Sale>
    <Amount>100.01</Amount>
    <RepName>Megan</RepName>
  </Sale>
  <Sale>
    <Amount>200.01</Amount>
    <RepName>Megan</RepName>
  </Sale>
  <Sale>
    <Amount>10.10</Amount>
    <RepName>Leah</RepName>
  </Sale>
  <Sale>
    <Amount>2000</Amount>
    <RepName>Misti</RepName>
  </Sale>
  <Sale>
    <Amount>50.10</Amount>
    <RepName>Leah</RepName>
  </Sale>
</ns0:Sales>

To create the mapping, follow these steps:

<xsl:for-each select="//Sale[not(RepName=preceding-sibling::Sale/RepName)]/RepName">
  <RepSales>
    <RepTotalAmount>
        <xsl:value-of select="sum(//Sale[RepName=current()]/Amount)"/>
     </RepTotalAmount>
    <RepName>
        <xsl:value-of select="current()"/>
    </RepName>
  </RepSales>
</xsl:for-each>

This XSLT script will produce the XML message shown in Listing 3-42, containing one RepSales element for each sales representative with the total sales and name of the representative.

<ns0:SalesByRep xmlns:ns0="http://tempURI.org">
  <RepSales>
    <RepTotalAmount>300.02</RepTotalAmount>
    <RepName>Megan</RepName>
  </RepSales>
  <RepSales>
    <RepTotalAmount>60.2</RepTotalAmount>
    <RepName>Leah</RepName>
  </RepSales>
  <RepSales>
    <RepTotalAmount>2000</RepTotalAmount>
    <RepName>Misti</RepName>
  </RepSales>
</ns0:SalesByRep>

The key feature of this inline XSLT example is the select statement appearing in the xsl:for-each element. This statement will create a list of values to create a group for, containing the distinct values of RepName in our example. Each RepName is located at //Sale/RepName in the input message. However, the select statement should obtain only the first occurrence of each distinct group value. This inline example achieves this by adding the filter [not(RepName=preceding-sibling::Sale/RepName)] to the select statement. The xsl:for-each element will loop through the first occurrence of each unique grouping value, and the value can be obtained within the xsl:for-each element with the current() function.

When the filter expression evaluates a Sale element, the condition RepName=preceding-sibling::Sale/RepName is true whenever there is an element appearing before it with the same RepName value. Placing the condition inside the not() function makes it true only when there are no preceding elements with the same RepName value, so it is only true for the first occurrence of each distinct RepName value.

The inline XSLT script in Listing 3-41 calculates the total sales of each representative and creates one record in the output message containing the total sales and the sales representative's name.

In addition to grouping fields in the output message, the map may need to perform aggregations for the groups of input message values. Perhaps BizTalk cannot determine the specific groupings that the map needs to perform until runtime, or static links may not be practical because of a large number of possible groups.

When inline XSLT performs the grouping, BizTalk applies the filter expression to the //Sale statement, which means BizTalk applies the filter expression to every Sale element in the input message. For each input message, the expression checks the value of every preceding-sibling and returns true when none of the preceding-sibling elements has the same RepName value. This algorithm is not efficient for large messages.

There is a generally more efficient alternative XSLT approach to the group by problem. This alternative approach is the Muenchian method. The Muenchian method is generally more efficient than the inline solution presented here, but the default BizTalk functoids cannot implement it. The Muenchian method declares an xsl:key element at the top level of the XSLT style sheet. The map directly obtains a node set for each distinct RepName with an xsl:key, eliminating the computational cost of checking every preceding sibling incurred with inline XSLT. However, since the top level of the xsl:stylesheet element must declare the xsl:key element, inline XSLT cannot implement it. Only a separate style sheet file can implement the Muenchian method. Place the XSLT style sheet in Listing 3-43 in a separate file for this example.

<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:key name="SalesByRepKey" match="Sale" use="RepName"/>
    <xsl:template match="/">
        <ns0:SalesByRep xmlns:ns0='http://tempURI.org'>
<xsl:apply-templates select="//Sale[generate-id()=
generate-id(key('SalesByRepKey', RepName)[1])]"/>
        </ns0:SalesByRep>
    </xsl:template>
    <xsl:template match="Sale">
        <RepSales>
            <RepTotalAmount>

<xsl:value-of select="sum(key('SalesByRepKey', RepName)/Amount)" />
            </RepTotalAmount>
            <RepName>
<xsl:value-of select="RepName" />
            </RepName>
        </RepSales>
    </xsl:template>
</xsl:stylesheet>

Specify the external XSLT file used by a BizTalk map (see the next recipe for steps on doing this).

You are fed up with the mapper and can't stand using functoids. You have a complex map that you feel like getting done programmatically, and you want to shell out to real XSLT.

It is quite simple to shell out to an XSLT document. Take these steps:

Sometimes, it is best to use XSLT directly, instead of using the BizTalk mapping functionality. This can be for a variety of reasons but generally is useful when there is a lot of complex mapping that uses If-Then-Else to populate fields. Because this type of logic can get complex with the use of Value Mapping functoids, pure XSLT can be much easier to use. See Figure 3-62.

Figure 3.62. Shelling out to an external XSLT style sheet

You have developed a map and are ready to test and view its output.

For the purposes of testing, there are two basic types of maps:

This solution will work through both types, illustrating several techniques for creating the necessary input documents and obtaining the test results. Figure 3-63 shows a simple map, with a Company schema being mapped from a combination of a Person schema and hard-coded values in two String Concatenate functoids.

Figure 3.63. A simple map

Use the following steps to test a simple map:

Testing complex maps requires several more steps to create a valid input instance. The main difference in testing the two types of maps lies in how the input instances are generated.

When a map has multiple source schemas, they are wrapped in a hierarchy created by BizTalk. This hierarchy must be matched if using anything other than Generate Instance for the TestMap Input. In cases where nodes such as Any elements or Any attributes exist in the source documents, generated instances will fail during testing. It then becomes a requirement to create by hand an instance of the multipart input document.

A map can have two or more source documents specified through the use of a Transform shape in a BizTalk orchestration (as shown in Figure 3-65).

Figure 3.65. Specifying two source schemas on a map in a Transform shape

Figure 3-66 shows a complex map with a Company schema being mapped from a combination of two source schemas, Person and SourceCompanyInfo.

Figure 3.66. A complex map

There is never a time in which multiple native instances can be set as source, since the only place that a map with multiple source schemas can be created is in a Transform shape within an orchestration. Therefore, the following steps are specific to creating XML instances that match the multipart input instance needed and can be taken to aid in producing a valid source instance:

The difficulty in testing maps lies in the creation of the source schema instances. There are a number of ways in which these instances can be created. The objective of this solution was to provide the steps necessary for creating documents that would allow for the testing of both simple maps and complex maps. Additionally, the steps necessary for producing the test output were described.

You need to step through your map code just like you would with other .NET code in order to debug.

Debugging a map can be done using the following steps:

Figure 3.69. Actively Debugging

Debugging a map is very straightforward, and can be useful in many situations. With some maps, such as Inline XSLT Call Templates, the debugger is not of much use, but for the majority of cases, it can be very helpful. Prior to BizTalk 2010, there were some techniques to debug the map, but they were not as readily available and easy to implement. Standard debug shortcuts apply, including

F5 to continue