Microsoft Identity Integration Server 2003 Developer Reference

Provisioning Objects in the Connector Space

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:

[Visual Basic .NET]
' 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
[C#]
//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:

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.