Appendix C: Troubleshooting FIM Configuration Migration

Article
07/11/2012

Applies To: Forefront Identity Manager 2010

This appendix includes descriptions for common troubleshooting issues for Microsoft® Forefront® Identity Manager (FIM) 2010.

Source and Target builds must be identical to perform a Configuration Migration

In order to migrate from one environment to another, the builds for both the source and the target servers must be identical.

See Get-Help for additional information on each cmdlet

The Windows PowerShell cmdlets include Get-Help information that includes specific details, such as which object types are exported by the Export-FIMConfig cmdlet.

Changing display names can lead to unintended consequences

For many object types, such as Management Policy Rules (MPR), the syncproduction.ps1 script uses the display name as the only anchor attribute between two systems. Consequently, a change to an existing MPR’s display name will result in a delete of the existing MPR, followed by the creation of a new MPR. This result occurs because the migration process cannot successfully join MPRs whose join criteria have changed. To work around this issue, you can bind a custom attribute to all configuration object types and use that attribute as the join criteria. The net result of this process, however, will be a production system with the correct policy.

Use undone imports to resume committing changes

If errors occur when you run the CommitChanges.ps1, use the changes that are captured in the undone.xml file to resuming committing changes. In extremely limited situations, it may be necessary to edit the first object in undone.xml to resolve the error. For an example, see the ResumeUndoneImports.ps1.

Changing intermediate files can lead to unintended consequences

While the file format and application programming interface (API) of the low-level objects are public and supported by developers to manipulate, we do not recommend that you change the contents of the intermediate formats during migration. However, it may be necessary to remove entire ImportObjects from changes.xml or to do find/replace-type operations on pilot.xml to replace version numbers or pilot Domain Name System (DNS) information for production DNS information.

Migration across version numbers requires replacement of the version number in pilot.xml

While migration across version numbers is not recommended or supported, you can often do this by replacing the pilot version number with the production version number in pilot.xml. Specifically, WorkflowDefinition and ActivityInformationConfiguration objects require the version number to refer precisely to workflow activities in the production environment. Failing to replace the version number will result in the Compare-FIMConfig cmdlet identifying differences between the XOML attributes on WorkflowDefinitions and migrating the pilot’s version number. The production FIM 2010 R2 Service may fail to start workflow activities with the incorrect version number.

Migrate policy objects only

If you want to migrate policy objects only, such as updated MPRs, Sets, and Workflow Definitions, you must edit ExportPilot.ps1 and SyncProduction.ps1 to include only the –policyConfig option when you use the Export - FIMConfig cmdlet.

Localized information not migrated by default

By default, the Windows PowerShell scripts that are included in this guide do not migrate localized information. To include localized display names, edit the ExportPolicy.ps1 and the SyncPolicy.ps1 so that the Export-FIMConfig cmdlet includes the –AllLocales option. This option instructs the cmdlet to download all localized information. However, its presence slows down the scripts.

Breaking cyclic references

If the Compare-FIMConfig cmdlet results in an error because of a cyclic reference, it is necessary to break the cycle manually. Because the Compare-FIMConfig cmdlet outputs a list of changes in precedence order, it requires that no cycles exist among the references of configuration objects. Cycles sometimes occur when Set A refers to Set B and Set B also refers to Set A. In general, cycles are not a best practice in FIM configuration. To fix this issue, it is necessary to change the definition of Set A or Set B so that they both do not refer to each other; then, restart the migration process.