Windows PowerShell Examples for Configuring FIM
Applies To: Forefront Identity Manager 2010, Forefront Identity Manager Certificate Management
The Microsoft® Forefront® Identity Manager (FIM) 2010 environment has within it a powerful tool for configuration management. This tool set is implemented through a Windows PowerShell™ module.
Windows PowerShell is a task-based, command-line shell and scripting language that is designed especially for system administration. This conceptual overview topic for the information technology (IT) professional introduces the primary concepts that an administrator should be familiar with to use the FIM 2010 R2 Windows PowerShell cmdlets for managing the FIM 2010 R2 Service configuration.
For an overview of FIM 2010 documentation and guidance for using it, see the Documentation Roadmap.
Understanding the Windows PowerShell Configuration Management Workflow
The Windows PowerShell cmdlet set is for managing configuration environments, specifically for moving tested configurations from a test (source) environment to a production (target) environment. A simple version of the workflow would include the following steps:
Export the FIM 2010 R2 configuration from the source environment.
Export the FIM 2010 R2 configuration from the target environment.
Join the results of the source and target exports.
Compare the results of the join operation.
Apply the resulting difference set to the target environment, making the target match the source.
Note
This simplified procedure assumes that there are both working source and target configuration environments to compare.
Using the Export-FIMConfig Cmdlet
Each ExportObject is an open and public property bag–like representation of a resource.
You can export these representations into XML by using the ConvertFrom-FIMResource cmdlet. You can then use them in Windows PowerShell scripts or Microsoft .NET Framework code. After you get ExportObject instances from both pilot and production environments, you must join the instances together by using the Join-FIMConfig cmdlet. The following are the predefined groupings of configurations to export at once.
Policy Configuration is defined as the following resource types:
ManagementPolicyRule
Set
WorkflowDefinition
EmailTemplate
FilterScope
ActivityInformationConfiguration
Function
SynchronizationRule
SynchronizationFilter
Schema Configuration is defined as the following resource types:
AttributeTypeDescription
BindingDescription
ObjectTypeDescription
ConstantSpecifier
SchemaSupportedLocales
Portal Configuration is defined as the following resource types:
Homepage Configuration
PortalUI Configuration
NavigationBarConfiguration
SearchScopeConfiguration
Configuration
ObjectVisualizationConfiguration
Custom Configuration is defined by the provided XPath filter, for example, /ContosoContact or /Person[DisplayName=’Administrator’]. The cmdlet follows references that are included in the custom configuration resources.
Common errors include the following:
Reference not found. If a FIM 2010 R2 resource contains a globally unique identifier (GUID) that does not refer to another FIM 2010 R2 resource, the cmdlet issues a warning. Inspect the specific GUID to ensure that it is not being used as a reference. For example, some Workflow instance parameters in Extensible Object Markup Language (XOML) and some Filters for GateTypeId include GUIDs that are not references. If you determine that the GUID is not a reference, you can ignore the warning.
Permission denied. If a FIM 2010 R2 resource does not exist or if the cmdlet does not have permission to access the resource, the cmdlet may receive a Permission denied error.
Message size exceeded. If a FIM 2010 R2 resource is too large to fit within a single Simple Object Access Protocol (SOAP) message, it may be necessary to increase the message size. This regularly happens when you export Set resources with thousands of explicit members. Often, administrators pick an arbitrarily large message size such as 999,999.
These resources include the following resource types:
ManagementPolicyRule
Set
WorkflowDefinition
EmailTemplate
FilterScope
ActivityInformationConfiguration
Function
SynchronizationRule
SynchronizationFilter
Resource types from the –schemaConfig parameter description.
AttributeTypeDescription
BindingDescription
ObjectTypeDescription
ConstantSpecifier
SchemaSupportedLocales
Resource types form the –portalConfig parameter description.
Homepage Configuration
PortalUI Configuration
NavigationBarConfiguration
SearchScopeConfiguration
Configuration
ObjectVisualizationConfiguration
Using the Import-FIMConfig cmdlet
The Import-FIMConfig cmdlet returns ImportObject instances that were not fully processed. Users should save the 'undone' ImportObject instances to a file by using ConvertFrom-FIMResource and edit the instances so that the changes succeed.
An ImportObject has a state and a list of attribute-level changes. Each ImportObject represents one Web service call. The state of the ImportObject determines the specific Web service call to make. The following are the states:
0 = Create
A Create operation creates new objects of the type ObjectType with initial attribute-level values in Changes. After creating the object, the Import-FIMConfig cmdlet replaces all instances of SourceObjectIdentifier inside attribute values with the ObjectID of the new object.
1 = Put
A Put operation updates the object TargetObjectIdentifier with the attribute-level Changes.
2 = Delete
A Delete operation deletes the object TargetObjectIdentifier. No changes are necessary.
3 = Resolve
A Resolve operation resolves an object in the FIM 2010 R2 Service by using the information in AnchorPairs as search criteria. Once resolved, the Import-FIMConfig cmdlet replaces all the instances of SourceObjectIdentifier inside the attribute values with the resolved ObjectID. The general form of the query is /ObjectType[AttributeName1=AttributeValue1 and AttributeName2=AttributeValue2 and ...].
4 = None
A None operation is ignored.
When updating existing objects, you must define the specific attribute-level changes. Each change is an ImportChange that represents a specific attribute value change. An ImportChange includes an Operation, which informs the Web service about the type of change to make on the specific attribute. You can identify which attribute to change in the AttributeName property.
The following are the operations:
0 = Add
1 = Replace
2 = Delete
3 = None
The Add operation indicates that the AttributeValue should be added to the multivalued attribute. The Replace operation indicates that the AttributeValue should replace the single-valued attribute. The Delete operation indicates that the AttributeValue should be removed from the multivalued attribute. The None operation indicates that the AttributeValue is included in a Create. The FullyResolved flag indicates whether the Import-FIMConfig cmdlet should search the AttributeValue for instances of SourceObjectIdentifier GUIDs. If true, the cmdlet assumes that all references are correct and submits the AttributeValue verbatim. If false, the cmdlet assumes that there exists at least one reference to either a Create or Resolve state. The cmdlet replaces all GUIDs with values retrieved from previous Create or Resolve states. If a GUID is found but cannot be matched, then the cmdlet aborts, executing this ImportObject as not all references are correct. Last, it is possible to specify the locale of the AttributeValue. The vast majority of attribute-level changes are in the Invariant locale or culture. However, some string updates can be performed in cultures like es-ES or fr-FR.
For more information about globalization in .NET Framework codes, see the Microsoft TechNet® topic CultureInfo Class (https://go.microsoft.com/fwlink/?LinkId=184343).
See Also
Reference
Microsoft.ResourceManagement.Automation