Simple Account Provisioning Walkthrough: Scenario Rules Extensions
Applies To: Windows Server 2003 with SP1
Previous Steps in This Walkthrough
Rules Extensions DLL Preparation
Before you modify any rules extensions, you must build the .dll files for the solutions found in the FabrikamADMA, FabrikamHRMA, and the HRProvisioning folders.
To modify the rules extensions provided with this scenario
Open Windows Explorer and navigate to C:\Scenarios\SimpleAccountProvisioning\FabrikamADMA.
Open the file FabrikamADMA.sln by using Visual Studio .NET 2003.
In the Solution Explorer pane, double-click FabrikamADMA.vb, as shown in Figure 2.46.
.gif "e902084e-2d6a-49ab-aa3f-d33e167f18f9")
Figure 2.46 Opening the Fabrikam AD MA Rules Extension
It is possible that in the first line of code in the file, which says Imports Microsoft.MetadirectoryServices, the Microsoft.MetadirectoryServices is underlined, indicating that Visual Studio .NET 2003 does not know where to locate this reference. If this is the case in your scenario setup, and you do not have an incorrect reference, perform the following steps.
In the Solution Explorer pane, expand the References collection.
Note the triangular warning icon over the Microsoft.MetadirectoryServices reference.
Right-click the reference and select Remove.
Right-click References in the Solution Explorer and select Add Reference.
Browse to C:\Program Files\Microsoft Identity Integration Server (or the location where you installed Microsoft Identity Integration Server 2003 on the computer).
In the Select Component, open the bin folder, and then the assemblies folder.
Doubleclick Microsoft.MetadirectoryServices.dll component, and then click OK to finish adding the reference.
Notice that Microsoft.MetadirectoryServices is no longer underlined in the first line of the code. This means that you have corrected the reference.
From the Build menu, select Build Solution.
You will see the following message in the Output window:
Build: 1 succeeded, 0 failed, 0 skipped.
Close Visual Studio .NET 2003.
Go back to Windows Explorer and navigate to the bin folder under the FabrikamADMA folder. Copy the file FabrikamADMA.dll to the Extensionfolder under the Microsoft Identity Integration Server 2003 installation path (C:\Program Files\Microsoft Identity Integration Server by default).
You must repeat this process of building the .dll file for the solutions found in the FabrikamHRMA and HRProvisioning folders as well. If you have changed the name of the domain to a name other than the name supplied in the scenario, ensure that you change these settings in the Simpleprov.xml file.
Fabrikam HR MA Extension
In the FabrikamHRMA folder in the scenario folder on the server running Microsoft Identity Integration Server 2003, open the file FabrikamHRMA.sln by using Visual Studio .NET 2003.
The following sections explain what the methods in this class do when they are run.
MapAttributesForImport
The MapAttributesForImport method, shown below, is called by the HR MA to handle the Advanced import attribute mapping that was created when the MA was set up. There were two attribute mappings defined earlier: the cn attribute, and the displayName attribute.
Select Case FlowRuleName.ToLower
Case "cn"
mventry ("cn").Value = csentry("sn").Value & ", " & csentry("givenName").Value
Case "displayName"
Mventry("displayName").Value = csentry("givenName").Value & " " & csentry("sn).Value
Case Else
End Select
The code in the rules extension sets the values of the two metaverse attributes based on values received from the HR attributes.
The Select Case statement determines what context is being called. In this scenario, two contexts are set up; one context is called cn and the other context is called displayName. The Select Case statement determines which attribute is being set and then takes the appropriate action.
The metaverse attribute cn is assembled by concatenating the values of the HR attributes givenName and sn using the following line of code:
mventry("cn").Value = csentry("sn").Value & ", " & csentry("givenName").Value
In the preceding code, the following values were used:
mventry(“cn”) is used to refer to the cn metaverse attribute.
.Value is the mventry object’s value of the cn attribute.
= is the assignment operator.
csentry(“sn”).Value is the sn HR attribute.
& “, ” is the code to concatenate a comma and space after the sn attribute’s value.
& csentry(“givenName”).Value is the code to append the givenName.
This code results in the metaverse cn attribute being set to Smith, John if the HR attribute sn has the value Smith and the HR attribute givenName has the value John.
The other case in the Select Case statement handles the setting of the displayName attribute in a similar way, only the result in this case would be John Smith.
Fabrikam AD MA Extension
From the FabrikamADMA folder, open FabrikamADMA.sln by using Visual Studio .NET 2003.
MapAttributesForExport
The MapAttributesForExport method is used for the userAccountControl, userPrincipalName and samAccountName attribute mappings defined when the Fabrikam AD MA was configured. This method will set the values of the connector space object attributes to be exported to Active Directory by assembling the values from data in the metaverse object being evaluated.
The outermost Select Case statement identifies which connector space object attribute is being set. For the userAccountControl attribute, the code sets the attribute value based on whether the value of the employeeStatus attribute for the metaverse object is active or inactive, which enables or disables the user account, respectively.
Fabrikam Provisioning Rules Extension
In the HRProvisioning folder from the scenario directory on the server running Microsoft Identity Integration Server 2003, open HRProvisioning.sln by using Visual Studio .NET 2003.
The Provision Method
The Provision method performs the most important operations in this scenario. Provisioning only takes place based on changes that occur in the metaverse, so this extension is not associated with any particular MA, but rather with the metaverse itself.
The first operation the Provision method performs is a check of the value of the employeeStatus attribute of the metaverse object, and then based on the values of the constants mentioned above, it sets the container value appropriately.
' Based on the value of "employeeStatus" determine the container in AD employeeStatus = mventry("employeeStatus").Value.ToLower
Select Case employeeStatus
Case "active"
Container = fabrikamUsersContainer
Case "inactive"
Container = fabrikamDisabledUsersContainer
Case Else
' employeeStatus must be active or inactive to be valid
' any other case is an error condition for this object.
' Throw an exception to abort this object's synchronization.
Throw New UnexpectedDataException("employeeStatus=" + employeeStatus.ToString)
End Select
After setting the container, the method determines the DN by using a utility function to concatenate its container DN with the RDN of the metaverse object (using the metaverse object CN attribute value).
' Based on the value of "cn" determine the RDN in AD
rdn = "CN=" & cnForObject
' Now construct the DN based on RDN and Container
dn = FabrikamADMA.EscapeDNComponent(rdn).Concat(container)
Next the method determines if a connector object is in the Fabrikam AD MA connector space. If there is no connector object, then it creates one by using the connectors.StartNewConnector and connector.CommitNewConnector method. If there was already a connector in the Fabrikam AD MA connector space, then the method sets the existing connector DN to the value calculated based on any change to the value of the employeeStatus attribute.
' If there is no connector present, add a new AD connector
' and call a subroutine to set the initial values on the CS Object numADConnectors = FabrikamADMA.Connectors.Count
If 0 = numADConnectors Then
csentry = FabrikamADMA.Connectors.StartNewConnector("user")
csentry.DN = dn
SetInitialValues(csentry, mventry)
Csentry.CommitNewConnector ()
Else If 1 = numADConnectors Then
' check if the connector has a different DN and rename if necessary
' First get the connector
myConnector = FabrikamADMA.Connectors.ByIndex (O)
' MIIS will rename/move if different, if not nothing will happen myConnector.DN = dn
Else
Throw New UnexpectedDataException("Multiple AD connectors:" + numADConnectors.ToString)
End If