Provisioning Objects in the Connector Space
After you install Forefront Identity Manager Synchronization Service (FIM Synchronization Service), one of the first steps to do after you project identity information from the different data sources into the FIM Synchronization Service database (metaverse) is to create and export new objects into other connected data sources. This process is known as provisioning. You implement provisioning by creating a rules extension that implements the Provision method. When the method is called, it gets passed the metaverse object as an MVEntry object.
We recommend that you follow these steps when you implement the provisioning logic:
Determine the state of the object.
Start creating a new connector or use the existing connector.
Set the appropriate distinguished name or attribute values.
Finish creating the new connector or disconnect or rename the existing connector.
Handle any exceptions.
Determine the State of the Object
Provision 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, 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 a New Connector or Use the Existing Connector
After you determine the state of the metaverse object, you can create a new connector or use an existing connector, depending on the value of the Count property. If this value is zero, start creating a new connector using the StartNewConnector method. If the property is 1, 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 StartNewConnector method. When you call this method, use the object type that was selected in the management agent as the parameter. To determine the object type that was selected, go to Select Object Types in the management agent properties.
To use the existing connector, use the ByIndex property or the ByDN property.
The following examples show how you can obtain 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, you must set additional information on the new CSEntry object. The information that you set depends on the connected data source:
Lightweight Directory Access Protocol (LDAP)-based connected data sources. These connected data sources require a distinguished name (DN) for each object. Some examples of LDAP-based data sources are those data sources that use the management agents for Active Directory Domain Services (AD DS), Sun ONE Directory Server 4.1x and 5.x (formerly iPlanet Directory Server), Netscape Directory Server 4.1 and 6.01, Microsoft Exchange Server 5.5, LDAP Data Interchange Format (LDIF), and Directory Service Markup Language Services for Windows (DSML). For these data sources, construct a distinguished name with either the EscapeDNComponent method or the CreateDN method. Use the CSEntry object that is returned by one of these methods to set the DN property. Finish the connector creation process by using the CommitNewConnector method. For a code example that shows how to provision objects in the connector space for LDAP-based connected directories, see How to: Provision LDAP-Based Connected Data Sources.
Note
Use uppercase letters when you specify naming attributes for an Active Directory DN such as OU, CN, and DC: for example, OU=marklee, OU=users, DC=fabrikam, DC=com. Using lowercase naming attributes may slow down the export of the management agent's data to AD DS.
Connected data sources that expect the anchor attributes to be provided by FIM Synchronization Service. These connected data sources use the attribute that is 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 that you set the specified anchor attribute values on the new connector object. For a code example that demonstrates how to provision these objects, see How to: Provision Connected Data Sources That Expect FIM Synchronization Service 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 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 How to: Provision Connected Data Sources That Generate Anchor Attributes.
Other Connected Data Sources. These connected data sources require specified property values before you add 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 you set the appropriate attribute values, you can do one of the following:
Finish creating the new connector using the CommitNewConnector method.
Disconnect the existing connector using the Deprovision method. For an example that shows how to disconnect an existing connector, see How to: Deprovision Objects After a Specified Time
Rename the existing connector. For an example, see How to: Create New Connectors or Rename Existing Connectors
Handle Any Exceptions
During the provisioning process, an exception might be thrown by the operating system, the Microsoft .NET Framework, or the rules extension. Decide if the exceptions should stop or continue the provisioning process. For more information, see How to: Catch Exceptions.