googleapps notes migration

Google Apps Migration forLotus NotesInstallation & Administration Guide

• Google Apps Premier Edition• Google Apps Education Edition

Copyright, Trademarks, and Legal

Google, Inc.1600 Amphitheatre ParkwayMountain View, CA 94043www.google.com

Part number: IAG_GAMLN_R208_2

September 18, 2009

© Copyright 2009 Google, Inc. All rights reserved.

Google, the Google logo, Google Message Filtering, Google Message Security, Google Message Discovery, Postini, the Postini logo, Postini Perimeter Manager, Postini Threat Identification Network (PTIN), Postini Industry Heuristics, and PREEMPT are trademarks, registered trademarks, or service marks of Google, Inc. All other trademarks are the property of their respective owners.

Use of any Google solution is governed by the license agreement included in your original contract. Any intellectual property rights relating to the Google services are and shall remain the exclusive property of Google, Inc. and/or its subsidiaries (“Google”). You may not attempt to decipher, decompile, or develop source code for any Google product or service offering, or knowingly allow others to do so.

Google documentation may not be sold, resold, licensed or sublicensed and may not be transferred without the prior written consent of Google. Your right to copy this manual is limited by copyright law. Making copies, adaptations, or compilation works, without prior written authorization of Google. is prohibited by law and constitutes a punishable violation of the law. No part of this manual may be reproduced in whole or in part without the express written consent of Google. Copyright © by Google, Inc.

Postini, Inc. provides this publication “as is” without warranty of any either express or implied, including but not limited to the implied warranties of merchantability or fitness for a particular purpose. Postini, Inc. may revise this publication from time to time without notice. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you.

GD Graphics Copyright Notice:

Google uses GD graphics.

Portions copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000 by Cold Spring Harbor Laboratory. Funded under Grant P41-RR02188 by the National Institutes of Health.

Portions copyright 1996, 1997, 1998, 1999, 2000 by Boutell.Com, Inc.

Portions relating to GD2 format copyright 1999, 2000 Philip Warner.

Portions relating to PNG copyright 1999, 2000 Greg Roelofs.

Portions relating to libttf copyright 1999, 2000 John Ellson ([email protected]).

Portions relating to JPEG copyright 2000, Doug Becker and copyright (C) 1994-1998, Thomas G. Lane.

This software is based in part on the work of the Independent JPEG Group.

Portions relating to WBMP copyright 2000 Maurice Szmurlo and Johan Van den Brande.

Permission has been granted to copy, distribute and modify gd in any context without fee, including a commercial application, provided that this notice is present in user-accessible supporting documentation.

This does not affect your ownership of the derived work itself, and the intent is to assure proper credit for the authors of gd, not to interfere with your productive use of gd. If you have questions, ask. “Derived works” includes all programs that utilize the library. Credit must be given in user-accessible documentation.

2 Google Apps Migration for Lotus Notes Installation & Administration Guide

http://www.google.com

This software is provided “AS IS.” The copyright holders disclaim all warranties, either express or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose, with respect to this code and accompanying documentation.

Although their code does not appear in gd 1.8.4, the authors wish to thank David Koblas, David Rowley, and Hutchison Avenue Software Corporation for their prior contributions.

Google Compliance Policies Notice:

Google assumes no responsibility in connection with the Compliance Policies lexicon-filtering feature, including any failure to recognize credit card or social security numbers that do not follow an applicable pattern as established in Postini’s systems or any failure to encrypt a credit card or social security number.

3

Contents

Introduction.......................................................................................................... 7About this guide..................................................................................................... 7

Chapter 1: Overview............................................................................................ 9Features ................................................................................................................ 9Mail Migration ........................................................................................................ 9Calendar Migration .............................................................................................. 10Contacts and Group Migration............................................................................. 10

Chapter 1: Architecture and Deployment Options ......................................... 11Architecture ......................................................................................................... 11Deployment Options ............................................................................................ 13

Chapter 2: Installation....................................................................................... 17Google Apps and System Requirements ............................................................ 17Things to do Before you Install Google Apps Migration for Lotus Notes ............. 18Create the Administration Database.................................................................... 22Configure the Administration Database ACL....................................................... 23Configure the Administration Database............................................................... 24Configure Your Sites ........................................................................................... 29Register Users..................................................................................................... 43Uninstalling the Migration System ....................................................................... 48

Chapter 3: Managing Your Migration............................................................... 49Activate Users ..................................................................................................... 49Mail Templates .................................................................................................... 52Manage User Mail Files....................................................................................... 56Monitor Migration Times and Database Size....................................................... 58

Chapter 4: Administration Tools...................................................................... 59Change a User’s Status....................................................................................... 60Change a User’s Location and Time Zone .......................................................... 60Toggle the Processed Flag for Folders ............................................................... 61Set a Google Apps Password for One or More Users......................................... 62Set Migration Cutoff Dates .................................................................................. 62

Contents 5

6

Toggle Migration Processing Status for Document Types .................................. 63Reset Google Tokens ......................................................................................... 64Actions-Menu Agents .......................................................................................... 64Open a User’s Mail Database ............................................................................. 66

Chapter A: Extended and Mixed-Character Support ..................................... 67

Chapter B: Working with the GAMLN API....................................................... 71

Chapter C: Custom Settings ............................................................................ 73

Chapter D: Handling CAPTCHA Challenges................................................... 75

Chapter E: Troubleshooting............................................................................. 77

Index................................................................................................................... 81

Google Apps Migration for Lotus Notes Installation & Administration Guide

Introduction

About this guide

This guide is provided to help you understand and implement Google Apps Migration for Lotus Notes.

What’s in this guide

This guide contains the following information:

• An overview of the features and functionality

• An explanation of the architecture and how information is migrated

• Instructions for installing and then configuring the application

• Troubleshooting tips

Who should use this guide

This guide is intended for the administrators who are responsible for the installation and management of Google Apps Migration for Lotus Notes. Those administrators need to have a thorough understanding of Lotus Notes administration.

Where to find the latest version of this guide

Google continually enhances its products and services, so the content of this guide will change from time to time. To ensure you have the most up-to-date version of this guide, go to:

http://www.google.com/support/a/bin/answer.py?answer=67780

7

http://www.google.com/support/a/bin/answer.py?answer=67780

How to provide comments about this guide

Google values your feedback. If you have comments about this guide or suggestions for its improvement, please send an email message to:

[email protected]

In your message, be sure to tell us the specific section to which your comment applies.

Thanks!

Disclaimer for Third-Party Product Configurations

Parts of this guide describe how Google products work with Lotus Notes and the configurations that Google recommends. These instructions are designed to work with the most common Lotus Notes scenarios. Any changes to Lotus Notes configuration should be made at the discretion of your Lotus Notes administrator.

Google does not provide technical support for configuring mail servers or other third-party products. In the event of a Lotus Notes issue, you should consult your Lotus Notes administrator. GOOGLE ACCEPTS NO RESPONSIBILITY FOR THIRD-PARTY PRODUCTS. Please consult the product's Web site for the latest configuration and support information. You may also contact Google Solutions Providers for consulting services and options.


Overview Chapter 1

Google Apps Migration for Lotus Notes (GAMLN) is a native IBM Lotus Notes application that you install on an IBM Lotus Domino server running on Microsoft Windows. Once you install GAMLN, you can then migrate Notes users and Mail-In databases to Google Apps. Migration includes mail, calendars, contacts, and groups.

The following sections outline the general features of the application, as well as functionality specific to mail, calendar, and contact/group migration.

Features

Unattended migration. Information is migrated to Google Apps by a set of scheduled agents that run in the Migration Administration database.

Multiple methods of user registration. You can register users one at a time, by server folder, by invitation, or via the Domino Directory.

Automatic provisioning of Google Apps accounts. If Notes users do not already have Google Apps accounts, those accounts are provisioned during migration.

Incremental updates. Users can continue to work with their Notes mail during migration.

Event and exception logging for each user.

Support for multiple time zones.

Invitations and notifications.

Mail Migration

Support for all Notes mail and attachments.

Support for Notes document, view, and database links.

9

Support for exclusion folder so users can exclude messages from migration.

Messages, contacts, and calendar entries are marked with update status during migration.

Logging for number of messages transferred and size of transfer per user.

Notes mail addresses are converted to Gmail addresses.

Folder names in Notes are mapped to labels in Gmail.

Follow-up flags in Notes are mapped to stars in Gmail.

Calendar Migration

Support for meetings, reminders, and all-day events, including single-instance and recurring events, and calendar-notification events.

Support for calendar privacy flags.

Support for Notes document, view, and database links.

Contacts and Group Migration

Note: To migrate contacts and groups successfully, users need to synchronize their mail files and personal address books prior to the migration.

Contact details and private groups are migrated for each user’s mail file.


Architecture and Deployment Options Chapter 1

Architecture

This section covers the primary architectural components, and the hierarchy employed to implement and manage data migration.

Components

Google Apps Migration for Lotus Notes comprises the following primary components. The components taken together are referred to as the migration server.

• Administration Database This native Notes database (Migration Administration) contains the configuration details.

• Feeder Databases These databases are the staging areas wherein Notes mail is converted to MIME, and then transformed to the XML format required by the Google Email Migration API. Feeder databases also manage the migration of calendar and contact information. A feeder database processes one user at a time. When you implement multiple feeder databases, the databases work simultaneously. For example, if you implement 10 feeder databases, then you can process 10 users at one time.

• Agents

• One agent (Check Feeders) runs in the administration database. This agent creates the feeder databases, and also creates a Mail-in database document in your Domino directory for each feeder database. If you delete a feeder database or Mail-in database document, this agent recreates them. This agent runs every 60 minutes by default.

• Agents (Migrate) in each feeder database carry out the data migration for each user who has been registered and activated in the administration database. This agent runs every 30 minutes by default.

11

The following diagram illustrates how the components work together:

During migration, a crawler in the feeder database scans each registered mail file and extracts mail, contact, and calendar details. Mail is transformed to XML for delivery to Google Apps. Contact and calendar details are delivered directly to Google Apps without undergoing transformation.

The system creates three views in each mail file so you can monitor the migration process. The views are created in the Migration Status folder; there is one view each for Calendar, Contacts, and Mail.

Management Hierarchy

Google Apps Migration for Lotus Notes employs the following hierarchy to let you implement and manage the migration of Notes data to Google Apps.

Global Settings

At the top level of the hierarchy, you define global settings, which include:

• Global migration status

• Global administrators

• Administration server

Global settings must be completed when you first install the system.

For a full discussion of global settings, see “Configure the Administration Database” on page 24.

Site Settings

At the second level of the hierarchy, you define site settings, which include:

Lotus Notes User Feeder Database

Administration Database

Google Apps

Mail Transformed Data

Configuration Settings Logs & Statistics

Calendar & Contacts

Calendar & Contacts


• Site location

• Site administrators

• Migration start/end date for this site

• Mail servers and the migration server for the site

• Default settings for each newly registered user

You must define at least one site profile before migration can begin.

For a full discussion of site settings, see “Configure Your Sites” on page 29.

Users

Below sites in the hierarchy, you have users.

A user is registered when you create a mail profile. As part of the registration process, the user is assigned to a site.

A mail profile stores the configuration settings that dictate how a user and the associated data are migrated to Google Apps. These settings include:

• Migration status

• Details of the users mail files (the primary database and any archives)

• Gmail user name and password

• Migration parameters such as cutoff dates, folder-mapping preferences, and the name of the exclusion folder.

For a full discussion of registering users, see “Register Users” on page 43.

Deployment Options

This section provides some examples of different deployment options. In these examples, the term site refers to a migration server and the mail servers for which it is migrating data.

Single Site

If you are migrating data for a single location, you can install the system on either the mail server for that location or on a dedicated server. We recommend installation on a dedicated server so that mail-server performance is not degraded.

In a single-site deployment, you install only a single instance of the administration database.

Architecture and Deployment Options 13

Multiple Site

If you are migrating data for multiple locations, you can install a separate instance of the administration database at each location. In this case, the migration for each site takes place independently of the others.

With a multiple-site deployment, you also have the option to replicate the administration database across sites. In this case, the migration agents in the feeder databases still manage just the local users, but you can get a view of the overall progress of the migration from any replica.

WARNING: You should never replicate the feeder databases.

Examples

Here are three of the most common deployment scenarios. You can replicate these scenarios exactly, or you can use them as the basis for more customized deployments.

Single Site, Single Server (Mail and Migration)

Domino Mail Server

FeederDatabase

Administration Database Google Apps

Migration Server


Single Site, Multiple Mail Servers, Single Migration Server

Multiple Sites, Replicated Administration Database

Google Apps

Domino Mail Server

Domino Mail Server

FeederDatabase


Migration Server

Google Apps

Domino Mail Server

Domino Mail Server

Domino Mail Server

FeederDatabase


Migration Server

Feeder Database

AdministrationDatabase

Migration Server

Architecture and Deployment Options 15

Installation Chapter 2

In order for you to successfully implement Google Apps Migration for Lotus Notes, it is important that you carefully follow the guidelines provided here. This section outlines the system requirements you need to meet, preparations you need to make to your environment before you install the product, the installation procedure, and then the database, site, and user configurations you need to make after you install the product.

Google Apps and System Requirements

To implement Google Apps Migration for Lotus Notes, your environment must meet the following minimum requirements for Google Apps, Lotus Domino and Notes, and Microsoft Windows.

Google Apps Requirements

Google Apps Premier Edition or Google Apps Education Edition.

System Requirements for Migration Server

• Lotus Domino Server 6.02 or higher for Windows (32 or 64 bit).

• If you are adding dedicated migration servers to your network, those servers must be registered as part of your existing Domino Organization.

• Microsoft Windows 2000 Server or higher.

• Administrator access to mail files.

17

• Microsoft Core XML Services 6.0. If your version of Windows does not include Core XML Services 6.09, you can download them at:

http://www.microsoft.com/downloads/details.aspx?FamilyID=993c0bcf-3bcf-4009-be21-27e85e1857b1&DisplayLang=en

Microsoft Core XML Services 6.0 are included with various Microsoft products (for example, Microsoft SQL Server and Microsoft Office. To see whether you have Microsoft Core XML Services 6.0 installed, you can search your Windows folder for msxml6.dll.

Things to do Before you Install Google Apps Migration for Lotus Notes

Once you have decided on your deployment configuration, you need to do some preparatory work on those systems before you install Google Apps Migration for Lotus Notes. If you ignore this preparatory work, you will encounter problems when you attempt to migrate your data.

Configure Google Apps

You need to enable the Provisioning API in Google Apps:

1. Open the Google Apps Control Panel.

2. Click the Users and groups tab.

3. Click the Settings link.

4. In the Enable provisioning API section, select the check box for Enable provisioning API.

5. Click Save Changes at the bottom of the page.

When you enable the provisioning API, you see the following warning in the Dashboard tab of the Control Panel:

API access is enabled. Any updates you make via this control panel will not transfer to your user management system.

Click the Learn more link for additional information.


http://www.microsoft.com/downloads/details.aspx?FamilyID=993c0bcf-3bcf-4009-be21-27e85e1857b1&DisplayLang=en

Prepare the Computer on Which you Plan to Install Google Apps Migration for Lotus Notes

Verify System Requirements

Make sure that the computer on which you plan to install Google Apps Migration for Lotus Notes meets all of the system requirements specified in “System Requirements for Migration Server” on page 17.

Note: Google Apps Migration for Lotus Notes can be co-located with your Domino mail server if that computer meets all of the Google Apps Migration for Lotus Notes system requirements.

Increase Max Concurrent Agents and Max LotusScript/Java Execution Times on Migration Servers

By using multiple feeder databases, you can run multiple simultaneous migrations from a single Notes server. In order to do this, you need to:

• Increase the daytime and nighttime values for Max concurrent agents on your server to a recommended minimum of 5. You can increase the value to the system maximum of 10, depending on your needs.

• Increase the daytime and nighttime values for Max LotusScript/Java execution times to 1440 minutes.

Note: Domino allows you to set execution times greater than 1440 minutes, which may be helpful for very large migrations.

These settings are found in your Server Document > Server Tasks > Agent Manager.

Check the Number of MAIL.BOX Files on Each Server

You need to have at least two MAIL.BOX files on each mail server and migration server to ensure optimum performance during migration.

To set the number of MAIL.BOX files:

1. Open Domino Administrator.

Installation 19

2. Click the Configuration tab, then click Server/Configurations.

3. Find the server configuration for each mail server and migration server.

4. In each server configuration, click the Router/SMTP tab, then click the Basics tab.

5. Set Number of mailboxes to 2 or more to ensure optimum performance during migration.

Set Your Servers’ MIME Outbound Settings

Set your servers’ MIME conversion settings so that Notes rich text is converted to HTML:

1. Open Domino Administrator.

2. Click the Configuration tab, then click Server/Configurations.

3. Find the server configuration for each mail server and migration server.


4. Click the MIME tab, click the Conversion Options tab, then click the Outbound tab.

5. Set Message content to from Notes to plain text and HTML.

Optimize Console Output

To reduce console output as email is routed through the feeder databases, you should add the following line to the Notes.ini file for each mail server and migration server:

converter_log_level=10

Set Trusted Servers

The servers on which you install the migration server need to have trusted access to your mail servers.

To identify your migration servers as trusted servers:

1. In the Domino Directory, open the Server document for each mail server.

2. On the Security tab, in the Trusted servers field, enter the name of the relevant migration server.

Restart Your Servers

Restart each migration server and each mail server that is involved in the migration process.

Sign the Installation Templates and Check Access

Use the Domino Administrator client to copy the Notes templates provided in the installation kit to each migration server. Sign each template with the server ID.

Installation 21

The ID with which you sign the templates requires the following minimum rights:

• Designer access to all mail databases that you want to migrate

or

Manager access to the mail databases if you want to limit the mail-file owner to reader access once the migration has completed.

• Create database rights on the migration server.

• Editor access to the Domino Directory, with Create document rights and the NetModifier role.

If you intend to replicate the administration database, keep in mind that each migration server must have at least Reader access to each mail file that you are going to migrate. The easiest way to achieve this is to make sure that the ACL for each mail database has a LocalDomainServers entry with at least Reader access.

[Optional] Disable mail database replication

We recommend that you disable replication of mail databases during the migration process. Mail is flagged with a migration status as it moves through the process, and so the Last Modified property changes each time a message is flagged. Each time this property changes, the message is replicated, which can cause a significant amount of unwanted network traffic.

This recommendation presumes you plan to stop using Notes once the migration to Gmail has begun.

Check File-Size Restrictions

By default, your Domino servers do not restrict the size of an individual message. If you have imposed a file-size restriction at any point, you need to relax that restriction so that the mail servers can send legacy messages that exceed the file size to the migration servers.

To check the Maximum message size setting:

1. In the Domino Directory, open the mail server’s Configuration document.

2. Click the Router/SMTP tab.

3. Click the Restrictions and Controls tab.

4. Click the Restrictions tab.

5. Set the Maximum message size to 0. This value imposes no limit on message size.

Create the Administration Database

Included in the files you receive with the installation package is a database template named gmail-migration.ntf.


Do not copy the template to an NSF file. If you do, the monitoring agents will not run and the ACL will not be set up correctly.

Use gmail-migration.ntf to create the administration database.

Configure the Administration Database ACL

Configure the administration database ACL as described below.

Global Administrators

Global administrators are handled internally by the system setup profile. You do not need to make any manual configuration of the ACL for global administrators.

Global administrators are granted manager rights, and assigned the [Admin] role.

Global administrators are responsible for configuring the administration database, and creating site documents.

Site Administrators

Site administrators are handled internally by the site profile. You do not need to make any manual configuration of the ACL for site administrators.

Site administrators are identified when you configure a new site document (General tab), and are assigned the [SiteAdmin] role, and given Author access to the database.

Site administrators are responsible for maintaining site profiles and the related user profiles. They can edit their profiles for their own sites, and view the profiles for all other sites. Site administrators cannot create or delete site profiles.

-Default- entry

If you are using invitations to have users start their own migrations, reduce the –Default- entry access level to No Access. If your users will be updating their own profiles in the administration database and/or entering their own Google Apps passwords into the system, then reduce this entry to Author. These users do not need document create or delete rights.

If you are not using invitations, then you do not need to grant any rights to your users.

Document Security

The following table details the security that is automatically applied to each type of document in the administration database.

Document Editors Readers

Global setup profile [Admin] All users

Domain administrator’s password

[Admin] [Admin]

Installation 23

Notes

Editor rights for the [Admin] role are implicit. Administrators need to be Managers of the database so they can edit any document.

When you create a site profile, the system automatically adds the Site role, using the site name, to the ACL, and grants Author access to the database to your Site administrators. The [SiteAdmin] role is also granted to all Site administrators. This role does not have any impact on document-level security, but does control the visibility of action buttons at the view level.

The Owner value represents the owner of the mail database, and is held in the NotesName field in the mail-profile and password documents.

Configure the Administration Database

Once you have created the administration database, a new setup form opens automatically. Follow the instructions in the sections below to complete the setup form.

General Tab

Site documents [Admin], Site administrators All users

Mail profile documents [Admin], Site administrators, owner

All users

User passwords [Admin], Site administrators, owner

[Admin], Site administrators, owner

Document Editors Readers


Configure the General tab as described below.

Global migration status

Set this field to Enabled so the crawl-and-feed process can run.

If you set this field to Disabled, the crawl-and-feed process does not run. The setting here overrides any site-level settings.

Global administrators

Select the users and groups you want as administrators. The default value is LocalDomainAdmins.

If you are not a member of LocalDomainAdmins, add your name here so you can complete the configuration process and have administrative access later.

Administration server

By default, the name of the server on which you are installing the administration database. This server is responsible for system housekeeping and directory registration.

Domino directory file name

Enter the name of the Domino directory.

Field or formula to use to generate Gmail username from each Person document

Enter the name of the field in each Person document that contains the Google-Apps user name for each user you are migrating. Usually this is the InternetAddress field, but you can use any field.

This field is used to map Notes names to Internet names during the migration of mail, calendar, and contact data.

You can also enter a formula in this field. The formula is evaluated at run time to map Notes names to Gmail user names. For example, the formula @LowerCase(ShortName)+”@<my-google-domain>.com takes the first value in each user’s ShortName/User ID field, converts it to lowercase, and appends @<my-google-domain>.com to create the Gmail user name/address.

Note: An invalid formula results in Name conversion failures during migration. Use the Check Formula button at the top of the form to validate your formula.

Installation 25

Google Domain Tab

Configure the Google Domain tab as described below.

Domain name

Enter the name of the Google-Apps primary domain to which you will be migrating data. You can find the primary-domain name in the Google-Apps Control Panel > Domain settings tab > Domain names tab > Primary domain field.

Administrator email address

Enter the Google-Apps email address of your domain administrator. After you enter the address, click Set Google Password at the top of the form. Enter the password for the administrator whose address you entered, then click OK.

Make sure the administrator account has been fully configured in the Google domain before you attempt to migrate data.

This address is necessary to facilitate migration of your email data. Calendar and contact data are migrated using the credentials of each user.


Advanced Tab

The options on the Advanced tab are covered here for the sake of providing complete information, however, you should not have to change any of the values.

Integrity checker agent mail template

An integrity-checker agent runs daily in the administration database to check the integrity of the system. If the agent finds a lack of integrity (for example, a replication or save conflict on a user profile), the system sends an email to the users and groups listed in the Global administrators field. This option lets you choose which mail template to use for the email.

Refresh authentication tokens after

As part of the migration process, the system must obtain authentication tokens from Google Apps for each user before any data can be submitted. These tokens are passed along with the content to prove that it is from an authorized user.

If there are frequent requests for new tokens, Google Apps can lock out an account under the assumption that the servers are under attack. Tokens are valid for 24 hours, and are retained for 23 hours to ensure that a valid token is always available.

Installation 27

Maximum mail size allowed

Google Apps currently allows messages up to 25 MB in size (message and any attachments). The default here is set to 25 MB to match the Google Apps limit. Any message that exceeds the maximum size set here is flagged in the user’s mail file, allowing that user to easily identify messages that were not migrated.

Maximum Google label length allowed

Google Apps currently supports a maximum label length of 40 characters. The default here is set to 40. Notes folders are mapped to Gmail labels. If the folder name exceeds the allowable number of characters, the name is truncated when it is mapped to a label. This field is configurable to accommodate future changes in the Google Apps limit on label names.

Additional mail forms

If your mail files have forms other than Memo and Reply that meet the basic requirements of an email, and you want to also migrate those forms, enter the form names here.

Each document is checked to verify that it has at least the From, SendTo, and Body fields. If any of these fields is missing, that mail is excluded from the migration process.

Site level custom settings/User level custom settings

These custom-settings fields let you expose on the site:

• A custom sub-form on the site

• Mail profiles

You can add your own fields to the sub-form. For example, you can show more details about each user (details are taken from the Domino-Directory Person documents), or you can add values at the site level that can be used in conjunction with the Provisioning API to extend the normal functionality of the migration server to support custom enhancements.

Google URLs

These fields list the Google URLs that referenced during migration. You should not change these values unless instructed to do so by a Google Apps representative.

Save Your Administration Database Configuration

After you have completed configuration of the General, Google Domain, and Advanced tab, you can save the setup document, and proceed with setting up your sites.

Security Warning

After you install the administration database, the default access level is set to Manager, and the Admin and SiteAdmin roles are applied.


You must adjust the ACL to ensure that only authorized personnel can access the database during the migration process.

If you plan to have only administrators involved in the process, then you can set the ACL to allow only administrators access to the database.

If you are going to use the Invitations feature and allow users to configure their own settings and passwords, then you need to grant those users Author rights to the administration database.

Once the feeder databases are created, you should also set the default level of access to those databases to prevent unauthorized access.

Configure Your Sites

Before you can register any of your users, you need to create at least one site document.

To create a site document:

1. Open the Sites view in the administration database.

2. Click New Site.

Installation 29

3. Enter a name for the new site.

A new site form is displayed.

General Tab

Configure the General tab as described below.

Site migration status

Set the status to Enabled or Disabled as required. This setting along with the Migration start date for this site setting allows you to control when users from this site will be migrated.

Note: The value you chose for Global migration status in the General tab of the administration-database setup form overrides this setting (see “Global migration status” on page 25 for reference).

Site time zone

Select the geographic location of the site. This information is used to ensure that calendar information is assigned to the correct time zone before it is migrated to Google Apps.


Site administrators

Select your site administrators from the Domino Directory.

Registration of users from Domino directory

Enable this if you want to automatically register users from your Domino Directory whose mail servers are included in this site (see “Servers” on page 32 for information about identifying mail servers for this site).

If you add new users to your Domino Directory, they will be registered the next time the agent runs.

Check accounts in the Google domain

Enable this feature to verify that each user account exists in the Google domain before migration begins.

If you enable this feature, you should also enable the next feature (Provision user accounts in Google domain) so that Notes accounts that do not exist in Google Apps are created, and migration proceeds as expected.

If you do not enable the next feature, when the system encounters a user that does not have a corresponding account in Google Apps, the system skips migration for that user and moves on.

Provision user accounts in Google domain

Enable this feature if you have not provisioned Google Apps accounts for your users.

When migration starts for a user, the system checks for a corresponding Google Apps account. If the Google Apps account does not exist, the system provisions one for that user with the credentials specified in the user profile.

To use this feature, you must also enable the preceding feature, Check accounts in the Google domain.

Migration start date for this site

Enter the date on which you want migration to begin. Leave this field blank to have migration begin immediately upon completion of the site profile.

Migration end date for this site

Enter the migration end date. Leave this field blank to let migrations continue indefinitely.

Allow migrations to continue if end date is reached

Set to Yes if you want to let migrations continue past the specified end date, for example, to allow for unseen delays

Set to No to enforce the end of migration on the date you specified.

Installation 31

Number of feeder databases

Enter the number of feeder databases you want to use for this site. The maximum is 10.

Note: You can use fewer than 10 to leave some agent manager threads available for other databases or applications if necessary.

Feeder databases are created automatically by the Check Feeders agent in the administration database. For each feeder database, the system creates a corresponding Mail-in database document in your Domino Directory.

Number of users each feeder database should process

Enter the maximum number of users that each feeder database can process during a single run of the Migrate agent. The default is 10.

Users are processed one at a time, but each time the agent runs, it processes one user after another until it has processed the number identified here. The agent runs at 30-minute intervals, so you want to keep this number low enough that the agent can, within its 30-minute interval, finish processing the number of users you specify.

Servers Tab

Configure the Servers tab as described below.

Servers

Select the servers for this site, including all the relevant mail servers and the migration server (the server hosting the administration and feeder databases).

Migration server

Select the migration server for the site (the server hosting the administration and feeder databases).


Databases Tab

Configure the Databases tab as described below.

Attachment database

This setting is optional. Lotus Notes supports attachments in calendar and contact documents. At this time, however, these attachments cannot be migrated to Google Apps Calendar or Contacts. If you want to retain links between Google Apps Calendar and Contacts entries and attachments in your Lotus Notes calendar and contacts documents, use the following procedure:

1. Create a standard document library on the server hosting the administration and feeder databases.

2. Click the + button in the Attachment database field to select the document library.

When you use this field to identify an attachment database, the system checks calendar and contact documents for attachments during migration. When the system finds an attachment, it creates a secure document in the attachment database, and creates a link in the calendar/contact entry in Google Apps that points to that secure document, providing users access to attachments from Google Apps.

Note: Clickable links are not currently supported in Google Apps Contacts, so you need to copy and paste the URL into your browser to access the attachment.

Installation 33

Default User Settings Tab

Configure the Default User Settings tab as described below. The values you set here become the default values for each new user profile. You can change the values for individual users if necessary.

Folder conversion

The system maps Notes folders to Gmail labels. Use the options here to determine how folder names are mapped to label names. Keep in mind that Gmail currently imposes a 40-character limit on label names.

• Full path: The label name is equivalent to the hierarchical path to the folder (up to 40 characters).

• Current node: The label name is equivalent to the folder in which the message resides

• Root node: The label name is equivalent to the topmost folder in the hierarchy.

• Do not convert: Folder names are not mapped to label names.


Mail exclusion folder

You can allow users to exclude mail from the migration process by moving those messages to a specific folder in their mail files. Enter the default name of the exclusion folder here.

Allow users to select archives

Set to Yes to allow users to add lists of archived databases to their migration profiles.

Set to No to disallow users from adding lists of archived databases to their migration profiles.

Users can select local archives. When a user selects a local archive, that file is moved to the migration server. In order to facilitate writing to the migration server, you need to give your users temporary Create Database and Create Replica rights on the migration server in their site. These rights can be revoked after the migration has finished, or left in place if you plan to shut down your Domino servers after migration.

This setting applies only to individual user rights. An administrator can always add archives to a profile.

Allow users to modify content controls

Administrators can set the following content controls at the site level:

• Mail processing status (and the optional cutoff date)

• Calendar processing status (and the optional cutoff date)

• Contacts/groups processing status (and the optional cutoff date)

These settings are made in the three fields below.

This field is used to specify whether end users can change the default values that are set at the site level.

Set to Yes to allow users to set these values for themselves.

Set to No to prevent users from modifying the default values.

Mail processing status

Set to Yes to migrate mail data for your users.

Set to No to not migrate mail data.

Optionally, set a date to identify the beginning of the time frame for which mail should be migrated. For example, if you have five years’ worth of mail data, you can set this value to migrate mail from only the last year or two rather than all five years.

Calendar processing status

Set to Yes to migrate calendar data for your users.

Set to No to not migrate calendar data.

Installation 35

Optionally, set a date to identify the beginning of the time frame for which calendar data should be migrated. For example, if you have five years’ worth of calendar data, you can set this value to migrate data from only the last year rather than all five years.

Note: If you apply a cut-off date to calendar data, the system selects only calendar entries for which the main appointment document was created/modified after the specified date. If there is a recurring event that was created/modified before the cut-off date that has instances after the cut-off date, then those instances are not migrated. In this case, set an earlier cut-off date or migrate the entire calendar.

Contacts and groups processing status

Set to Yes to migrate contacts and groups data for your users.

Set to No to not migrate contacts and groups data.

Optionally, set a date to identify the beginning of the time frame for which contacts and groups should be migrated. For example, if you have contacts and groups that span a five-year period, you can set this value to migrate only contacts and groups that were established within the last year or two.

Notifications Tab

Configure the Notifications tab as described below.


Notification status

Set to Enabled to have the system send notification email to your users regarding the specific events defined in the following settings.

Set to Disabled to keep the system from sending notification email to your users.

When enabled, notifications are still subject to other system controls such as system-wide status, site status, and migration start and end dates.

Provisioning mail

Keep the default value, Account provisioned, to have the system send an email notification when a user’s account has been provisioned in Google Apps.

Leave the value blank to prevent the system from sending a notification when a user’s account has been provisioned in Google Apps.

Invitation mail

Keep the default value, Invitation to migrate, to have the system send an email notification when migration has begun and the user’s status has changed to Draft.

Leave the value blank to prevent the system from sending a notification when migration has begun and the user’s status has changed to Draft.

For information about user status, see “User Status During Migration” on page 43.

Invitation reminder

Keep the default value, Migration reminder, to have the system send an email notification when a user’s status has been Invited for more than the number of days specified in the Reminder interval field.

Leave the value blank to prevent the system from sending an email notification when a user’s status has been Invited for more than the number of days specified in the Reminder interval field.

Reminder interval: Set the frequency (in days) at which you want the system to send an invitation reminder.

Start mail

Keep the default value, Migration started, to have the system send an email notification when a user’s migration has started.

Leave the value blank to prevent the system from sending an email notification when a user’s migration has started.

Completion mail

Keep the default value, Migration completed, to have the system send an email notification when a user’s migration has completed.

Installation 37

Leave the value blank to prevent the system from sending an email notification when a user’s migration has completed.

Migration exited early mail

Keep the default value, Migration exited early, to have the system send an email notification to the site administrators when migration has been forced to stop before completion.

Leave the value blank to prevent the system from sending an email notification when migration has been forced to stop before completion due to an event such as a network failure.

A migration can exit early for any of the following reasons:

• Google Apps becomes unavailable

• An administrator account is locked when a CAPTCHA is presented during authentication

• Network failure

• Access denied during provisioning

• Domain suspended

Network Tab

Configure the Network tab as described below.


Delay between HTTP posts

If you experience HTTP locks or service-unavailable responses from Google Apps, you may need to increase this value to introduce a delay between successive posts. For optimum performance, keep the default value of 0.0.

For additional information, see “My migration quits with the following error in the Domino server log: Agent printing: ** Feed terminated: Microsoft Http / Network error occurred **” on page 78.

HTTP transport

Use ServerXMLHTTP whenever possible.

XMLHTTP should only be used for small migrations, demonstrations, or proofs of concept. XMLHTTP does not support any proxy options.

Proxy server

If your servers connect to the web through a proxy server, enter that server’s <hostname:port> or <IP address:port> here.

Proxy credentials

If your proxy requires credentials, enter the username and password.

Network time-outs

You may, on occasion, experience time-outs between your servers and the Google servers. The normal behavior in these circumstances is for the system to exit early and wait for the next scheduled run.

To maintain normal system behavior, leave this set to the default value of On.

If you wish to ignore time-outs and have the system wait for the Google servers to respond, set this to Off. You should only do this, however, if you are experiencing regular time-outs.

Installation 39

Advanced Tab

Configure the Advanced tab as described below.

Keep log files for

Enter the number of days you want the system to keep log files. Log files are purged after the number of days you specify.

Enter 0 to never purge log files.

Record migration error details

Set to Enabled to have the system capture the original Notes XML output and the Google-server response to the HTTP POST when a migration error occurs, and store that information in an exception document for the relevant user.

Exception documents are available from the Migration Exceptions view.

Set to Disabled to prevent the system from capturing this information in response to a migration error.


Retry migration errors

Set to Enabled to have the system make another attempt to migrate Notes data that caused an earlier exception.

Set to Disabled to prevent the system from making additional attempts to migrate Notes data that caused an exception.

Delete existing exceptions:

• Set to Yes to have the system remove the previously saved exception document for the relevant user. When the system makes another attempt to migrate data that was subject to an earlier error and a new error occurs, a new exception document is created. In this case, an exception document exists for a user only if the latest migration attempt encountered an error.

• Set to No to prevent the system from removing the previously saved exception document for the relevant user. When the system makes another attempt to migrate data that was subject to an earlier error and a new error occurs, the existing exception document is overwritten with the latest details. In this case, an exception document exists for a user if any migration attempt encountered an error.

Detailed event logging

Set to Enabled to have the system log document-level events in a Notes log database (Google Apps Migration Log [gmail-migration-log.nsf]). The databases is created in the same folder with the administration database.

Enable this option only to assist with the resolution of a problem as it has a detrimental effect on performance.

Set to Disable to prevent the system from logging document-level events.

Router delay

Enter the number of seconds to have the system wait between successive messages when moving mail from the users’ mail files to the feeder databases.

Increase this delay if you experience router errors or flooding during the migration process.

You can also increase the number of MAIL.BOX files to load balance the system and avoid flooding. Having multiple MAIL.BOX files allows the server to multi-thread mail delivery and thereby optimize performance.

Apply folder references before migration

Some mail files may have folder references enabled, but there may be individual messages that do not have the fields that are needed to allow the system to obtain the folder information. This would happen typically when older mail files have been upgraded but the old email is not updated, or when an organization has modified the mail template and disabled folder references.

Set to Enabled to have the system go through the folders in the mail databases and stamp the correct references prior to migration.

Installation 41

Set to Disabled to prevent the system from going through folders in the mail database and stamping the correct references prior to migration.

Stop on folder reference error:

• Set to Yes to have the system stop processing the user if it encounters an error during the referencing process, which can happen when secure folders are involved.

• Set to No to have the system continue on to the next folder when it encounters an error during the referencing process.

This process runs once for each user. If you need to run the process again for a user, select the user profile from one of the system views and use Admin > Toggle Folders Processed.

Handling of email removed from Notes inbox

It is possible in Lotus Notes to remove a message from the inbox without placing it in a Notes folder. The message is then visible in the All mail view in Lotus Notes. This option allows you to control how this message is filed at migration time. The default is to show the message in the Gmail inbox, but you can also specify a Gmail label under which to file the message.

Restrict user access once migration is complete

Set to Yes to have the system update the access control list for each user’s mail database once migration is complete. The user will then have read-only access to the mail database, and will not be able to continue to create documents in the database.

Set to No to give users continued access to their mail databases once migration is complete.

Retry delay following server errors

Occasionally, Google Apps may not be able to process a batch request to migrate data. When this happens, the system waits for the period specified here before it attempts to repost the data.

Enter the number of seconds to wait before reposting data after a Google Apps server error.

Retry attempts following a server error

Enter the number of times you want the system to retry a POST following a Google Apps server error.

If the server still refuses the data after the final attempt, the migration agents exit early and wait for the next scheduled run.


Wait period for mail ‘Sent to repository’

Under normal circumstances, messages with the status Sent to repository are in the feeder database, and their next status is Migrated. On rare occasions, some email may not reach the feeder database. This setting controls how long a message is allowed to remain at Sent to repository before the system checks the feeder database for that message. If the message cannot be located, the system resubmits it for migration.

Note: If a message is resubmitted and it is not successfully migrated on the second attempt, it may be corrupt, and the Domino mail router cannot process it. If mail persists at this status even after resubmission, you need to mark those messages as Migrated in the user’s Notes mail file so the migration can complete for that user.

Time to wait for mail to reach the repository when using the ‘Generate XML File’ feature

The system includes an agent that generates Notes XML output to a file for any mail/calendar/contact/group document. When this agent is employed, the system routes mail from a user’s mail file to the feeder database. Once mail is in the feeder database, the system retrieves the mail to generate a MIME message and wrap it in an XML envelope for Google Apps.

Enter the number of seconds for the system to wait before it attempts to get the mail document from the repository after it has been sent. If you are migrating large messages, you may need to increase this value.

Save Your Site Configuration

After you have completed configuration of each tab, you can save the setup document, and proceed with registering your users.

Register Users

After you have configured the administration database and the related site, you can then begin registering your users.

User Status During Migration

During the migration process, a user’s status changes as follows:

Status Description

Draft The user has been registered but has not yet been activated in the system.

Regardless of how a user is registered (individually, as part of a bulk process, or automatically through the Domino Directory), each user’s first status is Draft.

Installation 43

Register a Single User

To register a single user for migration:

1. Open the administration database.

2. Select one of the views under Users.

Invited An Invitation-to-migrate email has been sent to the user.

The invitation email contains a link to that user’s mail profile in the administration database. The link opens the mail profile, wherein the user can complete the migration profile and enter a password. When the profile has been completed, the user can click Submit to start the migration.

Active The user’s Notes data is in the process of being migrated.

Complete The user’s Notes data has been successfully migrated.

If any documents have failed to migrate and are flagged as migration errors in the user’s mail file, the system does not change that user’s status to Complete. Under these circumstances, if you want to allow the migration to complete, you can use one of the following methods:

• Open the user’s mail file and manually mark the errors as Complete (see “Mark Notes Data as Migrated” on page 58 for more information)

• Use the Migrate Again feature (see “Resubmit Data to Google Apps” on page 57 for more information)

Once all the errors have been cleared, the user’s status changes to Complete.

Hold An administrator has suspended the migration for the user.

When the hold is released, the migration resumes from the point at which the suspension was implemented.

Status Description


3. Click Register > Single User.

4. In the User field, click the + icon.

5. Select a server, and then the mail database for the user you want to register.

Installation 45

6. If the correct Gmail username is not already displayed, enter the username in the Values column.

7. Click Set Google Password, enter and confirm the password, then click OK.

8. In the Folder conversion field, select the method you want to use to map folders to Gmail labels.

9. If the user wants to exclude email from migration, enter the name of the exclusion folder.

10. Select Yes or No for each document type (mail, calendar, contacts/groups) to specify whether those documents should be migrated.

Optionally, set a date to identify the beginning of the time frame for which data should be migrated.

11. If you want to migrate archived databases, click the Mail Archives tab.

12. In the Archive databases field, click the + icon, then select the server and databases you want to migrate.

13. When you have finished configuring the user profile, click Save, then click Exit.

Register Multiple Users

To register multiple users:

1. Open the administration database.


2. Select one of the views under Users.

3. Click Register > Multiple Users.

4. In the Server field, click the + icon.

5. Select the server you want, then click OK.

6. In the Folder path field, enter the name of the folder that contains the users you want to register.

7. In the Recurse subdirectories field, select Yes if you want to also register users in subdirectories of the folder you named above.

8. Click Register Now.

Register Users Automatically

You can set the system to register users automatically when you configure your site settings. Use the Registration of users from Domino directory setting on the General tab of your Sites document. See “General Tab” on page 30 for information.

Installation 47

Uninstalling the Migration System

To uninstall the migration system:

1. Delete all administration databases.

2. Delete the feeder databases, and optionally, any attachment-repository databases.

3. Delete the migration-administration and feeder templates from your servers.

4. Optionally, reverse the settings you applied as part of “Things to do Before you Install Google Apps Migration for Lotus Notes” on page 18.


Managing Your Migration Chapter 3

After you have created the administration database, configured your site, and registered your users, you are ready to initiate the migration process.

Activate Users

When a user is first registered, that user’s status is Draft. In order for that user’s data to be included in the migration process, the status must change to Active.

You can activate users individually, or send invitations to multiple users. Each scenario is covered below.

Activate Individual Users

To activate an individual user:

1. Open the profile for that user.

2. In the Action bar, click Activate.

Activate Users By Invitation

You have two methods of sending activation invitations to users:

Configure notifications at the site level

Use the Send > Invitation action.

Configure Notifications at the Site Level

For information about configuring site-level notifications, see “Notifications Tab” on page 36, in particular the sections covering the Invitation mail and Invitation reminder fields.

49

Use the Send > Invitation Action

To activate users by invitation:

1. Display a list of Draft users by opening one of the Users views in the administration database.

2. Select the users to whom you want to send invitations, then click Send > Invitation.


3. Click Choose mail template.

4. Select Invitation to migrate, then click OK.

The invitation form is populated with information from the mail template. It also includes buttons that provide options for users to synchronize their address books, decrypt email, and start the migration.

Managing Your Migration 51

5. Click Send > Invitation.

Each user you selected is sent an invitation email with a link to the respective user profile in the administration database. Each of those mail profiles moves to the status of Invited.

Mail Templates

You can create mail templates to serve as invitations to start the migration process, as reminders, or as any other type of communication you need to make to your users. The following templates are provided, and you can use them as is or as the basis for new templates:

• Account provisioned

• Invitation to migrate

• Migration reminder

• Migration started

• Migration completed

• Migration exited early


Create a Mail Template

To create a new template:

1. Open the administration database, and then open the Email Templates view.


2. Click New Email Template.

3. Complete the settings as follows:

4. Click Save, then click Exit.

Setting Value

Title Enter a title for the template. This value appears in any list of template choices.

Include link to user profile

Set to Yes if you want the email based on the template to include a link to the user’s profile.

Greeting Select or enter a greeting.

Name to user Select the format for the name following the greeting:

• First name only

• Full name

• None

Subject Enter the subject for the message.

Content Enter the body of the message.

This can include rich-text elements and attachments.

Sign-off Enter or select a closing for the message (for example, Regards or Sincerely).


The template is now available in any list of template choices, including the Send > Invitation and Send > Email commands.

Send Invitations

You can send invitations only to users whose status is Draft. If you want to send an invitation to a user who has a different status, you need to first reset that user’s status to Draft.

If you use the Send > Invitation command and select a user whose status is not Draft, no invitation is sent to that user.

When you send an invitation, the user’s profile is updated with the date and time the invitation was sent. The date and time are then used as a benchmark to determine when to send reminders.

Manage Body Content

You can add tags to the mail-template Content field. The tags are replaced at run time with the related field values from the Site profile document.

To add a tag to the Content field, simply enclose the appropriate field name in double chevrons (<<field name>>).

For example:

Migrations from <<Site>> will begin on <<MigrationStartDate>>

would return something like

Migrations from Mountain View will begin on 01/01/2010

To find the field names for the Site profile document:

1. Right-click the Site profile document, then click Document Properties.

2. Click the Fields tab.


Email Restrictions

If you want to send email from the system to more than one user at a time, each of those users must belong to the same site.

You must be identified as an administrator for a site in order to use the system to send email to users who belong to that site.

Manage User Mail Files

The system generates three Migration-Status views in each user’s mail file. These views let the user and administrator review progress of the migration at the individual-document level.

The following table outlines the different statuses applied to each type of document.

Status Calendar Contacts Mail Description

Unprocessed Yes Yes Yes Document not yet processed by the migration system.

Sent to repository

N/A N/A Yes Mail has been routed to feeder database for further processing.

Repository error

N/A N/A Yes An error occurred when sending this email to the feeder database. The system will try again later.

Migrated Yes Yes Yes Document sent to Google Apps.

Migration error Yes Yes Yes An error occurred when sending this document to Google Apps

Encrypted N/A N/A Yes Mail was not sent because it was encrypted.

Mail can be decrypted and resent using the Decrypt email button. The button is displayed in the Migration Status > Mail view.


Resubmit Data to Google Apps

To resubmit a user’s mail, calendar, or contact data that failed to migrate:

1. Open the user’s mail database.

2. Select one of the Migration Status views.

3. Select the documents you want to resubmit to Google Apps, then click Migrate Again.

Decrypt Mail

Because Gmail does not read encrypted mail, the system does not migrate encrypted mail. Encrypted messages are visible in each user’s mail database in the Migration Status > Mail view, and are categorized as Encrypted. To migrate those messages, the mail database owner must first decrypt them.

Have the user follow these instructions to decrypt messages:

1. Open the Migration Status > Mail view.

2. Select all messages categorized as Encrypted.

3. Click Decrypt Email in the action bar.

Those decrypted messages are migrated the next time the system process the user.

Note: The invitation-to-migrate email includes the Decrypt Email button, and users can decrypt mail before they initiate the migration process.

Exceeds allowable size

N/A N/A Yes Mail exceeds the maximum size set in the user’s site-profile document.

Excluded N/A N/A Yes Mail was excluded for one of the following reasons:

Mail is in the user’s exclusion folder.

Mail was generated by the migration system.

Mail contains an attachment not allowed by Gmail.

Status Calendar Contacts Mail Description


Mark Notes Data as Migrated

On occasion, Google Apps refuses to accept data from Notes. For example, a message may be corrupt in the Notes environment, or it may have an invalid email address or header information.

In cases like this, the data is marked Migration Error, and is displayed in the appropriate Migration Status view. If it is not possible to correct the errors in the data, you can manually mark the items as Complete so the system treats them as migrated, and can finalize migration for that user.

To manually mark an item as Complete:

1. Open the mail database for the user.

2. Open the relevant Migration Status view (Calendar, Contacts, or Mail).

3. Select the items marked as Migration Error.

4. Click Mark Complete in the action bar.

Monitor Migration Times and Database Size

Migration Times

Depending on numerous factors including your system topology, hardware and network capabilities, and the transfer speed from your Internet Service Provider to the Google servers, the speeds at which migrations proceed can vary widely.

For example, if a single feeder database processed one user with 100 MB of data in 30 minutes, then you can project that each 100 MB of data will take about 30 minutes, and that using 10 feeder databases will process 10 users with a total of 1000 MB of data in 30 minutes.

You can migrate just a few users, and then examine the logs in the administration database to see how much data was migrated and at what speed. From that information, you can extrapolate good approximations for the time required to migrate all your users.

Database Size

During the initial phase of migration, email is routed through the feeder databases, which in turn generates a lot of internal email traffic on your network. With this in mind, monitor the following conditions daily:

• The size of the MAIL.BOX databases. Check whether the server has been able to compact these databases, and if not, compact them manually.

• The size of the feeder databases. These databases can become large when you are migrating hundreds or more users. Check that the server has been able to compact these databases, and if not, compact them manually.


Administration Tools Chapter 4

You have administration tools available at the view and form levels, as well as a number of agents you can run from the Actions menu.

View-Level Actions

Form-Level Actions

59

Agent Actions

Change a User’s Status

You can override the system workflow and change the status of one or more users.

To change user status:

1. In the administration database, open one of the Users views and select one or more users, or open an individual profile.

2. Click Admin > Status Override.

3. Select a new status.

4. Click OK.

Change a User’s Location and Time Zone

When the system migrates a user’s calendar entries, it uses the time zone specified in that user’s site profile.

If you have users whose mail files reside in one time zone, but who work in a different time zone, you can change the location and time-zone settings for those users.


To change location and time-zone settings for a user:


2. Click Admin > Set Location.

3. Select a location and offset from GMT.

4. Click OK.

Note: Unlike site-level settings, the location-override feature does not take into consideration time-zone shifts (e.g., Daylight Savings Time) when migrating single-instance calendar events for users who are not in the same time zones as their mail servers.

As a workaround, you can use the cutoff-date feature along with the offset from GMT to successfully migrate this type of calendar event. For example, set the cutoff date to the date on which Daylight Savings Time began, and then select the appropriate offset from GMT.

Toggle the Processed Flag for Folders

The site-level setting Apply folder references before migration (Site document > Advanced tab) enables the system go through the folders in the mail databases and stamp the correct folder references prior to migration so that messages with missing folder-reference flags are migrated to the correct labels in Gmail. This process runs once for each user, but if you need to run the process again for a user, you can use the following procedure to flag that user’s folders as unprocessed. The next time the agent runs, that user’s folders are processed again to stamp the correct folder references.

To toggle the Processed flag for folders:


Administration Tools 61

2. Click Admin > Toggle Folders Processed.

Note: Alternatively, you can use the same procedure to mark folders as Processed if Apply folder references before migration is enabled at the site level but migration has not begun for a user.

You can use this approach to have the system skip folders that do not require correct folder references or that you are sure have the correct folder references.

Set a Google Apps Password for One or More Users

To set the same Google Apps password for one or more users:


2. Click Admin > Set Google Password.

3. Enter and confirm the password.

4. Click OK.

Set Migration Cutoff Dates

You can use this option to set migration cutoff dates for mail, calendar, and contact/group documents. Any changes you make with this feature are reflected in the profile for each user you select.

To set migration cutoff dates:

1. In the administration database, open one of the Users views and select one or more users.


2. Click Admin > Set Cutoff Dates.

3. Select Yes for each type of document for which you want to set a cutoff date. Enter a date or click the calendar control to select a date.

4. Click OK.

To clear migration cutoff dates:


2. Click Admin > Set Cutoff Dates.

3. Select Yes for each type of document for which you want to clear the cutoff dates.

4. Leave the date field blank.

5. Click OK.

Toggle Migration Processing Status for Document Types

You can use this option to toggle migration processing status for mail, calendar, and contact/group documents for specific users. For example if Mail processing status is set to Yes for a user and you click Admin > Toggle Mail Status, then Mail processing status is reset to No.



2. Click:

• Admin > Toggle Mail Status• Admin > Toggle Calendar Status• Admin > Toggle Contacts Status

The processing status for each document type is switched from its previous setting.

Reset Google Tokens

Google tokens are required for each user to migrate calendar and contacts/group documents. By default, these tokens are refreshed every 23 hours (see Configure the Administration Database > Advanced Tab). You can use this option to refresh the tokens immediately for specific users.

To reset Google tokens:


2. Click Reset Google Tokens.

Note: You normally do not have to reset tokens since the system manages them automatically. You would want to reset them, however, if you have migrated a user to a test account and now want to re-migrate that user to a new account in the same domain. Alternatively, you can set the refresh time to one hour and let the tokens refresh automatically at a more frequent interval. If you do set the refresh time to one hour, be sure to set it back to 23 hours when you have finished re-migrating users so that you can avoid authentication problems later.

Actions-Menu Agents

You also have access to the following agents from the Actions menu.

To access the agents, click Actions > Admin > <agent>.

Running the agents from the Actions menu does not override any site-level default schedules.

Automatic Registration

Runs the Automatic Registration agent. The agent’s default schedule is to run on each migration server at 12:30 A.M.

Send Invitations

Runs the Send Invitations agent. The agent’s default schedule is to run on each migration server at 2:00 A.M.


Purge Documents

Runs the Purge Documents agent. The agent’s default schedule is to run on each migration server at 1:30 A.M.

System-Integrity Checks

Runs a set of integrity checks against the system to make sure that all configuration documents are present. Also checks to see if there are any replication-conflict or save-conflict documents. The agent’s default schedule is to run on the administration server (see Configure the Administration Database > Administration server) at 1:00 A.M.

After you open the agent, click Check System Integrity and review the notes in the text field. If the agent identifies any problems, an email is sent to the global administrators.

If you see WARNING messages, see the table below for information about how to resolve the problem.

Generate XML File

This action is available only when you have a feeder database open.

Allows you to generate the XML that is sent to Google Apps for any mail, calendar, or contact/group document. The output is on the Notes client computer in Notes\Data\CS_temp.

Warning Possible Cause Remedy

xxx site conflicts found... Replicated migration database, and there is a replication conflict or save conflict on a site document.

Open the Sites view and resolve the conflicts.

xxx user conflicts found... Replicated migration database, and there is a replication conflict or save conflict on a user document.

Open one of the User views and resolve the conflict

Reapply passwords for the affected users.

xxx password conflicts found...

Replicated migration database, and there is a replication conflict or save conflict document on a user password.

The default system settings should prevent this in all cases. Replication and save conflicts can occur when you modify the default settings.

1. Open the ($Passwords) view: press CTRL + SHIFT, click View > Go To, then select ($Passwords).

2. Locate the conflicts and delete them.

3. Reapply the passwords for the affected users.


Open a User’s Mail Database

To open a user’s mail database:

1. In the administration database, open one of the Users views and select a user.

2. Click Open > Mail Database.


Extended and Mixed-Character Support Chapter A

To configure the system to support extended character sets (such as Japanese as defined in ISO-2022-JP):

1. Open the Domino Directory, then open the Configuration > Messaging > Configurations view.

2. Edit the configuration documents that apply to your mail servers and to any server that is hosting the administration and feeder databases, as described in the following steps.

67

3. Click the Basics tab.

4. Set the International MIME Settings for this document field to Enabled.


5. Click the MIME tab, then click the Settings by Character Set Groups tab.

6. Select the For outbound message options below use all possible choices (Advanced users) check box.

7. Use the MIME settings by character set group menu to select the character set group you want.

8. Under Outbound Message Options, set Header and Body Encoding to Quoted Printable.

9. Save your configuration document.

10. Repeat the procedure for any server involved in the migration process that is not covered by the document you just modified.

11. When you have updated all of the configurations, restart all the affected servers.

Extended and Mixed-Character Support 69

Working with the GAMLN API Chapter B

The feeder databases include a script library, Custom Events, that includes routines designed to let you interact with the GAMLN API. The routines are described below.

PostFinaliseUser (userProfile As NotesDocument)

Called after all email, calendar, and contacts/group entries have been successfully migrated to Google Apps, and the mail profile has the status of Complete. Passes in the user’s mail profile.

PostMigratedUser (userProfile As NotesDocument)

Called immediately after each user has been processed by the migration module. As it may take multiple cycles to fully migrate a user, this routine can be called multiple times for a user. Passes in the user’s mail profile.

PostMigrateUsers

Called at the end of each migration run.

PostUpdateRepository

Called at the end of each repository (feeder database) update.

PostUpdateRepositoryUser (userProfile As NotesDocument)

Called immediately after the repository (feeder database) has been updated for each user. Passes in the user’s mail profile.

Function QueryFinaliseUser (userProfile As NotesDocument) As Integer

Called after all email, calendar, contacts/groups entries have been successfully migrated to Google Apps, and just before the profile is set to complete. Return False to skip the user. Return True to let processing proceed. Passes in the user’s mail profile.

71

Function QueryMigrateUser (userProfile As NotesDocument) As Integer

Called for each user prior to migrating content to Google Apps. Return False to skip the user. Return True to let processing proceed. Passes in the user’s mail profile.

Function QueryMigrateUsers () As Integer

Called just before the feeder begins to process its first database. Return False to abandon the operation. Return True to let processing proceed.

Function QueryUpdateReposity () As Integer

Called just before the system populates the mail repository to convert Notes email to MIME email. Return False to abandon the operation. Return True to let processing proceed.

WARNING: Custom API code can interfere with the normal operation of the system. Google takes no responsibility for and provides no support for any system in which custom API code has been deployed and this code has been shown to interfere with normal operations.


Custom Settings Chapter C

The system includes two custom sub-forms. You can use the sub-forms to add additional fields and programming logic to the site mail-migration profiles. You can also use the sub-forms in conjunction with the Provisioning API to present values that are derived from your own custom API code.

Using the sub-forms requires that you are an experienced Notes developer.

By default, the Custom Settings tabs are not displayed. To display the tabs, you need to enable the custom-settings options on the Advanced tab of the System Setup form (see “Site level custom settings/User level custom settings” on page 28).

One way you can use the sub-forms is to present additional information about each user. That information can be derived from the logic of the form (for example, Domino Directory lookups for organizational details based on Notesname) or by using the API.

WARNING: Custom sub-form code can interfere with the normal operation of the system. Google takes no responsibility for and provides no support for any system in which custom sub-form code has been deployed and this code has been shown to interfere with normal operations.

73

Handling CAPTCHA Challenges Chapter D

Occasionally, a user account can become locked by Google Apps. In this case, Google Apps presents a CAPTCHA challenge that you need to address manually.

CAPTCHA challenges are recorded in the Migrate-Users-agent logs.

Locked accounts are identified by the padlock icon in the Users > Active view:

To unlock an account:

1. Go to the following URL:

https://www.google.com/a/<yourdomain>?/UnlockCaptcha

2. Log in as the locked-out user, and respond to the CAPTCHA challenge.

Once you have made a successful response to the challenge, Google Apps unlocks the account.

Note: An account can also be locked due to an invalid user name or password, or some other failure to verify the account. The system includes the Exceptions > Authentication Failures view that lists users who are having authentication problems, and the reasons why.

75

Troubleshooting Chapter E

I have registered users, but nothing is happening; and I see the following entries in my server log:

AMgr: Agent 'Migrate' in 'gmail-feeder-1.nsf' does not have proper execution access, cannot be run

OR

AMgr: Agent 'migrate' in 'gmail-feeder-1.nsf' encountered error: Error validating user's agent execution access

The Google Apps Migration for Lotus Notes templates were not signed before you installed the tool. You need to sign the administration database and each of the feeder databases with a trusted ID (server ID is recommended).

I’m getting an error that says “Notes error: Unable to open Name and Address Book...”

Make sure that the server on which the mail file resides has the migration server listed as a trusted server.

I have registered my users and I can see email in the feeder databases, but nothing is migrating to Google Apps.

Here are some reasons why you might see this behavior:

• The Domino server cannot communicate with the Google servers. Make sure that there are no network restrictions between Domino and Google. If you are using a proxy, make sure the proxy details are correctly entered into your Site profile document.

• The Google-administrator username and/or password you entered when you configured the administration database is incorrect. See “Administrator email address” on page 26.

• The provisioning API is not enabled in your Google Apps domain. This must be enabled even if you are not provisioning users. See “Configure Google Apps” on page 18.

Always check the log documents in the administration database for more details. Errors encountered during domain administrator authentication are captured in an attachment that is held in the “Migrate users” log documents (Logs > All By Site > yoursite > Migrate users). You can view this attachment for more detailed information about the error.

77

The number of messages migrated to Gmail is less than the number of messages in my Notes inbox.

Notes messages that are replies to one another are threaded together as conversations in Gmail. Where you may have four or five Notes messages that are replies back and forth around the same subject, you’ll have one Gmail conversation that comprises all those messages. Consequently, the number of migrated messages in Gmail can be significantly smaller than the original number in Notes.

My migration keeps stopping with the following error: Agent Manager: Agent printing: 4000' Notes error: Field is too large (32K)...

This error suggests the possibility of a corrupt message in Notes that is blocking the migration.

To locate the offending message and continue your migration:

1. Enable detailed logging at the site level (see “Detailed event logging” on page 41).

2. Run the migration again.

3. In the log database, find the message that is being processed when the migration stops, and identify the UNID for the message. Using the UNID, locate the message in the feeder database, and delete it from there.

4. The offending message will have a status of Sent to Repository in the user’s Migration Status > Mail view.

5. Select the message, then click Mark Complete so the migration process can complete for that user.

6. You can then forward the message to the user’s Gmail account from the Notes inbox.

I migrated a user’s mail to a test account, and now I want to migrate it to his real account. What do I need to do?

1. Change the user’s Gmail user name and password in his user profile. See “Register a Single User” on page 44.

2. Reset the Google tokens for that user. See “Reset Google Tokens” on page 64.

3. Use the Migrate Again button to reset all of the mail in that user’s mail file. See “Resubmit Data to Google Apps” on page 57.

Note: If you have used one instance of the tool to migrate to one Google domain (for example, a test domain) and now you want to migrate to another domain, you should reinstall Google Apps Migration for Lotus Notes to avoid authentication problems and ensure that all tokens are correctly renewed.

My migration quits with the following error in the Domino server log: Agent printing: ** Feed terminated: Microsoft Http / Network error occurred **

It is not uncommon to see occasional HTTP-connection time-outs. When these occur, the next migration run resumes from the point at which it left off.

You can set the system to ignore network time-outs. See “Network time-outs” on page 39 for more information.


I’m seeing the following error in the log: The connection with the server was terminated abnormally

This can be caused by your internal network blocking the URLs to which the system is posting data. The URLs are set by default (see “Google URLs” on page 28). Check that these URLs are not blocked for your migration servers.

I have a user whose status seems to be stuck in Active.

1. Open the mail database for that user.

2. Expand Views > Migration Status, then check the Calendar, Contacts, and Mail views to see whether the migration has encountered an error, or if it is just proceeding more slowly than you expect.

I see a padlock icon on one or more of my active user profiles, or one of my user accounts is not migrating.

Padlocks indicate an authentication problem. You should begin by opening the user profile. Then click the Authentication error: Click here for details link. A dialog box opens that details the server response for this user during login. Typically, authentication problems fall into 2 categories, Captchas or Invalid credentials. Each situation is dealt with differently.

• Captchas: These must be released manually. See “Handling CAPTCHA Challenges” on page 75.

• Invalid credentials: In this case, check that the username and password entered in the GAMLN profile match the Google Apps username and password. In some instances, extended characters can cause authentication problems, so if you are sure that the password is correct in GAMLN but the migration still fails, try changing the user password on both the GAMLN and Google Apps accounts to a less complex password using a combination of upper and lower case letters and numbers only.

Troubleshooting 79

Index

Aabout guide

audience 7contents 7find latest version 7send comments 8

administration database 11ACL 23configure 24create 22

administration toolsagent actions 60Automatic Registration agent 64change user location and time zone 60change user status 60clear migration cutoff dates 63form level 59generate XML file for migration data 65reset Google tokens 64Send Invitations agent 64set migration cutoff dates 62system-integrity checks 65toggle document processing status 63toggle folder Processed flag 61view level 59

agentsCheck Feeders 11Migrate 11

API routines 71architecture

administration database 11component interaction 12components 11data flow 12feeder databases 11global settings 12management hierarchy 12site settings 12users 13

Ccalendar migration 10

CAPTCHA, unlock account after challenge 75character support, configure 67Check Feeders agent 11contacts migration 10custom settings 73custom sub-forms 73

Ddata flow 12databases

administration 11administration database ACL 23administration database, configure 24administration database, create 22feeder 11monitor size during migration 58open user mail database 66

decrypt mail for migration 57deployment options

examples 14multi site 14

disclaimer, third-party products 8

Ffeeder databases 11

Gglobal settings 12Google tokens, reset 64group migration 10

Iinstallation

administration database ACL 23administration database, configure 24configure sites 29create administration database 22Google Apps requirements 17register users 43register users, automatically 47register users, multiple 46register users, single 44system requirements 17

Index 81

uninstall 48invitations, sending 55

Mmail migration 9management hierarchy 12Migrate agent 11migration

activate individual users 49activate users 49activate users by invitation 49clear cutoff dates 63create mail template 53decrypt mail 57document status 56mail templates 52mark Notes data as migrated 58monitor database size 58monitor time 58resubmit data to Google Apps 57send invitations 55set cutoff dates 62unlock account after CAPTCHA challenge 75

migration estimate time 58multi-site deployment 14

Ooverview

calendar migration 10contacts and group migration 10features 9mail migration 9

Ppre-installation

configure Google Apps 18prepare Domino servers 19

Ssite settings 12sites

configure 29supported Google Apps editions 17system requirements 17system-integrity checks 65

Ttroubleshooting 77

Uuninstall 48users

activate by invitation 49activate for migration 49change location and time zone 60change status 60open mail database 66register 43status during migration 43


googleapps notes migration

Documents

correct references prior

avoid authentication problems

correct folder references

google apps accounts

handling captcha challenges

exception document exists

map notes names

google apps migration