1. Problem
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.
2. Solution
To cross-reference the identifiers within a map, take the following steps:
Click the Database Functoids tab in the Toolbox.
Drag the Get Common ID functoid onto to the map surface.
Open the Input Parameters dialog box for the Get Common ID functoid.
Add
a constant parameter and set the value to the ID type you wish to
cross-reference. For instance, you may set the value to something like Customer.ID.
Add
a second constant parameter to the Get Common ID functoid, and set the
value to the source system application instance. For instance, you may
set the value to something like Siebel_01.
Connect the unique source identifier node you wish to cross-reference from the source schema to the Get Common ID functoid.
Drag
the Get Application ID functoid from the Database Functoids tab onto
the map surface, and place it to the right of the Get Common ID
functoid.
Open the Input Parameters dialog box for the Get Application ID functoid.
Add
a constant parameter and set the value to the ID type you wish to
receive. For instance, you may set the value to something like Customer.ID.
Add
a second constant parameter to the Get Common ID functoid and set the
value to the destination system application instance. For instance, you
may set the value to something like Oracle_01.
Connect the Get Common ID functoid to the Get Application ID functoid.
Connect the functoid to the unique destination identifier node.
3. How It Works
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:
Using
the source identifier, source instance, and source entity type,
retrieve the common identifier by calling the Get Common ID functoid.
NOTE
The common identifier is commonly not stored in any system. It is an identifier used to associate one or more identifiers.
Using
the common identifier, destination system instance, and destination
entity type, retrieve the destination identifier by calling the Get
Application ID functoid.
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 1.
Table 1. ID Cross-Referencing API
| Member | Description |
|---|
| GetCommonID | With
an application instance, entity/ID type, and application identifier
value, retrieves a common identifier. If a cross-reference does not
exist, a blank will be returned. If the application instance or
entity/ID type does not exist, an exception will be thrown. |
| GetAppID | With
a common identifier, application instance, and entity/ID type,
retrieves the application identifier value. If a cross-reference does
not exist, a blank will be returned. If the application instance or
entity/ID type does not exist, an exception will be thrown. |
| SetCommonID | With
an application instance, entity/ID type, application identifier value,
and optionally a common identifier, create a relationship in the
cross-referencing tables. If a common identifier is not passed to the
method, one will be created and returned. If the application instance or
entity/ID type does not exist, an exception will be thrown. |
|
