With FIM we lost this capability, and Microsoft claim we were never supposed to be doing it anyway – that it was “unsupported” all along. So what do you do if you’ve got string data and you really need references? One Sync-based way is to loop the data through a SQL MA, bringing it back in as a reference.

The method outlined here generates a manager attribute from the two string attributes position and superiorPosition, which hold position numbers (as distinct from employee numbers).

Create SQL Tables

Create the following tables:

• GenerateRef_Objects

DN [nvarchar] (200)

objectType [nchar] (50)

• GenerateRef_MultiValue

DN [nvarchar] (200)

attribute [nchar] (50)

Reference [nvarchar] (200)

The plan for these tables is to export data to them so that the Objects table lists the possible position numbers along with an objectType of “position”, and the MultiValue table shows the relationship between the positions, with the one in the Reference column being the manager.

Note that the “x” entry is just a placeholder I put in while creating the MA, because it needs to see at least one objectType specified. Once the MA is created I can delete that line.

Create a SQL MA

Start by creating the SQL Management Agent in the usual way:

Set the anchor to the DN column:

You will also have to configure the Multi-Value settings. These are a little obscure, and I’ve explained them in more detail elsewhere, so I’ll just show a piccy here:

As well you have to set an object type. For flexibility I’m just going to point it at my “objectType” column, meaning I could, potentially, support multiple types with this MA.

Set a join rule between the column where the position number is stored in the Objects table (in this case the “DN”) and the position attribute in the Metaverse.

Now for the flow rules: we want to flow the superiorPosition string value out to manager, and then the same value back to the manager attribute in the Metaverse – but now magically transformed to a reference.

Finally set your deprovisioning rules:

Metaverse Code

The final step is to write the provisioning code that creates the position objects in the SQL table.

(As this is a Sync-based method I’m going classic with none of that “declarative” malarky. If you had the Portal in the mix you may well be sorting out this manager stuff in there anyway.)

    Public Sub Provision(ByVal mventry As MVEntry) Implements IMVSynchronization.Provision
        If mventry.ObjectType <> PersonObjectClass Then
            Exit Sub
        End If

        Dim DoesExist As Boolean = False
        Dim ShouldExist As Boolean = False

        If mventry.ConnectedMAs(MAName).Connectors.Count > 0 Then
            DoesExist = True
        End If

        If mventry("position").IsPresent Then
            ShouldExist = True
        End If

        If ShouldExist And Not DoesExist Then
            Dim csentry As CSEntry
            csentry = mventry.ConnectedMAs(MAName).Connectors.StartNewConnector("position")
            csentry("DN").Value = mventry("position").Value
            csentry.CommitNewConnector()

        ElseIf DoesExist And Not ShouldExist Then
            Dim csentry As CSEntry
            csentry = mventry.ConnectedMAs(MAName).Connectors.ByIndex(0)
            csentry.Deprovision()
        End If
    End Sub

What should happen

When you sync your person objects you should see “position” objects being provisioned. Export, Import and Sync and you should see the reference value flow back into the Metaverse.

Note that this method does assume position numbers are unique – if you have a possibility of duplicate position numbers (such as with a job share) then you will need to get a bit more creative.

If you have a lot of data you should also look at generating a Delta table for the confirming Import step.

Implementing the Activity

As is the case with most of these FIM activity components, you need to set the stage with some code first.

Inside my code activity I have to set the following two properties:

• the To field – a comma separated list of email addresses, and
• the Email Template, which must exist in the FIM Portal, and is identified by its ResourceID.

The following example is the most simple as I’ve just hardcoded the values.

Me.emailNotificationActivity_To1 = "jack.black@somecompany.com,jack.white@somecompany.com"
Me.emailNotificationActivity_EmailTemplate1 = New System.Guid("727756dc-92b3-4861-8cab-4ab81ca28a3d")

Of course you won’t be hardcoding values in your code like this – where you get them from I’ll leave up to you.

In my case I get the email addresses by looping through the group’s Owners. The email template I’m getting through the completely inelegant approach of hardcoding the template’s ResourceID in my Workflow configuration. If anyone can tell me how to get an Identity Picker into the Workflow UI I’d be much oblidged!

Fleshing out your email with WorkflowData

The other thing I found is that I needed to use WorkflowData parameters to improve the content of my notification email.

For example, you don’t want to send an email to someone saying “A group has changed” – that’s not very informative! You want to send them “Group ’Dark Chocolate Fans’ has changed; Carol Wapshere has been added to group ‘Dark Chocolate Fans’ “.

In my prototype I could get the name of the of the user whose membership had changed through the //Target construct, but I was reading the changed group (or groups) from the Request object. This meant that the Group Name was something I would only have access to while the workflow was running.

I added a string property to the Workflow UI where the user can enter a WorkflowData parameter name:

I then made sure that I was using the same parameter name in my Email Template:

And finally, I added this code to the initNotification activity, after setting the To and Template parameters. Note that WFParamName is the UI Property I defined. And the object readGroup_Resource1 is the result of an earlier ReadResourceActivity where I looked up the group object.

            '' Return group name in WorkflowData to use in email template
            Dim containingWorkflow As SequentialWorkflow = Nothing
            If Not SequentialWorkflow.TryGetContainingWorkflow(Me, containingWorkflow) Then
                Throw New InvalidOperationException("Unable to get Containing Workflow")
            End If
            Try
                If containingWorkflow.WorkflowDictionary.ContainsKey(Me.WFParamName) Then
                    containingWorkflow.WorkflowDictionary.Remove(Me.WFParamName)
                End If
                containingWorkflow.WorkflowDictionary.Add(Me.WFParamName, readGroup_Resource1("DisplayName"))
            Catch
                Throw New InvalidOperationException("Unable to update WorkflowData parameter " & Me.WFParamName)
            End Try

It’s designed to work with the Function Evaluator

The first point to note is that, unless you’re running a script or cmdlet that takes no parameters, you’re going to have to generate a parameter string. For BPOS this will include the BPOS Identity as a minimum. I use the Function Evaluator ahead of this activity to generate my powershell parameter string, which I then pass to the powershell activity through WorkflowData.

The Parameter string must be in an expected format

My activity only supports parameter strings in the format “-Param ‘Argument’ -Param ‘Argument’”.

• Scripts using the arg(0), arg(1) method are not supported.
• String arguments only.
• All arguments have to be enclosed in single-quotes, even if you don’t have to do this when running the cmdlet directly in powershell.

Using the Activity

General Control Settings

• Enable/Disable activity
• Logging to Application Event Log
• Workflow type:
  • Action: activity completes irrespective of powershell return value,
  • AuthZ: activity fails if powershell returns an error.

Powershell Command

• Name of powershell cmdlet or full path to script
• Specify plugin (in case using another library, eg., MessageOps)
• Parameters passed via WorkflowData parameter generated earlier (see above).

Return Values

• Specify WorkflowData parameters to return the result of the powershell command (“Succeeded”,”Failed”) and/or a detailed message. These can then be used in a subsequent activity, such as a Notification.

Post-Execution Behaviour

• Reverse simple changes in certain cases eg.,
  • Clear a change password attribute on both success and failure,
  • Clear a check box if the requested change failed.

Connection Settings

• If using Remote Powershell specify the remote server name and connection details. Assumes “localhost” if left blank.
• Specify BPOS username and password of an administrator account.
• Note that passwords must be re-entered whenever the activity is edited.

The Code

You can download a copy of the activity here.

Please note you will need to fix the references and compile it yourself.

This code is provided as an example only with no warranty or support. It may not be applicable for your environment. Make sure you understand it and adapt it appropriately.

The Basic Code

The code, which you will put into your custom workflow, is very simple. To start with, get the containing workflow which gives you access to any existing WorkflowData parameters:

'' Get containing Workflow
Dim containingWorkflow As SequentialWorkflow = Nothing
If Not SequentialWorkflow.TryGetContainingWorkflow(Me, containingWorkflow) Then
    Throw New InvalidOperationException("Unable to get Containing Workflow")
End If

Then add a new parameter with the data you want to communicate back out of your code:

    containingWorkflow.WorkflowDictionary.Add("MyParam", "My Value")

You can then use [//WorkflowData/MyParam]  in subsequent steps within the same FIM workflow.

Pass the Parameter to the Custom Workflow

You can make your workflow a bit more flexible if you allow the user to set the parameter name when configuring the activity.

Here I’ve added a string parameter to my workflow UI. This allows the user to enter a WorkflowData parameter while configuring the activity. The following code snippet will return a message in the parameter.

'' Write the return details if it was requested
If Me.ResultDetails.Contains("WorkflowData") Then
    Dim seperator() As Char = {"[", "]", "\", "/"}
    Dim wfkey As String = Me.ResultDetails.Split(seperator, StringSplitOptions.RemoveEmptyEntries)(1)
    containingWorkflow.WorkflowDictionary.Add(wfkey, returnMessage)
End If

But now I’ve had a play with it, and figured out how to update the field (it needs to be in XML) and why it’s very cool to do so (it makes the message easily available to the user).

In my custom workflow I have the following activities:

• A CurrentRequestActivity
• A code activity, and
• A ResourceUpdateActivity.

During my code activity I have set two variables:

• Boolean “success”, and
• String “returnMessage”.

Now at the end of my code activity I add the following code to prepare the ground for the ResourceUpdateActivity (which I’ve named “updateRequestDetails”) that writes the message back.

        Me.updateRequestDetails_ActorId1 = New Guid(FIMADMIN_GUID)
        Me.updateRequestDetails_ResourceId1 = Me.currentRequestActivity.CurrentRequest.ObjectID
        Dim returnXML As String
        Dim returnLevel As String
        If success Then
            returnLevel = "Information"
        Else
            returnLevel = "Error"
        End If
        returnXML = "<RequestStatusDetail xmlns:xsi=""http://www.w3.org/2001/XMLSchema-instance"" " _
                    & "xmlns:xsd=""http://www.w3.org/2001/XMLSchema"" DetailLevel=""" & returnLevel & """ " _
                    & "EntryTime=""" & DateTime.Now.ToUniversalTime().ToString("yyyy'-'MM'-'dd'T'HH':'mm':'ss'.000'") & """>" _
                    & returnMessage & "</RequestStatusDetail>"
        Dim updateInstruction As New UpdateRequestParameter
        updateInstruction.PropertyName = "RequestStatusDetail"
        updateInstruction.Mode = UpdateMode.Insert
        updateInstruction.Value = returnXML
        Me.updateRequestDetails_UpdateParameters1 = New UpdateRequestParameter() {updateInstruction}

I’ve used the FIM Admin account to write the message, and I had to explicitly give it permission to write to the RequestStatusDetail attribute of the Request resource type. You could also use the requestor’s account to update the field (Me.updateRequestDetails_ActorId1 = Me.currentRequestActivity.CurrentRequest.Creator), but you will still need to explicitly grant permissions with an MPR (have a look at the “Request Management: Request creators can…” MPRs to see what you need to do).

And here’s a picture of the Request after the custom workflow activity failed.

What does the documentation say?

The first thing I did was consult the official document Developing Custom Activities and Workflows. The only thing I could find about passing data was this:

Passing Data between Workflow Phases

Some scenarios may require that an authorization workflow share some information with an action workflow that runs for the same request. (For more information, see Request Processing.) The recommended approach for accomplishing this scenario is as follows:

Passing Data from an Authorization Workflow Activity to an Action Workflow

1. Create and bind one or more attributes to the Request resource type in the FIM schema that can store the information that you want to share between activities. You can do this through Web services or by using the FIM Portal.
2. Grant permissions to the person or resource that will be assigned to the ActorID of the activity to read and modify the new attribute. Note that this step is not required if the ActorID is set to the FIM Service Account resource. For more information, see Microsoft.ResourceManagement.Workflow.Activities.
3. In the authorization workflow activity, use the UpdateResourceActivity activity to set the desired value on the new attribute.
4. In the action workflow activity, use the ReadResourceActivity to get the value of the new attribute.

However this didn’t seem to address my simpler situation. I’m not trying to pass a value between an AuthZ and an Action workflow – I just want to pass the data between two steps in the same Action workflow. Perhaps I can use a WorkflowData parameter?

But as I thought about it I decided that maybe the method mentioned in the documentation was the right way to go. Essentially I am updating the request object itself with the results of the activity, and this then forms a permanent record. To jump ahead in the story, here’s what a request object looks like after a failed password reset operation. I think that’s pretty useful!

Create the Attributes

So following step one from the documentation, I created the following attributes and bound them to the Request resource type:

• “Activity Status” – indexed string. This will normally contain “Succeeded” or “Failed”.
• “Activity Status Message” – unindexed string. Here I can put extra info about why an activity failed.

Grant permissions to the new attributes

I added the new attributes to both of the following MPRs:  Request management: Request creators can read their approval resources and Request management: Request participants can read their request resources.

I also updated Administration: Administrators can control requests because I’m using the FIM service account to make the changes to the request (note the documentation above says you don’t have to do that if using the service account . I think that may be a mistake as rights always have to be granted, and I certainly had to).

Code the custom workflow activity to update the Request

The custom workflow must include a CurrentRequestActivity to get the details of the current request – I think this is probably standard anyway. Here I’m finishing up with two UpdateResourceActivities which update respectively the “Activity Status” and “Activity Status Message”. And I also need a code activity somewhere to feed the values to the UpdateResourceActivities. I tack this at the end of the code activity where I’m running my password reset code, because that’s where I have easy access to the results of the reset attempt. This code that sets up the UpdateResourceActivities is below. Note I am using the Built-In Admin account to update the request object. The variable “failureMessage” was already set earlier in the code.

    Const FIMADMIN_GUID As String = "7fb2b853-24f0-4498-9534-4e10589723c4"

    '' Prepare variables for UpdateRequest activities which write the activity status back to the Request object.
    Me.updateRequest1_ActorId1 = New Guid(FIMADMIN_GUID)
    Me.updateRequest1_ResourceId1 = Me.currentRequestActivity1.CurrentRequest.ObjectID
    Dim updateInstruction1 As New UpdateRequestParameter
    updateInstruction1.PropertyName = "ActivityStatus"
    If success Then
        updateInstruction1.Mode = UpdateMode.Modify
        updateInstruction1.Value = "Succeeded"
    Else
        updateInstruction1.Mode = UpdateMode.Modify
        updateInstruction1.Value = "Failed"
    End If

    Me.updateRequest1_UpdateParameters1 = New UpdateRequestParameter() {updateInstruction1}
    Me.updateRequest2_ActorId1 = New Guid(FIMADMIN_GUID)
    Me.updateRequest2_ResourceId1 = Me.currentRequestActivity1.CurrentRequest.ObjectID
    Dim updateInstruction2 As New UpdateRequestParameter
    updateInstruction2.PropertyName = "ActivityStatusMessage"
    If success Then
        'No message
    Else
        updateInstruction2.Mode = UpdateMode.Modify
        updateInstruction2.Value = failureMessage
    End If
    Me.updateRequest2_UpdateParameters1 = New UpdateRequestParameter() {updateInstruction2}

Accessing the values from an Email Template

My final step is to create the Email Template that will be used by the Notification Activity.

For the Subject:

BPOS Password Reset [//Request/ActivityStatus]

And in the body I add the following:

<p class="MsoNormal"><b>Request Status:</b></p>
<p class="MsoNormal">[//Request/ActivityStatus]</p>
<p class="MsoNormal">[//Request/ActivityStatusMessage]</p>
<p class="MsoNormal"><o:p> </o:p></p>

The result is that the password reset operation runs and depending on the result of the attempt, the user gets one of these emails:

And I think that that’s pretty cool!

Note: I have also uploaded a version of this to the Technet Wiki: How to Add a RadioButtonList to a FIM Custom Workflow UI

Here I’m adding a control which allows me to set a Logging Level. I then use the value Me.LoggingLevel in my code to decide which messages to write to the event log.

Define the property in the Activity code

The radio control will return a string value so I need to define the property in the Activity code.

    '''
    '''  Identifies the target attribute
    '''
    Public Shared LoggingLevelProperty As DependencyProperty = DependencyProperty.Register("LoggingLevel", GetType(System.String), GetType(MyActivity))
    <Description("Please specify the target attribute")> _
    <DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)> _
    <Browsable(True)> _
    Public Property LoggingLevel() As String
        Get
            Return DirectCast(MyBase.GetValue(MyActivity.LoggingLevelProperty), [String])
        End Get
        Set(ByVal value As String)
            MyBase.SetValue(MyActivity.LoggingLevelProperty, value)
        End Set
    End Property

UI code functions

Add the following functions to your UI code:

#Region "Radio Functions"
    Private Function AddTableRowRadioList(ByVal labelText As [String], ByVal controlID As [String], _
                                          ByVal radioOptions As String(), _
                                          ByVal defaultValue As [String]) As TableRow
        Dim row As New TableRow()
        Dim labelCell As New TableCell()
        Dim controlCell As New TableCell()
        Dim label As New Label()
        Dim radioList As New RadioButtonList()
        Dim item As String

        label.Text = labelText
        label.CssClass = MyBase.LabelCssClass
        labelCell.Controls.Add(label)

        radioList.ID = controlID
        For Each item In radioOptions
            radioList.Items.Add(New ListItem(item, item))
        Next
        radioList.SelectedValue = defaultValue
        radioList.RepeatDirection = RepeatDirection.Horizontal
        controlCell.Controls.Add(radioList)
        row.Cells.Add(labelCell)
        row.Cells.Add(controlCell)
        Return row
    End Function

    Private Function GetRadioSelection(ByVal radioListID As String) As String
        Dim radioList As RadioButtonList = DirectCast(Me.FindControl(radioListID), RadioButtonList)
        Return radioList.SelectedValue
    End Function

    Private Sub SetRadioSelection(ByVal radioListID As String, ByVal radioSelection As String)
        Dim radioList As RadioButtonList = DirectCast(Me.FindControl(radioListID), RadioButtonList)
        If radioList IsNot Nothing Then
            radioList.SelectedValue = radioSelection
        Else
            radioList.SelectedValue = radioList.Items.Item(0).Text
        End If
    End Sub

    Private Sub SetRadioListReadOnlyOption(ByVal radioListID As String, ByVal [readOnly] As Boolean)
        Dim radioList As RadioButtonList = DirectCast(Me.FindControl(radioListID), RadioButtonList)
        radioList.Enabled = Not [readOnly]
    End Sub

    Protected Overrides Sub CreateChildControls()
        Dim controlLayoutTable As Table
        controlLayoutTable = New Table()

        'Width is set to 100% of the control size
        controlLayoutTable.Width = Unit.Percentage(100.0)
        controlLayoutTable.BorderWidth = 0
        controlLayoutTable.CellPadding = 2
        ' The following lines add the Radio Control
        Dim loggingOptions As String() = {"Normal", "Verbose"}
        controlLayoutTable.Rows.Add(Me.AddTableRowRadioList("Logging Level:", "txtLoggingLevel", loggingOptions, "Normal"))
        Me.Controls.Add(controlLayoutTable)

        MyBase.CreateChildControls()
    End Sub

#End Region

Modify the default methods of the UI code

Finally modify the default metods of the UI code to handle the value.

    Public Overrides Function GenerateActivityOnWorkflow(ByVal workflow As SequentialWorkflow) As Activity
        If Not Me.ValidateInputs() Then
            Return Nothing
        End If
        Dim MyActivity As New MyActivity()
        MyActivity.LoggingLevel = Me.GetRadioSelection("txtLoggingLevel")
        Return MyActivity
    End Function

    Public Overrides Sub LoadActivitySettings(ByVal activity As Activity)
        Dim MyActivity As MyActivity = TryCast(activity, MyActivity)
        If MyActivity IsNot Nothing Then
            Me.SetRadioSelection("txtLoggingLevel", MyActivity.LoggingLevel)
        End If
    End Sub

    Public Overrides Function PersistSettings() As ActivitySettingsPartData
        Dim data As New ActivitySettingsPartData()
        data("LoggingLevel") = Me.GetRadioSelection("txtLoggingLevel")
        Return data
    End Function

    Public Overrides Sub RestoreSettings(ByVal data As ActivitySettingsPartData)
        If data IsNot Nothing Then
            Me.SetRadioSelection("txtLoggingLevel", DirectCast(data("LoggingLevel"), String))
        End If
    End Sub

    Public Overrides Sub SwitchMode(ByVal mode As ActivitySettingsPartMode)
        Dim [readOnly] As Boolean = (mode = ActivitySettingsPartMode.View)
        Me.SetRadioListReadOnlyOption("txtLoggingLevel", [readOnly])
    End Sub

Note: I have also posted a version of this to the Technet Wiki: How to Add a CheckBox to a FIM Custom Workflow UI

The code I’m sharing here adds an “Enabled” checkbox to the workflow UI in the FIM Portal. Whether or not it is ticked returns a boolean value which you can then reference in your code.

Define the boolean property in the Activity code

This is pretty much like the regular way UI properties are defined, just typing it as a Boolean instead of a String.

    '''
    '''  Identifies the target attribute
    '''
    Public Shared WFEnabledProperty As DependencyProperty = DependencyProperty.Register("WFEnabled", GetType(System.Boolean), GetType(MyActivity))
    <Description("Please specify the target attribute")> _
    <DesignerSerializationVisibility(DesignerSerializationVisibility.Visible)> _
    <Browsable(True)> _
    Public Property WFEnabled() As Boolean
        Get
            Return DirectCast(MyBase.GetValue(MyActivity.WFEnabledProperty), [Boolean])
        End Get
        Set(ByVal value As Boolean)
            MyBase.SetValue(MyActivity.WFEnabledProperty, value)
        End Set
    End Property

UI code functions

Add the following functions to your UI code:

#Region "CheckBox Functions"
    Private Function AddTableRowCheckBox(ByVal labelText As [String], ByVal controlID As [String], _
                                         ByVal defaultValue As [Boolean]) As TableRow
        Dim row As New TableRow()
        Dim labelCell As New TableCell()
        Dim controlCell As New TableCell()
        Dim label As New Label()
        Dim checkbox As New CheckBox()

        label.Text = labelText
        label.CssClass = MyBase.LabelCssClass
        labelCell.Controls.Add(label)

        checkbox.ID = controlID
        checkbox.Checked = defaultValue

        controlCell.Controls.Add(checkbox)
        row.Cells.Add(labelCell)
        row.Cells.Add(controlCell)
        Return row
    End Function

    Private Function GetIsChecked(ByVal checkBoxID As String) As Boolean
        Dim checkBox As CheckBox = DirectCast(Me.FindControl(checkBoxID), CheckBox)
        Return checkBox.Checked
    End Function

    Private Sub SetIsChecked(ByVal checkBoxID As String, ByVal isChecked As Boolean)
        Dim checkBox As CheckBox = DirectCast(Me.FindControl(checkBoxID), CheckBox)
        If checkBox IsNot Nothing Then
            checkBox.Checked = isChecked
        Else
            checkBox.Checked = True
        End If
    End Sub

    Private Sub SetCheckBoxReadOnlyOption(ByVal textBoxID As String, ByVal [readOnly] As Boolean)
        Dim checkBox As CheckBox = DirectCast(Me.FindControl(textBoxID), CheckBox)
        checkBox.Enabled = Not [readOnly]
    End Sub

#End Region

Modify the default methods of the UI code

Finally modify the default metods of the UI code to handle the value.

    Public Overrides Function GenerateActivityOnWorkflow(ByVal workflow As SequentialWorkflow) As Activity
        If Not Me.ValidateInputs() Then
            Return Nothing
        End If
        Dim MyActivity As New MyActivity()
        MyActivity.WFEnabled = Me.GetIsChecked("bWFEnabled")
        Return MyActivity
    End Function

    Public Overrides Sub LoadActivitySettings(ByVal activity As Activity)
        Dim MyActivity As MyActivity = TryCast(activity, MyActivity)
        If MyActivity IsNot Nothing Then
            Me.SetIsChecked("bWFEnabled", MyActivity.WFEnabled)
        End If
    End Sub

    Public Overrides Function PersistSettings() As ActivitySettingsPartData
        Dim data As New ActivitySettingsPartData()
        data("WFEnabled") = Me.GetIsChecked("bWFEnabled")
        Return data
    End Function

    Public Overrides Sub RestoreSettings(ByVal data As ActivitySettingsPartData)
        If data IsNot Nothing Then
            Me.SetIsChecked("bWFEnabled", DirectCast(data("WFEnabled"), Boolean))
        End If
    End Sub

    Public Overrides Sub SwitchMode(ByVal mode As ActivitySettingsPartMode)
        Dim [readOnly] As Boolean = (mode = ActivitySettingsPartMode.View)
        Me.SetCheckBoxReadOnlyOption("bWFEnabled", [readOnly])
    End Sub

    Protected Overrides Sub CreateChildControls()
        Dim controlLayoutTable As Table
        controlLayoutTable = New Table()

        'Width is set to 100% of the control size
        controlLayoutTable.Width = Unit.Percentage(100.0)
        controlLayoutTable.BorderWidth = 0
        controlLayoutTable.CellPadding = 2
        ' The following line adds the CheckBox
        controlLayoutTable.Rows.Add(Me.AddTableRowCheckBox("Enabled:", "bMyCheckBox", True))
        Me.Controls.Add(controlLayoutTable)

        MyBase.CreateChildControls()
    End Sub

Using the value

Once all that’s done I simply access the value in my Activity code using Me.WFEnabled.

Many target systems are supported OOB, but for BPOS you have to get a little creative and write your own Password Extension. This post shows you how I did that.

Before I continue however, I do feel obliged to make a comment about the security implications of doing this. There is an argument that passwords used internally should never be sent outside the firewall, and this should be considered in your environment. In my case the source AD was created just for DirSync so the accounts there are not actually being used for anything else, and the password remains different to the user’s normal desktop logon. Password Sync provides an alternative to the BPOS admin console, and opens the way for reset through the FIM Portal.

First, you need a connector space which represents your BPOS user objects

This should be pretty obvious – for password sync to work it needs a direct join, through the Sync Service, from the source AD to the target account. So you need a connector space with objects that represent your BPOS users and contain, at an absolute minimum, the BPOS Identity which you will use in the powershell password change process.

For ideas about creating a BPOS MA see Three Different Ways to Create a BPOS Management Agent.

The MA has to run in process

There is apparently a bug with password extensions in FIM Sync – if you run the MA in a seperate process the sync service can’t find the extension and you see these errors in the event log:

An unexpected error has occurred during a password set operation.
BAIL: MMS(4948): ma.cpp(373): 0x80040154 (Class not registered)

Running the MA in process fixes this problem.

The Powershell Runspace doesn’t dispose quickly enough

I ran into a problem with a System.AppDomainUnloadedException. The password sync worked fine, but then five minutes later the entire miiserver.exe process crashed with this exception.

The Sync service loads an extension dll when it is needed, and keeps it open while it’s being used. Five minutes after the last use of the dll it runs any termination code and unloads the dll. Clearly something was going wrong here.

At this point I’m going to shout out a big thanks to Brian Desmond and Craig Martin who helped me with this problem. While I still don’t completely understand what’s going on, I gather it has something to do with the sync service unloading the password extension while the runspace is still being disposed. The solution I found is to add a System.Threading.Thread.Sleep(0) straight after the Dispose instruction, which is an instruction to wait for other threads to finish.

Install and configure PCNS

 
I’m not going to go into this. There is perfectly good documentation (see Peter Geelen’s overview and troubleshooting tips here) and actually the instructions haven’t changed since MIIS 2003.

Though I will just add, in case anyone’s interested, yes you can install PCNS on a server core domain controller (though not an RODC for the obvious reason that it can’t process a password change).

Configuring the Sync Service

Start by enabling Password Sync:Tools –> Options –> Enable Password Synchronization
Configure the AD MA which is the source for synchronization of changed passwords: On the “Configure Directory Properties” tab, tick to enable the partition as a password synchronization source. Click “Targets” and select your BPOS MA.
Configure the BPOS MA: On the “Configure Extensions” tab, tick to enable password management and select the password extension dll file (code below). You will also have to set the connection credentials. As I’m accessing the MSOnline cmdlets via remote powershell I actually need two sets of credentials – one for the remote server connection and one for BPOS. However the MA config for password extensions only gives you space for one username and password. I have gone with the completely inelegant workaround of including both usernames and both passwords, separated by a semi-colon, like so:    mydomainUser;bposUser    mydomainPassword;bposPassword It’s not pretty and I don’t much like it, but it’s working for now.

The Code

And here is the password extension code.

Imports Microsoft.MetadirectoryServices
Imports System.Management.Automation
Imports System.Management.Automation.Host
Imports System.Management.Automation.Runspaces
Imports System.Diagnostics

Public Class BPOSPasswordExtension

    Implements IMAPasswordManagement

    Dim myRunSpace As Runspace
    Dim bposCred As PSCredential

    Public Sub BeginConnectionToServer(ByVal connectTo As String, _
        ByVal user As String, _
        ByVal password As String) _
        Implements Microsoft.MetadirectoryServices.IMAPasswordManagement.BeginConnectionToServer

        Dim PSRemoteUser As String = ""
        Dim PSRemotePassword As String = ""
        Dim BPOSUser As String
        Dim BPOSPassword As String

        If user.Contains(";") Then
            PSRemoteUser = user.Split(";")(0)
            BPOSUser = user.Split(";")(1)
        Else
            BPOSUser = user
        End If

        If password.Contains(";") Then
            PSRemotePassword = password.Split(";")(0)
            BPOSPassword = password.Split(";")(1)
        Else
            BPOSPassword = password
        End If

        If Not connectTo = "" Then
            If PSRemoteUser = "" Or PSRemotePassword = "" Then
                Throw New BadServerCredentialsException("If Connect To is configured in the Password Settings then " _
                & "there must be two semicolon separated Users (psremoteuser;bposuser) and two semicolon separated " _
                & "passwords (psremotepassword;bpospassword)")
                Exit Sub
            End If
        End If

        ' Open powershell runspace
        If connectTo = "" Then
            myRunSpace = OpenLocalRunspace()
        Else
            myRunSpace = OpenRemoteRunspace(connectTo, PSRemoteUser, PSRemotePassword)
        End If
        If myRunSpace Is Nothing Then
            Throw New PasswordExtensionException("Failed to open powershell runspace to server " & connectTo)
            Exit Sub
        End If
        WriteToEventLog("Successfully opened powershell runspace to " & connectTo, EventLogEntryType.Information)

        ' Create credential for attaching to BPOS
        Dim bpospass As New Security.SecureString
        For Each c In BPOSPassword
            bpospass.AppendChar(c)
        Next
        bposCred = New PSCredential(BPOSUser, bpospass)

        ' Add plugin required for BPOS cmdlets
        Dim psh As PowerShell = PowerShell.Create()
        psh.Runspace = myRunSpace
        psh.AddCommand("Add-PSSnapin")
        psh.AddParameter("Name", "Microsoft.Exchange.Transporter")
        Try
            psh.Invoke()
        Catch ex As Exception
            Throw New PasswordExtensionException("Failed to add PS snapin. " & ex.Message)
        End Try

    End Sub

    Public Sub ChangePassword(ByVal csentry As Microsoft.MetadirectoryServices.CSEntry, _
        ByVal OldPassword As String, _
        ByVal NewPassword As String) _
        Implements Microsoft.MetadirectoryServices.IMAPasswordManagement.ChangePassword
    End Sub

    Public Sub EndConnectionToServer() _
        Implements Microsoft.MetadirectoryServices.IMAPasswordManagement.EndConnectionToServer
        If Not myRunSpace Is Nothing Then
            myRunSpace.Dispose()
            System.Threading.Thread.Sleep(0)
            WriteToEventLog("Runspace closed.", EventLogEntryType.Information)
        End If
    End Sub

    Public Function GetConnectionSecurityLevel() As Microsoft.MetadirectoryServices.ConnectionSecurityLevel _
        Implements Microsoft.MetadirectoryServices.IMAPasswordManagement.GetConnectionSecurityLevel
    End Function

    Public Sub RequireChangePasswordOnNextLogin(ByVal csentry As Microsoft.MetadirectoryServices.CSEntry, _
        ByVal fRequireChangePasswordOnNextLogin As Boolean) _
        Implements Microsoft.MetadirectoryServices.IMAPasswordManagement.RequireChangePasswordOnNextLogin
        ' This method is not used
        Throw New EntryPointNotImplementedException
    End Sub

    Public Sub SetPassword(ByVal csentry As Microsoft.MetadirectoryServices.CSEntry, _
        ByVal NewPassword As String) _
        Implements Microsoft.MetadirectoryServices.IMAPasswordManagement.SetPassword

        Dim psh As PowerShell = PowerShell.Create()
        Dim psresult As New System.Collections.ObjectModel.Collection(Of PSObject)
        psh.Runspace = myRunSpace

        psh.AddCommand("Set-MSOnlineUserPassword")
        psh.AddParameter("Identity", csentry.DN.ToString)
        psh.AddParameter("Password", NewPassword)
        psh.AddParameter("ChangePasswordOnNextLogon", False)
        psh.AddParameter("Credential", bposCred)
        Try
            psresult = psh.Invoke()
        Catch ex As Exception
            Throw New PasswordExtensionException(ex.Message)
        End Try

        If psh.Streams.Warning.Count > 0 Then
            Throw New PasswordExtensionException(psh.Streams.Warning.Item(0).Message)
        ElseIf psh.Streams.Error.Count > 0 Then
            Throw New PasswordExtensionException(psh.Streams.Error.Item(0).ErrorDetails.Message)
        End If

        psh.Dispose()

    End Sub

#Region "Powershell Functions"
    Private Function PSCredObject(ByVal username As String, ByVal password As String) As PSCredential
        Dim PWSecureString As New Security.SecureString
        Dim c As Char
        For Each c In password
            PWSecureString.AppendChar(c)
        Next
        Dim PSCred As New PSCredential(username, PWSecureString)
        Return PSCred
    End Function

    Private Function OpenRemoteRunspace(ByVal RemoteServer As String, ByVal RemoteUser As String, ByVal RemotePassword As String) As Runspace
        Const SHELL_URI As String = "http://schemas.microsoft.com/powershell/Microsoft.PowerShell"

        ' Open remote powershell session
        Dim serverUri As New Uri("http://" & RemoteServer.ToUpper & ":5985/wsman")
        Dim connectionInfo As New WSManConnectionInfo(serverUri, SHELL_URI, PSCredObject(RemoteUser, RemotePassword))
        Dim myRunSpace As Runspace
        Try
            myRunSpace = RunspaceFactory.CreateRunspace(connectionInfo)
            myRunSpace.Open()
        Catch ex As Exception
            Throw New PasswordExtensionException(ex.Message)
            Return Nothing
            Exit Function
        End Try
        Return myRunSpace
    End Function

    Private Function OpenLocalRunspace() As Runspace
        Dim config As RunspaceConfiguration = RunspaceConfiguration.Create()
        Dim myRunSpace As Runspace
        Try
            myRunSpace = RunspaceFactory.CreateRunspace(config)
            myRunSpace.Open()
        Catch ex As Exception
            Throw New PasswordExtensionException(ex.Message)
            Return Nothing
            Exit Function
        End Try
        Return myRunSpace
    End Function

#End Region

    Public Function WriteToEventLog(ByVal Entry As String, ByVal eventType As EventLogEntryType)
        Dim appName As String = "BPOS Password Sync"
        Dim logName = "Application"

        Dim objEventLog As New EventLog()

        Try
            'Register the App as an Event Source
            'Note: this only works if the service account has rights to the reg key http://support.microsoft.com/kb/842795
            If Not EventLog.SourceExists(appName) Then
                EventLog.CreateEventSource(appName, logName)
            End If

            objEventLog.Source = appName
            objEventLog.WriteEntry(Entry, eventType)
            Return True
        Catch Ex As Exception
            Return False
        End Try
    End Function

End Class

One case involves “contract” records from an HR database – a person who had moved around the company may have several. The second is an LDAP data source for a univeristy where an inidvidual may have both staff and student profiles simultaneously, and as a student, may have multiple active “enrollments”.

In an ideal situation

There is a key best practise at stake here, which I believe becomes even more significant when you put the FIM Portal into the mix:

Each individual should only be represented once in the Metaverse.

In an ideal situation you will project each person only once from your source data. Changes to contract, enrollment etc would be treated simply as attribute updates to the core Metaverse object, which remains the same.

If your source data lists people multiple times, as in my examples above, you might do some automated manipulation prior to presenting the data to the Sync Service – selecting the best representation of each person and merging data where appropriate. Then you can have a nice one-to-one relationship between your projectoin source and your Metaverse.

But what if you need access to those individual contracts?

This was my problem. In the case of the HR database contract records, the local IT only had access to the contract number. For them the important information related to the person’s job at that site. But for us, centrally, looking to automate moves and changes across the organisation, we needed a way to link those seperate contract numbers to one individual.

At first, and against my better judgement, we started off projecting the contracts into the Metaverse as seperate people. I was assured that, when people moved jobs, all their old accounts were deleted including their mailbox. Pretty quickly this turned out to be not the case at all, and I started with the messy gymnastics needed to reconnect existing accounts to the newer better contract in the Metaverse, without actually deleting anything.

Step One in solving data source MPD: Split the data into “Persons” and “Contracts”

When it became clear that a redesign was necessary, I started by splitting the data into “persons” and “contracts”. In fact for the university this was already the case, but with the HR database I had to use some SQL queries in an SSIS package to split the data into “objectType=person” and “objectType=contract” rows. Clearly a unique identifier is needed for both persons and contracts.

My persons have the following basic information:

• objectType (=person)
• personID
• Data that should be independant of the contracts, like name, gender, date of birth.

My contracts must include the personID so I can join them correctly:

• objectType (=contract)
• contractID
• personID
• Data that is specific to the contract, like department, job title, start and end dates.

Create Seperate MAs for Persons and Contracts

Once the data was seperated I created different MAs for persons and contracts. The aim is to project the person only once into the metaverse, and then join the changeable contract records from the second MA.

But what about the Import Flows?

The big problem here is that you want to flow data into the metaverse from the Contracts MA. If multiple contracts are joined you’ll get the ambiguous-import-flow-from-multiple-connectors error. Besides which you probably don’t want to be importing from multiple contracts anyway. In my case (both cases in fact) I had to try and choose the “best” contract and then just flow the data from that one. As the “best” could change I have to re-evaluate the selection each time.

Why not just join one contract at a time?

The cleanest setup would be to only have one contract joined to the Metaverse object. The IAF rules are then very simple.

But, unless you can block all except one contract per person using Connector Filters, you may find this tricky to achieve.

Partly the problem is the way the Sync Service does its sync’ing – that is, it works on one connector space object at a time. Additionally, the only other connector space objects accessible during this sync operation are those that can be found by following joins.

So, while sync’ing this connector space object we can only know about other connector space objects where a direct join relationship exists.

This essentially means I can only figure out if the current CS object is really the best choice if all possible contracts are joined to the Metaverse person at the same time.

Blocking Import Flows

So here’s where I ended up.

1. I let the multiple contracts be joined to the Metaverse person, but I only allow import flows from one of the contracts.
2. I write the “preferred contract” number into an attribute on the person object.
3. When sync’ing a CS object I compare it to the current “preferred contract”. If this one is better I replace the contract number on the Metaverse object.
4. All the import flows (which must all be Advanced rules) check if this CS object is the preferred contract before allowing (or skipping) the flow.

While my IAF rules are now more complex, there have been definite advantages to this approach. The non-preferred contracts are still accessible from the Metaverse object and this has allowed us to more easily identify errors in the source data. Sometimes we have forced a particular contract to be preferred by disconnecting the currently preferred contract and syncing another one.

There is also the benefit of having some information as opposed to none. If I was, for example, blocking all expired contracts from entering the connector space in the first place I would be losing valuable deprovisioning information. If the best pick contract for a person is an expired one, I still want to see it.

Flow Blocking Method 1: The Double Sync

I have tried out two different ways of blocking IAFs. The first is simpler to implement but the downside is you have to Sync twice. Because the evaluation of the contract is done as part of the “import_contractID” rule, and this might happen at any point in the set of flow rules, to ensure all IAFs run for the new preferred contract you have to sync twice.

Case "import_contractID"
  If mventry("contractID").Value <> csentry("contractID").Value
      Whatever comparisons you need to do to see if this contract is preferable to the values
      already imported to the Metaverse object. If it's better, replace the contractID.
  End If

Case "import_otherAttribute"
  'Replicates a Direct IAF
  If mventry("contractID").IsPresent AndAlso mventry("contractID").Value = csentry("contractID").Value
    If csentry("otherAttribute").IsPresent Then
      mventry("otherAttribute").Value = csentry("otherAttribute").Value
    Else
      mventry("otherAttribute").Delete()
    End If
  End If

Flow Blocking Method 2: The First Touch

In an effort to avoid the double-sync I have started using another method where I run my comparison tests above the Case statement, and then set a Utils.TransactionProperties to show the test has run.

Utils.TransactionProperties is the way to pass values between different bits of code run as part of the same object’s Sync operation.

While I now only need to sync once, I still don’t know which IAF rule will get called first, so I have to pass all comparison CS attributes to each IAF rule.

Here’s what the MapAttributesForImport Sub looks like now:

Public Sub MapAttributesForImport(ByVal FlowRuleName As String, ByVal csentry As CSEntry, ByVal mventry As MVEntry) Implements IMASynchronization.MapAttributesForImport

  '' Evaluate this CS object to see if it is a better source for attribute flows to the joined Metaverse object.
  '' Using the Utils.TransactionProperties flag will ensure this test is made only at the start of sync'ing the CS object.

  If Not Utils.TransactionProperties.Contains("FlowEnabled") Or Not mventry("contractID").IsPresent Then

    Dim BestMatch As Boolean = False
    If mventry("contractID").IsPresent Then
      If mventry("contractID").Value = csentry("contractID").Value Then
        BestMatch = True
      Else
          Comparison tests - set BestMatch=True if this is a better match.
      End If

      If BestMatch Then
        Utils.TransactionProperties("FlowEnabled") = csentry("contractID").Value
          ''Note: I set this to the contractID to avoid unexpected behaviour following a disconnection.
      Else
        Utils.TransactionProperties("FlowEnabled") = "false"
      End If

    End If

    '' Do not continue with flow rules if this CS object has a different id to the best match.
    If Not Utils.TransactionProperties("FlowEnabled").Equals(csentry("contractID").Value) Then
      Exit Sub
    End If

    Select Case FlowRuleName

      Case "Import_contractID"
        mventry("contractID").Value = csentry("contractID").Value

      Case "Import_otherAttribute"
        If csentry("otherAttribute").IsPresent Then
          mventry("otherAttribute").Value = csentry("otherAttribute").Value
        Else
          mventry("otherAttribute").Delete()
        End If

      ....

  End Select
End Sub

Importing a reference

There is one final advantage I can extract out of seperating my data into persons and contracts – I can, if I need to, also import “contract” objects into the Metaverse and, with the addition of a multivalue table (for database MAs) I can construct a reference attribute that directly links the person to their contract ojects. This would be very useful if I wanted a person’s contracts to be accessible in the FIM Portal.