Planning Synchronization Rules for MIIS 2003

Applies To: Windows Server 2003 with SP1

Download Instructions

This document is available for download as a Microsoft Word document at

Overview of Planning Synchronization Rules

Planning synchronization rules for your Microsoft Identity Integration Server (MIIS) 2003 solution is one of the most important steps you can take in the Design and Planning process. Without careful planning of your synchronization rules, your synchronization might fail. This subject explains how you can plan synchronization rules for your MIIS 2003 solution. As the synchronization rules planner, you can use the information that is contained in the system dataflow design document to plan the synchronization rules for your deployment scenario and to produce a synchronization rules specification. This subject is part of the Design and Planning collection of the MIIS 2003 Technical Library.

Data synchronization in MIIS 2003 is based on the processing of synchronization rules. You must configure synchronization rules for your deployment before synchronization takes place. You must plan your synchronization rules before you configure them to ensure the validity of data and absence of conflicts between rules. A synchronization rules specification provides specific information about what synchronization rules can be implemented and when they can be implemented. A synchronization rules specification also provides a functional specification of the rules extensions that you have determined are necessary for your MIIS 2003 solution.

The Synchronization Rules Planner

As the synchronization rules planner, you are responsible for:

  • Coordinating with the project team and data source owners to ensure that they understand the deployment scenario.

  • Planning the synchronization rules and rules extensions that enable the synchronization and provisioning of specified identity objects.

  • Creating the synchronization rules specification based on information contained in the system dataflow design document.

  • Previewing and testing the enforcement of synchronization rules on objects and refine the synchronization rules design specification as necessary.

Before you begin planning synchronization rules, coordinate with the project team to ensure that you understand the deployment scenario. At a minimum, you need the system dataflow design document and the metaverse plan that are created by the project team because they contain the specific synchronization objectives for your solution.

After you plan your synchronization rules, assemble the planning information, policies, and the rules themselves into a synchronization rules specification and include that plan in the system dataflow design document. Ensure the project team reviews and approves the plan. When the synchronization rules specification is ready, you should provide it to the rules extension builder for the deployment.

Figure 1 illustrates the steps in the synchronization rules planning process. The corresponding procedures are provided in “Steps for Planning Your Synchronization Rules” later in this subject.


Planning Synchronization Rules Concepts

This section provides concepts about MIIS 2003 synchronization rules. For architectural details about synchronization rules, see “Essential Concepts of Microsoft Identity Integration Server 2003” in the Technical Reference collection of the MIIS 2003 Technical Library.

What You Have Already Done and What You Do Now

In the first stage of your design, you did the following:

  • Selected your identity integration solution and created a solution proposal.

  • Designed a system dataflow model for MIIS 2003.

  • Planned the metaverse MIIS 2003.

By referring to the work that you have already done, you can now complete the Planning Synchronization Rules worksheets that are in “Design and Planning Worksheets for MIIS 2003” in this collection of the MIIS 2003 Technical Library. You can include those worksheets in your synchronization rules specification and hand them off to the rules extensions builder for your deployment.

When synchronization rules are called

Figure 2 shows during which phase of synchronization each rule may be called.


Types of Synchronization Rules

Synchronization rules are categorized as either declarative or extension-implemented.

Declarative Synchronization Rules

A declarative synchronization rule is a rule that you select and configure in the Identity Manager, the user interface (UI) management utility for MIIS 2003. No external code is required. For example, when you map a user object in Connected Data Source 1 to a contact object in Connected Data Source 2 by using Identity Manager, you can express a declarative synchronization rule this way:

CS1User = CS2Contact

You can express attribute mappings this way:

User.displayName = Contact.displayName
User.telephoneNumber = Contact.telephoneNumber

Extension-Implemented Synchronization Rules

A rules extension is the coded logic that adds functionality to those synchronization rules that cannot be configured entirely through the UI. Based on the current state of the data, you can use a rules extension to validate data as it is imported into the metaverse or to verify that the data is in the correct format before exporting it to other connected data sources. You can prepare one rules extension for each management agent and one for the metaverse.

As the synchronization rules planner, you do not need to deal directly with the underlying code to create rules extensions for MIIS 2003. The rules extension builder accesses the interfaces and classes necessary to build the rules extensions that you document in the synchronization rules specification. However, you need to determine whether the functionality that you require is available in a declarative rule or requires a rules extension. For more information about the different synchronization rules and the declarative and rules-extension capabilities of MIIS 2003, see “Synchronization Rules Reference” later in this subject.

Identifying Your Synchronization Scenario

Your team should determine and document the complexity of your synchronization scenario in earlier planning documents. This section describes how the different scenarios affect rules planning.

Homogeneous Synchronization Scenario

In a homogeneous object synchronization scenario, the source and target object types interacting with the metadirectory are the same. For example, the user object of Connected Data Source 1 is being synchronized with the user object of Connected Data Source 2. If neither connected data source controls the other one, then you must determine which source is considered the master and which one is considered the subordinate for that particular synchronization and plan your rules accordingly. All synchronization rules planned must include instructions for rules that determine which connected data source is the master.

For a homogeneous object scenario, object deletion decisions should be made and implemented in the code of an object deletion rules extension. Object deletion decisions can also be made and implemented in the provisioning rule by using the deprovisioning functionality of the metaverseobject provided for a particular management agent. For more information about object deletion rules, see “Object Deletion Rules” later in this subject. For more information about provisioning rules, see “Provisioning Rules” later in this subject.

Single Master Synchronization Scenario

A single master object synchronization scenario is a particular type of homogeneous scenario, in which there is only one dedicated connected data source that is authoritative for a given object type. No other data source has master-level control over this object type. The object deletion rule in this scenario can be configured declaratively, based on the data source of the master object type. The only rules extension that has to be planned for this scenario is the provisioning rule. For more information about planning provisioning rules, see “Provisioning Rules” later in this subject. For more information about object deletion rules, see “Object Deletion Rules” later in this subject.

Heterogeneous Synchronization Scenario

In a heterogeneous object synchronization scenario, different source and target object types interact. For example, assume that the user object of Connected Data Source 1 is being synchronized with the contact object of Connected Data Source 2. Because the master role for each object type is easier to delineate in this scenario, you can plan object deletion rules for this type of scenario based on object types. For more information about object deletion rules, see “Object Deletion Rules” later in this subject.

Synchronization Rules Reference

Synchronization rules can be categorized by functionality into two groups: link management, and dataflow.

Link management-based synchronization rules affect the link between a connector space object and a metaverse object. Until there is a valid link between a connector space object and a metaverse object, no data can flow.

Connector Filter Rules

When synchronization begins, MIIS 2003 processes the connector filter rule first. This synchronization rule is used during the synchronization process to determine if a connector space object should be processed by any subsequent synchronization rules. Create one connector filter rule per object type, based on comparisons of attribute values between a connector space object and values specified in the connector filter rule. A management agent can contain several connector filter rules per object type, and each connector filter rule can consist of multiple attribute comparisons. In multiple attribute value comparison, all comparisons must evaluate to True for the connector filter rule to be true.

For example, the connector filter rule might evaluate all user objects to determine if the value of the account attribute equals Disabled. If the value equals Disabled, then subsequent synchronization rules do not process these objects. No link is established with a metaverse object, and the object remains disconnected.

You can use the connector filter rule to implement your data aggregation strategy. For example, if you want to synchronize enabled user accounts in Connected Data Source 1 with contacts in Connected Data Source 2, you can use one of two strategies. By using strategy A, you can apply a connector filter rule during data aggregation to map only required objects to the metaverse. The filtered objects remain in the connector space and can be processed later. By using strategy B, you can choose not to use a connector filter rule and write as much identity data as possible to the metaverse. If you choose strategy B, the processing of required objects occurs during the provisioning and export attribute flow rules.

When planning your rules, you should also compare your connector filter rules to your export attribute flow rules to ensure that they do not conflict with each other. A conflict between these rules can cause an infinite loop in the synchronization process. For example, an attribute change might be flowed from the metaverse to a connector space object that causes the connector filter rule to resolve as true. At the next full synchronization, the connector space object becomes a normal disconnector object, and the attribute change is recalled. After the attribute change is recalled, the connector filter rule is no longer true, and the normal disconnector object is rejoined on the next full synchronization where the attribute change is flowed again.

Although you can use a rules extension to augment the connector filter rule, you can create complex filters for most applications by using a declarative synchronization rule.

Join Rules

A join rule links a connector space object to an existing metaverse object. A join rule consists of two parts: search criteria and resolution. The search criteria compare connector space object attribute values to metaverse object attribute values. When you run a management agent, the join rules are applied to each object in the connector space, and they attempt to find corresponding objects in the metaverse, based on the search criteria.


You can increase the efficiency of searches by using indexed attributes. Only metaverse attributes that are defined as indexable can be set as indexed. For more information about indexing attributes, see “Edit indexed property for an attribute” in the MIIS 2003 Help.

When one or more matches are found, the join resolution script, if one is defined, determines how to proceed. If no match is found, then processing continues on the projection rules. You can determine how all join resolutions proceed by creating a rules extension. If one or more matches are found, the rules extension logic determines which objects are joined or which objects are not joined. Only object synchronization is performed during the join process. Attribute synchronization is not performed until the attribute flow rules are processed.

For example, a join rule might use the employeeID attribute as the criteria. If a single metaverse object with the same employeeID is found, then it is linked to the connector space object. A metaverse object with the same employeeID might not be found, or multiple matches might be found. In either of these situations, the join resolution script, if one is defined, determines whether to search again with additional criteria, select one of the found matches, or reject all matches and continue processing the projection rules.

By default, if two or more possible matches are found, the connector space object is not joined to the metaverse. If you want to resolve join matches other than by the default method, then you must create a rules extension. For example, you can write a join resolution rules extension to determine whether or not to join the object based on the current data.

Projection Rules

A projection rule creates a metaverse object based on the connector space object type, and then links the metaverse object to the connector space object. The management agent processes a projection rule only if a join rule is not specified, or if a match is not found after processing the join rules. If you are using multiple management agents to gather object data from multiple sources, you only project the object to the metaverse once. Only object-level operations are performed during the projection process. No attribute-level operations are performed until attribute flow rules are processed.

For example, you might be gathering data from both a human resources (HR) database and a Telephone database. If you want the HR database to be the authoritative data source, create both a join rule and a projection rule for the HR management agent, but create only a join rule for the Telephone management agent. This configuration ensures that a metaverse object is only projected by the HR management agent. You can then join the Telephone connector space object to the metaverse object created through the HR projection rule and the telephoneNumber attribute synchronized with the linked metaverse object.

A declarative projection rule defines a basic object type mapping, where the source and target object types are selected from the available connector space object types and metaverse object types. You must create a rules extension if you want to base a decision on the current state of an individual object, including the decision to project the object or not, and if so, as what object type to project it.

Provisioning Rules

Provisioning is the process of creating, connecting, disconnecting, or renaming objects in a connector space, based on changes to objects in the metaverse. You can both rename objects by changing their distinguished name attributes and move objects by using provisioning rules.


The provisioning rule is the only synchronization rule that cannot be configured declaratively by using the Identity Manager. Provisioning rules must be implemented through a rules extension.

For example, a human resources management team has decided that all employee titles must meet specific naming requirements for certain job positions. In this situation, you can use a provisioning rule to check the title attribute for all metaverse person objects and to ensure that they meet the specified naming requirements. Based on these results, the provisioning rule performs additional actions, such as alerting an administrator by e-mail message when a title is entered incorrectly.

By using the deprovisioning functionality of the metaverseobject provided for a particular management agent, you can write the provisioning rule to make object deletion decisions and implement them.

Deprovisioning Rules

MIIS 2003 processes deprovisioning rules during account management to manage, or clean up, connector space objects after they have been disconnected from a metaverse object. These rules trigger the cleanup of one or more accounts in the corresponding connected data source.

A declarative deprovisioning rule either makes the connector space object a normal disconnector object, an explicit disconnector object, or deletes the connector space object by staging a delete for the next export run. Create a rules extension if you want to evaluate the object’s attributes before deprovisioning. A deprovisioning rules extension can also perform other actions, such as moving or renaming the object, or modifying the object’s attributes; for example, setting the userStatus attribute to disabled.

Object Deletion Rules

Object deletion rules determine under what conditions to delete a metaverse object. MIIS 2003 processes an object deletion rule whenever a link is disconnected between a connector space object and a metaverse object. A link can be disconnected when a deletion operation from a connected data source is imported and affects a joined connector space object, or when a connector filter rule is applied.

Figure 3 illustrates the processing for an object deletion rule



You can disconnect links during the data aggregation phase or the account management phase of synchronization. When the disconnection occurs during data aggregation, the object deletion rule is processed to determine if there are any consequences for the disconnected metaverse object. When a link is disconnected during account management, the deprovisioning rule is processed to determine if there are consequences for the disconnected connector space object.

The object deletion rule can perform either of the following actions if it is declarative. It can:

  • Delete the metaverse object when the last connector space object that links to the metaverse object is disconnected.

  • Delete the metaverse object when the last connector space object from a specified management agent is disconnected.

If any other actions are required, such as basing an object deletion on the value of a specific attribute, you must create a rules extension. See “Identifying Synchronization Scenarios” earlier in this subject.

Dataflow Rules

With MIIS 2003, you can use two types of attribute flow, import attribute flow and export attribute flow. Import attribute flow is the flow of attributes from a connected data source object to a metaverse object, while export attribute flow is the flow of attributes from a metaverse object to a connected data source object. You can configure attribute flow declaratively through Identity Manager or through a rules extension.

Import Attribute Flow Rules

An import attribute flow rule creates a mapping of attributes from the connector space object to the metaverse object or sets a constant attribute value for the metaverse object. It is used by MIIS 2003 to enforce the integrity of data in the connected system over time.

Each import attribute flow rule represents an import attribute mapping that generates a target attribute value from one or more source attribute values. You can create declarative import attribute flow rules as one of the following three mapping types:

  • Direct. One-to-one mapping such as employeeID to userID.

  • Constant. Sets the target attribute to a defined value, such as company=ABC Org.

  • Distinguished Name. Maps a component of a distinguished name to a single attribute, such as CN=Miked,CN-Users,OU=MIIS,O=Microsoft to usersname=MikeD. Many-to-many mappings are not supported.

A rules extension must be defined to map multiple source attributes to a single target attribute. For example, an employee name is defined by two attributes, firstname and lastname. The corresponding metaverse object defines a fullname attribute. You can combine the values for the firstname and lastname attributes into a single value for the fullname attribute by using an import attribute flow rules extension.

If you are creating an attribute flow rules extension, configure the name of the rule in the UI, and pass this name on to the rules builder. For example, if you are combining multiple attributes to a single value, such as in the example above, specify the flow rule name in the UI as cd.person:firstname,lastname->mv.person:fullname. The rules builder uses this name when coding the actual rules extension.

Export Attribute Flow Rules

An export attribute flow rule, during the export process reconciles differences among attributes that are located in connected data sources, the connector space, and the metaverse. MIIS 2003 uses an export attribute flow rule to enforce the integrity of data in the connected system over time. You define export attribute flow rules in Identity Manager at the same time as import attribute flow rules.

Export attribute flow rules are called in the following situations:

  • When a source metaverse object is synchronized with a newly connected target connector space object or when any run profile that reevaluates the rules is run. In these cases, a full export synchronization is run.

  • When a source metaverse object has previously been synchronized to the destination connector space object. In this situation, a delta synchronization is run; that is, only values that have changed are flowed from the metaverse to the connector space.

  • When a reference attribute on the source metaverse object references another metaverse object that has had a connector space object in the destination connector space connected or disconnected. This referencing changes the possible values that can be flowed to the destination connector space object, because only values that reference a metaverse object that is linked to a connector space object in the destination connector space can be flowed. In this situation, the references are flowed from the metaverse to the connector space.

  • When a synchronization runs from the connector space to the metaverse to another connector space. Export attribute flow rules are called here to flow values from the metaverse object back to the connector space object that initiated the synchronization. For example, if connector space A has a pending attribute change that initiates a synchronization run, that change is applied to the metaverse object and then to connector space B. However, if connector space B has precedence for that attribute, then the attribute change is pushed back to connector space A, and the value of the attribute reverts to the original value.

Other Rules That Are Applied During Attribute Flow Control

The MIIS 2003 synchronization process first performs object-level operations, such as joining and projecting objects. It then performs attribute-level operations to support the import and export attribute flow synchronization rules for all connector space objects linked to a metaverse object. Associated with these operations are several attribute flow control rules that enhance attribute flow. These rules are implemented as options that you set in Identity Manager. The attribute flow control rules are:

  • Attribute flow precedence rules

  • Allow nulls on export rules

  • Recall attributes from metaverse on disconnect rules

Attribute Flow Precedence Rules

When two or more management agents are synchronizing data to the same metaverse object, you can appoint one data source to control others, or have precedence. This precedence ensures that the data source with lower precedence never overwrites data that has been contributed by the data source with higher precedence.

Like most other MIIS 2003 rules, the attribute flow precedence rule can be defined as a declarative rule or as a rules extension. Use the declarative attribute flow precedence rules if you can, and use the “Import Attribute Flow Rules Worksheet” in Design and Planning Worksheets for MIIS 2003 to document if the attribute flow precedence rules defined cannot be implemented by using a declarative rule, and pass the precedence rules to the rules extension builder.

By using the declarative method, you specify the precedence order in which rules are selected For declarative precedence rules, MIIS 2003 enables an import attribute flow rule to write a change to a metaverse attribute under any of the following conditions:

  • The metaverse attribute is empty (null).

  • This import attribute flow rule provided the current value, and it has a new value.

  • This import attribute flow rule has a higher precedence than the rule that provided the current value.

If a null value is flowed by a rule, then the next rule in the list can provide a value, and so on until a value is provided or the rules are exhausted.

An attribute flow precedence rules extension is required for any rule that is expressed in terms other than “management agent X has higher precedence than management agent Y.” For example, you must use a precedence rules extension if you want to populate a metaverse attribute value only in the case where the employeeStatus equals Active.


A single management agent might have multiple import attribute flow rules applying to the same metaverse attribute. These synchronization rules are ordered by the attribute flow precedence rule

In some cases, you might want to disable attribute flow precedence for a particular attribute. In these cases, you can configure an attribute to use manual precedence. Manual precedence is only available for attribute flows that use a rules extension. For example, if you have multiple management agents that all need to contribute values to a multi-valued attribute in the metaverse, attribute precedence would, by default, force one of the management agents to have precedence and the others would be unable to update the attribute. If you configure the attribute to use manual precedence, the rules extension accumulates the values from all the management agents and writes them all to the multi-valued attribute. For more information about configuring manual precedence, see the MIIS 2003 Developer Reference.

Import and export attribute flows can often overlap; that is, an attribute for export attribute flow is also the target of import attribute flow. To keep lower precedence data sources from overwriting higher precedence data sources, MIIS 2003 determines the populator precedence of the import mapping that populated the metaverse attribute for an export flow. It then evaluates the import attributes. It stops evaluating import attributes when it finds an attribute with precedence greater than the populator precedence. When it has evaluated all the attributes for precedence and has not rejected the attribute flow, MIIS 2003 processes the export attribute flow rule.


Empty attributes are considered to have the lowest possible precedence. Thus, if there is an overlap on an empty attribute, export attribute flow terminates.

Allow Nulls on Export Rule

When the last source attribute of an export attribute flow mapping has been deleted, the export attribute flow rules, by default, are not called, and the target attribute is not modified or deleted. To allow attribute deletions to flow to the target connector space, specify the Allow Nulls option during the setup of the export attribute flow rules in Identity Manager.

Recall Attributes from Metaverse on Disconnect Rules

By default, when a connector space object is disconnected from a metaverse object, all of the attribute values that the connector space object contributed to the metaverse object are recalled from the metaverse object. If there are any import attribute flow rules for these attributes configured on other management agents that have connector space objects linked to this metaverse object, the attribute flow rules are evaluated in order of their precedence settings. Then, the metaverse can be repopulated with the values for these attributes. The rules engine processes all of the connector space objects until the attributes are repopulated or the available connector space objects are exhausted.

However, there are certain situations in which you might need the attribute values to remain in the metaverse, even though the source for those attribute values has been disconnected. For example, you might import user accounts from one directory to populate another directory. After the initial migration, you can delete the accounts from the source directory. By default, the objects in the source connector space are disconnected, and the attributes contributed by them are recalled from the linked metaverse objects. When you select the option in the Management Agent Designer to not recall attributes upon disconnection, the objects can be safely disconnected in the source connector space without affecting the attribute values in the metaverse objects.


The repopulation of attributes resulting from attribute recall does not affect attribute flow precedence. Data source attribute values for lower precedence management agents continue to be prevented from replacing higher precedence values for a disconnected or deleted connector space object. Data sources for higher precedence management agents continue to replace the values.

The following flowchart illustrates the order in which the synchronization rules are applied: