Building Rules Extensions for MIIS 2003
Applies To: Windows Server 2003 with SP1
Download Instructions
This document is available for you to download from the Web at https://go.microsoft.com/fwlink/?LinkId=30436.
In This Guide
Overview of Building Rules Extensions
At some point in your Microsoft Identity Integration Server (MIIS) 2003 deployment, you are likely to build rules extensions. The synchronization rules planner plans synchronization rules that support the identity integration policies for your deployment and identifies which rules must be implemented in a rules extension. As the rules extension builder, you build those rules that have been identified as extension implemented in the synchronization rule specification of the system data flow design document. This subject is part of the Design and Planning collection of the Microsoft Identity Integration Server 2003 Technical Library
A rules extension is a software module that adds functionality to MIIS 2003 synchronization rules. MIIS 2003 supports rules extensions for both management agent rules and metaverse rules. The synchronization rules planner can define rules as extension implemented, and you can build rules extensions that are called at appropriate points during an MIIS 2003 synchronization.
You implement a rules extension within a Microsoft .NET Framework assembly, saved to a dynamic link library (.dll) file. The two .NET Framework interfaces for synchronization rules—IMASynchronization and IMVSynchronization—enable you to provide:
one rules extension .dll for each management agent that calls for any rules to be evaluated by a rules extension, implementing the IMASynchronization interface and
one rules extension .dll for the metaverse if the solution calls for either a metaverse deletion rule to be evaluated by a rules extension or if any provisioning is required (because provisioning can only be done through a rules extension).
For more information about rules, see “Planning Synchronization Rules for Microsoft Identity Integration Server 2003” in this collection of the MIIS 2003 Technical Library.
Note
Not all management agents require a rules extension. For those that do, you can combine .dlls, sharing one .dlls between two or more management agents with similar requirements, or even between the metaverse and one or more management agent. However, it is best to keep .dlls separate.
You can use the Microsoft® Visual Studio® .NET 2003 development system or other tool to build these rules extension .dlls and place them in the Extensions folder for MIIS 2003. MIIS 2003 then calls your rules extensions from that folder when it runs extension-implemented rules during the synchronization process.
Through the MIIS 2003 user interface (UI), you can build Visual Studio .NET 2003 project templates for your rules extensions. You can modify the templates to meet the requirements of your solution. These templates make it as easy as possible for nonexpert developers to customize rules. However, the person who implements the rules extensions is most likely a senior consultant with a working knowledge of programming techniques in a relevant language.
Note
Only someone who is a member of the MIISAdmins security group can put the .dll in the Extensions folder for MIIS 2003.
Before you begin to build your rules extensions, coordinate with the project team to ensure that you understand the deployment scenario. The synchronization rule specification, which is contained in the metadirectory design document that the project team created for your deployment, determines what extensions you build and how you build them.
Before starting any coding, produce at least an outline functional specification and design document. Where a team of developers is involved, this step is especially important. After you have completed your rules extensions and provided the operable and tested files to the project team, these documents can be completed. The .dlls, plus the documents, comprise the output of the steps described in this subject.
Figure 1 illustrates the steps in the process described in this subject. The corresponding procedures are provided in “Steps for Planning Rules Extensions” later in this subject.
.gif "Build Extension Rules Step")
Figure 1: Rules Extension Steps
Rules Extensions Concepts
This section provides concepts about MIIS 2003 rules extensions. For architectural details of rules extensions, see “Essential Concepts of Microsoft Identity Integration Server 2003” in the Technical Reference collection of the MIIS 2003 Technical Library. For information about synchronization rules, see “Planning Synchronization Rules for Microsoft Identity Integration Server 2003” in this collection of the MIIS 2003 Technical Library.
Motivation for Using a Rules Extension
MIIS 2003 uses a flexible synchronization engine, with rules that can be configured to implement the business rules for the deployment scenario. Because you can use the synchronization capabilities in many ways by applying your business logic to a variety of connected data sources, the deployment scenario can become complex. Apart from provisioning, all rules are either declarative (implemented in the UI) or extension implemented. Simple declarative rules address many synchronization actions in your design, but you might need to extend the functionality of these rules for particular circumstances. For example, you might want to combine a person’s first name and last name, from a connected data source, into a single display name attribute in the metaverse. You can enable this combination by using a rules extension. For more information about the types of synchronization rules, see “Planning Synchronization Rules for Microsoft Identity Integration Server 2003” in this collection of the MIIS 2003 Technical Library.
When Rules Extensions Are Useful
Rules extensions are not always necessary. Use them if you want to perform any of the following common tasks:
Transforming Data
Flowing attributes (into or out of the metaverse). Data transformation is one of the most common tasks for which management agent rules extensions are used. A typical requirement is for generating destination attribute values based on one or more source attribute values.
Finding join candidates. Data transformation can also be used to generate values to be used for searching the metaverse for suitable join candidates.
Creating new accounts. Along with synchronization and data transformation, the most common task that MIIS 2003 is used for is creating new objects, such as user accounts or mail contacts, in single or multiple connected data sources. This is known as provisioning.
Checking for attribute value. Sometimes it is necessary to check for attribute values before making a decision about how, or if, an object is processed by MIIS 2003. Attribute values can be checked for objects in the connector space or in the metaverse.
Creating unique attribute values
MIIS 2003 can be used to ensure the uniqueness of specific attribute values, such as an email alias or a logon account name. Every connected data source has a naming attribute for its entries or objects that must be unique. For example, in a Lightweight Directory Access Protocol (LDAP) directory, this is the distinguished name (DN).
Such attributes are usually based on metaverse data. Your rules extension code can check whether an object with the same value for the attribute already exists, or it can catch the error that is generated if it is not unique. Either way, the rules extension generates an alternative.
Deprovisioning account. Deprovisioning is the process of managing objects in the connector space (connector space objects) after they have been disconnected from an object in the metaverse (metaverse object) under certain circumstances. In some situations, you might want to remove an object in the connector space permanently. In other situations, you might want to keep the connector space object in a disconnected state and have it available to link to an object in the metaverse at a later time.
Moving objects. A common task in administering directories is to move objects within a hierarchy. You can move an object by creating a new naming attribute and assigning it to the object.
Setting initial values. During the provisioning of a new account, you can set any attribute values that will not change during normal (future) attribute flow. For example, you can assign an initial password. A rules extension can be written to immediately assign an initial password when a new account is created.
Enabling and disabling objects. Some data sources contain objects that are security principles. For example, a user object for the Microsoft® Active Directory™ directory service can be enabled or disabled by manipulating one portion of the userAccountControl attribute.
When a Rules Extension Is Required
You must provide a rules extension any time that at least one rule is defined as extension implemented. Rules for provisioning are always extension implemented.
Writing a Functional Specification
Before you write any rules extensions, you should create at least an outline for a functional specification that describes the functions that you have defined in your rules extensions. As you build the rules extensions for your deployment, this document should be filled out to provide accurate documentation of what you have done.
To write the functional specification
For each rules extension, state the function name and how you have defined it. Add any special information that is necessary to enhance another team member’s understanding of the function.
Add this specification in the appropriate place in the metadirectory design document.
Furnish the specification and the rules extension files to the project team for approval.
When the deliverables are approved, provide them to the configuration planner for the project team.
Next
See Also
Concepts
Rules Extension Environment
Identifying Rules Extension Requirements
Management Agent Rules Extensions
Hints and Tips for Building Rules Extensions
Best Practices for Coding
Implementing a New Version of Rules Extensions