Appendix B: Annotated Configuration Migration Windows PowerShell Scripts

Applies To: Forefront Identity Manager 2010

The included scripts contain standard Windows PowerShell commands, along with commands that are specific to the FIM Configuration Migration Tool.

Exporting configurations

The following Windows PowerShell command exports the specified resource configurations from the FIM Service.

$pilot = Export-FIMConfig -uri https://localhost:5725/ResourceManagementService -policyConfig -schemaConfig -portalConfig

Although this example shows all three parameters being used in one command, it is possible that each type of configuration can be exported separately, as indicated in the following table.

Parameter	Configurations exported
-policyConfig	ManagementPolicyRule Set WorkflowDefinition EmailTemplate FilterScope ActivityInformationConfiguration Function SynchronizationRule SynchronizationFilter SystemResourceRetentionConfiguration
-schemaConfig	AttributeTypeDescription ObjectTypeDescription BindingDescription
-portalConfig	SearchScopeConfiguration HomepageConfiguration ObjectVisualizationConfiguration NavigationBarConfiguration PortalUIConfiguration ConstantSpecifier

The following optional parameters also exist:

1. You can add the –AllLocales optional parameter to export localized information.

2. You can include the –CustomConfig optional parameter to specify custom objects by specifying an XPath filter that includes the Object Type to include.

For example, to export both Schema and a custom object type, ContosoContact, you can use the following Windows PowerShell command.

$pilot = Export-FIMConfig -uri https://localhost:5725/ResourceManagementService -schemaConfig -customConfig “/ContosoContact”

The following Windows PowerShell command saves the results to a specified file.

$pilot | ConvertFrom-FIMResource -file $pilot_filename

Joining configurations

The following Windows PowerShell script excerpt defines the anchor attributes that are used to match the configuration objects between the pilot environment and the production environment.

$joinrules = @{
    # === Customer-dependent join rules ===
    # Person and Group objects are not configuration will not be migrated.
    # However, some configuration objects like Sets may refer to these objects.
    # For this reason, we need to know how to join Person objects between
    # systems so that configuration objects have the same semantic meaning.
    Person = "MailNickname DisplayName";
    Group = "AccountName DisplayName";
    
    # === Policy configuration ===
    # Sets, MPRs, and Workflow Definitions are best identified by DisplayName
    # DisplayName is set as the default join criteria and applied to all object
    # types not listed here.
    
    # === Schema configuration ===
    # This is based on the system names of attributes and objects
    # Notice that BindingDescription is joined using its reference attributes.
    ObjectTypeDescription = "Name";
    AttributeTypeDescription = "Name";
    BindingDescription = "BoundObjectType BoundAttributeType";
    
    # === Portal configuration ===
    ConstantSpecifier = "BoundObjectType BoundAttributeType ConstantValueKey";
    SearchScopeConfiguration = "DisplayName SearchScopeResultObjectType Order";
    ObjectVisualizationConfiguration = "DisplayName AppliesToCreate AppliesToEdit AppliesToView"
}

The following Windows PowerShell command matches, or joins, the resources from the pilot environment to the resources from the production environment, based on the specified anchor attributes. The –defaultJoin parameter is required when not all resource types have explicit join criteria.

$matches = Join-FIMConfig -source $pilot -target $production -join $joinrules -defaultJoin DisplayName

Warning

During the join procedure, the pilot, or source, environment is fully authoritative over the production, or target, environment. You should always manually examine the differences in both environments before you commit the import operation.

The following Windows PowerShell commands compare the results of the join process and then save the comparisons to a file so that you can review it before you commit the changes.

$changes = $matches | Compare-FIMConfig

$changes | ConvertFrom-FIMResource -file $changes_filename

Importing configurations

The following Windows PowerShell command performs the actual import of the join results into the production environment. Any errors during the import are written to $undoneImports.

$undoneImports = $imports | Import-FIMConfig -uri https://localhost:5725/ResourceManagementService

The information that is stored in $undoneImports is subsequently written to a specified file:

$undoneImports | ConvertFrom-FIMResource -file $undone_filename

See Also

Concepts

Configuration Migration Deployment Guide
Migration Scenarios
Configuration Migration Deployment Steps
Appendix A: Configuration Migration Windows PowerShell Scripts
CommitChanges.ps1
ResumeUndoneImports.ps1
SyncPolicy.ps1
SyncSchema.ps1
ExportSchema.ps1
ExportPolicy.ps1
Appendix C: Troubleshooting FIM Configuration Migration