Using the Notes® single user to multi-user migration assistant tool

Use this procedure to convert an existing Notes® single user installation or simulated multi-user installation to a true Notes® multi-user installation within a single Notes® release. After migration you can then upgrade the release level of the Notes® multi-user client.

Before you begin

Review the information in the topic Understanding the Notes® single user to multi-user migration assistant tool,
To run the tool you must be logged in to Windows™ as an administrator to ensure necessary permissions for copying and moving data.
Before running the tool, consider backing up the Notes® client. For details, see the article Backing up and restoring Notes® client data, included in the links at the end of this topic.
Verify that users have required read/write/delete permission for the new target directories.

About this task

Procedure

Exit the Notes® application; Notes® cannot be running during the migration.
Locate the files MUMigrationAssistant.vbs and MUMigrationAssistant.ini in the Utility folder in the Notes® install kit.
Open the MUMigrationAssistant.vbs script and review its embedded documentation.

Open the MUMigrationAssistant.ini configuration file in a text editor and specify the following values:

Option	Description
CURRENTINIPATH	(Required) Specifies the current NOTES.INI file location. The tool obtains the user's data directory location from their NOTES.INI file.
NOTESPROGRAM	(Optional) Specifies the current location of the user's notes.exe file. If not specified, the tool attempts to determines the location first from the Windows registry (HKLM/SOFTWARE/Notes/`version`/Path first for versions 8.5.x and earlier, or HKLM/SOFTWARE/Notes/Path for Notes 9.0 or greater), and then from the user's NOTES.INI file.
MULTIUSERBASEDIR	(Optional) Specifies the target location for the user's data directory. When you run the tool, it confirms that the specified directory exists and that the tool has read/write permission to the directory. The tool appends Notes\Data for versions of Notes® prior to 9.0, or appends HCL\Notes\Data for Notes® 9.0 or later. When you set this value, you must include %USERNAME% in MULTIUSERBASEDIR. If you do not specify a value for MULTIUSERBASEDIR, the default value CSIDL_APPDATA is used. Important: If you specify a value for this setting, then you must also specify a value for MULTIUSERCOMMONDIR.
MULTIUSERCOMMONDIR	(Optional) Specifies the location for the common shared data directory is located. When you run the tool, it confirms that the users whose data is being moved have read permission to the specified directory. If you specify a value, the tool checks that the value includes the %USERNAME% environment variable. If you do not specify a value for MULTIUSERCOMMONDIR, the default value CSIDL_COMMON_APPDATA is used. The tool appends Notes\Data for versions of Notes® prior to 9.0, or appends HCL\Notes\Data on Notes® 9.0 or later. Important: If you specify a value for this setting, then you must also specify a value for MULTIUSERBASEDIR.
DRYRUN	(Optional) True (default) - When you run the tool it generates a report listing the changes that would result from running the tool, but it does not perform the migration. False - When you run the tool it performs the migration
MIGRATE_REGISTRY	True - The tool migrates HKLM registry settings and updates desktop shortcuts and start menu shortcuts for all users. False - The tool does not migrate registry settings or update shortcuts. When migrating from a simulated multi-user Notes® installation, you can specify this options at the command prompt when running the cscript command
MIGRATE_USER_REGISTRY	True - The tool migrates registry settings and updates desktop shortcuts and start menu shortcuts for the user running the tool only. False - The tool does not migrate registry settings or update shortcuts. When migrating from a simulated multi-user Notes® installation, you can specify this options at the command prompt when running the cscript command
MIGRATE_SHARED_DIR	True - The tool migrates the common data files to be shared among all users. These are the files that would be installed to the common shared directory during a Notes® multi-user installation False - The tool does not migrate common data files. If you have other files to move, such as a user's templates, you can list them in a file and specify the location in the next setting, MIGRATE_SHARED_FILES. To customize the target location for moved files, use the MULTIUSERCOMMONDIR setting. When migrating from a simulated multi-user Notes® installation, you can specify this options at the command prompt when running the cscript command
MIGRATE_SHARED_FILES	Specifies the name and location of the migratefilelist.txt text file that lists other files to move to the target shared directory, for example, user-defined templates or that were not installed by Notes®. To used this setting you must set the value of the previous setting, MIGRATE_SHARED_DIR, to `True`. When migrating from a simulated multi-user Notes® installation, you can specify this options at the command prompt when running the cscript command
MIGRATE_USERDATA_DIR	Use this setting only when migrating a simulated multi-user installation to a true multi-user installation. True - The tool migrates the user's personal data files (for example, user ID, templates, databases) to the directory specified by the MULTIUSERBASEDIR setting. The value should be set to true for every user. False - The tool does not move personal data. The tool determines the location of the source data directory from the NOTES.INI file and then confirms that each file to be migrated exists in the data directory and that the tool has permission to operate on the files. You can create a batch file in the StartUp Group or the RunOnce registry key to run the script to migrate data automatically for every user when they log in to Windows for the first time after the migration. If the source data directories for each use reside on separate drives, you must run the tool separately for each user. If no value is set for MULTIUSERBASEDIR, data is migrated to the location specified by the default user data path. For Notes® 8.5x and earlier, the default path is: C:\Documents and Settings\`username`\Local Settings\Application Data\Notes\Data; for Notes® 9.0 or later, the default path is: C:\Documents and Settings\`username`\Local Settings\Application Data\HCL\Notes\Data . When migrating from a simulated multi-user Notes® installation, you can specify this options at the command prompt when running the cscript command

Save and close the MUMigrationAssistant.ini file.
Close the MUMigrationAssistant.vbs script.
Perform a test run of the migration by setting the value of the DRYRUN option in the configuration file to true and then typing the following at the command prompt:
```
cscript MUMigrationAssistant.vbs configuration_setting=value
```
When you run the tool, it verifies settings in the configuration file before performing the migration. If the NOTESPATH and CURRENTINIPATH settings, which specify the location of the notes.exe and notes.ini files are not valid, the migration will stop:
Note: If conflicts occur between settings specified on the command line and in the configuration file, the settings specified at the command line take precedence.
Review the output report and determine if any MUMigrationAssistant.ini file adjustments are required. If so, make them now.
Perform the migration by setting the value of the DRYRUN option to false in the configuration file and then typing the following at the command prompt:
```
cscript MUMigrationAssistant.vbs configuration_setting=value
```
A NOTES.INI file will be generated in the shared data directory. The original NOTES.INI file will be moved to the directory specified by the MULTIUSERBASEDIR variable. The new data directory will be located in the directory specified by the MULTIUSERBASEDIR variable and the shared directory will be that specified by the MULTIUSERCOMMONDIR variable.

Results

The tool logs activity to the Install.log file, which resides in the installing user's My Documents folder and the migrated user's data directory.

Example

Example: Simulated multi-user installation to (true) multi-user installation

In this scenario, several users are configured to work on a single computer using a simulated multi-user environment and a shared drive containing their common and user-specific data files.

The NOTES.INI file is H:\data\notes.ini.
The Notes® installer setup.exe file is located at C:\Program Files\HCL\Notes.
The user's data directory is H:\data.
The shared data directory is C:\notes\common\Notes\data.
The migratefilelist.txt file, located in the directory from which you run the migration tool, specifies that the following additional files will be moved:
- H:\data\template1.ntf
- H:\data\template2.ntf
- H:\data\template3.ntf

Migrate users based on your applicable use case as follows:

Use case 1 - Simple single user to multi-user migration for all versions of Notes®

In this use case, Notes® 8.5.1 is installed in single user mode with Program Files installed to C:\Program Files\HCL\Notes and data files installed to C:\Program Files\HCL\Notes\Data,

Run the tool to do the following:

Migrate the registry entries to make it a true multi-user installation.
Migrate the common files to be used by all user to C:\Documents and Settings\AllUsers\Application Data\Notes\Data.
Migrate the user's data files and NOTES.INI to C:\Documents and Settings\username\Local Settings\Application Data\Notes\Data.

The values specified in the MUMigrationAssistant.ini are as follows:

DRYRUN=true
CURRENTINIPATH=C:\Program Files\HCL\Notes\Data\notes.ini
NOTESPROGRAM=C:\Program Files\HCL\Notes
IS_SIMULATED_MODE=false
MIGRATE_REGISTRY=true
MIGRATE_USER_REGISTRY=true
MIGRATE_SHARED_DIR=true
MIGRATE_USERDATA_DIR=true
MULTIUSERCOMMONDIR= 
MULTIUSERBASEDIR=

Note: Leave MULTIUSERBASEDIR and MULTIUSERCOMMONDIR blank to use the default value.

Use case 2 - Simulated multi-user to true multi-user migration - First run of the tool to move all the shared data

In this use case, Notes® 8.5.1 is installed in single user mode but each user's data directory are mapped on a network drive. Program Files are installed to C:\Program Files\HCL\Notes and data files are installed to H:\data. When the source data directory for all users is local or resides on a common network drive, you can run the tool to move data to the target data directory location for all the users of that Notes® client instance.

Run MUMigrationAssistant as an administrator from a system that has access to the mapped data drive(s) for the users. to do the following:

Convert the HKLM registry settings to specify a true multi-user installation.
Creates a shared data directory, C:\notes\common\Data
Migrates the common files for all users to the shared directory.

The values specified in the MUMigrationAssistant.ini are as follows:

DRYRUN=true
CURRENTINIPATH=H:\data\notes.ini
NOTESPROGRAM=C:\Program Files\HCL\Notes
IS_SIMULATED_MODE=true
MIGRATE_REGISTRY=true
MIGRATE_USER_REGISTRY=false
MIGRATE_SHARED_DIR=true
MIGRATE_USERDATA_DIR=false
MULTIUSERCOMMONDIR=C:\notes\common
MULTIUSERBASEDIR=H:\data

Use case 3 - Simulated multi-user to true multi-user migration with subsequent running of the tool when each user logs in to move each user's data

In this use case, Notes® 8.5.1 is installed in single-user mode, but each user's data directory is resides on a mapped drive. The administrator has migrated the single-user settings on the Notes® client to a multi-user installation. (as per Use case 2). Each user now logs in to the system.

Run MUMigrationAssistant when the user logs in to do the following:

Migrate the HKCU registry entries for that particular user.
Move the user's data from the mapped drive to the default location C:\Documents and Settings\username\Local Settings\Application Data\Notes\Data.

The values specified in the MUMigrationAssistant.ini are as follows:

DRYRUN=true
CURRENTINIPATH=H:\data\notes.ini
NOTESPROGRAM=C:\Program Files\HCL\Notes
IS_SIMULATED_MODE=true
MIGRATE_REGISTRY=false
MIGRATE_USER_REGISTRY=true
MIGRATE_SHARED_DIR=false
MIGRATE_USERDATA_DIR=true
MULTIUSERCOMMONDIR=C:\notes\common
MULTIUSERBASEDIR=

Note: Leave MULTIUSERBASEDIR blank at its default value.