BizTalk Server Tutorial

BizTalk Server Concepts and Common Errors

Cross Reference Functoids Description and Example in BizTalk Server

While using BizTalk server for Integration of Applications, we may face a situation where a Value – for Eg: A status of “Pending” – in Application1 may have to be mapped to an equivalent and different value in Application2.

Literally, you may receive a message in which Status is “Pending” and assume you may have to map this to a status call “On Hold” to an outgoing message.

How can we achieve this??

There are many possible ways.

1. Write an inline script / xslt in a Scripting Functoid

2. Use an External dll that takes an input and returns an equivalent output

3. Use of BizTalk Server Cross Reference Functoids.

4. Custom Functoids and Lots of more options….

This article will describe the use of BizTalk Server Cross Reference.

Problem:

Assume that you input message status has to be mapped to an output message status in the following way.

Input Status (Application1 Message) –> Output Status (Applicaiton2 Message)–> Common Value which we use to Represent both of them

1. Approved –> Accepted –> Accept

2. Pending –> On Hold –> Hold

3. Denied –> Stopped –> Deny

Approach:

The idea behind the Cross Reference is Simple.

a) You create XML Files that represent the Cross Reference Data.

b) These XML files (data) are imported to a set of Tables inside BizTalk Management Database using a Cross Reference Utility

There are 2 types of Cross Reference – ID Cross Reference and Value Cross Reference.

The purpose of both of them will be same and the way they operate internally will be different.

c) From the input message, if you receive the status as “Approved”  use this status “Approved” and the Application Source as “Application1” and find the Common Value “Accept”

(This is done using Get Common Value / Get Common Id Functoids)

d) Use the Common Value as “Accept” and use the Application Name as “Application2” and find the key word “Accepted” which is mapped to Application2

(This is done using Get Application Value / Get Application Id Functoids)

Solution:

Hope this gives an Idea. So lets start working on the above 4 points.

Using ID Cross Referencing.

a) create XML Files that represent the Cross Reference Data.

Below are the XML Files Required for ID Cross Referencing.

SetUp-Files Document- Download the Sample here

listOfAppType Document- Download the Sample here

listOfAppInstance Document- Download the Sample here

listOfIDXRef Document – Download the Sample here

listOfIDXRefData Document – Download the Sample here

Purpose of the above XML Files:

SetUp-Files – This will have the path to all other files

listOfAppType – This will have the list of applications. In our case it is “Application1” and “Application2”

listOfAppInstance – For each Application created, an instance should be created

listOfIDXRef – This XML file will hold the IDs for which we create Data. In our case it is the “Status”

listOfIDXRefData –  This file will hold the data for Common value, “Application1” data and “Application2” Data

b) Modify the above XML files.

SetUp-Files:

Create a folder named IDXref in C Drive and copy all the XML files to that location. The name of the XML files that you mention in the Setup file should match the physical name of the XML Files.

Update the Setup-File like below.

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<Setup-Files>
<App_Type_file>c:\IDXref\ListOfAppType.xml</App_Type_file>
<App_Instance_file>c:\IDXref\ListOfAppInstance.xml</App_Instance_file>
<IDXRef_file>c:\IDXref\ListOfIDXRef.xml</IDXRef_file>
<IDXRef_Data_file>c:\IDXref\ListOfIDXRefData.xml</IDXRef_Data_file>
</Setup-Files>

listOfAppType – Here we have 2 applications “Application1” & “Application2”

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<listOfAppType>
<appType>
<name>Application1</name>
</appType>
<appType>
<name>Application2</name>
</appType>
</listOfAppType>

listOfAppInstance – Here create an Instance for each of the 2 applications.

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<listOfAppInstance>
<appInstance>
<instance>Application1Instance</instance>
<type>Application1</type>
</appInstance>
<appInstance>
<instance>Application2Instance</instance>
<type>Application2</type>
</appInstance>
</listOfAppInstance>

listOfIDXRef – Here we create IDs for each of the cross referencing we do.

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<listOfIDXRef>
<idXRef>
<name>Status</name>
</idXRef>
</listOfIDXRef>

listOfIDXRefData – Here we define the data for both “Application1” & “Application2”

<listOfIDXRefData>
<idXRef name=”Status“>
<appInstance name=”Application1Instance“>
<appID commonID=”Accept“>Approved</appID>
<appID commonID=”Hold“>Pending</appID>
<appID commonID=”Deny“>Denied</appID>
</appInstance>
<appInstance name=”Application2Instance“>
<appID commonID=”Accept“>Accepted</appID>
<appID commonID=”Hold“>On Hold</appID>
<appID commonID=”Deny“>Stopped</appID>
</appInstance>
</idXRef>
</listOfIDXRefData>

c) Now you have all the data that you need for your ID cross Reference. Now deploy these data to the BizTalk Management Database.

Give the following Command in your command prompt c:\IDXref\.

btsxrefimport  –file=setupfile

Note: Your current prompt should be pointing to the path c:\IDXref\. The name of the setup file should be setupfile.xml

Now log into the BizTalk Management Database, check the below tables.

xref_AppType, xref_AppInstance ,xref_IDXRef ,xref_IDXRefData.

These tables would have been updated with the data that you imported.

d) Using the Cross Reference in your MAP.

From the Tool box drop the Get Common ID Functoid and connect the Status field from your source schema to it.

Double Click the Get Common ID Functoid and add 2 more inputs as shown below

First Input – ID which you added in listOfIDXRef XML file.

Second Input – Application Instance from which the input is coming.

Third Input – Actual value which should be converted.

The output of this Functoid will be our common values. Eg: Accept, Deny, Hold based on the input.

Now drop the Get Application ID Functoid and connect the output of Get Common ID Functoid to this one.

Configure the Get Application ID Functoid Inputs as shown below.

First Input – ID which you added in listOfIDXRef XML file.

Second Input – Application Instance to which the input is to be converted.

Third Input – Common value from the Get Common ID Functoid.

The Output of this Functoid will be the equivalent Application2 value for the Application1 Input.

Using Value Cross Referencing:

Value cross Reference is used in the same way as ID Cross Reference. The only change is the Input to the Get Common Value and Get Application Value Functoids.

However there is a difference in which these two operate internally.

a) Create XML Files that represent the Cross Reference Data.

Below are the XML files required for Value Cross Referencing.

SetUp-Files Document- Download the Sample here

listOfAppType Document- Download the Sample here

listOfAppInstance Document- Download the Sample here

listOfValueXRef Document – Download the Sample here

listOfValueXRefData Document – Download the Sample here

Purpose of the above XML Files:

SetUp-Files – This will have the path to all other files

listOfAppType – This will have the list of applications. In our case it is “Application1” and “Application2”

listOfAppInstance – For each Application created, an instance should be created

listOfValueXRef – This XML file will hold the IDs for which we create Data. In our case it is the “Status”

listOfValueXRefData –  This file will hold the data for Common value, “Application1” data and “Application2” Data

b) Modify the above XML files.

SetUp-Files:

Create a folder named ValueXref in C Drive and copy all the XML files to that location. The name of the XML files that you mention in the Setup file

should match the physical name of the XML Files.

Update the Setup-File like below.

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<Setup-Files>
<App_Type_file>c:\ValueXref\ListOfAppType.xml</App_Type_file>
<App_Instance_file>c:\ValueXref\ListOfAppInstance.xml</App_Instance_file>
<ValueXref_file>c:\ValueXref\ListOfValueXref.xml</ValueXref_file>
<ValueXref_Data_file>c:\ValueXref\ListOfValueXrefData.xml</ValueXref_Data_file>
</Setup-Files>

listOfAppType – Here we have 2 applications “Application1” & “Application2”

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<listOfAppType>
<appType>
<name>Application1</name>
</appType>
<appType>
<name>Application2</name>
</appType>
</listOfAppType>

listOfAppInstance – Here create an Instance for each of the 2 applications.

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<listOfAppInstance>
<appInstance>
<instance>Application1Instance</instance>
<type>Application1</type>
</appInstance>
<appInstance>
<instance>Application2Instance</instance>
<type>Application2</type>
</appInstance>
</listOfAppInstance>

listOfValueXref – Here we create IDs for each of the cross referencing we do.

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<listOfValueXRef>
<valueXRef>
<name>Status</name>
</valueXRef>
</listOfValueXRef>

listOfValueXrefData – Here we define the data for both “Application1” & “Application2”

<?xml version=”1.0″ encoding=”UTF-8″ ?>
<listOfValueXRefData>
<valueXRef name=”Status“>
<appType name=”Application1“>
<appValue commonValue=”Accept“>Approved</appValue>
<appValue commonValue=”Hold“>Pending</appValue>
<appValue commonValue=”Deny“>Denied</appValue>
</appType>
<appType name=”Application2“>
<appValue commonValue=”Accept“>Accepted</appValue>
<appValue commonValue=”Hold“>On Hold</appValue>
<appValue commonValue=”Deny“>Stopped</appValue>
</appType>
</valueXRef>
</listOfValueXRefData>

Note: While defining this XML, Application name is used. Whereas in IDXref Application Instance is used.

c) Now you have all the data that you need for your ID cross Reference. Now deploy these data to the BizTalk Management Database.

Give the following Command in your command prompt c:\ValueXref\.

btsxrefimport  –file=setupfile

Note: Your current prompt should be pointing to the path c:\ValueXref\. The name of the setup file should be setupfile.xml

Now log into the BizTalk Management Database, check the below tables.

xref_AppType, xref_AppInstance ,xref_ValueXref ,xref_ValueXrefData.

These tables would have been updated with the data that you imported.

d) Using the Cross Reference in your MAP.

From the Tool box drop the Get Common Value Functoid and connect the Status field from your source schema to it.

Double Click the Get Common Value Functoid and add 2 more inputs as shown below

First Input – ID which you added in listOfValueXRef XML file.

Second Input – Application Name (not Instance) from which the input is coming.

Third Input – Actual value which should be converted.

The output of this Functoid will be our common values. Eg: Accept, Deny, Hold based on the input.

Now drop the Get Application Value Functoid and connect the output of Get Common Value Functoid to this one.

Configure the Get Application Value Functoid Inputs as shown below.

First Input – ID which you added in listOfValueXRef XML file.

Second Input – Application Name (Not Instance name) to which the input is to be converted.

Third Input – Common value from the Get Common Value Functoid.

The Output of this Functoid will be the equivalent Application2 value for the Application1 Input.

To get the differences between these 2 concepts further refer my another post.

– Shiv


Web Counters

November 11, 2010 - Posted by | Maps | , , , , , , ,

No comments yet.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: