Directory Migration Tool

You can run the Directory Migration tool in either of the following modes:

• Batch Mode. Migrates a range of sequential users.

• On-Demand Mode. Migrates one user at a time, on an as-needed basis.

You can run multiple instances of the Directory Migration tool simultaneously. When both modes are used to migrate a directory, the batch mode migrates all users together. For users who access the site before their accounts are migrated, on-demand migration can be triggered so the user can proceed on the new site with minimal interruption. The migration objects are installed on one or more servers and will migrate a user upon request. In batch mode, a sequential range of users is migrated. In on-demand mode, one user at a time is migrated as they log in to the Commerce Server 2000 site. The file Login.asp in the <Drive:>\Program Files\Microsoft Commerce Server\SDK\Tools\MembershipMigration\Client directory can be used to migrate users on demand.

To track the status of each user migration, the Migration attribute is added to the Membership Directory user schema. The Migration attribute type is binary.

For each attribute that is migrated, the Directory Migration tool assigns True to the Migration attribute if the migration was successful, and False if the migration was not successful. If the migration was unsuccessful, check the log for the reason.

Note

• The Directory Migration tool interprets the lack of a migrated attribute as "no migration attempted."

MigrationMainObj Object

The MigrationMainObj object is the primary object that manages the migration of individual users or ranges of users upon demand. It calls the objects in the following order for each user to be migrated:

1. MigrationReadObj object

2. MigrationModifyObj object

3. MigrationWriteObj object

4. MigrationLogObj object

If the MigrationMainObj object is configured to run in batch mode, it uses a filter to generate Lightweight Directory Access Protocol (LDAP) queries for user profiles matching the filter criteria (for example, user names starting with "Aaa" through "Adz"). This filter is used to help prevent LDAP time-outs. For more information about this filter, see Migration ProfileBuilder Tool.

The following figure shows how the Directory Migration tool processes a user profile.

The Directory Migration tool performs the following steps to process a user profile:

1. It retrieves information from an Extensible Markup Language (XML) configuration file that contains details on the objects to be used, and instructions for mapping the data to be read to the data to be written.

2. The MigrationMainObj object receives a request to migrate a user profile.

3. The MigrationMainObj object sends the request to the MigrationReadObj object.

4. If the Migration attribute is not set to True or False, the MigrationReadObj object sets the Migration attribute to True, which prevents other instances of the Directory Migration tool from migrating the same user profile again. If the update succeeds, the migration process continues to the next step; otherwise it fails.

5. The MigrationReadObj object retrieves the user profile from the Membership Directory.

6. If indicated in the XML configuration file, the MigrationReadObj object calls the MigrationModifyObj object.

7. The MigrationModifyObj object changes the user profile as specified, and then returns the modified buffer to the MigrationReadObj object.

8. The MigrationReadObj object sends a pointer to the buffer to the MigrationMainObj object. If the MigrationReadObj object returns a failure, the MigrationMainObj object logs the failure, calls the MigrationReadObj object to set the Migration attribute to "Failed," and then prepares to process the next migration request.

9. The MigrationMainObj object sends the buffer to the MigrationWriteObj object, which writes the user profile to the Profiles data store.

10. The MigrationWriteObj object sends the write request to the ProfileService object. If it succeeds, the MigrationWriteObj object then adds the user profile to the appropriate groups, and updates the MemberOf attribute accordingly. If the write fails, the write is rolled back. If the rollback fails, the MigrationWriteObj object logs the rollback failure.

11. The ProfileService object returns a success/fail return code on the write attempt.

12. If the migration is an Active Directory migration, the MigrationWriteObj object adds the user to the proper groups through direct Active Directory Service Interfaces (ADSI) calls.

13. The MigrationWriteObj object logs the success (or failure) of the write attempt and adds users to the appropriate groups when completed. The MigrationWriteObj object returns the success/fail code as appropriate.

14. The MigrationMainObj object logs a successful or failed migration attempt and returns the success/fail return code to the calling component.

MigrationReadObj Object

The MigrationReadObj object reads the user profile attributes from the Site Server 3.0 Membership Directory. The MigrationMainObj object calls the MigrationReadObj object when each user profile is to be migrated.

The source code for the MigrationReadObj object is provided in the SDK\Tools\MembershipMigration folder.

MigrationModifyObj Object

You use the MigrationModifyObj object to modify user profile data as it is migrated. The MigrationModifyObj object is responsible for buffer management. Refer to the source code for examples of buffer management.

The source code for a MigrationModifyObj object is provided in the SDK\Tools\MembershipMigration folder.

MigrationWriteObj Object

The MigrationWriteObj object writes the migrated user profile data to the ProfileService object. In addition, if the user is a member of a group, the MigrationWriteObj object adds it to the equivalent group in Active Directory.

MigrationLogObj Object

The MigrationLogObj object is used to create a transaction log, which you use to diagnose problems encountered during the migration process.

See Also

Programmer's Reference for Migration

All rights reserved.