Knowledge Base

How to build a new management agent to replace an existing management agent

Article ID: 827117

Article Last Modified on 2/23/2007

APPLIES TO

Microsoft Identity Integration Server 2003 Enterprise Edition
Identity Integration Feature Pack for Microsoft Windows Server Active Directory

INTRODUCTION

This article describes how to replace an existing management agent (MA). You may have to replace an existing management agent for the following reasons:

The Microsoft Identity Integration Server (MIIS) 2003 Cumulative Fix includes fixes that resolve changes to the original management agent design. However, these fixes do not affect the existing management agents but only new management agents. Therefore, if you experience a problem with a management agent, you must build a new management agent that is the same and then delete the existing one.
You migrate from different versions of a connected directory, such as from IPlanet 4.16 to SunOne 5.2. These versions have different schemas and anchor attributes for connected directory objects. Therefore, Microsoft does not support using the same management agent.

Important If you do not consider all aspects of your MIIS configuration, you may create problems in other connected directories inadvertently, depending on your deletion and deprovisioning rules. This article describes how to successfully perform this migration.

MORE INFORMATION

Steps that you must follow to perform a successful management agent migration

Follow these steps to successfully perform this migration. To validate success in production, do all these steps in a test lab with the exact production data.

Step 1: Back up the MIIS database

Test this first in a test lab. If you have a Quality Assurance (QA) lab, start there. A QA lab is a lab that has a mirror of production environment for effective change control best practices.

If you do not have a QA lab, use a test server and build a server running MIIS or a server running SQL Server to test this procedure. Drop a full import file, and then move it to the test environment. In the test environment, resume from file so that no connectivity to production is required.

Use SQL server to back up the MIIS database. For more information about how to back up and restore MIIS database, see Help.

Step 2: Evaluate MV deletion rules

Open Identity Manager, click Metaverse Designer, and then click Configure Object Deletion Rule.
In the deletion rules, match one of the following for each object type that you are processing through MIIS:
1. Delete the metaverse object when the connector from Management Agent Being Migrated is disconnected. If the rule is set for the management agent that you are migrating to, make a note. You must have this information after you import the management agent.
2. If the rule is set to a custom extension, you must evaluate the code more. If custom code deletes any objects when the connector from this management is disconnected, make a note.
3. If the metaverse deletion rule is not set, the metaverse entry will not be deleted until the last connector is deleted. Therefore, it will not affect this scenario.
Click OK or Cancel to close the dialog box.

Step 3: Export the existing management agent

Open Identity Manager, click Management Agents, and then select the management agent that you are trying to migrate.
In the Action panel, click Export Management Agent.
In the Save As dialog box, type a name in the form of Management Agent Name, where Management Agent Name is the name of your management agent.

Step 4: Rename the existing management agent

In the Management Agents view, with the existing management agent selected, click Properties in the Action panel.
In the Properties dialog box, in the Name box, add OLD to the end of the management agent name, and then click OK to save changes.

If you are successful, the new management agent name appears in the Management Agents view. If you are successful, go step 4.

Step 5: Create a new management agent

You have two options for creating a new management agent. You can frequently use the import management option to reduce the time that you spend re-creating a management agent. However, in certain circumstances, you may not be able to use the import option. For example, you may not be able to use the import management option if the management agent design includes code changes.

Option 1: Create a management agent

On the Tools menu, click Management Agents.
On the Actions menu, click Create.
In Management Agent Designer, click the type of management agent that you want to create under Management agent type.
In the Name box, type a name for the management agent.
In the Description box, type a description for the management agent.
Click Next, and then follow the instructions to configure additional pages in Management Agent Designer.

Option 2: Import the exported management agent

In the Management Agents view, make sure that the existing management agent is selected.
In the Action pane, click Import Management Agent.
Locate the XML file that you saved in the procedure for the "Step 3: Export the existing management agent" section.
Click OK to reimport the saved management agent.
In the Create Management Agent dialog box, click Next.
- If the management agent is call-based, type the password that the account that the management agent will use to contact the connected directory in the Configure Connection dialog box.
- If the management agent is not call-based, this step is not present. Click Next, and then accept all the default values.
Click Finish to complete the configuration.

Step 6: Verify that the join rules are configured

Open Identity Manager, click Management Agents, and then click the newly-created management agent (original name).
In the Action panel, click Properties.
In the Properties dialog box, click Configure Join and Projection Rules.
For each entry in the Data Source Object Type section, make sure that there are corresponding join rules that are configured for each existing projection rule. You must do this to avoid duplicating metaverse objects that were previously projected by the original management agent. For more information about how to configure join rules, see Help.

Step 7: Modify metaverse deletion settings

Open Identity Manager, click Metaverse Designer, and then click Configure Object Deletion Rule in the Object Types section of the Action panel.
If the deletion rule is Delete Metaverse object when the connector from this management agent is disconnected, update the name of the management agent in the list. Change the value of the management agent name from the old (renamed) management agent to the newly-created management agent with the original name.
If the management agent deletion rule is using a custom extension, you do not have to make changes. You do not have to make changes if the management agent name that is referenced in the extension matches the name of the newly-created management agent (with the original name).

Step 8: Change the attribute precedence to set the new management agent at a higher precedence

In Metaverse Designer, for each object type listed in the Object Types section, verify that the correct Attribute Flow Precedence has been set for any attribute that has an Import Flow value that is greater than 1.

For example, if object type Person has an attribute cn in the Attributes section with an Import Flow value of 2, click the CN attribute in the Attributes section, and then click Configure Attribute Flow Precedence in the Action section. The existing precedence rules for CN will appear. Use the arrow keys to resequence the order so that the new management agent is higher than that of the renamed MA. For all object types, resequence the Import Flow values in this way for all attributes that have a value that is greater than 1.

Step 9: Run a Full Import (Stage Only) to stage connectors into the new management agent

If the management agent is not call-based, make sure that the input file from the original (renamed) management agent is available to input to the new (original name) management agent. To do this, follow these steps:

Open the Program Files\Microsoft Identity Integration Server\MaData\Renamed MA Name folder. Copy the input file to the Program Files\Microsoft Identity Integration Server\MaData\Original MA Name folder.
In Identity Manager, click Management Agents.
Click the new management agent (original name), and then click Configure Run Profiles.
In the list of management agent run profiles, make sure that one profile is Full Import (Stage Only). If this profile is not available, create a new Run Profile. For more information about how to create run profiles, see Help.
Click Run, and then click Full Import (Stage Only).
When the management agent run is complete, the statistics reflect the correct number of objects that are being imported.
Use the preview functionality to verify that the full synchronization will be successful. In particular, that the CS object will successfully join to the preexisting metaverse object that was created by the original MA. For more information about how to use the preview functionality see Help.
Spot check several instances of each object type that is being processed.

Step 10: Run the new management agent to join existing entries and update the last contributing management agent property for each metaverse attribute that is updated

In the Management Agents view, click Management Agent, and then click Run. Click a Full Synchronization run profile, and then click OK.

Note The name of the management agent run profiles varies, based on your run profile configuration.

When the management agent run is complete, use Metaverse Search to verify that the full synchronization was successful. Double-click one of the search result objects. On the Attributes tab of the Metaverse Object Properties dialog box, the value for Contributing MA should be the name of the new management agent for all attributes.
Verify the connections from the metaverse to the original management agent and verify the connections from the metaverse to the new management agent. To do this, click the Connectors tab, and then verify that the Management Agent column contains both the old and new management agent names. Verify several objects of each object type.

For more information about how to use Metaverse Search, see Help.

Step 11: Decommission the original management agent

Perform either option 1 or option 2 immediately.

Note Option 2 takes an extended period of time. If you perform option 2, you will not be able to run any management agents until the deletion is complete. Therefore, reserve option 2 for a time when Management Agent runs are not required.

Option 1: Decommission the management agent attribute flow properties for the original management agent.

Note You do not have to perform this option. However, it is recommended because it prevents attribute flow rules from being applied to the metaverse in case a full synchronization that uses the old management agent is performed.
1. In the Management Agents view, click the renamed management agent, and then click Properties.
2. In the Join/Project dialog box, remove all join and projection rules that are associated with this management agent.
3. In the Attribute Flow dialog box, remove all attribute flow rules, and then click OK.
Option 2: Delete the original management agent
1. In the Management Agents view, right-click the management agent, and then click Delete.
2. When you are prompted, click Delete Management Agent.
3. Check each of your other management agents, depending on their deprovisioning rules. To do this, follow these steps:
  1. Use Search Connector Space to search pending export for all delete operations for the management agents that have deprovisioning set to Stage a Delete on the Object for the Next Export Run. By doing this, you can make sure that you are not staging a delete of a whole CD. If you see many deletes that are staged for export, stop them before they export the deletes to the connected directory. Check pending export deletion values for each management agent that has deprovisioning rules set to Stage a Delete to the connected directory deprovisioning rules. For more information about how to use the Search Connector Space functionality, see Help.
  2. Run the CSExport.exe file. This is a MIIS tool that located in the Bin folder. The tool checks for an unusual number of Normal and Explicit disconnectors for each management agents that have these types of deprovisioning rules. For more information about how to use the CSExport.exe tool, see Help.

Step 12: Resume the MIIS run schedule

If everything appears to be successful in all previous steps, turn your management agent schedule back on and have your management agents resume their configured management agent runs. You can also run each successive management agent manually so that you have more control over stopping the run sequence. Either way, carefully monitor the server for failures and unexpected activities.

Keywords: kbinfo KB827117

Microsoft KB Archive/827117

Contents