Share via

Rules Extension Environment

  • Article

Applies To: Windows Server 2003 with SP1

Previous Sections in This Guide

About the Rules Extension Environment

From within the MIIS 2003 UI, you can create well-structured Visual Studio .NET 2003 projects. For management agent rules extensions, MIIS 2003 prepopulates code in the project with the rule name for any join, join resolution, or flow rules that have been defined as extension implemented. For example, for an import attribute flow rule, MIIS 2003 inserts a case statement with the flow rule name into the project.

For information about the MIIS 2003 development environment, see “Install.htm” on the MIIS 2003 installation CD. For a set of example projects, see the “Simple Account Provisioning” in the Scenarios folder on the installation CD.

Note

Any developer can also create a rules extension by using any programming language and a compiler that creates a Microsoft .NET Framework assembly using the Common Language Runtime. The most-used languages are the Microsoft® Visual Basic® .NET development system and the Microsoft® Visual C#® .NET 2003 development tool, with the compiler in Visual Studio .NET 2003. For development instructions, see the Microsoft Identity Integration Server 2003 Developer Reference

Running Multiple Metaverse Rules Extensions

For projects in which multiple management agents require provisioning, you can break your metaverse rules extension into separate .dlls (one per management agent), each of which implements IMVSynchronization interface methods such as Initialize, Provision, ShouldDeleteFromMV, and Terminate. A “routing” .dll, which also implements the IMVSynchronization interface method, is registered with MIIS 2003 as the metaverse extension; when a method is called in the router, it passes the call onto the equivalent method in each of your .dlls. By using this technique, you produce self-contained .dlls that can be reused for other projects. This technique can be particularly helpful when multiple developers are working on a project. For sample code for the router, see the MIIS 2003 Developer Reference.

Management Agent Rules Extension Environment

When you define a management agent rule as extension implemented, you do so in the Management Agent Designer of the MIIS 2003 UI. Management agent rules are associated either with inbound or outbound synchronization.

Inbound Synchronization Rules

Inbound synchronization rules apply to connector space objects that are managed by the management agent being run and are of the type to which the scope of the rule applies. There are five types of inbound synchronization rules:

  • Connector filter rule

  • Join search rule

  • Join resolution rule

  • Projection rule

  • Import attribute flow rule

The actual set of objects to be processed during a run depends on the run step being applied to the management agent:

  • A delta import and a delta synchronization process only those objects with changes imported by this step.

  • A delta synchronization without an import processes all objects with pending status (an imported change or a normal disconnector).

  • A full synchronization processes all objects except explicit disconnectors.

Note

Placeholders are a special kind of connector space object that are kept to satisfy references, and they take no part in synchronization

When an object is processed, not all of the rules are necessarily applied:

  • The join and projection rules are not applied to connectors.

  • The filter rule does not apply to explicit connectors.

  • Attribute flow rules apply only to connectors.

  • No rules are applied to explicit disconnectors.

  • During a delta synchronization, only those attribute flow rules that are based on attributes whose values have changed are applied; but, during a full synchronization all attribute flow rules are applied.

  • An extension-implemented import flow rule is not processed if all the connector space attributes on which it depends are null; instead, a null value is simply flowed to the appropriate metaverse attribute.

Outbound Synchronization Rules

Outbound synchronization rules apply to connector space objects that are managed by the management agent being run, or are connected to metaverse objects to which the above are connected, and are of the type to which the scope of the rule applies. There are two types of outbound synchronization rules:

  • deprovisioning rule

  • export attribute flow rule

  • provisioning rule

The objects that are processed during a run are:

  • Connector space objects that are managed by the appropriate management agent and that are processed during inbound synchronization, and

  • Any connector space objects that are managed by any management agent and that are affected by changes to metaverse objects from the application of inbound rules (i.e. metaverse object deletions or attribute changes).

When an object is processed, not all of the rules are necessarily applied:

  • The deprovisioning rule is only applied for objects are disconnected, whether by metaverse object deletion or by code, such as in the provisioning rules extension.

  • During a delta synchronization, the only export attribute flow rules that are applied are those based on attributes whose values have changed; but, during a full synchronization all attribute flow rules are applied.

  • An extension-implemented export flow rule is not processed if all the metaverse attributes on which it depends are null; instead, a null value is simply flowed to the appropriate connector space attribute.

Management Agent Project Templates

The project template created by MIIS 2003 presents you with the basic instructions that you need to configure management agent rules. You modify these instructions to provide your own code for each rule that is defined as extension implemented. The template includes some coding stubs, which are prewritten code snippets in the template; comments that indicate where to place your code; and a line of code that causes the rule to throw an exception if called. A thrown exception can indicate that you have not provided code for a rule that has been defined as extension implemented in the UI. Remove this line of code when you provide your code for a rules extension.

Note

Even if you do not implement a function or method that is included in the management agent rules extension project, you must not remove it from your project. If you do, your project will not compile.

Figure 2 shows an example management agent rules extension project template. This template was generated from MIIS 2003 by using Create Rules Extension Projectin Management Agent Designer in the MIIS 2003 UI. It only contains default code stubs for each rules extension, many of which contain a Throw Exception instruction. The file shows the Visual Basic code generated for this project.

Example Template for a Management Agent Rules Extension Project

Imports Microsoft.MetadirectoryServices
Public Class MAExtensionObject
    Implements IMASynchronization
    Public Sub Initialize() Implements IMASynchronization.Initialize
        ' TODO: Add initialization code here
    End Sub
    Public Sub Terminate() Implements IMASynchronization.Terminate
        ' TODO: Add termination code here
    End Sub
    Public Function ShouldProjectToMV(ByVal csentry As CSEntry, ByRef _
MVObjectType As String) As Boolean Implements _
IMASynchronization.ShouldProjectToMV
        ' TODO: Remove this throw statement if you implement this method
        Throw New EntryPointNotImplementedException()
    End Function
    Public Function FilterForDisconnection(ByVal csentry As CSEntry) _
As Boolean Implements IMASynchronization.FilterForDisconnection
        ' TODO: Add connector filter code here
        Throw New EntryPointNotImplementedException()
    End Function
    Public Sub MapAttributesForJoin(ByVal FlowRuleName As String, _
ByVal csentry As CSEntry, ByRef values As ValueCollection) Implements _
IMASynchronization.MapAttributesForJoin
        ' TODO: Add join mapping code here
        Throw New EntryPointNotImplementedException()
    End Sub
    Public Function ResolveJoinSearch(ByVal joinCriteriaName As String, _ 
ByVal csentry As CSEntry, ByVal rgmventry() As MVEntry, ByRef imventry As _ 
Integer, ByRef MVObjectType As String) As Boolean _ 
Implements IMASynchronization.ResolveJoinSearch
        ' TODO: Add join resolution code here
        Throw New EntryPointNotImplementedException()
    End Function
    Public Sub MapAttributesForImport(ByVal FlowRuleName As String, _ 
ByVal csentry As CSEntry, ByVal mventry As MVEntry) Implements _
IMASynchronization.MapAttributesForImport
        ' TODO: write your import attribute flow code
Throw New EntryPointNotImplementedException()
    End Sub
    Public Sub MapAttributesForExport(ByVal FlowRuleName As String, _ 
ByVal mventry As MVEntry, ByVal csentry As CSEntry) Implements _
IMASynchronization.MapAttributesForExport
        ' TODO: Add export attribute flow code here
        Throw New EntryPointNotImplementedException()
    End Sub
    Public Function Deprovision(ByVal csentry As CSEntry) As DeprovisionAction _
Implements IMASynchronization.Deprovision
        ' TODO: Remove this throw statement if you implement this method
        Throw New EntryPointNotImplementedException()
    End Function
End Class

Metaverse Rules Extension Environment

You specify the requirement for a Metaverse rules extension through Tools/Extensions in the Identity Manager Designer for MIIS 2003.

The Metaverse Rules

There are two types of metaverse rules:

  • Provisioning

  • Metaverse Object Deletion

Important

Provisioning must be specifically enabled in the UI. You can disable provisioning during the discovery part of the deployment, during which the metadirectory is built. When existing objects have been fully synchronized, you can enable provisioning for the ongoing operation of MIIS 2003.

Metaverse Rules Extension

MIIS 2003 can create a project containing code stubs into which you place any code required for your deployment scenario.

Although only one metaverse rules extension per deployment is necessary, you can split your code into multiple metaverse rules extensions that are called in sequence by a single controlling extension. In this way the members of the development team can concentrate on their metaverse rules extension without causing conflicts with each other. For example, the provisioning code for three connector spaces can be split into three modules. For more code samples for implementing the controlling extension, see the Microsoft Identity Integration Server 2003 Developer Reference.

Note

Even if you do not implement a function or method that is included in the metaverse rules extension project, you must not remove the associated instructions from your project. If you do, your project will not compile.

Figure 3 shows an example metaverse rules extension project. The file shows the Visual Basic code that is generated by MIIS 2003, but in this instance the project has been previously modified to create an Active Directory user. The Provision function area has been filled in with instructions specific to a deployment.

Figure 3   Example Metaverse Rules Extension Project

Imports Microsoft.MetadirectoryServices
Imports Microsoft.MetadirectoryServices.Logging
Public Class MVExtensionObject
    Implements IMVSynchronization

    Public Sub Initialize() Implements IMvSynchronization.Initialize
        ' TODO: Add initialization code here
    End Sub

    Public Sub Terminate() Implements IMvSynchronization.Terminate
        ' TODO: Add termination code here
    End Sub

    Public Sub Provision(ByVal mventry As MVEntry) Implements _ 
IMVSynchronization.Provision
        Dim adMA As ConnectedMA
        Dim csentry As CSEntry
        Dim dn as ReferenceValue

        adMA = mventry.ConnectedMAs("Fabrikam AD MA")

        ' Construct the distinguished name
        dn = adMA.EscapeDNComponent("CN=" + _
mventry("cn").Value).Concat("ou=employees,dc=fabrikam,dc=com")

        If adMA.Connectors.Count =0 then
            csentry = adMA.Connectors.StartNewConnector("user")
            csentry.DN = dn
            csentry.CommitNewConnector 
        End If
        
    End Sub

    Public Function ShouldDeleteFromMV(ByVal csentry As CSEntry, _ 
ByVal mventry As MVEntry) As Boolean Implements _
IMVSynchronization.ShouldDeleteFromMV
        ' TODO: Add MV deletion code here
        Throw New EntryPointNotImplementedException()
    End Function
End Class

MIIS 2003 .NET Framework Interfaces and Classes

You define synchronization rules for a management agent through two predefined .NET Framework interfaces: the IMASynchronization interface for management agent rules extensions and the IMVSynchronization interface for metaverse rules extensions.

To implement the business logic in each rules extension, you use a set of classes that are defined in these interfaces. Examples of important classes are the CSEntry class, which represents connector space objects, and the MVEntry class, which represents metaverse objects. For details of these classes and their interfaces, see the Microsoft Identity Integration Server 2003 Developer Reference.

Next

See Also

Concepts

Introduction to Building Rules Extensions for MIIS 2003
Identifying Rules Extension Requirements
Management Agent Rules Extensions
Hints and Tips for Building Rules Extensions
Best Practices for Coding