BizTalk 2010 Recipes : Document Mapping - Seeding Cross-Reference Tables with ID Cross-References

1. Problem

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).

2. Solution

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

Example 1. List_Of_App_Type.xml

<?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 2.

Example 2. List_Of_App_Instance.xml

<?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.

Example 3. List_Of_IdXRef.xml

<?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 4.

Example 4. List_Of_IdXRef_Data.xml

<?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 5.

Example 5. Setup-Config.xml

<?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 5:

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

3. How It Works

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:

• xref_AppInstance

• xref_IdXRef

• xref_IdXRefData

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.