Using the Lotus Notes single user to multi-user migration assistant (MUMA) tool

News


Abstract

You can use the supplied single user to multi user tool to migrate a Notes single user install to a Notes multi-user install for an existing Notes release prior to upgrading to a new release. This enables you to convert an existing Notes single user install to a multi-user install for both Notes basic and Notes standard configuration deployments. It also enables you to convert a simulated multi-user install (where the user's data directory is on a mapped drive) to a true multi-user install. This tool is available for Notes Notes 6.5.x, 7.x, 8.x and 9.x installations on supported Windows platforms only.

Content

You can use the supplied single user to multi user tool to migrate a Notes single user install to a Notes multi-user install for an existing Notes release prior to upgrading to a new release. This enables you to convert an existing Notes single user install to a multi-user install for both Notes basic and Notes standard configuration deployments. It also enables you to convert a simulated multi-user install (where the user's data directory is on a mapped drive) to a true multi-user install. This tool is available for Notes Notes 6.5.x, 7.x, 8.x and 9.x installations on supported Windows platforms only.
The Notes multi-user migration assistant (MUMA) tool runs a supplied Visual Basic script (MUMigrationAssistant.vbs), which in turns is driven by a customized configuration file (MUMigrationAssistant.ini). The configuration file enables you to customize the migration for your unique deployment environment. The tool files are supplied in the Utility folder of the Notes install kit.

There are two use cases for this migration tool:

-- Clean single user Notes installation to multi-user installation within same release
-- Simulated multi-user Notes installation (a Notes single user installation where each user's data directory is mapped to shared drives to simulate a multi user environment) to true multi-user installation within same release

Once you have migrated from single user or simulated multi-user to multi-user within the same release, you can then upgrade from that release to a new release Notes multi-user installation.

Note: While the MUMigrationAssistant.vbs script can be edited, it is designed to be used as supplied with a customized configuration file MUMigrationAssistant.ini. The editable configuration file is supplied in the install kit's Utility subdirectory. However, the MUMigrationAssistant.vbs script is documented internally, so opening the script and reviewing the embedded comments is helpful. The tool provides basic functionality and you can modify the script for your own environment. Most installations can be addressed by just editing the configuration file. However, for uniquely customized installations, you can edit the MUMigrationAssistant.vbs script as needed.

As an administrator, you'll edit fields in the supplied configuration file with user-specific details such as location of the old and new data directories.
Note: Be sure to have enabled permission for needed read/write/delete operations in those directories.
When you start the MUMigrationAssistant.vbs tool, it reads the configuration file and performs the necessary migration operations, including modification of user-specific NOTES.INI values and needed registry setting changes, and migrates the single user install to a multi-user install.

Understanding a simulated multi-user Notes installation

Notes 8.5.1 introduced install options to configure MULTIUSERBASEDIR and MULTIUSERCOMMONDIR directory paths. In Notes 8.5.1 we introduced install options to configure MULTIUSERBASEDIR and MULTIUSERCOMMONDIR directory paths. A simulated multi-user Notes installation was sometimes used prior to the support of a configurable data directory. A simulated multi-user installation is a single user Notes client installation where the user's data directory is mapped to a shared drive. Each user who logs in to the system will have their own data directory on their shared drive, thereby simulating a multi-user environment. The MUMigrationAssistant tool migrates user data and registry entries properly to move from the simulated multi-user Notes installation to a true Notes multi-user installation.

1. An administrator runs the MUMigrationAssistant for the admin user on the system where they have access to the mapped data drive for a specific user.

2. The MUMigrationAssistant tool runs and does the following:

- Creates a shared data directory

- Modifies registry settings to multi-user

- Moves the current user's data from the mapped drive, for example H:\, to the value specified in the MULTIUSERBASEDIR.option

Note: To keep "as is" you can set MULTIUSERBASEDIR to H:\ and set MIGRATE_USERDATA_DIR=false.

- Modifies shortcuts for pre-8.0 versions

- Registers itself in the registry to indicate that it has been run once

3. The administrator configures the Windows login script for each user to run the tool when they log in to the computer (OS login).

4. As each user logs in, the MUMigrationAssistant tool runs again and migrates that user's data as per the configuration ini file.

Note: Run the tool initially to migrate the common files shared between all users, and also modifiy the registry settings entries for the whole machine. As each user logs in, a login script is run, with different parameters, which moves only that user's data from his mapped drive and also modifies that user's registry settings.

Considerations:

The following considerations exist:

-- Migration is only available for Notes client installations that were installed in single user mode and Notes-only mode. Single user installations in which Domino Designer and/or Domino Administrator were also installed are not supported. An "unsupported configuration" message appears if the source install is not single user and if the single user install is an Allclient installation.

-- To run the tool you must be logged in to your Windows OS as an administrator to allow permissions for copying and moving of data.

Note: Exceptions exist if you are migrating from a simulated multi-user installation, see the "Understanding a simulated multi-user Notes installation" section above.

-- You can run the migration tool in two modes -- "dry run" and "actual." In dry run mode, you receive a report indicating what the tool would have done had you actually run it.

-- The tool writes actions information to the LotusInstall.log. The LotusInstall.log file resides in the installing user's My Documents folder and the migrated user's data directory.

-- When the source data directory is local or is on a shared network drive for all users on the machine, an administrator can run MUMigrationAssistant.vbs and provide the target data directory locations in the MUMigrationAssistant.ini file for all the users on the machine.

-- When the source data directory is mapped on each user's network share, the MUMigrationAssistant.vbs must be run separately for each user. Each user logging in would then execute MUMigrationAssistant.vbs, which would have permission to read from each user's network share.

-- MULTIUSERBASEDIR, MULTIUSERCOMMONDIR and MIGRATE_USERDATA_DIR are only available on Notes 8.5.1 and greater.

-- MULTIUSERBASEDIR and MIGRATE_USERDATA_DIR can only be used with MULTIUSERCOMMONDIR.

-- MIGRATE_USERDATA_DIR is for use when migrating a simulated multi-user installation to a true multi -user installation.

-- Prior to Notes 8.5.1, the configurable data directory was not supported, thus MIGRATE_USERDATA_DIR = false is not available for those releases. If using the MIGRATE_USERDATA_DIR option on a Notes 8.5 or earlier release, user data will be migrated to the default user's data directory.

-- For Notes 8.5.1 release and later, the MULTIUSERBASEDIR is available. If using MULTIUSERBASEDIR in combination with MIGRATE_USERDATA_DIR=false, the data directories of existing users will not be migrated to the default location however the data directories of users created after migration will be created in the user's default data directory.

Checkpoints

Before the tool performs the migration it verifies the following checkpoints. If the NOTESPATH or CURRENTINIPATH are not valid, migration will stop. If the other settings are not specified or are incorrect, migration will continue.

Note: The MULTIUSERBASEDIR and MULTIUSERCOMMONDIR settings must either both be specified or not be specified at all.

  • NOTESPATH -- Confirms that the setting points to a directory that contains a notes.exe
  • CURRENTINIPATH -- Confirms that the setting points to a directory that contains NOTES.INI, and that the tool has permission to read the NOTES.INI
  • Current data directory -- The tool reads the Notes data directory path from NOTES.INI, and checks the migrate file list to confirm that each file exists in the data directory and that the tool has permission to operate on these files.
  • MULTIUSERCOMMONDIR -- The tool confirms that all users have permissions to read this directory. If not using the default value, it checks that the value includes the %USERNAME% environment variable.
  • MULTIUSERBASEDIR -- Confirms that the setting points to an existing directory and that it tool has read/write permission to that directory.
  • Verifies read and write permissions to access the following registry keys:

HKLM/SOFTWARE/Lotus/Notes/ version/DataPath

HKLM/SOFTWARE/Lotus/Notes/version/MultiUser

  • MIGRATEFILELIST -- Verifies that the files or directories are valid and that it has permission to operate on those files
  • Additional checks for simulated multi-user Notes installation -- If specified, confirms that the following option values are usable during migration: MIGRATE_REGISTRY, MIGRATE_USER_REGISTRY, MIGRATE_SHARED_DIR, MIGRATE_SHARED_FILES, MIGRATE_USERDATA_DIR, and IS_SIMULATED_MODE

If an Allclient kit (single user allclient installation) is detected on the system the tool exits with a message indicating that the source installation is not supported for multi-user migration.

If a multi-user kit (multi-user source installation) is detected on the system the tool exits with a message indicating that the installation is already multi-user.

Procedure -- Editing the configuration file and running the migration tool

After reviewing the considerations and behavioral description of the tool, configure and run the tool as follows.

1. Exit the Notes application; Notes cannot be running during the migration. If Lotus Symphony is installed, it must also be shut down.

2. Locate MUMigrationAssistant.vbs and MUMigrationAssistant.ini in the Utility folder in the Notes install kit.

3. Open the MUMigrationAssistant.vbs script and review its embedded documentation .

4. Open MUMigrationAssistant.ini in a text editor and specify needed values as follows:

CURRENTINIPATH -- Specifies the current NOTES.INI file location, The tool obtains the user's data directory location from their NOTES.INI file. This setting is required; all others are optional.

NOTESPROGRAM -- Specifies where the user's notes.exe resides. If not specified, the tool obtains this value from registry HKLM/SOFTWARE/Lotus/Notes/version/Path first, then from the user's NOTES.INI file.

MULTIUSERBASEDIR -- Specifies where the user's data directory is located. The tool appends Lotus\Notes\Data. If not specified, the default value is CSIDL_APPDATA.

MULTIUSERCOMMONDIR -- Specifies where the common shared data directory is located. The tool appends Lotus\Notes\Data. If not specified, the default value is CSIDL_COMMON_APPDATA. If not using the default value, include the %USERNAME% environment variable.

DRYRUN -- If set to true (default) the tool does not actually run commands but instead generates a report indicating what the tool would have done had you actually run it. If set to false, migration occurs.

Note: The following settings, denoted with an asterisk, are used only when migrating from a simulated multi-user Notes installation where the Notes client is installed in single user mode on one
computer and multiple users are able to use Notes on that computer because their Notes data directory is mapped to H:\, which in turn is mapped to each user's private network share directory.

Note: The following settings can be specified on the cscript command line. If a setting is specified on the command line and in the MUMigrationAssistant.ini file, the command line setting takes precedence.

*MIGRATE_REGISTRY= true/false -- If set to true, migrates HKLM registry settings and updates desktop shortcuts and start menu shortcuts for all users.

Note: This applies to the AllUsers group on Windows and sets the machine registry settings to be multi-user. This is not the per user setting.

*MIGRATE_USER_REGISTRY=true/false -- If set to true, migrates registry settings and updates desktop shortcuts and start menu shortcuts only for the user running the tool.

*MIGRATE_SHARED_DIR=true/false -- If set to true, migrates the common data files to be shared among all users. This moves files that would have been installed to the common shared directory during a Notes multi-user installation.

Note: If other files must also be moved, such as the user's templates, specify them in a file whose location is set to MIGRATE_SHARED_FILES as below.

Note: Use the MULTIUSERCOMMONDIR option to specify the location at which to move the files or leave blank to accept the default.

*MIGRATE_SHARED_FILES = file_name_and_path -- Specifies a text file name and location that contains the names of additional user-defined templates or other files that were not installed by Notes, to move to the target common directory to be shared by all users.

Note: Use with the MIGRATE_SHARED_DIR=true option.

*MIGRATE_USERDATA_DIR=true/false -- If set to true, migrates all of the user's personal data files (for example, user's ID file, templates, databases) to the directory specified by the MULTIUSERBASEDIR option. This can be configured using a command line to run for each user when they first log in to the computer. The option works with MULTIUSERBASEDIR to determine where to move the files. If no value is set for MULTIUSERBASEDIR, the default of C:\Documents and Settings\username\Local Settings\Application Data\Lotus\Notes\Data is used.

Note: Set the value to false if you do not want the user's personal data to be moved.

Note: This value should be set to true for every user. To run the script for every user when they first log in to the OS, create a batch file to run the script in the StartUp Group or the RunOnce registry key.
Use the following external instructions as a guide:
RunOnce information is available at http://msdn.microsoft.com/en-us/library/windows/hardware/ff550714(v=vs.85).aspx.

5. Save and close the MUMigrationAssistant.ini file.

6. Close the MUMigrationAssistant.vbs script.

7. Run the migration in "dry run" mode by enabling the DRYRUN option in the MUMigrationAssistant.ini file and then using the following command line statement:

cscript MUMigrationAssistant.vbs

8. Review the output report and determine if any MUMigrationAssistant.ini file adjustments are required. If so, make them now.

9. Perform the actual migration by disabling the DRYRUN option in the MUMigrationAssistant.ini file and then using the following command line statement:

cscript MUMigrationAssistant.vbs

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 data directory will be that specified by the MULTIUSERBASEDIR variable and the shared directory will be that specified by the MULTIUSERCOMMONDIR variable.

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 in C:\Program Files\IBM\Lotus\Notes.
  • The user's data directory is H:\data.
  • The shared data directory is C:\notes\common\Lotus\Notes\data.
  • The addition files to move are specified in migratefilelist.txt, which consists of the following:

Note: The .txt file resides in the directory from which you run the migration utility.

H:\data\template1.ntf
H:\data\template2.ntf
H:\data\template3.ntf

Migrate users based on your applicable use case as follows:

Note: The following use cases have not been exhaustively tested; if you encounter any issues, especially with the combinations of variables, please report your findings.

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\IBM\Lotus Notes and
data files installed to C:\Program Files\IBM\Lotus\Notes\Data.

Run the MUMigrationAssistant 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\Lotus\Notes\Data.
Migrate the user's data files and NOTES.INI to C:\Documents and Settings\username\Local Settings\Application Data\Lotus\Notes\Data.

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

DRYRUN=true
CURRENTINIPATH=C:\Program Files\IBM\Lotus\Notes\Data\notes.ini
NOTESPROGRAM=C:\Program Files\IBM\Lotus\Notes
IS_SIMULATED_MODE=false
MIGRATE_REGISTRY=true
MIGRATE_USER_REGISTRY=true
MIGRATE_SHARED_DIR=true
MIGRATE_USERDATA_DIR=true
Only for versions 8.5.1 and beyond set the following additional variables.
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 is mapped on a network drive. Program Files are installed to C:\Program Files\IBM\Lotus\Notes and data files are installed to H:\data.

Run MUMigrationAssistant as an administrator to do the following:
Migrate the HKLM registry entries to make it a true multi-user installation.
Migrate the common files to be used by all user to C:\notes\common\Data.

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

DRYRUN=true
CURRENTINIPATH=H:\data\notes.ini
NOTESPROGRAM=C:\Program Files\IBM\Lotus\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 mapped on a network drive. The administrator has migrated the single user settings on the Notes client system to a multi-user mode. (as per Use case 2 above). 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\Lotus\Notes\Data.

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

DRYRUN=true
CURRENTINIPATH=H:\data\notes.ini
NOTESPROGRAM=C:\Program Files\IBM\Lotus\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 to its default value.

Related information

Wiki - Notes and Domino community posts and related doc
Information Center - Notes and Domino product documenta
Lotus Support Portal
Notes Install Cleanup Executable (NICE) tool

Rate this page:

(0 users)Average rating

Document information


More support for:

IBM Notes
Install/Setup

Software version:

8.5.3, 9.0

Operating system(s):

Windows

Reference #:

1459627

Modified date:

2011-10-04

Translate my page

Machine Translation

Content navigation