Knowledge Base

Configuring the Join in Microsoft Metadirectory Services

Article ID: 250586

Article Last Modified on 1/25/2006

APPLIES TO

Microsoft Metadirectory Services 2.1
Microsoft Metadirectory Services 2.2 Service Pack 1

This article was previously published under Q250586

SUMMARY

This article describes how the join criteria is configured in Microsoft Metadirectory Services (MMS) Management Agents (MAs).

MORE INFORMATION

When an MA performs an automated join, it uses the following procedure:

The MA selects each disconnected entry in the connector space.
It uses the search attribute to find matching candidate records in the metaverse.
It applies each element of the join criteria to each candidate record so that at least one criterion results in a unique metaverse match.
It links the connector space object with the first unique metaverse match.

The complete join criteria consists of a list of search attributes and a set of inclusion rules.

To properly configure the join in an MMS MA, you need to specify appropriate search attribute(s) (the attribute should be hashed). When you have discovered the connected directory and populated the connector space, specify a connector space attribute which produces the best metaverse match. The best match is usually a Unique Identifier (UID). Because it is assumed that the identifier is unique, a successful search of the metaverse should only return a single object. Alternatively, the common name (CN) may be used, but it is more likely that multiple candidate objects are returned when you initiate a search. If the number of candidate objects proves to be excessive, consider another search attribute, such as surname (SN) or telephone number. The best situation is to have a one-to-one mapping between connector space entries and metaverse entries based on the search criteria. However, this scenario is not always possible.

The join links disconnected directory entries to corresponding metaverse entries based on the criteria that is specified. Join inclusion rules are used to refine the set of candidate metaverse search objects. When you define inclusion rules, you are setting one or more conditions, and testing the search results against the criteria. An inclusion rule may be either simple or complex. As each candidate object from the metaverse search is compared to the connector space entry, when a condition is met, the object is recognized as a match for that single condition, and then is set aside. When all of the search results have been compared to all the inclusion criteria, there must be a single metaverse match for at least one condition for the join to proceed.

A connector space object is not joined if there are either zero or multiple matches for all given criteria. If more than one condition matches a single search object, then the object associated with the first match that was encountered in the list of conditions is accepted and joined. The fact that there are multiple unique matches based on different criterion does not diminish the validity of any given match.

A join may not succeed for one of the following reasons:

There are no entries in the metaverse that match the search criteria. This issue can occur if the search attribute is not hashed or if the hash database needs to be regenerated by using either the VIACompact tool or the VIAHashTool utility. Because no candidate records were returned by the search, it is not possible to join.
There is no single inclusion criterion which uniquely matches a single metaverse entry. This issue occurs when you attempt to join based on "weak" criteria. For example, if the join inclusion criteria has two conditions:

$cd.cn = $mv.cn

-and-

$cd.sn = $mv.sn

only one of these conditions must be uniquely met for the join to succeed. For a pair of objects, the connector namespace (CS) object and the candidate metaverse (MV) object, assume that the MV common name value is User Name, the MV surname is Name, the CD common name is U Name and the CD surname is Name. In this example, the first criterion (cn) is not successful, although the second criterion (sn) matches. However, if the surname value is a common surname, it may be difficult to find a unique match across the entire metaverse and the join may not succeed.

Conditions Rules Applied to Inclusion Rules

The following condition rules are applied to inclusion rules:

Implicit "AND" between lines in the condition
Implicit "OR" between conditionsNOTE: It is recommended that you specify the most restrictive condition first.

In the following example, the inclusion rules specify that if either the employee ID is the same, or both the surname and the telephone number are the same, then the join is possible:

Condition 1
$mv.uid = $cd.empid

Condition 2
$mv.sn = $cd.sn
$mv.telephoneNumber = $cd.telephoneNumber

The join only happens between a connector space entry and a metaverse entry. However, the inclusion rules may specify attributes from either the metaverse, connected directory, or the connector namespace. The three attribute designators are specified as:

$MV = Metaverse
$CD = Connected Directory
$CS = Connector Namespace

Usually, multiple connector namespace entries are joined to a single metaverse entry. The relationship of connector namespace entries to metaverse entries can be one-to-one or many-to-one, but it is never one-to-many. It is not possible to have one connector namespace entry joined to many metaverse entries. When this occurs, there could be corruption in the MMS database.

Setting a Search Attributes

To set a search attribute, follow these steps:

Click Bookmarks.
Click the MA that you want to use for the join.
Click the Join button.
Click the Configure to Join tab.
In the Search using these attributes box, configure the search attribute(s). For example, if you want to specify that the common name from the connected directory should match every hashed attribute in the metaverse, you would use $cd.cn.
After you have configured the appropriate search attribute(s), click Perform the Join.

NOTE: Click the Operator's Join Log tab to view the progress of the join.

Setting Join Inclusion Rules

To set join inclusion rules, follow these steps:

Click Bookmarks.
Click the MA that you want to use for the join.
Click the Join button.
Click the Configure to Join tab.
In the Join using these inclusion rules, set your conditional statements based on the inclusion criteria. These criteria may be either simple (single line) or complex (multiple line).

For additional information about the join operation, click the article number below to view the article in the Microsoft Knowledge Base:

250528 Using the Account Joiner Utility in Microsoft Metadirectory Services

Additional query words: via zoomit MMS

Keywords: kbinfo kbenv KB250586

Microsoft KB Archive/250586

Contents