Microsoft Identity Integration Server 2003 graphic

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 Visual Studio .NET Professional 2003 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.

Caution

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.

Note

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.

Note

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 Full Synchronization 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 Microsoft Identity Integration Server 2003 Developer Reference and Create a script for a management agent run profile. You can also automate the processing of run profiles by using MASequencer and MASequenceConfiguration in the Resource Tool Kit for Microsoft Identity Integration Server 2003, an unsupported set of tools available on the Microsoft Download Center.

Creating log files

With the exception of the Delta Synchronization and Full Synchronization steps, each of the step for a run profile has the option to create an 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.

Note

You can also transform and view management agent export files as HTML files by using MAConfigurationViewer in the Resource Tool Kit for Microsoft Identity Integration Server 2003, an unsupported set of tools available on the Microsoft Download Center.

Refresh the management agent schema

Microsoft Identity Integration Server 2003 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 Application Mode (ADAM) Active Directory global address list (GAL) Exchange Server 5.5 Exchange Server 5.5 (bridgehead server) 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.
Lotus Notes Windows NT 4.0	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.

Caution

Do not change or modify the anchor attribute when you refresh a management agent schema. Microsoft Identity Integration Server 2003 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 occurences	The last time that the error occurred
Initial occurences	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 Object Properties 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 Visual Studio .NET Professional 2003 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

Microsoft Identity Integration Server 2003 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.