Provisioning Objects in the Connector Space

  • Article

After installing Microsoft Identity Integration Server 2003, one of the first steps after you project identity information from the different data sources into the metaverse is to create and export new objects into other connected data sources. This process is known as provisioning. Provisioning is implemented by creating a rules extension that implements the IMVSynchronization.Provision method. When the method is called, the method gets passed the metaverse object as an MVEntry object.

We recommend that you follow these steps when implementing the provisioning logic:

  1. Determine the State of the Object.
  2. Start Creating a New Connector or Use the Existing Connector.
  3. Set the Appropriate Distinguished Name or Attribute Values
  4. Finish Creating the New Connector or Disconnect or Rename the Existing Connector
  5. Handle Any Exceptions

Determine the State of the Object

Provisioning the objects in the connector space by first investigating attribute values to determine the current state of the MVEntry object as passed to the method. If the MVEntry object meets a certain condition by matching expected attribute values, then you can apply the appropriate provisioning logic to the CSEntry object. MVEntry objects that do not meet a certain condition stay in the same state without having to add additional logic into the provisioning code.

Start Creating the New Connector or Use the Existing Connector

After determining the state of the metaverse object, you can create a new connector or use an existing connector depending upon the value of the ConnectorCollection.Count property. If this value is zero, then start creating a new connector with the ConnectorCollection.StartNewConnector method. If the property is 1, then use the existing connector. Throw an UnexpectedDataException exception if the property value is greater than 1 and if this is an unexpected value.

To start creating the connector, use the ConnectorCollection.StartNewConnector method. When calling this method, use the object type selected in the management agent as the parameter. To determine the object type that has been selected, go to Select Object Types in the management agent properties.

To use the existing connector, use the ConnectorCollection.ByIndex or the ConnectorCollection.ByDN property.

The following example shows you how to get the number of connectors and then create a new connector, use an existing connector, or throw an exception depending upon the number of connectors:

    ' Get the number of connectors for this MVEntry object under
    ' this management agent
    Dim ManagementAgent As ConnectedMA
    Dim Connectors As Integer
    Dim csentry As CSEntry
    Dim DN As ReferenceValue
    
    Connectors = ManagementAgent.Connectors.Count
    DN = ManagementAgent.EscapeDNComponent(System.Guid.NewGuid().ToString)
    
    If 0 = Connectors Then
          ' Create the new connector
          CSEntry = ManagementAgent.Connectors.StartNewConnector("person")
    
          ' Assign the distinguished name
          CSEntry.DN = DN
    
          ' Finish creating the new connector
          CSEntry.CommitNewConnector()
    
    ElseIf 1 = Connectors Then
          ' Assign the distinguished name using the existing connector
          CSEntry = ManagementAgent.Connectors.ByIndex(0)
          CSEntry.DN = DN
    
    Else
          Dim ExceptionMessage As String
          ExceptionMessage = "Multiple Connectors on Management Agent"
          Throw New UnexpectedDataException(ExceptionMessage)
    
    End If

    //Get the number of connectors for this MVEntry object under
    // this management agent.
    int Connectors;
    ReferenceValue DN;
    
    Connectors = ManagementAgent.Connectors.Count;
    DN = ManagementAgent.EscapeDNComponent(System.Guid.NewGuid().ToString());
    
    if(0 == Connectors)
    {
        //Create the new connector
        csentry = ManagementAgent.Connectors.StartNewConnector("person");
        
        // Assign the distinguished name    
        csentry.DN = DN;
        
        // Finish creating the new connector.
        csentry.CommitNewConnector();
    }
    
    else if(1 == Connectors)
    {
        // Assign the distinguished name using the existing connector
        csentry = ManagementAgent.Connectors.ByIndex[0];
        csentry.DN = DN;
    }
    
    else
    {
        string ExceptionMessage;
        ExceptionMessage = "Multiple Connectors on Management Agent";
        throw new UnexpectedDataException(ExceptionMessage);
    }

Set the Appropriate Distinguished Name or Attribute Values

To create a new valid connector, additional information must be set on the new CSEntry object. The information that need to be set depends upon the connected data source:

  • LDAP-based connected data sources. These connected data sources require a distinguished name for each object. Some examples of LDAP-based data sources are those data sources that use the management agents for Active Directory, Sun ONE Directory Server 4.1x and 5.x (formerly iPlanet Directory Server), Netscape Directory Server 4.1 and 6.01, Exchange 5.5, LDAP Data Interchange Format (LDIF), Directory Service Markup Language Services for Windows (DSML). For these data sources, construct a distinguished name with either the ManagementAgent.EscapeDNComponent or the ManagementAgent.CreateDNmethod. Use the CSEntry object returned by one of these methods to set the CSEntry.DN property. Finish the connector creation process with the CSEntry.CommitNewConnector method.

    For a code example that shows you how to provision objects in the connector space for LDAP-based connected directories, see Example: LDAP-based Connected Directories.

    Note  Use uppercase letters when specifying naming attributes for an Active Directory DN such as OU, CN, and DC; for example, OU=marklee, OU=users, DC=fabrikam, DC=com. Use of lowercase naming attributes may slow down the export of the management agent's data to Active Directory.

  • Connected data sources that expect the anchor attributes to be provided by Microsoft Identity Integration Server 2003. These connected data sources use the attribute specified in Set anchor of Configure special attributes in the management agent properties for the primary key. The anchor attribute can be a calculated value based on a single or multiple attributes. These data sources require the specified anchor attribute values to be set on the new connector object. For a code example on provisioning these objects, see Example: Connected Data Sources that Expect Identity Integration Server to Provide the Anchor Attributes.

  • Connected data sources that generate the anchor attributes. These connected data sources typically generate a primary key value from an auto-incremented identity column. For these types of data sources, you set the CSEntry.DN property to a temporary value and then add the new connector. When the new connector object is exported, the connected data source provides the permanent anchor. For a code example that shows you how to provision objects from data sources that provide the primary key, see Example: Connected Data Sources that Generate the Anchor Attribute.

  • Other Connected Data Sources. These connected data sources require specified property values prior to adding the connector to the connector collection. For a code example that shows you how to provision these objects, see the following code examples:

Finish Creating the New Connector or Disconnect or Rename the Existing Connector.

After setting the appropriate attribute values, you can do one of the following:

Handle Any Exceptions

During the provisioning process an exception may be thrown by the operating system, the .NET Framework, or the rules extension. Decide if the exceptions should stop or continue the provisioning process. For more information, see Catching Exceptions.

Send comments about this topic to Microsoft

Build date: 2/16/2009