Configuring Management Agents

Management agents control the data flow between a connected data source and the metadirectory. You use management agents to create, configure, and run management agents, as well as to configure run profiles, import and export management agents, refresh the connected data source schema, search the connector space, or create a Microsoft® Forefront Identity Manager (FIM) 2010 R2 project.

Creating and editing management agents with Management Agent Designer

Management Agent Designer provides an easy-to-follow, step-by-step process for configuring management agents. When you create a new management agent, Management Agent Designer guides you through a series of tasks that are necessary for the type of management agent that you are creating. When you configure an existing management agent, you can change the configuration or properties for a task by clicking the appropriate page in Management Agent Designer. Only those pages that are necessary for the management agent type that you are configuring are displayed. For more information, see Configure Management Agents with Management Agent Designer. For more information about specific management agent requirements, see Using Management Agents.

Deleting a management agent and its connector space objects

There might be situations in which you import inaccurate data to the connector space or connector space data becomes corrupted. It might be necessary and more efficient, in these cases, to delete the connector space objects and import clean data again. With the Management Agents tool, you can delete a management agent and its connector space objects or delete the connector space objects only. When you delete the connector space objects only, the management agent configuration, including its run history, remains.

CautionCaution
When either of the Delete management agent options are selected, provisioning rules are disabled automatically for the operation. However, all other rules remain in effect and can be applied as a result of objects being deleted from the connector space. This can result in objects being deleted from the metaverse or having attributes recalled. Review your existing rules carefully before deleting a management agent or deleting objects from a connector space. For more information, see Understanding Management Agent Rules and Understanding Metaverse Rules.

Creating run profiles

A run profile specifies the parameters with which a management agent is run. You can create one or multiple run profiles for a management agent. Further, each profile consists of one or more steps. By combining steps in a profile, you can more accurately control how your data is processed. The steps available for a run profile are:

Delta Import (Stage Only)

Imports only those objects and attributes from the connected data source whose values have changed since the last time the management agent was run and then stops the run. Any pending changes must be processed by another run profile step, such as Delta Synchronization or Full Synchronization.

Full Import (Stage only)

Imports all objects and attributes from the connected data source to the connector space and then stops the run. Any pending changes must be processed by another run profile step, such as Delta Synchronization or Full Synchronization.

Delta Import and Delta Synchronization

Imports only those objects and attributes from the connected data source whose values have changed since the last time the management agent was run. Management agent rules are then reapplied only to objects that have pending changes from the delta import, that have errors, or where a change to the target of a reference attribute is detected. For more information about reference attributes, see The Metaverse and the Connector Space. If you know that only a small number of objects have changed, a delta import and delta synchronization can be more efficient.

noteNote
Only the objects specified above are evaluated. All other disconnectors are not evaluated.

Full Import and Delta Synchronization

Imports all objects and attributes from the connected data source, and then management agent rules are reapplied to all objects that have pending changes.

Full Import and Full Synchronization

Imports all objects and attributes from the connected data source, and then the management agent rules are reapplied to all normal disconnector objects in the connector space to determine if they should be joined to objects in the metaverse. By running this step, you also reapply attribute flow rules. Note: if newly provisioned objects are in the connector space, or in other connector spaces that have links to affected metaverse objects, they are deleted. This is to allow the provisioning rules to run again with the most current configuration.

Delta Synchronization

Applies the management agent rules to objects in the connector space that have pending changes. All disconnectors are also reevaluated. No import from or export to any connected data sources is processed.

noteNote
This step differs from the Delta Synchronization portion of the preceding Delta Import and Delta Synchronization combined step because the Delta Synchronization step evaluates all disconnectors.

Full Synchronization

Applies the management agent rules to all the objects in the connector space and runs a full synchronization from the connector space to the metaverse and out to any other affected connector spaces. No import from or export to any connected data sources is processed. If there are newly provisioned objects in the connector space, or in other connector spaces that have links to affected metaverse objects, they are deleted. This allows the provisioning rules to run again with the most current configuration.

Export

Runs a delta export of all objects and attributes from the metaverse to the target connected data sources.

You can also specify a deletion threshold for each run step (except FullSynchronization and Delta Synchronization). The deletion threshold setting is used to prevent accidental deletions during import and export and will stop the management agent, or prevent it from starting, when the threshold limit is reached. An event log message will be generated whenever the deletion threshold is reached. For an Export run step, the deletion threshold will monitor the number of pending export deletions. When the management agent starts, the number of pending export deletions is checked. If this count meets or exceeds the deletion threshold, the management agent is stopped and an event log entry is generated.

For more information, see Create a Management Agent Run Profile.

You can automatically create a Visual Basic or C# script that runs the run profile from a command line or from another script. This can be helpful when you are batch-processing several run profiles and automating runs by using Windows Task Scheduler. For more information about creating scripts for run profiles, see the FIM Developer Reference and Create a Script for a Management Agent Run Profile.

Creating log files

With the exception of the Delta Synchronization and Full Synchronization steps, each of these steps for a run profile has the option to create a log file when the management agent is run. Log files are created in an XML format, and they can be helpful for verifying that data has been staged to the connector space correctly before it is synchronized with the metaverse. For more information, see Create a Management Agent Run Profile.

Exporting, importing, or updating a management agent

In some cases, you might need several management agents that are similar to each other. For example, you might need to import data from several similar, connected data sources. By exporting the management agent to a file, you can then import it, modify it, and save it with a new name, thereby eliminating the need to create a new one from scratch. Use Update Management Agent to move a management agent that has been exported from your test system to your production system. Export files are saved in an XML format. For more information about exporting management agents, see Export a Management Agent to File.

Refresh the management agent schema

FIM creates a schema for each management agent when that management agent is created. When the structure of the connected data source changes, such as when object types or attributes for an object type are added or removed, the management agent schema is not automatically updated. To keep the management agent schema synchronized with the connected data source structure, you must manually update the schema by using Refresh Schema.

The following table describes how Refresh Schema works for the different management agents.

 

Management agent for Action

Active Directory

Active Directory Lightweight Directory Services (ADLDS)

Active Directory global address list (GAL)

IBM DB2 Universal Database

Microsoft SQL Server

Novell eDirectory

Oracle Database

Sun and Netscape directory servers

The connected data source schema is rediscovered, the current management agent schema is updated, and then Management Agent Designer starts. In Management Agent Designer, you can correct any inconsistencies that are introduced by the updated schema, such as deleted object types or deleted attributes.

Delimited text files

Directory Services Markup Language (DSML)

Fixed-width text files

LDAP Data Interchange Format (LDIF)

Management Agent Designer starts, reads the template input file, and then updates the management agent schema. Then, you can update the management agent configuration based on the new schema.

FIM Certificate Manager

Lotus Notes

Refresh schema is not available for these management agents. Both of these connected data sources use a static schema that cannot be changed.

Attribute-value pair text files

Refresh schema is not available for this management agent because you can configure the structure of the data in Management Agent Designer.

CautionCaution
Do not change or modify the anchor attribute when you refresh a management agent schema. FIM treats all changes to anchor attributes as new objects, which can result in object deletions in the connector space and, through provisioning, can result in object deletions in other connector spaces.

For more information about management agent schemas, see Connected Data Sources and Management Agents and Refresh a Management Agent Schema.

Searching the connector space

Use Search Connector Space to locate objects in the connector space and view their properties. Searching the connector space can be helpful when looking for errors after a join or projection. Searches can be run based on error status, pending updates, or actions taken since a specified date. Objects that are returned from the search are displayed in a table, which lists the error and attribute values that you select.

Search Connector Space provides the following features:

  • Properties of a connector space object

  • Preview

  • Validation of an object against the schema

Properties of a connector space object

The properties dialog box for a connector space object can contain the following information about the connector space object:

  • Properties

     

    Column Description

    Change

    The pending change on an attribute. For the Properties tab, the value of this field is always None.

    Attribute name

    The attribute name as defined in the connector space schema

    Type

    The attribute type as defined in Management Agent Designer

    Value

    Current value of the attribute

  • Import, Export awaiting confirmation, Export in Progress, Pending Export

    • Import—Indicates that there are pending import changes staged to the connector space that have not yet been applied to the metaverse.

    • Export awaiting confirmation—Indicates that there are export changes that have been sent to the connected data source but have not yet been confirmed by a reimport operation. This is for call-based management agents only.

    • Export in Progress—Indicates that there are export changes that have been sent but have not yet been reimported.

    • Pending Export—Indicates that there are pending export changes staged to the connector space that have not yet been applied to the connected data source.

       

      Column Description

      Change

      The pending change on the attribute. Possible values for this field are:

      • Add

      • Delete

      • Replace

      • Update

      Attribute name

      The attribute name as defined in the connector space schema

      Type

      The attribute type as defined in Management Agent Designer

      Old Value

      The current value of the attribute before the change has been processed

      New Value

      The new value of the attribute after the change has been processed

  • Synchronization Error, Export Error

     

    Item Description

    Running management agent

    The management agent that was running at the time of the error

    Error

    The error returned by the synchronization engine

    Latest occurrences

    The last time that the error occurred

    Initial occurrences

    The first time that the error occurred

    Retry count

    The number of times this operation has been retried

  • Lineage

     

    Item Description

    Distinguished Name

    The value of the anchor attribute that is defined for this object type

    Last import change

    The date and time of the last import change

    Last export change

    The date and time of the last export change

    Object state

    The type of connector. Possible values are:

    • Connector

    • Explicit connector

    • Disconnector

    • Explicit disconnector

    • Filtered disconnector

    • Placeholder

    Connection operation

    The type of connection operation. Possible values are:

    • provisioning-rules

    • join-rules

    • projection-rules

    Date

    The date and time of the connection operation

    Metaverse Object Properties

    Opens the Metaverse ObjectProperties dialog box for that object

Preview

With Preview, you can see how an individual object will be synchronized without committing the change to the metaverse. For more information about Preview, see Using Preview.

Validate object against schema

Validate object against schema compares the object waiting to be exported with the known schema for that management agent and then displays any schema mismatches. The following table lists and describes the three possible tabs that you can view in the Export Validation dialog box.

 

Tab Description

Pending Export

Displays any errors for an object that is waiting to be exported to the connected data source

Export in Progress

Verification of the export cannot be confirmed until an import is run to verify that the exports were successful. The object appears on this page until an import is run.

Export in Escrow

For management agents such as Active Directory, exports can be confirmed immediately from the connected data source. The object appears on this page until an import is run.

For more information about searching the connector space, see Search for a Connector Space Object.

Creating a rules extension project

Create Rules Extension Project creates the files that are necessary for a FIM project by using either the Visual Basic .NET language or the Visual C# .NET language. Create the rules extension project only after you finish configuring your rules. In addition to creating \Bin and \Obj folders for each project, the files listed in the following table are created.

 

Language Files

Visual Basic .NET

  • AssemblyInfo.vb

  • Microsoft.MetadirectoryServices.dll

  • projectname.vb

  • projectname.vbproj

  • projectname.vbproj.user

  • projectname.sln

Visual C# .NET

  • AssemblyInfo.cs

  • Microsoft.MetadirectoryServices.dll

  • projectname.cs

  • projectname.csproj

  • projectname.csproj.user

  • projectname.sln

For more information about using rules extensions, see the FIM Developer Reference. For more information about management agent rules, see Understanding Management Agent Rules.

Viewing statistics

Administrators need access to statistics for management agents so that they can track run histories, monitor the management agents, or view the number of objects. For each management agent, current statistics are listed for the number of objects, number and types of connectors and disconnectors, import and export statistics, and start and end time for the last run of the management agent. For more information, see View Cumulative Management Agent Statistics.

Show: