Installing & Running the Extractor

Lotus Notes is the only messaging system supported by MigrationWiz that requires installation of local client software to perform a migration. The Lotus Extractor is a small console application (available here) responsible for extracting data from the Domino server, and securely streaming this data to your MigrationWiz web portal.

The Extractors need to be set up on physical or virtual machines that are part of the customer's Local Area Network. The Lotus Extractors will communicate directly with the Source Lotus Notes or Domino servers. The Lotus Extractor will then be used for the communication to BitTitan servers. Communication to BitTitan occurs as follows: 

• To BitTitan MSPComplete and MigrationWiz platforms to retrieve the endpoints and submitted mailboxes.
• To one or more migration servers in the cloud (to receive migration commands and push Lotus Notes data).

The diagram below provides an overview of this mechanism.

     

This method is best suited to large-scale migrations, intended for large businesses and distributed environments.

• There is no need for additional connectivity for additional Lotus Extractors, like external IP addresses, since the communication is initiated by the Extractor.
• We recommend that customers do not work with their mail files during the migration. We also recommend that custom Domino agents, if any, working with mail files, are stopped during the migration to avoid document locking.
• Install one Lotus Extractor per machine (or virtual machine). MigrationWiz can migrate up to 15 mailboxes per Extractor. ​Each running Lotus Extractor requires a separate endpoint in MSPComplete and a separate machine (or virtual machine).​​

Prerequisites

To run Lotus Extractor, you need to have the following:

• A MigrationWiz account
• A Lotus Notes administrative account
• Web access
• Recommended hardware: 3.0 GHZ Quad Core processor or better. 
• A Windows-based computer that is not the Lotus Notes server
  • An ideal configuration would be 8+ GB of RAM with Windows 7 or Server 2008+
• The machine you run the Extractor on can be either 32-bit or 64-bit
• .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​​.​
• Lotus Notes v6.5+ client installed. We only support migrations from Domino Server v6.5 to v9.0.1.
• The Lotus Extractor will require ports 80 and 443 to be open.
• Free disk space for saving Lotus Extractor logs
  • The size of the required free space may be estimated using the following formula: 100MB + 50MB * (number of mailboxes to be migrated). For very large mailboxes (10GB or larger), the log file size per mailbox may reach 100MB.

Important Details:

• The Lotus Extractor cannot be run on a machine with Domino Administrator or any Lotus Server components installed.
• Depending on system and server resources, Lotus Extractor can migrate up to 15 concurrent mailboxes per instance.
• Multiple Extractors can be set up to support your migration from Lotus Notes, or Lotus Domino, to Destinations, such as Office 365. However, only one instance of Lotus Extractor can run per physical or virtual machine.
• Because each Lotus Extractor Identifier is unique, each Lotus Extractor requires its own MigrationWiz endpoint and its own mailbox migration project in MigrationWiz.
• When running Domino on A/S 400, we recommend first running a proof of concept to validate that your A/S 400 version is supported. Our QA department has not tested all versions of A/S 400, so we cannot guarantee that all are supported.

Setting up the Lotus Extractor

Follow these steps on each machine that will run a Lotus Extractor:

1. Install the Lotus Notes client on the machine (or virtual machine).
2. Open the Lotus Notes client and log in with the same administrative account that was set up for migration.
3. Retrieve the ID file for the administrative account being used for migration and copy it to the machine (or virtual machine).
4. Ensure that the Internet proxy settings are correct on the machine (or virtual machine). If you are unable to connect to the internet with this option disabled, contact the network administrator to allow the Lotus Extractor.
5. Close the Lotus Notes client. This will release the lock taken by the Lotus Notes client on the notes.ini file.
6. Install the Lotus Extractor. It is available for download here.
7. Once installed, start the Lotus Extractor.
8. Each Lotus Extractor displays a unique identifier called Lotus Extractor Identifier, which can be found near the top of the .exe window. See the screenshot below. Copy this identifier, because it will be needed later, during the migration configuration.

   

9. Enter your BitTitan account username and password.
10. Enter the password of the Lotus Notes administrative account that was created for migration.

Important:

• Each Lotus Extractor can simultaneously migrate up to 15 mailboxes. Therefore, once you have set up your MigrationWiz mailbox migration projects, you should go into Advanced Options and set the number of concurrent migrations to 15. This is explained in your migration guide.
• Deploy each Lotus Extractor within the same Local Area Network where its target Lotus Domino server is located.
• Do not deploy a Lotus Extractor on a machine on which the Lotus Domino server is deployed.
• In the case of clustered Domino servers set up with replication enabled, a single Domino server has to be selected as a source of data for all migration activities using MigrationWiz.
• Do not deploy more than one Lotus Extractor on the same machine.
• Do not stop a running Lotus Extractor. Leave the console window open; the migration will start automatically after the last step of the configuration.
• After authenticating, the Lotus Extractor will generate a CSV file named "LotusExtractor.csv". This can be used to bulk add users within your MigrationWiz project.

Manual installation

The Lotus Extractor used to perform Lotus Notes migrations is auto-updating, and should check for and install the most recent versions when they are available. In some instances it may be necessary to manually reinstall the Lotus Extractor. To manually install the current version of the Lotus Extractor:

1. Navigate to location %UserProfile%\appdata\local on the extractor machine.
2. Rename the folder LotusExtractor to LotusExtractor.old.
3. Download the Lotus Extractor.
4. When creating a new mailbox migration project, after selecting a Lotus 6.5+ Source endpoint, click on the Download The Lotus Extractor Agent button.
5. When editing an existing Lotus 6.5+ migration project, select the Source Settings properties, and click on the Download The Lotus Extractor Agent button.
6. Use the Lotus Extractor shortcut created on the desktop as the only method of launching the Lotus Extractor.

Lotus Notes Extractor FAQs

Security

MigrationWiz is used by the most secure organizations including healthcare, government and banking institutions. The Lotus Extractor communicates with MigrationWiz web services using HTTPS. All communications with MigrationWiz web services are therefore encrypted and authenticated using SSL.

The Lotus Extractor also communicates with a set of secure migration servers. For this purpose, the Lotus Extractor sends and receives data over HTTP. Note that HTTP is a non-encrypted (clear text) communication channel. However, the Lotus Extractor encrypts all mailbox data using military-grade AES encryption when communicating over this IP-based channel (for which SSL certificates are not available).

The key used to encrypt mailbox data is specific to each Lotus Notes connector. This ensures that all communications can only be decrypted by two parties: the Lotus Extractor and peered migration servers. MigrationWiz uses 256 bit AES keys to encrypt the data, providing connector-specific military-strength encryption to all mailbox data.

During initialization, the Lotus Extractor will request both MigrationWiz and Lotus Notes credentials. Any specified password is masked during input so as to protect the confidentiality of your data. Credentials you specify are kept in memory but never saved to disk. As a result, you must provide credentials each time you restart the Lotus Extractor.

Finally, the Lotus Extractor is built from source code and zipped as part of our build process. Therefore, no human intervention is required in order to generate the Lotus Extractor executable and its corresponding zip archive. This eliminates risks associated with manual generation of zip archives (including embedding of a virus or Trojan).

Stability & Performance

The BitTitan Lotus Extractor uses the IBM Notes client library to access data within a mailbox. As a result, the stability and performance of the Lotus Extractor is highly dependent on the IBM Notes client library. Consequently, since the IBM Notes client library only supports single user access, so does the Lotus Extractor.

Accessing multiple user mailboxes from the same process causes the library to crash because it was never designed for concurrent access. Though, in order to ensure scalable migrations, the BitTitan Lotus Extractor must be able to migrate multiple user mailboxes concurrently.

To deal with this limitation and achieve a higher number of concurrent migrations, the Lotus Extractor spawns multiple processes, each loading a unique copy of the IBM Notes client library and each of which, in turn, access a single mailbox. Unfortunately, even this does not fully limit the opportunity for crashes within the Notes client library because it uses shared memory.

The Lotus Extractor attempts to detect such crashes and restart automatically. However, in some situations, crashes are frequent enough to penalize the migration. Sometimes this can even require a full machine reboot to clean shared memory. Therefore, we recommend migrating one mailbox per Extractor and slowly increasing the concurrent migration count to find the "sweet spot" which maximizes total throughput without crashing. A maximum of 15 mailboxes can be migrated per Extractor.

Note: Deploying the additional Lotus Extractor on different physical or virtual machines is a safe way to resolve this issue. 

Proxied Connections

Lotus Extractor supports proxied connections to the Internet.

1. If a proxy server does not require authentication, Lotus Extractor does not require any modifications to work. Make sure that under "Internet Options" -> "Connections" tab -> "LAN Settings", a checkmark is set beside "Automatically Discover Settings".

2. If an internet connection is established through a proxy server requiring credentials, a separate plain text file entitled "ProxyCredentials.txt" has to be created and placed in the same directory where LotusExtractor.exe was unzipped. The first line should contain the URL of the proxy server, the second line should contain the full username, and the third one a plain password, for example:

http://proxyserver:8080/
CORP\testuser
mypassword

Setting US-only IP addresses

The Lotus Notes Extractor uses IP Checking from non-US-based IP addresses. In extremely strict environments, this may cause the Extractor to function incorrectly.​

​To bypass this IP check, add <add key="IsDev" value="false"/>​​​​ as an entry to the LotusExtractor.exe.config file, which is located in  %localappdata%\LotusExtractor on the migrating machine.

This config file edit needs to be added below the following line:

<appSettings>
<!-- Version -->
<add key="IsDev" value="false"/>​​

The end result appears like this:​​​​

Now, save the file and run the Extractor.​

Troubleshooting

How many mailboxes can be migrated at a time?

You can migrate up to 15 mailboxes simultaneously. Once you have created your migration project, go to MigrationWiz advanced options and set the number of concurrent migrations to 15. 

Where should the Lotus Extractor be deployed?

Deploy the Lotus Extractor to the same local area network where the target Domino server is located. However, do not deploy the extractor to a computer on which the Domino server is deployed.
Deploy no more than one extractor instance to a given computer.

The Lotus Extractor just disappears

Historically when this happens we see there is nothing in the logs leading up to the crash. For this, we will have you run an extractor in a PowerShell session with transcribing enabled which should catch what is happening at least in the shell leading up to the crash. To do this, open a PowerShell session on the extractor machine and run the following:
Open the Lotus Extractor to make sure you have the latest version. Once the version is determined

Start-Transcript
cd $ENV:APPDATA
cd LotusExtractor
$name = Get-ChildItem | ?{$_.name match "App"} | sort -Descending | Select -First 1
cd $name.name
.\LotusExtractor.exe

This will start the transcript in the PowerShell session. If the extractor dies, run the following:

Stop-Transcript

This will let you know where the transcript is located. Please navigate to that location, zip the transcript .txt, and reply to this ticket with that .zip file attached.

Navigate to the %localappdata% directory on the extractor, add the entire BitTitan folder to a .zip file, include the name of the extractor in the zip file name, and add it as an attachment to your Support ticket. If the files are larger than 20MB, please contact Support and let them know you need an FTP location created to upload the logs.

The Shared Memory error

The "Shared Memory from a previous Notes/Domino run has been detected, this process will exit now" error thrown during migrations occur due to the Lotus Notes Client being built using a shared-memory architecture. This means the Lotus Notes Client creates a shared memory space when it runs.

The Lotus Extractor uses the Lotus Notes Client library to perform migrations, during which the Lotus Notes Client writes to the shared memory space created. Unfortunately, portions of the shared memory space being used by one thread can get overwritten by other threads before the original thread is done, or the shared memory block can become corrupted, but the Lotus Notes Client still tries to use the shared memory space.

In either case, the only way to clear the shared memory space is to follow the steps here when the "Shared Memory from a previous Notes/Domino run has been detected, this process will exit now" is thrown.
If the error is thrown and the OK button is clicked the error window will close, but the same shared memory space is still being used. This is why after clicking the OK button the error may not come back but migrations will eventually fail even though the extractor looks like it is processing migrations. If the steps are not followed, the error will eventually come back up.

Items causing issues

Delivery Failure Report Messages and Calendar/meeting update items (i.e. meeting cancellation, meeting acceptance, meeting date/time update, etc.) cannot be migrated by MigrationWiz. If either of these message types are in a folder, it will slow down the processing time substantially, and may cause the `GetFullItems` or `GetAllItems` command to not return anything within the timeout threshold for the command, causing this error and failing the migration. There are two ways to resolve or prevent this error:

1. Delete all of the Delivery Failure Report Messages and Calendar/meeting update items from the source mailbox, or;
2. Create a new folder to move these items into, and filter out that folder from the migration. Instructions for this process can be found here.

Having a lot of corrupt items in the Inbox folder.

MigrationWiz will attempt to repair corrupt items the best it can but is not always able to repair corrupted items. Corrupted items also take a lot of time to process before they are determined to be too corrupt to fix and moving to the next item, causing the `GetFullItems` or `GetAlltems` command to not return anything within the timeout threshold for the command, causing this error and failing the migration. Have your Domino Admin run an offline defrag of the NSF file, or a FixUp against the end-users NSF file on the source Domino server then re-submit the migration.

Having too many items in the Inbox folder. 

If there is a very large number of items in a folder, lets us Inbox as an example folder, the `GetFullItems` or `GetAlltems` command may fail to return anything within the timeout threshold for the command and cause this error, failing the migration. If there are more than 20,000 items in the Inbox folder you will need to create sub-folders under the Inbox folder and distribute the content of the Inbox folder equally across the number of sub-folders created. I would recommend not putting any more than 15,000 items in each sub-folder. An example would be if an Inbox folder has 60,000 items in it, you would:

1. Create 4 subfolders under the Inbox folder named something like Inbox-1, Inbox-2, Inbox-3, and Inbox-4

2. Move 15,000 items from the Inbox to Inbox-1, another 15,000 items from the Inbox to *Inbox-2*, etc., until all items are distributed across all 4 sub-folders equally. Note: Move the items, do not copy them.

3. Reset statistics. 

Having a lot of large items in a folder.

Having a lot of large-sized items in a folder, lets use Inbox as an example folder, can cause GetFulltems failures as well. If this is the case:

1. 1. Create subfolders under the Inbox folder named something like Inbox-LargeItems-1, Inbox-LargeItems-2, etc.

   2. Sort items in the Inbox folder by size in descending order

   3. Move all items, say, larger than 10MB, equally distributing them, to the newly created subfolders

   4. Follow the process in our knowledge base article [How do I reset statistics for my item(s)?](https://help.bittitan.com/hc/en-us/articles/115008259728-How-do-I-reset-statistics- Re-submit the migration

Multiple extractors and large concurrent migrations

Multiple extractors can alleviate some issues and provide higher migration value, however, there are some things to consider, the biggest being not to over-submit the number of migrations that can be handled per Domino servers themselves, and the other that there should be no more than 3 extractors pointed to a single Domino server, with no more than 5 migrations running on any of those extractors at any given time.

Each instance of Lotus Extractor requires a separate mailbox migration project in MigrationWiz.

A common misconception is that the more extractors being used the more throughput can be gained during Lotus Notes migrations. The bulk of migrations are processed on the Domino server itself, such as copying items, performing item conversion, cleaning up copied and converted items, then process the next batch of items, consistently. This means if there are 8 migrations processing all at the same time, the Domino server resources are going to be heavily used and in most cases, the resource will be exhausted if too many migrations are run concurrently.

The number of concurrent migrations needs to be determined on a per-migration basis, meaning, if migrations are coming from a Domino Server DOMSRV01, then it will need to be determined how many migrations can be done on DOMSRV01 concurrently. This may be a bit painful because the process is to do a single migration and wait for it to complete, then determine how the performance was. If the performance is good, increase the Maximum number of concurrent migrations of a MigratoinWiz project from 1 to 2, submit 2 migrations and let them complete, then determine how the performance was. If the performance was good, increase to 3, let 3 migrations complete successfully and determine how that performance was, etc., increasing the number to find out what a good number of concurrent migrations is. If the number is 6, and you are using 3 extractors, then you should have no more than 2 migrations per extractor at any one time. If the number is 4, then only run 4 at a time across multiple extractors, or 4 on one extractor if it is easier to track that way.

The bad news here is that if running 1 migration works and running more than 1 crashes or causes problems, you will need to run 1 migration at a time. If it is one particular migration causing problems, such is the case you seem to be having, you will want to run the trouble migrations 1 at a time, with no other migrations running from any other extractors pointing to that Domino server until those migrations are completed.

Domino servers of version 10 or higher are not supported as a MigrationWiz migration source.

Why are there frequent updates being made to the Lotus Extractor?

The Lotus Notes Extractor is part of a larger system which is built using "Continuous integration". The larger system depends on other supporting libraries (logging, reporting etc.), which must be rebuilt continuously to remain synchronized.

The entire system is deployed at once, which results in the daily updates.

Is there any way to make the Lotus Notes Extractor more self healing? 

We have added significant code to try to react to certain errors that are thrown by the IBM Lotus Notes Client itself (unfortunately we do not have control over this library)

In some cases we are able to reset the connection and retry the request.

Have you ever set up the Lotus Notes Extractor to restart itself on a regular basis using PowerShell or batch? 

Currently we don't have any evidence that periodic restarts are going to give a benefit but this is also something that could be implemented at the customer-VM level.

The architecture of our software is such that we actually start a new Windows Process for each mailbox extraction so this gives us a level of protection.

Unfortunately the IBM client does use Windows shared memory so this can cause issues between those processes. Sometimes Windows has trouble killing these processes.

In such cases we recommend a full reboot in order to clear out any IBM Lotus Notes process, threads or blocks of shared memory as the best remediation strategy.