Lotus Migrator Server Guide

You must accept the FirstClass License Agreement before you can use this product. If you do not accept the terms of the License Agreement, do not install the software and return the entire package within 30 days to the place from which you obtained it for a full refund. No refunds will be given for returned products that have missing components.

Information in this document is subject to change without notice. Certain features and products described in this document may not be currently available in all geographic regions. Distribution or reproduction of this document in whole or in part must be in accordance with the terms of the License Agreement.

All rights reserved. FirstClass is a registered trademark of Open Text Corp. subsidiary used under license. Open Text, the Open Text logo, and the FirstClass logo are trademarks of Open Text Corp. All other trademarks are property of their respective owners.

This edition applies to Release 7.1 of FirstClass and to all subsequent releases and modifications until otherwise indicated in new editions. This document is bound by international copyright law and the FirstClass Software License Agreement and Limited Warranty included with every FirstClass product.

Technical support

Telephone technical support is available to registered administrators with valid M&S contracts at the following numbers:

Toll free in North America: 1-800-346-9180

Toronto: 905-762-7060

International: +353-61-725-200.

Online support questions may be directed to support@firstclass.com.

Introduction

FirstClass® Migrator for Lotus® Domino/Notes (FirstClass Migrator) is a utility designed to facilitate the migration of Notes address books and databases to FirstClass. It has two running modes: Server Mode and Client Mode.

Server Mode

While running in Server Mode, Migrator can be used to migrate:

• public address books (local or remote)

The Notes accounts contained in the specified Notes public address books will migrate to the FirstClass server as regular users, and the original accounts will be marked as Hidden (meaning the Notes Connector will hide them from the FirstClass Directory) and AutoForwarded (meaning all messages sent to them will be automatically forwarded to the corresponding FirstClass accounts using the Notes Connector).

• shared databases (local or remote).

The content within the specified shared databases will be duplicated into a specified conference/folder residing on the FirstClass administrator's Desktop as folders. You can specify the views and subfolders you'd like to work with in the Database View, and the databases' hierarchical structure will be retained after migrating to FirstClass.

Client Mode

While running in Client Mode, Migrator can be used to migrate:

• private address books (local or remote)

Contacts contained in the specified Notes private address books will migrate into the corresponding FirstClass user's address book as private address book entries.

• personal databases (local or remote).

The content within the specified personal databases will be duplicated into a specified conference/folder residing on the corresponding FirstClass user's Desktop.

You can specify the views and subfolders you would like to work with in the Database View. The databases' hierarchical structure will be retained after migrating to FirstClass. The calendar entries (Meetings and ToDo's) contained in these databases will migrate into the FirstClass user's Calendar folder as Calendar Events and Tasks respectively.

Who should read this book

This book is intended for the FirstClass administrator who will perform the migration on user accounts, public address books, public databases and prepare the client-side of the utility for users.

What you will find in this book

This book describes how to install and use FirstClass Migrator. It also lists the installation requirements.

This book does not document how to use FirstClass, FirstClass Notes Connector or Lotus Domino Server features. For that information, see our online help and applicable product documentation.

What you should already know

This book is intended for administrators who want to copy their Lotus Domino Server information into FirstClass format. We assume you are familiar with your Windows® operating system, Lotus Domino Server, and FirstClass functionality.

Requirements

FirstClass Migrator can be installed on any machine that can reach both the Lotus Domino Server and the FirstClass server simultaneously.

Note

We do not recommend installing FirstClass Migrator on the same machine as the Lotus Domino Server or the FirstClass server.

Minimum installation requirements for FirstClass Migrator:

• Windows 9x/Me/2000/XP

• 64 MB RAM

• 100 MHz Pentium processor (233 MHz processor recommended)

• Lotus Notes 4.6 or higher version installed

Installing FirstClass Migrator

To install FirstClass Migrator:

1 Insert the FirstClass Migrator for Lotus Domino Server CD into the CD-ROM drive.

If the installer doesn’t load automatically:

a Select Run from the Start menu.

b Type drive:\fcnminst.exe where drive is the letter of your CD-ROM drive.

2 Follow the prompts.

Note

To ensure a successful server migration:

• Never run two instances of FirstClass Migrator in Server Mode simultaneously. FirstClass Migrator will prevent two instances of the application running on the same computer, but it is your responsibility to make sure there is only one instance running on the network.

• Always try to run FirstClass Migrator from the same computer because the program settings are saved locally on the computer where FirstClass Migrator is installed.

General Information

This section explains how to start FirstClass Migrator and discusses the user interface and runtime log.

Application command line syntax

To run FirstClass Migrator, click the corresponding shortcuts created by the FirstClass Migrator installer program within the system Start menu, or from the command prompt, type

installation path\fcnm.exe [/Mode:<Server|Client>]

where

• installation path is the folder where you installed FirstClass Migrator

• /Mode is the command line switch to toggle the application's run mode between Server Mode and Client Mode. If omitted, Client Mode is assumed.

Note

In this document, we always assume you run FirstClass Migrator in Server Mode. To run FirstClass Migrator in Server Mode from the command prompt, provide the command line parameter "/Mode:Server".

User interface

After FirstClass Migrator starts you will see the following window:

It consists of three views: Log View, Directory View and Message Database View. The user can switch between them by clicking the corresponding buttons on the toolbar.

Tip

When you resize or reposition the main window, its size and position will be saved automatically, so the next time you run FirstClass Migrator, it will remember your settings.

Log View

The Log View is the default view when FirstClass Migrator starts up (as seen in the above screen). It is a text list that shows the current Runtime Log information.

You can switch to the Log View by choosing View > Log View, or by clicking the toolbar button

The lines in the Log View have the following format:

[Time Stamp] [Log Type] Log Text

where Log Type represents the type of current log information (see the Runtime Log section below for more information).

Note

Not all log lines consist of these three parts: the Text type log line only contains Log Text, while some information lines have no Time Stamp.

Directory View

You can switch to the Directory View by choosing View > Directory View, or by clicking the toolbar button

The Directory View displays the Notes address books you have specified in the Settings Form. It consists of three panes:

Address Book list

The left pane lists all of the Notes address books listed on the Address Books tab within the Settings Form, which will be discussed later. If a specified address book is opened successfully, the icon

will display beside the entry. Otherwise, the icon

will be displayed instead, which means the address book either does not exist or is inaccessible to FirstClass Migrator.

Content list

The top right pane lists the content of an address book when it is selected in the Address Book List. This is a multi-column list which consists of the following columns from left to right:

• checkbox

Can be toggled on/off to indicate whether the current entry will migrate or not during the next migration process.

• type

Various icons that represent different address book entry types (currently we only support the Notes account entries in the public address books and the Contact entries in the private address books.)

• hidden

Indicates whether the current entry is marked as hidden from the FirstClass Directory. If an entry is hidden, the FirstClass Notes Connector will not create the corresponding Remote Name into the FirstClass Directory, and an "H" will be displayed in this column. You cannot check on these hidden entries in the list, since they should have already migrated to FirstClass (it is FirstClass Migrator that marked them as hidden when they migrated before). If for any reason you want to migrate them again, you have to unhide them first by choosing the menu command Edit > Unhide, or by clicking the Unhide toolbar button

• name

The full name of the entry. It is in the format "First_Name Initials Last_Name".

• mail address

Contains the "Forwarding Address" property of the current entry. This property will be modified by FirstClass Migrator as a part of the "AutoForward" operation during its migration.

Property information sheet

The bottom-right pane displays an entry's properties when it is selected in the Content List. Some of these properties are the entry's native Notes properties, which are mostly read-only, while others are about the corresponding FirstClass objects to be created, such as the FirstClass user ID and password. These values are derived from the native Notes properties, but you can modify them as you wish. Some of the more important properties are discussed below:

• Notes Short Name

The value of the Notes "Short Name" property.

• FirstClass User ID

The designated user ID of the FirstClass user account that will be created. The default value is the first entry in the Notes "Short Name" property, if one exists. If no "Short Name" exists the user ID will be set to blank and you have to provide a valid value before its migration.

• FirstClass Password

The designated password of the FirstClass user account that will be created. It is initialized to be the same as the FirstClass User ID field.

• FirstClass Initials

You can change the initials if the specified user name (the full name) already exists in the FirstClass public directory.

• FirstClass OU

The designated FirstClass Organizational Unit that the FirstClass user account that will be created will belong to. (The current version does not support this feature yet.)

Message Databases View

You can switch to the Message Database View by choosing the menu command "View > Message Database View", or by clicking the toolbar button

The Message Database View displays the Notes databases you have specified in the Settings Form. It consists of two panes:

Database list

The left pane is a tree view that shows all of the Notes databases listed on the "Databases" tab within the Settings Form, which will be discussed later. If a specified address book opens successfully, the icon

will display beside the entry. Otherwise, the icon

will display, which means it either does not exist or is inaccessible to FirstClass Migrator.

Content list

The right pane lists the contained messages within a subfolder/view when it is selected in the Database List. This is a multi-column list which consists of the following columns from left to right:

• checkbox

Can be toggled on/off to indicate whether the current entry will migrate during the next migration process

• type

Various icons that represent different message types. Currently we only support plain messages (

), documents (

), meeting events (

), and ToDo tasks(

• from

Sender of the current message.

• subject

Subject of the current message.

• received

Received date/time of the current message.

• migrated.

The migration date/time of the current message if it had been migrated before.

Runtime log

The application runtime log is used to record various information and events that occurred when FirstClass Migrator was run. There are four types of information that will be recorded in the Runtime Log:

• Text: Describes Runtime Log states.

• Info: Describes various application actions, migration tasks and the corresponding results.

• Error: Describes various exceptions or failures the application encountered.

• Warning: Describes various abnormal situations that may result in errors or malfunctions.

You can specify which information you would like the Runtime Log to record by selecting the corresponding log level in the settings form. There are four log levels you may choose from. Each of them will enable some log types while disabling the others.

• Quiet: Only Text will be logged.

• Basic: Both Text and Info will be logged.

• Normal: All information logged at Basic Level plus Errors.

• Detailed: All information supported.

While FirstClass Migrator is running, the logged runtime information will be displayed in the Log View window and simultaneously written into the log file, "fcnm.log", which resides in the application's installation folder. As soon as FirstClass Migrator exits, the file "fcnm.log" will be archived automatically by being renamed in the following format:

FCM_YYYY_MM_DD_hh_mm_ss.LOG

Where YYYY_MM_DD_hh_mm_ss represents the date and time when FirstClass Migrator exited.

Migrating server information

Warnings

• When you migrate user accounts, you are actually creating regular users on the FirstClass server, so it is important to make sure you have enough FirstClass licenses to add these new users. If you do not have enough licenses, some of the accounts may fail to migrate.

• When running FirstClass Migrator, make sure both Lotus Domino Server and FirstClass Notes Connector are running. Otherwise, you will receive errors when launching FirstClass Migrator or during the migration.

• Since FirstClass Migrator relies on the FirstClass FPP service to send the necessary batch admin scripts to the FirstClass server, you must ensure that FPP access is enabled on the FirstClass server. For more information about FPP access, see FirstClass Administrator's Guide.

Migration process

To migrate server information, follow these steps:

STEP 1: Generate a FirstClass Migrator license file

STEP 2: Configure FirstClass Migrator

STEP 3: Select the information to migrate

STEP 4: Migrate the information.

STEP 1: Generate a FirstClass Migrator license file

Whether in Server Mode or Client Mode, FirstClass Migrator needs the FirstClass administrator's password to access the FPP service provided by FirstClass Server. Since this password is critical to system security, FirstClass Migrator lets you encode the password by creating a binary file, called the FirstClass Migrator license file, using the FirstClass Migrator License Generator.

As soon as the license file is created, you must put it into the FirstClass Migrator installation folder before performing any migration tasks. In addition, as described below, you must also specify the created license file in the application settings form.

Note

Usually you only need to create the license file once, and then use it for both the server migration and the client migration. Whenever you change the administrator password, you must generate the license file again.

For more information about using the FirstClass Migrator License Generator to create a FirstClass Migrator license file, see Appendix A: The FirstClass Migrator License Generator program.

STEP 2: Configure FirstClass Migrator

Before starting your server migration, there are a number of application parameters you must specify to customize FirstClass Migrator to suit your environment. These parameters are stored in the FirstClass Migrator initialization file, "fcnm.ini", which is located in the Windows system folder (for example, "\WinNT" for NT, "\Windows" for 9x). Each time FirstClass Migrator is started it will attempt to locate and open this INI file. If it succeeds the settings it contains will load; otherwise, the default settings will load.

Since FirstClass Migrator is to be run in two different modes (Server or Client) it provides two "settings forms", one for each mode. While the Server Mode settings form provides full access to almost all parameters in the INI file, the Client Mode settings form is much more limited. This feature is intended to prevent end users from accidentally modifying sensitive or critical application parameters.

This section will concentrate on the Server Mode settings form. For more information about the Client Mode Settings Form, see the Client section of this document.

Note

Although you can modify the values of the system parameters by editing the INI file directly, we highly recommend setting them through the Settings form to minimize the chance of errors.

1 Start FirstClass Migrator.

If you are prompted for an access password, simply close the prompt window or click Cancel to bypass the login.

Note

You may be prompted more than once if you have specified several address books or databases in the INI file.

2 Configure the application parameters using the Settings form.

To show the settings form, choose File > Settings from the menu, or click the corresponding toolbar button

Server Mode Settings form

There are five tabs within the Settings Form:

General tab

• Log Level

Specify the Runtime Log level you prefer.

• Quiet: Only Text will be logged.

• Basic: Both Text and Info will be logged.

• Normal: All information logged at Basic Level plus Errors.

• Detailed: All information supported.

• Raw mode

FirstClass Migrator has some internal filters used to preprocess the Notes information to make it more user-friendly in appearance. If this parameter is selected, those internal filters will be disabled.

Connection tab

FirstClass

• Server Address

The IP address or network name of the FirstClass server you are migrating to.

• User ID

The user ID of your FirstClass administrator account. The default ID is "admin".

• License File

The filename of the FirstClass Migrator license file that contains the password to the FirstClass administrator's account. The license file has to be in the FirstClass Migrator installation folder. The default filename is "License.cmi".

• Domino Connector Name

The FirstClass gateway name assigned to the Domino Connector. You can find this name within the "Gateways" form that resides on the FirstClass administrator's Desktop.

Lotus Notes

• Server Address

The address of the Domino server in the format of "<server name>@<domain name>".

• FirstClass Connector Name

The Notes foreign domain name assigned to the FirstClass connector.

Address Books tab

• Local Address Books

Filenames of the local Notes address books you want to migrate.

• Remote Address Books

Filenames of the address books on the server you want to migrate.

Note

You can find an address book's filename in its "Basics" database property page, and use the Add, Remove, and Remove All buttons to manipulate the list.

Databases tab

• Local Databases

Filenames of the local Notes databases you want to migrate.

• Remote Databases

Filenames of the Notes databases you want to migrate.

Note

You can find a database's filename in its "Basics" database property page, and use the Add, Remove, and Remove All buttons to manipulate the additional views and folders.

• Additional Views and Folders

The views and folders you want to open for each database in the Databases view.

Migration tab

• Target FirstClass Address Book

The FirstClass container into which the Notes Public Address Book entries will go. This field is read-only and its value is "Desktop" by default, which represents the FirstClass Global Directory.

• Target FirstClass database container

The FirstClass container (conference or folder) into which the Notes shared databases will be duplicated. If omitted, the migrated databases will be directly created onto the FirstClass administrator's Desktop. The default container is "General Conferences".

• Conference/Folder name conflict handling

Determines how FirstClass Migrator will react if the destination folder of a database or its subfolder/view already exists in FirstClass.

When you are satisfied with the settings, close FirstClass Migrator.

Note

Any modification of the application settings will not take effects until FirstClass Migrator restarts.

STEP 3: Select the information to migrate

1 Start FirstClass Migrator in Server Mode. You may be prompted for the access password to the user ID of the user you logged in as last time. If the indicated user ID is not the one you want to use:

a Close FirstClass Migrator.

b Launch the Notes client.

c Switch to the desired user ID.

d Run FirstClass Migrator again.

Note

You may be prompted more than once if there are several address books or databases specified in the INI file.

2 Select the object(s) to migrate.

Tip

To check/uncheck a group of entries quickly in the Address Book/Database list view, you can select the desired entries and then choose the Check/Uncheck command from the menu or click the Check

/Uncheck

buttons on the toolbar.

Warning

There is no internal restriction in FirstClass Migrator to prevent you from migrating a Notes object more than once. It is your responsibility to avoid duplicated migration for a specified Notes object. This issue is especially significant for message migration, since the messages within a database may appear in several subfolders/views simultaneously. To reduce unnecessary message duplication, you should pay special attention when configuring the "Additional Views and Folders" list on the Settings Form, and also when selecting messages within the Message Database view.

STEP 4: Migrate the information

1 Start the migration by choosing the menu command "File > Migrate" or by clicking the toolbar button

2 A progress indicator on the status bar will show you the progress of the migration process.

Note

You can abort the migration process at any time by choosing the Abort menu command, or clicking the toolbar button

3 When the migration is completed, log into the FirstClass administrator account using the FirstClass client to check the migrated objects.

If there are any unexpected results, you can turn to FirstClass Migrator and look for more information in the Runtime Log to see what occurred. Once any issues are addressed, you can migrate any failed Notes objects again.

Note

When in Server Mode, FirstClass Migrator cannot migrate private address book entries.

Migrating client information

The client part of the migration is intended to be executed by end users, using the FirstClass Lotus Domino/Notes Migrator application running in Client Mode. As the administrator, you are expected to prepare the end users so they are able to properly use FirstClass Migrator to migrate their private information. This involves:

• customizing the INI file for the client migration

• distributing necessary files to the end users.

For detailed information about how to use FirstClass Migrator in Client Mode, see the online document "FirstClass® Migrator for Lotus® Domino/Notes Client Guide (version 2.0)."

Customize the INI file for client migration

While running in Client Mode, FirstClass Migrator shares most application settings with the Server Mode, except the "Target FirstClass Containers" parameters. This makes the customization of the Client Mode much easier, since you need only modify a few of the settings provided you have already set up the Server Mode successfully.

In order to prevent end users from changing critical parameters (for example, FirstClass Domino Connector names, Additional Views and Folders, and so on) by accident, the Client Mode Settings form is limited. This limitation makes it necessary for you to define some Server Mode settings in advance that end users will not have access to.

To create a template INI file for the client migration:

1 Install the FirstClass Migrator application on a separate machine and set up the Server Mode appropriately with the Server Mode Settings form.

If you have already set up FirstClass Migrator to perform the server migration and want to use the same copy to generate the Client Mode INI file, you should back up your current INI file first, so after creating the template INI file for the client migration you can recover the previous settings to continue the server migration.

2 Make any necessary changes within the Client Mode Settings form. This mainly involves the specifications of the Log Level and the Target FirstClass Database Container.

3 Perform a test client migration with the template INI file you just created to ensure it works properly.

Distribute files to the end users

The necessary files for a successful client migration include:

• the FirstClass Migrator executable file (fcnm.exe)

• client document

• FirstClass Migrator license file

• template INI file for the client migration

• (optional) a guideline for end users who will be customizing FirstClass Migrator to further suit their personal environments, such as instructions to set up remote/local address books, databases, and so on.

Tip

You can arrange the client migrations in a parallel manner to improve migration efficiency. For example, you can arrange for 10 clients to begin their migrations on 10 computers at the same time. It will greatly reduce the time required to complete the entire client migration project.

Considerations

• Each time FirstClass Migrator completes a migration process, it refreshes the Directory View and the Database View by reloading all of the Lotus Notes information. This means that all custom settings will be lost.

• You have to click OK after typing the password. Pressing Enter may not suffice.

• FirstClass Migrator does not support Notes Mail Group objects migration yet.

• All double quotation marks (") within the message subject and recipient addresses will be replaced with single quotation marks (').

• When migrating Notes accounts, you may receive errors (for example, 1031: eAlreadyReg - you have attempted to add a user with the same user ID as an existing user, and so on). Check your errors against the FirstClass Error Messages Reference in online help for more detail about the specific error.

• Only part of the Contact information will currently be migrated. This will be addressed in a later release. The information that will be migrated includes: First Name, Middle Name, Last Name, Email, Office Phone, Office Fax, and Business address.

• After migrating Tasks/To-Do, the time values may be inaccurate. However, the date value will be accurate.

Troubleshooting

Q: The Migrator always fails to complete some operations during migration, such as setting the message recipient list or migrating user accounts. How do I determine where the problem is?

A: First, make sure the FPP is functional. FirstClass Migrator needs to send batch admin scripts up to the FirstClass server occasionally to perform some special operations. By default, the FPP is disabled by the FirstClass server. You have to enable it manually before any migration attempts. Read the related FirstClass documents for more information about FPP.

Note

FirstClass Migrator will by default use FPP port 333 to establish the FPP connection. If your FPP port setting is different, you have to modify the corresponding key value manually in the FCNM.INI file.

Q: On the Settings form, I specified several shared Notes databases to migrate. However, FirstClass Migrator cannot open some of them because each database requires a different user ID to access it. Is there a way to specify which user ID to use to open the corresponding database in the Migrator?

A: No. You have to make all of those databases accessible to a specific user ID that FirstClass Migrator will use.

Appendix A: The FirstClass Migrator License Generator program

The FirstClass Migrator License Generator (License Generator) is used by the FirstClass Lotus Notes Migrator to generate a license file to encode and transfer the FirstClass administrator password.

You need to distribute the generated license file, along with the FirstClass Migrator application, to end users to enable client migration functionality.

It can be run as a GUI application or as a simple command line tool.

GUI mode

To run the application in GUI mode:

1 Run the GenLic.exe application.

2 Enter the FirstClass Admin password.

3 Re-enter the password to confirm it.

Note

The only restriction on the password fields is that they cannot be blank.

4 Save the file with a desired name.

You can also specify the folder where this file will be located.

Command line mode

Run the License Generator using the following syntax:

GenLic.exe password filename

where

password is the FirstClass administrator password

filename is the name you are assigning to the file. It is an optional field. If omitted, the default name "license.cmi" will be used.

The file will be stored in the same location as the GenLic.exe application.