Lotus Notes Migrations Best Practices

Lotus Notes migrations utilize the Lotus Notes Extractor. Setup and troubleshooting information can be found in the Lotus Notes Extractor FAQ. The following information is useful when setting up and running a migration from Lotus Notes. 

Planning a Lotus Notes Migration

During Lotus Notes migrations, some data is processed and temporarily stored at the Source. Items are discovered in separate pages of 1,000 items. During processing:

  • Each page is processed in batches of 50 items or 5MB, whichever is less
  • Each item processed is temporarily stored in a temporary hidden folder in the mailbox
  • The entire temporary hidden folder is cleaned when one of the following occurs:
    • Each time GetPageOfItems is called (summaries, 1000 items/page)​
    • When it is done with GetFullItems on a batch (only the items in the batch)

The following should be considered when planning migrations because of the constant read, write, and delete actions during item processing: 

  • There will be consistently high disk input/output
  • Fluctuating free disk space
  • Verbose logging can cause excessive resource use as each action is logged
  • Without circular logging enabled, log files might use up free disk space quite rapidly​

Important: Some antivirus programs will block the Lotus Notes Extractor from accessing the Lotus Extractor to Access the Lotus client and mailboxes. It may also prevent the Extractor from reaching back to MigrationWiz. Before beginning the migration, ensure that the Extractor isn't being blocked by your antivirus program.

Set up Lotus Notes administrator account

A single administrative account will be used to migrate all mailboxes. This means there is no need to specify a password for each user's mailbox.

In order to set up an administrator account on the Domino server, proceed as follows:

  1. Open Notes/Domino Administrator.
  2. Select the server where the mailboxes are located.
  3. Go to the Files tab.
  4. Select the folder containing the mailboxes and right-click on it.
  5. Go to the menu to manage access control.
  6. Select the user to be used to perform the migration.
  7. Grant this account sufficient rights to access the mailboxes.

The administrator account will need to have the following included for permissions applied to each nsf file being migrated.

  • Access: Manager
  • Delete Documents: Enabled (This is not a default permission, and must be manually selected, or your Domino server will run out of space very quickly.)

Export a user list

The Lotus Extractor works with the Lotus Client to create a list of all users.  On initial startup, the Lotus Extractor will generate a CSV file named "LotusExtractor.csv" that can be used to bulk import mailboxes for migration into MigrationWiz. This file is automatically generated in the same directory as the Lotus Extractor executable. If the file already exists, it will not be regenerated when opened. If you need to generate a new CSV file, delete the existing one, and restart the Lotus Extractor.This generated file contains all identified user email addresses from the Domino Directory. Our Lotus Notes migration solution requires administrative credentials, so the “Source Username” and “Source Password” fields will not be used in either the LotusExtractor.csv or the Bulk Upload option within MigrationWiz.


  1. Open the folder where the Lotus Extractor has been installed.
  2. Locate the LotusExtractor.csv file.
  3. Copy the LotusExtractor.csv file to the desktop or another location.
  4. Open the copy of the LotusExtractor.csv file from the save location.
  5. Find the column titled Source Email.
  6. Delete all columns except the Source Email column.
  7. Make sure that all the email addresses in the Source Email column are the ones to be included in the migration. Email addresses can be added or removed from this column without affecting the Lotus Extractor.
  8. Save the file.

This can then be copied into the Bulk Add form.

Determining item type association with a Lotus Notes item

We will only migrate items whose type is identified by the Notes subsystem.  To check the item type associated with a Lotus Notes item:

  1. Start your Notes client.
  2. Select a single email.
  3. Click on the File menu.
  4. Click on Properties.
  5. Look for the Form property​.
  6. Checkmark the associated value.

You should see something like this for email:


If the Form property​ is empty, then the item type is not specified, and so we will not migrate the item.

Lotus Notes Resource Rooms

Lotus Domino is unique in that it can store multiple Resource objects within a single database file, also referred to as a Notes Storage Facility (NSF) file. The MigrationWiz Lotus Extractor software cannot directly access the Resource NSF. To facilitate this, a fake person document is created and linked to a copy of the Resource NSF. The Extractor software will access this fake person document, which is tied to the Resource NSF, to pull the data. Within MigrationWiz, a filter is specified for each Resource migration thread so that the proper information is filtered from the NSF and migrated to the Destination.

Migration of Lotus Domino Resource objects requires the following to be taken into consideration:

  • We always recommend migrating Lotus Domino Resource objects at the end of a mailbox migration project plan. For instance, once the MX and mail flow cutover is completed and all users are utilizing the new mail system, we recommend then migrating the Resource object data. This will ensure that the latest Resource data is migrated.
  • Make a new migration project for all the Resource objects you plan to migrate. Within the Advanced Options of this project, set the concurrent migration value to 3 or lower. This setting will ensure that the NSF file is not overloaded on the Domino Source.
  • Be aware that certain steps in this process MAY require a reboot of the Domino environment.

Migration process steps

1. Create the Resource person document. MigrationWiz must have a person document to use as a migration endpoint on the Lotus Domino Source for the Resource objects. In this step, a fake person document will be created which will be used for all Resource user migrations.

  1. Open Lotus Domino Admin and navigate to People & Groups > Domain’s Directory > People. Right-click on People and then click on Register Person.
  2. Under the Basics tab, give the fake person a Firstname, Lastname, and a password. Checkmark the Advanced box, and then click on Address. Assign a unique internet address to the fake person, such as resourcemigrationuser@yourdomain.com. This value will be used in the Source email field within MigrationWiz. Click on Register All.

2. Make a copy of your current Resource NSF. Resource data is predominately calendar-based items. As with all migration guidance, we recommend that the migration of calendar data is always done during the Full Migration pass at the end of your migration plan. Calendar data changes frequently, and if that data is migrated prematurely, you may not migrate crucial changes to these items.
This step needs to be completed at the end of the mailbox migration to ensure that you capture and migrate the latest version of your Resource data.

  1. Locate the current Resource NSF file. Typically this file is located in C:\Program Files (x86)\IBM\Lotus\Domino\data and will be called resource.nsf. Your file and location may vary; to verify the Resource NSF location, open up one of the Resource document files in People & Groups > Domain’s Directory > Mail-In Databases and Resources > Rooms. Within the Resource document, you should see a File name attribute.
  2. Make a copy of the Resource NSF file found in the previous step, and place it into the C:\Program Files (x86)\IBM\Lotus\Domino\data\mail directory. This new file can be renamed if you choose. If the file is renamed, make note of the new name.

3. Link fake person document to Resource NSF copy. MigrationWiz will be using the fake person document as a migration item for migration of the Resource objects. To make this work, the newly created person document must be linked to the Resource NSF file that was copied to the C:\Program Files (x86)\IBM\Lotus\Domino\data\mail directory.

  1. Open up Lotus Domino Admin and navigate to People & Groups > domain’s Directory > People. Find the fake person document that you created, and double-click on the user.
  2. Once the person document is open, click on Edit Person, and navigate to the Mail File attribute. Replace the current mail file entry with the location and name of the copied Resource NSF file. The attribute syntax should be mail\yourfilename.nsf since the Resource NSF file was copied to the C:\Program Files (x86)\IBM\Lotus\Domino\data\mail directory in Step 2 above. Click on Save & Close.

4. Set up ACL entry on Resource NSF copy. The administrator account used to connect the MigrationWiz Lotus Extractor to the Domino server must be given manager rights to the Resource NSF copy to allow the Extractor to pull data from the file. This is typically the account that is used to log into the Domino Admin application.

  1. Open up Lotus Domino Admin and navigate to Files > mail directory folder. Find the Resource NSF file that was created/copied. Right-click on the NSF file and navigate to Access Control > Manage.
  2. Under the Basic tab, ensure that the People, Servers, Groups selection is set to Show All. Within this list, find the user that is being used for the Lotus Extractor local server administrator. Click on this user and set the permissions to Manager and also check mark the box for Delete Documents. Click on OK to set the permissions.
    At this point, a reboot MAY be required of your Domino environment. Attempt to open up the newly linked Resource NSF by going to People & Groups > Domain’s Directory > People. Find the fake person document that was created and had the Resource NSF copy linked to it. Click on the person document and then click on Open Mail File. If the mail file opens up correctly, proceed to the next step. If the NSF does not open, reboot the Domino server.

5. Set up Resource Migration project. A separate migration project for Resource objects should be set up to allow customization to the project that is geared toward Resource migration utilizing the MigrationWiz Lotus Extractor.

  1. Log in to the MigrationWiz portal, and start a new mailbox migration project. Fill out the required fields as requested by the tool. Click on Additional Options at the bottom left of the project creation screen.
  2. Within the Additional Options page, find the Maximum Concurrent Migrations setting and set this to a maximum of 3. Any higher than 3, and there is a risk of potential corruption of data due to overloading of the Source NSF file. Once all settings and credentials have been entered, click Save to complete the project.
  3. Create a Resource object migration entry for each Resource within the NSF.
    • Resource object migration entries within the project will always use the address created from Step 2 of the "Create Resource person document" section above for the Source email field.
    • The Destination email field will be the Destination Resource email address where the objects will be migrated to.
  4. Each Resource migration entry must have a support option customization to filter out the appropriate objects for that specific migration entry. Select one of the Resource migration entries and then click on the Edit icon.
  5. Within each Resource migration entry, a filter must be put in place that will filter objects based on the Resource Name attribute for the specific Resource item. For example, if the Resource Name attribute of a Resource object is "ConferenceRoom1/BitTitan Bellevue", the Resource Name is "ConferenceRoom1", and the Site Profile is "BitTitan Bellevue". Based on this, the following will be entered in the support options field:
    LotusNotesRoomResourceFilter=BitTitan Resource/BitTitan Site Profile
    The logic above would migrate any data found within the Resource NSF copy file that has a Resource name of "ConferenceRoom1/BitTitan Bellevue".
    • A filter is required for every resource migration. Be sure that each resource migration has a filter in place before attempting a migration pass.
    • Remember the Resource Name consists of both the Resource Name value and the Site Profile name it is associated with.
  6. Repeat this procedure for every migration entry in the project, and ensure that the filter put in place is correct for the Destination mailbox you are migrating data into.

6. Start the Extractor and run a Full Migration. The MigrationWiz Lotus Extractor will generate a CSV the very first time it is started for user mapping. The CSV is generated by an exploration of the Domino directory. Once the CSV is generated, it will not be modified or regenerated without first deleting it.

  • The Lotus Extractor requires that you have the .NET Framework version 4.6.1 or later installed on the computer on which you install and run the extractor. To determine the .NET Framework version currently installed, follow instructions provided by Microsoft: How to: Determine Which .NET Framework Versions Are Installed.
  • If you have already run the MigrationWiz Lotus Extractor before this step, it will be necessary to delete the lotusextractor.csv file, which is located in the root directory where the Lotus Extractor was unzipped. Make sure that no migrations are currently processing, and delete the lotusextractor.csv file. Once the CSV file is deleted, restart the Extractor and let it regenerate the CSV file.
  1. Open LotusExtractor.exe and log in with the administrator credentials from the Domino server and the MigrationWiz credentials where the project created in Step 5 was made.
  2. Once the Lotus Extractor is ready for processing, select the migration entries in the project and select Start > Full Migration.

Lotus Notes MIME Content Logging

Lotus Notes MIME content logging can be enabled by adding the following support option within the Advanced Options of a project or user(s):  


Explanation of syntax:

Key = LotusDumpMimeContent

Value = the subject of the email



(This will store the MIME content for all email)


(This will store the MIME content only for email with the subject "Welcome")

The output is dumped to a text file named LotusDumpMimeContent.txt. This file should be attached to any support tickets which involve such troubleshooting of MIME content.

This text file will be in the same folder as the Lotus Extractor that is being used for the project.

It dumps the MIME content for one, several or all email. This is useful to determine if the MIME content was properly generated by the Lotus MIME conversion library.


Syncing Lotus Notes contacts on the Lotus Domino server

Lotus Notes contacts are stored locally on the user’s hard drive (.nsf file). In order to migrate them, each user must have synchronized their personal address book on the Lotus Domino server before performing a migration (or a Full/Delta Pass).

For Lotus Notes 8+ - 9.0.1

Lotus Notes versions after 9.0.1 are not supported.

Each user must proceed with the following on their own machine.

To synchronize contacts manually:

  1. Start the Lotus Notes client and open its session.
  2. From the File menu, select Preferences.
  3. Under the Contacts section, checkmark Enable "Synchronize Contacts" on the Replication and Sync tab.
  4. Click  on OK.
  5. From the Tools menu, select Replicate and Sync All. 
  6. Click Open > Replication, or if Open List is docked, click on the Replication icon.
  7. Make sure that there is a checkmark next to Synchronize Contacts in the Enabled column, and click on Start Now
To synchronize contacts automatically:
  1. Open the Schedule.
  2. Set your Replication Schedule options and define when the replication should occur, when the client starts or is shut down, and click on  OK.​​
  3. Then, under Schedule, select Enable Scheduled Replication for it to take effect.

For Lotus Notes 6 and 7

Each user must proceed with the following on their own machine:

  1. Start the Lotus Notes client and open its session.
  2. From the Actions menu, select Synchronize Address Book.​

Migrating with IBM Lotus Domino DAOS

MigrationWiz uses native APIs to access the IBM Domino mailbox data, and is not affected by whether DAOS service is running or not. Lotus Domino Object and Attachment Service (DAOS), a feature introduced in Lotus Domino 8.5.0, is designed for saving disk space. DAOS extracts attachments from email messages and stores them in a separate location, replacing them with a reference to the stored data. DAOS is completely transparent to C API calls, agents, and LotusScript.

When migrating from IBM Domino to Office 365 and Exchange, make sure that the Lotus Notes mailbox size (mail file size + attachments stored in DAOS) does not exceed maximum mailbox size for Office 365 or Exchange prior to migration.

Mail-in databases and Archive .nsf files

Out-of-the-box MigrationWiz does not support migration of mail-in databases or archive.nsf files. However, with a few configuration steps, MigrationWiz can be configured to support the migration of mail-in databases and archive.nsf files.
Note: The content in this article is specific to Domino mail-in databases, but be aware that this approach is also valid for archive.nsf files. 

A mail-in database must be created using a MAIL type file template, e.g., mail85.ntf, mail9.ntf, etc. Migrations of databases that are created from any other template, that is not a standard Lotus Domino mail-in database template, are not supported.

  1. Create a fake person document on the Domino server.  This fake person is going to be used in the MigrationWiz project when performing the migration.
  2. Make sure the Internet address field is assigned to that person. This internet address will be used in MigrationWiz to identify this migration.
  3. If the LotusExtractor has already been run, delete the "LotusExtractor.csv" file. This file has to be regenerated if any modifications are made in the Domino NAB. Adding an new person is a modification.
  4. Make sure that the administrator account being used for the migration has access to the newly created account. The administrator account will require "Manager" access, including "Delete Documents".
  5. The person's document has to be modified to point the mail file to the mail-in archive to be migrated. After saving "Mail File" modification, the Domino server has to be restarted.
  6. The fake person is migrated as usual, using the regular steps in MigrationWiz.  Make sure to use the fake person's internet address as the Source email address within the migration project. The Destination mailbox will contain the contents of the mail-in or archive database. If calendaring has to be migrated from a mail-in or archive, then the internet address of the fake person in the Domino person document must match the mail-in database internet address. This will require either a MigrationWiz - Mailbox license or a User Migration Bundle license, since this migration is being performed as a mailbox migration.

Support for Lotus Notes

The following configuration should be followed for any Lotus Notes NSF files sent to Support for review. 

Before submitting the NSF file to Support for review, the following must be done to give Support the ability to access the file:

  1. Set the Default and Anonymous users to have manager rights, and checkmark the box for Delete Documents.

  2. Make sure that the file is decrypted.

  3. Compact the database with default settings.?

In addition to performing the above three steps, it is helpful for Support to know which version of Domino the NSF file is being used in. Prior to uploading the NSF to BitTitan's FTP site, please add the Domino version to the NSF file name if possible. Example : If the NSF is Userx.NSF and is being used in the Domino 8.5 environment, rename the file to Domino.8.5.Userx.NSF before uploading. Alternatively, upload an additional .txt file along with the NSF file that includes the name of the NSF file, and the Domino version the NSF file is being used in.?
NSF File : Userx.NSF
Domino Version : 8.5

Was this article helpful?
0 out of 1 found this helpful