FIM PowerShell Synchronization Extensions

The extension looks for scripts in the .\MaData\<MA>\PowerShell directory of the current MA for the API call being made. It then loads the script and passes the named parameters to the script. If the API function being called returns a value or expects output there is an implicit contract that the script should satisfy in order to run error free.

Installation

Copy the FIM.PowerShell.dll to the Extensions directory of the FIM Synchronization Service folder.

FIM.PowerShell.ps1

This script is located in the .\Extensions directory and is loaded into each runspace as it is initialized. This allows for the definition of shared code that all the extension scripts can make use of.

One particular interesting usage is keeping any settings or constants defined in this script so the MA scripts can be easily migrated between FIM server environments.

Example:
#Requires -Version 3.0

function Add-PSTypeAccelerator {
	[CmdletBinding()]
	param(
		[Parameter(Mandatory = $true, ValueFromPipeline = $true)]
		[ValidateNotNull()]
		[Type] $Type,

		[Parameter(ValueFromPipelineByPropertyName = $true)]
		[ValidateNotNullOrEmpty()]
		[Alias('Alias')]
		[string] $Name = $Type.Name
	)

	begin {
		$PSTypeAccelerators = [Type]::GetType("System.Management.Automation.TypeAccelerators, $([PSObject].Assembly.FullName)")
	}

	process {
		if ($PSTypeAccelerators::Add) {
			if ($PSTypeAccelerators::Get.ContainsKey($Name)) {
				$PSTypeAccelerators::Remove($Name) | Out-Null
			}

			$PSTypeAccelerators::Add($Name, $Type)
		} elseif ($PSTypeAccelerators::AddReplace) {
			$PSTypeAccelerators::AddReplace($Name, $Type)
		}
	}
}

Add-Type -Path "${ENV:PROGRAMFILES}\Microsoft Forefront Identity Manager\2010\Synchronization Service\Bin\Assemblies\Microsoft.MetadirectoryServicesEx.dll"

# Import all public types from Microsoft.MetadirectoryServices (exclude interfaces)
[Microsoft.MetadirectoryServices.MVEntry].Assembly.GetTypes() |? { $_.Namespace -eq 'Microsoft.MetadirectoryServices' -and $_.Name -notlike 'I*' } | Add-PSTypeAccelerator

# Helper types
Add-PSTypeAccelerator -Name SecureString -Type ([System.Security.SecureString])

PowerShell Script Signatures

Refere to the MSDN document for the IMVSynchronization and IMASynchronization interfaces for a complete understand of how to implement the scripts based on the expected implementation of the interfaces. These go in the MADATA folder for each MA that uses the extension.

Provision.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Evaluates connected objects in response to a change to a metaverse object.

	.PARAMETER mventry
	Contains an MVEntry object that represents the metaverse object that has changed.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imvsynchronization.provision(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[mventry] $mventry
)
ShouldDeleteFromMV.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Called when a connector space entry is disconnected during an import operation. This method determines whether the metaverse entry that is connected to the disconnecting connector space entry should be deleted.

	.PARAMETER csentry
	Contains a CSEntry object that represents the connector space entry that has been disconnected.

	.PARAMETER mventry
	Contains an MVEntry object that represents the metaverse entry that will be deleted if this method returns true.

	.OUTPUTS
	Returns true if the connected metaverse entry should be deleted, or false if it should not be deleted.

	.NOTES
	A connector space entry will be disconnected during an import operation when the connector space entry is deleted from the connected directory. The disconnection can also occur when Forefront Identity Manager Synchronization Service (FIM Synchronization Service) determines that the connector space entry should be a disconnector, which means the object should not be connected.

	The ConnectionState property is not available in this method. Accessing this property in this method results in an exception.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imvsynchronization.shoulddeletefrommv(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[csentry] $csentry,
	
	[Parameter(Mandatory)]
	[ValidateNotNull()] 
	[mventry] $mventry
)

begin {
	$ShouldDeleteFromMV = $false
}

process {
}

end {
	$ShouldDeleteFromMV
}
Deprovision.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Called when a metaverse entry is deleted and the connector space entries that are connected to the metaverse entry become disconnector objects.

	.PARAMETER csentry
	Contains a CSEntry object that represents the connector space entry that was connected to the deleted metaverse entry.

	.OUTPUTS
	Returns one of the DeprovisionAction values that determines which action should be taken on the connector space entry.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imasynchronization.deprovision(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[csentry] $csentry
)

begin {
	$Action = [DeprovisionAction]::Disconnect
}

process {
}

end {
	$Action
}
FilterForDisconnection.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Determines whether a connector CSEntry object will be disconnected. A connector space or CSEntry object is disconnected when a delta export matches a filter, or if the filter rules are changed and the new filter criteria for disconnecting an object are met.

	.PARAMETER csentry
	Contains the CSEntry object to which this method applies.

	.OUTPUTS
	Returns true if the object will be disconnected, or false if the object will not be disconnected.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imasynchronization.filterfordisconnection(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[csentry] $csentry
)

begin {
	$FilterForDisconnection = $false
}

process {
}

end {
	$FilterForDisconnection
}
MapAttributesForExport.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Called to map attributes from a metaverse entry to a connector space entry.

	.PARAMETER FlowRuleName
	Contains the name of the flow rule. You must use only alphanumeric characters for the FlowRuleName parameter; otherwise, you can encounter problems in a rules extension.

	.PARAMETER mventry
	Contains a CSEntry object that represents the source metaverse entry.

	.PARMAETER csentry
	Contains a CSEntry object that represents the destination connector space entry.

	.NOTES
	Flow rules are not executed in the order shown in Synchronization Service Manager. Forefront Identity Manager Synchronization Service (FIM Synchronization Service) uses these rules according to the state of the metaverse object. Configure your rules based on the state of the object instead of the rules that are called in a predetermined order.

	This method is called when:
		- The export flow rules do not overlap with the import flow rules, or
		- If the source attribute has a precedence greater than or equal to the precedence of the overlapping import flow rule. You set management agent precedence in Metaverse Designer.

	For more information about setting management agent precedence, see the Forefront Identity Manager Synchronization Service 2010 Help on Microsoft TechNet.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imasynchronization.mapattributesforexport(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNullOrEmpty()]
	[string] $FlowRuleName, 

	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[mventry] $mventry,
	
	[Parameter(Mandatory)]
	[ValidateNotNull()] 
	[csentry] $csentry
)
MapAttributesForImport.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Called to map attributes from a connector space entry to a metaverse entry.

	.PARAMETER FlowRuleName
	Contains the name of the flow rule. You must use only alphanumeric characters for the FlowRuleName parameter; otherwise, you can encounter problems in a rules extension.

	.PARAMETER csentry
	Contains a CSEntry object that represents the source connector space entry.

	.PARAMETER mventry
	Contains a CSEntry object that represents the destination metaverse entry.

	.NOTES
	Flow rules are not executed in the order that is shown in Synchronization Service Manager. Forefront Identity Manager Synchronization Service (FIM Synchronization Service) uses these rules according to the state of the connector space object. Configure your rules based on the state of the object instead of the rules being called in a predetermined order.

	For multiple import flow rules, the management agent that has precedence provides the attribute value. You set management agent precedence in the Metaverse Designer. For more information about setting management agent precedence, see the Forefront Identity Manager Synchronization Service 2010 Help on Microsoft TechNet.

	Attribute flow mapping is called only if a source attribute exists. When the last source attribute of an import attribute flow mapping is deleted, the attribute flow rules are not called, and the target attribute is automatically deleted.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imasynchronization.mapattributesforimport(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNullOrEmpty()]
	[string] $FlowRuleName, 
	
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[csentry] $csentry, 
	
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[mventry] $mventry
)

MapAttributesForJoin.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Generates a list of values based on the CSEntry attribute values that will be used to search the metaverse.

	.PARAMETER FlowRuleName
	Contains the name of the flow rule. You must use only alphanumeric characters for the FlowRuleName parameter; otherwise you can encounter problems in a rules extension.

	.PARAMETER csentry
	Contains a CSEntry object that represents the connector space entry.

	.PARAMETER values
	Contains a ValueCollection object that receives the list of attribute values that are generated by this method to be used to search the metaverse.

	.NOTES
	Flow rules are not executed in the order shown in Synchronization Service Manager. Forefront Identity Manager Synchronization Service (FIM Synchronization Service) uses these rules according to the state of the connector space object. Configure your rules based on the state of the object rather than the rules being called in a predetermined order.

	Use this method to convert attribute values to a format used in the metaverse. For example, the metaverse stores the full name attribute as a single string made up of the first name and last name, while the connected data source stores a first name and a last name as separate attributes. You can use this method to combine a first name and last name into a single string that can be used to search the full name attribute in the metaverse.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imasynchronization.mapattributesforjoin(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNullOrEmpty()]
	[string] $FlowRuleName, 
	
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[csentry] $csentry, 

	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[ValueCollection] $values
)
ResolveJoinSearch.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Called when a join rule is configured to use a rules extension to resolve conflicts, and when one or more results from a metaverse search match the values that are generated by the MapAttributesForJoin method.

	.PARAMETER JoinCriteriaName
	Contains a string that contains the name of the join criteria. You must use only alphanumeric characters for the joinCriteriaName parameter, otherwise you can encounter problems in a rules extension.

	.PARAMETER csentry
	Contains the CSEntry object that represents the connector space entry that will be joined to the metaverse entry.

	.PARAMETER rgmventry
	Contains an array of CSEntry objects that represent the metaverse entries that match the join operation criteria. On return, the imventry parameter receives the index of the object in this array to which the connector space entry will be joined.

	.PARAMETER MVObjectType
	Contains a string that contains the name of the metaverse class.

	.OUTPUTS
	The index of the object in the rgmventry parameter to which the connector space entry will be joined.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imasynchronization.resolvejoinsearch(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNullOrEmpty()]
	[string] $JoinCriteriaName, 
	
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[csentry] $csentry, 
	
	[Parameter(Mandatory)]
	[ValidateNotNullOrEmpty()]
	[mventry[]] $rgmventry,

	[Parameter(Mandatory)]
	[ValidateNotNullOrEmpty()]
	[string] $MVObjectType
)

begin {
	$imventry = -1
}

process {
}

end {
	$imventry
}
ShouldProjectToMV.ps1
#Requires -Version 3.0

<#
	.SYNOPSIS
	Called to determine whether a new connector space object should be projected to a new metaverse object when the connector space object does not join to an existing metaverse object.

	.PARAMETER csentry
	Contains a CSEntry object that represents the new connector space entry.

	.OUTPUTS
	A String object that, on output, receives the name of the metaverse class to which the connector space entry should be projected.

	.LINK
	http://msdn.microsoft.com/en-us/library/microsoft.metadirectoryservices.imasynchronization.shouldprojecttomv(v=vs.100).aspx
#>
[CmdletBinding()]
param(
	[Parameter(Mandatory)]
	[ValidateNotNull()]
	[csentry] $csentry
)

Last edited May 2, 2014 at 12:26 AM by adweigert, version 8

Comments

No comments yet.