Chat now with support
Chat with Support

Binary Tree Migrator for Notes 20.11 - User Guide

Section 1. Introduction Section 2. Pre-migration Activities Section 3. User Provisioning Section 4. Email Repliability Section 5. Migrating Mail Files Section 6. Rooms and Resources Database Migration Section 7. Mail-in Database Migration Section 8. Setting Migration Status Section 9. Access and Delegation Migration Section 10. All Accounts Section 12. Logs Appendix A: Staging Replicas Appendix B: Pre-Migration Troubleshooting Appendix C: Work with Files (Import/Export) Appendix D: Item Processing Results Appendix E: Migration Result Statuses Appendix F: Recovery Process Appendix G: Automatic Migration Restart Appendix H: Folder Processing Order Third Party Components

Set Migration Status

The following results are returned to the migration controller server for the overall migration status of all items:

  • Migrated Successfully – Completed processing all items, no problems during initialization, no critical errors encountered; there may be non-critical Warnings, Errors or failures during individual document processing, but these do not stop the migration; the migration will still be considered successful even if there are document warnings or errors

  • Migration Failed – Critical errors/failures encountered that prevent the migration from continuing/completing; this status is typically caused by network/server connectivity problems

  • Terminated Abnormally – This status is set by the migration worker when CMTProxy.exe (migration engine) crashes; this is typically caused by corrupt source data, a Notes client crash or Exchange terminating the migration connection

  • Failed to Initialize – Incorrect/Incompatible configuration settings, missing configuration or reference files, failure to connect to source or destination servers, and so on; no data is migrated

  • Migration cancelled – Manual cancellation of the migration the user

  • Not Queued: Migration history is pending update – The migration was not started due to the history of a previous migration not being updated

  • Migration failed: Exchange is not available – The migration failed because Exchange was not available

  • Nothing in Source File – The source mailfile is able to open but does not contain any data

  • Source Database Not Initialized – The source mailfile fails to open with “Database Not Initialized”

  • AutoDiscover Failure – The Target mailbox fails to connect with Autodiscover

     


Additional details for a migration can be viewed in the migration log. Most commonly encountered errors with resolutions can be found in the Knowledge Base that is hosted on the product web site under the Support section.


A migration of an account can be marked as Migrated Successfully but have non-critical errors for individual source Notes documents items. The individual items with errors will not necessarily have migrated correctly. If there are errors recorded during a successful migration the error count will be shown in the Migrator for Notes Migration views. These can be checked in the Migration Log for the account and verified. For example, the end user did not decrypt source Notes messages or a source Notes document did not have all expected field data. In these cases, the migration is considered as successful as the source data for individual documents could not be processed but the migration was not aborted by either Notes or Outlook. Re-migrating the account could potentially resolve these errors. In cases where specific details are required a migration profile with Verbose logging enabled should be used to re-migrate an account.

To manually update the status of migrated items, follow the steps below.

  1. Expand the Migration | Advanced view; select rooms and resources in the Data Pane

  2. At the top menu, click Actions | Other; the Run Agent dialog box will open

  3. Select Set Migration Status and click Run:

  4. From the Set Migration Status dialog box, then, for example, select Ready to Process and click OK:

  5. A status message box displays showing that the migration status will be changed for the selected rooms; click Yes to confirm

    Notice that the selected rooms and resources are now listed under the applied status:

Set Migration Group

  1. At the top menu, click Actions | Other; the Run Agent dialog box will open

  2. Select Set Migration Group in the dialog box and click Run:

  3. Specify the migration group name in the Migration Group dialog box and click OK:

  1. A status message box displays showing that the migration group will be changed for the selected rooms; click Yes to confirm

    Notice that the selected rooms and resources are now listed under the applied status:

Set Migration Workstation

  1. At the top menu, click Actions | Other; the Run Agent dialog box will open

  2. Select Set Migration Workstation in the dialog box and click Run:

 

  1. From the Set Migration Workstation dialog box, select a workstation on which to run the selected users’ migrations, and then click OK:

  2. A confirmation box appears; click Yes to confirm that you want the selected migration workstation to be set for selected rooms and resources

  3. A status message box displays showing that the migration workstation will be set for the selected rooms; click Yes to confirm

    Notice that the selected rooms and resources are now listed under the applied status

Clear Migration Status

  1. In the same way, you can clear set migration status, migration group, and migration workstation by selecting appropriate options; if you do not set the migration workstation manually, Migrator for Notes will automatically farm the migration job out to the next available worker in the migration farm

  2. Select the rooms and the resources, then click the Additional Actions button to display its drop-down menu options:

    The drop-down menu options are as follows:

Option

Description

Clear Selected DB(s) and re-populate

Selected room or resource will be cleared and then repopulated to import the updated information

Delete Selected DB(s)

Selected room or resource will be deleted from the Migrator for Notes database as well as the database into which the rooms or resources schedule was exported

 

  1. After you have performed all the pre-migration actions on the rooms and resources, go back to the Migrate view

  2. Select all the rooms and resources you wish to migrate then click the Migrate Rooms & Resources button in the Data Pane toolbar

  3. The Select Migration Priority dialog box appears; click OK to trigger the migration:

    Depending on the size of the data being migrated, the transfer may take from few minutes to several minutes

  4. The Refresh Migration Status button allows you to refresh the status of the selected rooms and resources

     

Set Migration MCC

In some cases, you have the option to set the Migration MCC. Refer to the chart below for a description of these MCC options:

 


This option should only be used in cases where more than 120 migration workers are required and an additional migration control center server cannot be deployed.

 

Option

Description

Set Migration MCC

Appears only if multiple Migration Control Centers (MCCs) are enabled on the Migrator for Notes Settings | Other Settings | Enable Advanced Features

 

Allows you to manually assign a Migration Control Centers (MCC) to process an item’s data

Clear Migration MCC

Appears only if multiple Migration Control Centers (MCCs) are enabled; Allows you to clear the Migration MCC assigned to item(s)

 

Appendix F: Recovery Process

The Migrator for Notes migration engine has been enhanced to track the status of processed messages during migration to help recover failed migrations.

If a critical failure occurs in the migration engine, the migration process can terminate unexpectedly. The user status must be reported in Notes Migrator.nsf as “Migration terminated abnormally.” After correcting the cause of the failure, the new recovery feature allows Migrator for Notes users to restart migrating to an Exchange mail store or to a PST file from the point of crash. It prevents the application from reprocessing messages that were migrated during the initial run of the migration and moves to the next message in the message store without attempting to reprocess the message that caused the failure.

In addition, this feature also allows Migrator for Notes users to restart the migration on a secondary workstation if the first workstation is now busy after the original failed status.

This section outlines the common reasons for a failed migration and recovery processes for each possible scenario and provides a background to the implementation and usage of this new feature.

Implementation and Feature Functionality

By default, this feature is enabled in the Enable Recovery setting in the Advanced tab of the migration profile used on each migration workstation. With this setting enabled, during each migration, the migration engine generates a text file, CMTUProcessedNoteIDs-[username].txt, in the temp directory. This .txt file contains all the NoteIDs processed during the migration. If a crash occurs causing the migration to fail, the last entry in the .txt file is the NoteID that caused the failure. If the migration is successful, this file is deleted during cleanup.

A migration workstation, when it first starts and between user migrations, checks the temp directory (typically c:\windows\temp\) for any existing CMTUProcessedNoteIDs-[Username].txt file(s). If a file is found, the migration workstation uploads the list of NoteIDs from the file into the migrated messages table in Migrator for Notes before starting the migration. This updates the Migrator for Notes migrated message table for the failed migration, then processes the pending queue as normal. This allows any migration workstation to run follow-up migrations.

Common Failure Types

Before restarting a failed migration, you must first examine the migration status of the user and log files from the failed migration to determine the cause of the failure. If the cause of the failure is corrupted views or database design elements, restarting the migration will not help. The migration will continue to fail until the problem is resolved and the recovery process will not allow the migration to continue past the point of failure.

If the cause of the failure is a failed physical attribute that needs correcting, then provided below are the four most common types of physical attribute failures with their corresponding example log files, and possible resolutions.

Cannot Open Mail File: “Migration initialization failed”

If the mail file does not exist at the specified location, or the migration account does not have access to the mail file, Migrator for Notes reports a status of “Migration initialization failed.” This status can appear if either the source or destination server is unavailable, or if the migration account does not have access to the message store. Regardless of the number of attempts made, this type of problem cannot be successful until it is resolved. If the log file records a similar message as the following example, “Unable to open mail file CN=SERVERNAME/OU=MS/OU=SVR/O=ONE!!mail6\harr0156,” either the mail file is not present or there is an ECL alert on the workstation that is running that user. In case of ECL alerts, click through them until they stop appearing.

Corrupt Tables:

When the log file records the following statement “NSFDbGetModifiedNoteTable returned 'No documents have been modified since specified time.' while getting Note IDs of folders to process”, the tables in the mail template are corrupt. To fix this, the common practice is to create a new copy of the mail file, then replace the database design.

 


When you create a copy or a replica of the mail file to correct corrupt tables, you must remember that the recovery log does not work as expected with the copy or the replica. This is because all the documents in the mail file now have new NoteIDs. So, when you restart the migration, all the documents in the mail file are migrated and you will end up with duplicates.

To resolve this, when you restart the migration, you must treat it as a complete redo of that user’s mail file migration, and clear the contents of the user's Exchange mailbox before proceeding.

 

Corrupt Views:

When the log file contains a statement like the one shown right before the summary “Error: NSFNoteOpen returned 'You are not authorized to perform that operation' opening view note”, some of the views in the mail template are corrupt, and you need to create a new copy of the mail file, then replace design as instructed above.

Notes Crash:

If there is a critical error in the Lotus Notes client, the user’s status must be reported as “Migration Terminated Abnormally.” The can also be verified by viewing the migration log: the log file’s last statement will show this “3/2/2009 10:05:17 PM Migration preformed on workstation na svr20 workstation 1.”  To resume migration, restart the migration worker application on the Migration Workstation that is stated at the end of the log, then reset the user in Migrator for Notes and migrate again. Users in this status can be restarted and the migration will be successful.

This type of crash can be easily identified if the log file does not contain a summary of the events before ending the log with the statement “Migration performed on workstation…”. In such a case, if you restart the migration with recovery enabled, the migration is allowed to continue past the point of failure. However, if the log ends without the “Migration performed on workstation…” statement, then when you restart the migration, you will need to ensure that the migration is processed by the same workstation (that processed it earlier at the time of crash) to ensure that it properly resumes from the point of failure.

General Recovery

If a crash condition does occur, then the following procedures should be followed to recover from the failed migration. A failed status in Migrator for Notes will appear as illustrated in the image below.

Depending on the reason why the migration failed, the status may also be set to Migration Cancelled, in which case the same procedure should be followed to recover the migration. As stated earlier, a recovery can be executed on the Migration Control Center or on one of the AWD (Automated Workload Distribution) Migration Workstations within the original set or farm. The following sections outline the procedures for recovery for all scenarios.

General Recovery Process:

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  1. Under Mail File Migration, expand Migration and click Advanced

  2. Select the user in the Data Pane whose migration failed

  3. Click the Clear or Reset User(s) button in the Data Pane, and select Reset User(s) from the drop-down menu

  4. Open the AWD Migration Workstation where the original migration failed

  5. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  6. Right-click on the Windows Bar, then select Task Manager

  7. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may shut it down

  8. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  9. If you restarted, then verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  10. Go back to the Migration Control Center

  11. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  12. Select the same profile as previously used for this migration

  13. Select the original workstation or a new workstation to continue the migration process where it left off; AWD assigns a migration workstation when a new migration job is queued, and it may or may not be the original workstation where the crash occurred, but if you want to specify a specific workstation to perform the migration, then you can follow the procedure given below:

    1. Select the user in the Migrate view, click the Change to… button, and select any one of the options to bring the user to the Preparation view

    2. Once moved, go to the Preparation -> Advanced view, and select the user

    3. Click the Set Migration Status button, and select the Set Migration Workstation option from the drop-down menu

    4. From the dialog box, select either the same workstation that originally processed the user or a new one

  14. If migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST is created and you may end up with two PSTs; this may not be desirable

  15. Monitor the migration as needed; to recover a failed migration, when you restart a migration, it does not start right from the last message that was migrated. It, in fact, processes every message again just like the first time; however, the recovery table and the migration history allow Migrator for Notes to skip everything that was previously migrated; therefore, the first part of the migration proceeds through all the folders and messages very quickly until it reaches the point where it previously failed, then it slows down as it starts moving data again

  16. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

The final sections will cover each variant within this procedure so you may gain a better understanding of how the feature operates with respect to your migration project. 

Recovery to Exchange

Recovery from a migration failure to a Microsoft Exchange mailbox is a very simple process whether you are recovering from the original workstation or a secondary one as long as the original AWD farm is utilized.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD migration workstation where the original migration failed

  6. Right- click on the Migrator for Notes Worker App icon located on the Task Bar, then select Exit Now to shut down the service:

  1. Right-click on the Windows Bar, then select Task Manager

  1. Close the Outlook.exe process if still running; if the CMTProxy.exe process is still running, you may shut it down

  2. (Optional) You may restart or log-off the Migration Workstation to avoid steps 6 – 8

  3. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  4. Go back to the Migration Control Center

  5. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  6. Select the same profile as previously used for this migration

  7. Select the original workstation or a new workstation to continue the migration process where it left off; refer to step 14 in the General Recovery procedure for more details on this step

  8. Monitor the migration as needed

  9. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Recovery to PST

Recovery from a PST migration is no different from the above process except that it involves a PST rather than the Exchange message store. The following process is the preferred method for recovery from a failed PST migration because it assumes the same workstation is being utilized at the time of restart as was during the original run.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  1. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may shut it down

  2. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  3. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  4. Go back to the Migration Control Center

  5. Select Migrate in the Mail File Migration -> Migration view. Select the user(s) to be migrated in the Data Pane

  6. Select the same profile as previously used for this migration

  7. Select the original workstation to continue the migration process where it left off; perform the following procedure to select the original workstation for migration; Select the user in the Migrate view, click the Change to… button, and select any one of the options to bring the user to the Preparation view:

    1. Once moved, go to the Preparation -> Advanced view, and select the user

    2. Click the Set Migration Status button and select the Set Migration Workstation option from the drop-down menu

    3. From the dialog box, select the workstation that originally processed the user

  8. Monitor the migration as needed

  9. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover.

Recovery to PST using secondary AWD Workstation

As in the previous process, the recovery from a PST migration is no different from any other except for the location of the PST file. Either it must be centrally located (shared drive) for all workstations to update or the PST must be copied to the AWD Migration Workstation where the processing is designated to restart. This method is used when the original workstation is busy with other migrations.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  8. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may also shut it down

  9. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  10. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  11. Go back to the Migration Control Center

  12. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  1. Select the same profile as previously used for this migration

  2. Select a new workstation to continue the migration process where it left off. Refer to step 14 in the General Recovery procedure for more details on this step

  3. When migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST will be created and you may end up with two PSTs, which is not desirable

  4. Monitor the migration as needed

  5. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Recovery to PST using Manual Processes

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed.

  4. Click the Clear or Reset User(s) button in the Data Pane, and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right- click on the Migrator for Notes Worker App icon located on the Task Bar, then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  8. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may also shut it down

  9. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  10. If you restarted, verify the original workstation has restarted and the Migrator for Notes Worker App is running again.

  11. Go back to the Migration Control Center

  12. Select Migrate in the Mail File Migration -> Migration view. Select the user(s) to be migrated in the Data Pane

  13. Select the same profile as previously used for this migration

  14. Select the original workstation or a new workstation to continue the migration process where it left off; Refer to step 14 in the General Recovery procedure for more details on this step

  15. If migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST is created and you may end up with two PSTs, which is not desirable

  16. Monitor the migration as needed

  17. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Implementation and Feature Functionality

The Migrator for Notes migration engine has been enhanced to track the status of processed messages during migration to help recover failed migrations.

If a critical failure occurs in the migration engine, the migration process can terminate unexpectedly. The user status must be reported in Notes Migrator.nsf as “Migration terminated abnormally.” After correcting the cause of the failure, the new recovery feature allows Migrator for Notes users to restart migrating to an Exchange mail store or to a PST file from the point of crash. It prevents the application from reprocessing messages that were migrated during the initial run of the migration and moves to the next message in the message store without attempting to reprocess the message that caused the failure.

In addition, this feature also allows Migrator for Notes users to restart the migration on a secondary workstation if the first workstation is now busy after the original failed status.

This section outlines the common reasons for a failed migration and recovery processes for each possible scenario and provides a background to the implementation and usage of this new feature.

By default, this feature is enabled in the Enable Recovery setting in the Advanced tab of the migration profile used on each migration workstation. With this setting enabled, during each migration, the migration engine generates a text file, CMTUProcessedNoteIDs-[username].txt, in the temp directory. This .txt file contains all the NoteIDs processed during the migration. If a crash occurs causing the migration to fail, the last entry in the .txt file is the NoteID that caused the failure. If the migration is successful, this file is deleted during cleanup.

A migration workstation, when it first starts and between user migrations, checks the temp directory (typically c:\windows\temp\) for any existing CMTUProcessedNoteIDs-[Username].txt file(s). If a file is found, the migration workstation uploads the list of NoteIDs from the file into the migrated messages table in Migrator for Notes before starting the migration. This updates the Migrator for Notes migrated message table for the failed migration, then processes the pending queue as normal. This allows any migration workstation to run follow-up migrations.

Common Failure Types

Before restarting a failed migration, you must first examine the migration status of the user and log files from the failed migration to determine the cause of the failure. If the cause of the failure is corrupted views or database design elements, restarting the migration will not help. The migration will continue to fail until the problem is resolved and the recovery process will not allow the migration to continue past the point of failure.

If the cause of the failure is a failed physical attribute that needs correcting, then provided below are the four most common types of physical attribute failures with their corresponding example log files, and possible resolutions.

Cannot Open Mail File: “Migration initialization failed”

If the mail file does not exist at the specified location, or the migration account does not have access to the mail file, Migrator for Notes reports a status of “Migration initialization failed.” This status can appear if either the source or destination server is unavailable, or if the migration account does not have access to the message store. Regardless of the number of attempts made, this type of problem cannot be successful until it is resolved. If the log file records a similar message as the following example, “Unable to open mail file CN=SERVERNAME/OU=MS/OU=SVR/O=ONE!!mail6\harr0156,” either the mail file is not present or there is an ECL alert on the workstation that is running that user. In case of ECL alerts, click through them until they stop appearing.

Corrupt Tables:

When the log file records the following statement “NSFDbGetModifiedNoteTable returned 'No documents have been modified since specified time.' while getting Note IDs of folders to process”, the tables in the mail template are corrupt. To fix this, the common practice is to create a new copy of the mail file, then replace the database design.

 


When you create a copy or a replica of the mail file to correct corrupt tables, you must remember that the recovery log does not work as expected with the copy or the replica. This is because all the documents in the mail file now have new NoteIDs. So, when you restart the migration, all the documents in the mail file are migrated and you will end up with duplicates.

To resolve this, when you restart the migration, you must treat it as a complete redo of that user’s mail file migration, and clear the contents of the user's Exchange mailbox before proceeding.

 

Corrupt Views:

When the log file contains a statement like the one shown right before the summary “Error: NSFNoteOpen returned 'You are not authorized to perform that operation' opening view note”, some of the views in the mail template are corrupt, and you need to create a new copy of the mail file, then replace design as instructed above.

Notes Crash:

If there is a critical error in the Lotus Notes client, the user’s status must be reported as “Migration Terminated Abnormally.” The can also be verified by viewing the migration log: the log file’s last statement will show this “3/2/2009 10:05:17 PM Migration preformed on workstation na svr20 workstation 1.”  To resume migration, restart the migration worker application on the Migration Workstation that is stated at the end of the log, then reset the user in Migrator for Notes and migrate again. Users in this status can be restarted and the migration will be successful.

This type of crash can be easily identified if the log file does not contain a summary of the events before ending the log with the statement “Migration performed on workstation…”. In such a case, if you restart the migration with recovery enabled, the migration is allowed to continue past the point of failure. However, if the log ends without the “Migration performed on workstation…” statement, then when you restart the migration, you will need to ensure that the migration is processed by the same workstation (that processed it earlier at the time of crash) to ensure that it properly resumes from the point of failure.

General Recovery

If a crash condition does occur, then the following procedures should be followed to recover from the failed migration. A failed status in Migrator for Notes will appear as illustrated in the image below.

Depending on the reason why the migration failed, the status may also be set to Migration Cancelled, in which case the same procedure should be followed to recover the migration. As stated earlier, a recovery can be executed on the Migration Control Center or on one of the AWD (Automated Workload Distribution) Migration Workstations within the original set or farm. The following sections outline the procedures for recovery for all scenarios.

General Recovery Process:

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  1. Under Mail File Migration, expand Migration and click Advanced

  2. Select the user in the Data Pane whose migration failed

  3. Click the Clear or Reset User(s) button in the Data Pane, and select Reset User(s) from the drop-down menu

  4. Open the AWD Migration Workstation where the original migration failed

  5. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  6. Right-click on the Windows Bar, then select Task Manager

  7. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may shut it down

  8. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  9. If you restarted, then verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  10. Go back to the Migration Control Center

  11. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  12. Select the same profile as previously used for this migration

  13. Select the original workstation or a new workstation to continue the migration process where it left off; AWD assigns a migration workstation when a new migration job is queued, and it may or may not be the original workstation where the crash occurred, but if you want to specify a specific workstation to perform the migration, then you can follow the procedure given below:

    1. Select the user in the Migrate view, click the Change to… button, and select any one of the options to bring the user to the Preparation view

    2. Once moved, go to the Preparation -> Advanced view, and select the user

    3. Click the Set Migration Status button, and select the Set Migration Workstation option from the drop-down menu

    4. From the dialog box, select either the same workstation that originally processed the user or a new one

  14. If migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST is created and you may end up with two PSTs; this may not be desirable

  15. Monitor the migration as needed; to recover a failed migration, when you restart a migration, it does not start right from the last message that was migrated. It, in fact, processes every message again just like the first time; however, the recovery table and the migration history allow Migrator for Notes to skip everything that was previously migrated; therefore, the first part of the migration proceeds through all the folders and messages very quickly until it reaches the point where it previously failed, then it slows down as it starts moving data again

  16. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

The final sections will cover each variant within this procedure so you may gain a better understanding of how the feature operates with respect to your migration project. 

Recovery to Exchange

Recovery from a migration failure to a Microsoft Exchange mailbox is a very simple process whether you are recovering from the original workstation or a secondary one as long as the original AWD farm is utilized.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD migration workstation where the original migration failed

  6. Right- click on the Migrator for Notes Worker App icon located on the Task Bar, then select Exit Now to shut down the service:

  1. Right-click on the Windows Bar, then select Task Manager

  1. Close the Outlook.exe process if still running; if the CMTProxy.exe process is still running, you may shut it down

  2. (Optional) You may restart or log-off the Migration Workstation to avoid steps 6 – 8

  3. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  4. Go back to the Migration Control Center

  5. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  6. Select the same profile as previously used for this migration

  7. Select the original workstation or a new workstation to continue the migration process where it left off; refer to step 14 in the General Recovery procedure for more details on this step

  8. Monitor the migration as needed

  9. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Recovery to PST

Recovery from a PST migration is no different from the above process except that it involves a PST rather than the Exchange message store. The following process is the preferred method for recovery from a failed PST migration because it assumes the same workstation is being utilized at the time of restart as was during the original run.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  1. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may shut it down

  2. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  3. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  4. Go back to the Migration Control Center

  5. Select Migrate in the Mail File Migration -> Migration view. Select the user(s) to be migrated in the Data Pane

  6. Select the same profile as previously used for this migration

  7. Select the original workstation to continue the migration process where it left off; perform the following procedure to select the original workstation for migration; Select the user in the Migrate view, click the Change to… button, and select any one of the options to bring the user to the Preparation view:

    1. Once moved, go to the Preparation -> Advanced view, and select the user

    2. Click the Set Migration Status button and select the Set Migration Workstation option from the drop-down menu

    3. From the dialog box, select the workstation that originally processed the user

  8. Monitor the migration as needed

  9. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover.

Recovery to PST using secondary AWD Workstation

As in the previous process, the recovery from a PST migration is no different from any other except for the location of the PST file. Either it must be centrally located (shared drive) for all workstations to update or the PST must be copied to the AWD Migration Workstation where the processing is designated to restart. This method is used when the original workstation is busy with other migrations.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  8. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may also shut it down

  9. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  10. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  11. Go back to the Migration Control Center

  12. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  1. Select the same profile as previously used for this migration

  2. Select a new workstation to continue the migration process where it left off. Refer to step 14 in the General Recovery procedure for more details on this step

  3. When migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST will be created and you may end up with two PSTs, which is not desirable

  4. Monitor the migration as needed

  5. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Recovery to PST using Manual Processes

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed.

  4. Click the Clear or Reset User(s) button in the Data Pane, and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right- click on the Migrator for Notes Worker App icon located on the Task Bar, then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  8. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may also shut it down

  9. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  10. If you restarted, verify the original workstation has restarted and the Migrator for Notes Worker App is running again.

  11. Go back to the Migration Control Center

  12. Select Migrate in the Mail File Migration -> Migration view. Select the user(s) to be migrated in the Data Pane

  13. Select the same profile as previously used for this migration

  14. Select the original workstation or a new workstation to continue the migration process where it left off; Refer to step 14 in the General Recovery procedure for more details on this step

  15. If migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST is created and you may end up with two PSTs, which is not desirable

  16. Monitor the migration as needed

  17. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Common Failure Types

The Migrator for Notes migration engine has been enhanced to track the status of processed messages during migration to help recover failed migrations.

If a critical failure occurs in the migration engine, the migration process can terminate unexpectedly. The user status must be reported in Notes Migrator.nsf as “Migration terminated abnormally.” After correcting the cause of the failure, the new recovery feature allows Migrator for Notes users to restart migrating to an Exchange mail store or to a PST file from the point of crash. It prevents the application from reprocessing messages that were migrated during the initial run of the migration and moves to the next message in the message store without attempting to reprocess the message that caused the failure.

In addition, this feature also allows Migrator for Notes users to restart the migration on a secondary workstation if the first workstation is now busy after the original failed status.

This section outlines the common reasons for a failed migration and recovery processes for each possible scenario and provides a background to the implementation and usage of this new feature.

Implementation and Feature Functionality

By default, this feature is enabled in the Enable Recovery setting in the Advanced tab of the migration profile used on each migration workstation. With this setting enabled, during each migration, the migration engine generates a text file, CMTUProcessedNoteIDs-[username].txt, in the temp directory. This .txt file contains all the NoteIDs processed during the migration. If a crash occurs causing the migration to fail, the last entry in the .txt file is the NoteID that caused the failure. If the migration is successful, this file is deleted during cleanup.

A migration workstation, when it first starts and between user migrations, checks the temp directory (typically c:\windows\temp\) for any existing CMTUProcessedNoteIDs-[Username].txt file(s). If a file is found, the migration workstation uploads the list of NoteIDs from the file into the migrated messages table in Migrator for Notes before starting the migration. This updates the Migrator for Notes migrated message table for the failed migration, then processes the pending queue as normal. This allows any migration workstation to run follow-up migrations.

Before restarting a failed migration, you must first examine the migration status of the user and log files from the failed migration to determine the cause of the failure. If the cause of the failure is corrupted views or database design elements, restarting the migration will not help. The migration will continue to fail until the problem is resolved and the recovery process will not allow the migration to continue past the point of failure.

If the cause of the failure is a failed physical attribute that needs correcting, then provided below are the four most common types of physical attribute failures with their corresponding example log files, and possible resolutions.

Cannot Open Mail File: “Migration initialization failed”

If the mail file does not exist at the specified location, or the migration account does not have access to the mail file, Migrator for Notes reports a status of “Migration initialization failed.” This status can appear if either the source or destination server is unavailable, or if the migration account does not have access to the message store. Regardless of the number of attempts made, this type of problem cannot be successful until it is resolved. If the log file records a similar message as the following example, “Unable to open mail file CN=SERVERNAME/OU=MS/OU=SVR/O=ONE!!mail6\harr0156,” either the mail file is not present or there is an ECL alert on the workstation that is running that user. In case of ECL alerts, click through them until they stop appearing.

Corrupt Tables:

When the log file records the following statement “NSFDbGetModifiedNoteTable returned 'No documents have been modified since specified time.' while getting Note IDs of folders to process”, the tables in the mail template are corrupt. To fix this, the common practice is to create a new copy of the mail file, then replace the database design.

 


When you create a copy or a replica of the mail file to correct corrupt tables, you must remember that the recovery log does not work as expected with the copy or the replica. This is because all the documents in the mail file now have new NoteIDs. So, when you restart the migration, all the documents in the mail file are migrated and you will end up with duplicates.

To resolve this, when you restart the migration, you must treat it as a complete redo of that user’s mail file migration, and clear the contents of the user's Exchange mailbox before proceeding.

 

Corrupt Views:

When the log file contains a statement like the one shown right before the summary “Error: NSFNoteOpen returned 'You are not authorized to perform that operation' opening view note”, some of the views in the mail template are corrupt, and you need to create a new copy of the mail file, then replace design as instructed above.

Notes Crash:

If there is a critical error in the Lotus Notes client, the user’s status must be reported as “Migration Terminated Abnormally.” The can also be verified by viewing the migration log: the log file’s last statement will show this “3/2/2009 10:05:17 PM Migration preformed on workstation na svr20 workstation 1.”  To resume migration, restart the migration worker application on the Migration Workstation that is stated at the end of the log, then reset the user in Migrator for Notes and migrate again. Users in this status can be restarted and the migration will be successful.

This type of crash can be easily identified if the log file does not contain a summary of the events before ending the log with the statement “Migration performed on workstation…”. In such a case, if you restart the migration with recovery enabled, the migration is allowed to continue past the point of failure. However, if the log ends without the “Migration performed on workstation…” statement, then when you restart the migration, you will need to ensure that the migration is processed by the same workstation (that processed it earlier at the time of crash) to ensure that it properly resumes from the point of failure.

General Recovery

If a crash condition does occur, then the following procedures should be followed to recover from the failed migration. A failed status in Migrator for Notes will appear as illustrated in the image below.

Depending on the reason why the migration failed, the status may also be set to Migration Cancelled, in which case the same procedure should be followed to recover the migration. As stated earlier, a recovery can be executed on the Migration Control Center or on one of the AWD (Automated Workload Distribution) Migration Workstations within the original set or farm. The following sections outline the procedures for recovery for all scenarios.

General Recovery Process:

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  1. Under Mail File Migration, expand Migration and click Advanced

  2. Select the user in the Data Pane whose migration failed

  3. Click the Clear or Reset User(s) button in the Data Pane, and select Reset User(s) from the drop-down menu

  4. Open the AWD Migration Workstation where the original migration failed

  5. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  6. Right-click on the Windows Bar, then select Task Manager

  7. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may shut it down

  8. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  9. If you restarted, then verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  10. Go back to the Migration Control Center

  11. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  12. Select the same profile as previously used for this migration

  13. Select the original workstation or a new workstation to continue the migration process where it left off; AWD assigns a migration workstation when a new migration job is queued, and it may or may not be the original workstation where the crash occurred, but if you want to specify a specific workstation to perform the migration, then you can follow the procedure given below:

    1. Select the user in the Migrate view, click the Change to… button, and select any one of the options to bring the user to the Preparation view

    2. Once moved, go to the Preparation -> Advanced view, and select the user

    3. Click the Set Migration Status button, and select the Set Migration Workstation option from the drop-down menu

    4. From the dialog box, select either the same workstation that originally processed the user or a new one

  14. If migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST is created and you may end up with two PSTs; this may not be desirable

  15. Monitor the migration as needed; to recover a failed migration, when you restart a migration, it does not start right from the last message that was migrated. It, in fact, processes every message again just like the first time; however, the recovery table and the migration history allow Migrator for Notes to skip everything that was previously migrated; therefore, the first part of the migration proceeds through all the folders and messages very quickly until it reaches the point where it previously failed, then it slows down as it starts moving data again

  16. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

The final sections will cover each variant within this procedure so you may gain a better understanding of how the feature operates with respect to your migration project. 

Recovery to Exchange

Recovery from a migration failure to a Microsoft Exchange mailbox is a very simple process whether you are recovering from the original workstation or a secondary one as long as the original AWD farm is utilized.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD migration workstation where the original migration failed

  6. Right- click on the Migrator for Notes Worker App icon located on the Task Bar, then select Exit Now to shut down the service:

  1. Right-click on the Windows Bar, then select Task Manager

  1. Close the Outlook.exe process if still running; if the CMTProxy.exe process is still running, you may shut it down

  2. (Optional) You may restart or log-off the Migration Workstation to avoid steps 6 – 8

  3. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  4. Go back to the Migration Control Center

  5. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  6. Select the same profile as previously used for this migration

  7. Select the original workstation or a new workstation to continue the migration process where it left off; refer to step 14 in the General Recovery procedure for more details on this step

  8. Monitor the migration as needed

  9. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Recovery to PST

Recovery from a PST migration is no different from the above process except that it involves a PST rather than the Exchange message store. The following process is the preferred method for recovery from a failed PST migration because it assumes the same workstation is being utilized at the time of restart as was during the original run.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  1. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may shut it down

  2. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  3. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  4. Go back to the Migration Control Center

  5. Select Migrate in the Mail File Migration -> Migration view. Select the user(s) to be migrated in the Data Pane

  6. Select the same profile as previously used for this migration

  7. Select the original workstation to continue the migration process where it left off; perform the following procedure to select the original workstation for migration; Select the user in the Migrate view, click the Change to… button, and select any one of the options to bring the user to the Preparation view:

    1. Once moved, go to the Preparation -> Advanced view, and select the user

    2. Click the Set Migration Status button and select the Set Migration Workstation option from the drop-down menu

    3. From the dialog box, select the workstation that originally processed the user

  8. Monitor the migration as needed

  9. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover.

Recovery to PST using secondary AWD Workstation

As in the previous process, the recovery from a PST migration is no different from any other except for the location of the PST file. Either it must be centrally located (shared drive) for all workstations to update or the PST must be copied to the AWD Migration Workstation where the processing is designated to restart. This method is used when the original workstation is busy with other migrations.

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed

  4. Click the Clear or Reset User(s) button in the Data Pane and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right-click on the Migrator for Notes Worker App icon located on the Task Bar, and then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  8. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may also shut it down

  9. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  10. If you restarted, verify that the original workstation has restarted and the Migrator for Notes Worker App is running again

  11. Go back to the Migration Control Center

  12. Select Migrate in the Mail File Migration -> Migration view; select the user(s) to be migrated in the Data Pane

  1. Select the same profile as previously used for this migration

  2. Select a new workstation to continue the migration process where it left off. Refer to step 14 in the General Recovery procedure for more details on this step

  3. When migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST will be created and you may end up with two PSTs, which is not desirable

  4. Monitor the migration as needed

  5. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Recovery to PST using Manual Processes

  1. Open Migrator for Notes on the Migration Control Center where the migration failed

  2. Under Mail File Migration, expand Migration and click Advanced

  3. Select the user in the Data Pane whose migration failed.

  4. Click the Clear or Reset User(s) button in the Data Pane, and select Reset User(s) from the drop-down menu

  5. Open the AWD Migration Workstation where the original migration failed

  6. Right- click on the Migrator for Notes Worker App icon located on the Task Bar, then select Exit Now to shut down the service:

  7. Right-click on the Windows Bar, then select Task Manager

  8. Close the Outlook.exe process if still running. If the CMTProxy.exe process is still running, you may also shut it down

  9. (Optional) You may restart or log-off the workstation to avoid steps 6 – 8

  10. If you restarted, verify the original workstation has restarted and the Migrator for Notes Worker App is running again.

  11. Go back to the Migration Control Center

  12. Select Migrate in the Mail File Migration -> Migration view. Select the user(s) to be migrated in the Data Pane

  13. Select the same profile as previously used for this migration

  14. Select the original workstation or a new workstation to continue the migration process where it left off; Refer to step 14 in the General Recovery procedure for more details on this step

  15. If migrating to PST, make sure the file is available to the workstation now running the process; if it is not available, then a new PST is created and you may end up with two PSTs, which is not desirable

  16. Monitor the migration as needed

  17. The migration should complete with a status of Migrated Successfully unless it encounters a new error, in which case follow the same process to recover

Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating