Create a control CSV file for user accounts
Before you migrate your data using G Suite Migration for Microsoft® Exchange (GSMME), create a control comma-separated values (CSV) file to ensure that your legacy data correctly maps to your new G Suite domain.
How to create the control CSV file
- You can use any spreadsheet software to create the CSV file.
- We recommend that you copy the final file and save it in a text editor as a CSV file so that you can review the syntax for consistency. Some spreadsheet editors add quotation marks to cells, which you need to delete before running the migration. Adding a space after the comma is optional.
- Make sure your CSV file is correctly formatted, or the migration won't run successfully.
- If you plan to use multiple client machines, you need a separate CSV file for each client. Each file must contain a unique set of users.
- We recommend that you don’t exceed 1,000 users in a single CSV file.
- Verify whether you also need a mapping CSV file. See When do I also need a mapping file?
Format of the control CSV fileMigrating email and contacts
The general structure of the control CSV file is sourceuser, destinationuser. You don't need to include destinationuser if it's identical to sourceuser.
Example: email@example.com, firstname.lastname@example.org
If you're migrating calendar resources as well as email and contacts, you need to add the calendar resources to the control CSV file. The format for adding calendar resources to the control CSV file is exchange-resource-email, GSuite-resource-email.
Example: email@example.com, firstname.lastname@example.org
To find the G Suite calendar resource email:
- From the Admin console Home page, go to AppsG SuiteCalendar.
- Click Resources.
- Click the calendar resource name.
- Next to Email, copy the G Suite calendar resource email.
In certain situations when you're migrating calendar resources, you will also need a mapping CSV file. For details, see Create a mapping CSV file.
Variations on the control CSV file formatMigrating from an Exchange server
If you're migrating from an Exchange server, we recommend that you use the same usernames in G Suite as you do in your current mail server. You’ll have one name or SMTP address per line in the CSV file. You don't need to enter your users' passwords in the CSV file because authentication is through your Exchange server administrator account.
If the addresses in your mail server are different from the addresses in G Suite, then you need 2 addresses per line in the CSV file—the mail-server address followed by the G Suite address.
Example: email@example.com, firstname.lastname@example.org
IMAP migration using an administrator's password
Some IMAP servers support migration using an administrator's password. Therefore, you don't have to enter every user password.
- For Cyrus or Mirapoint IMAP migrations—Enter the administrator credentials in step 1 of the tool. Use the following syntax for the control CSV file: email@example.com, firstname.lastname@example.org.
Ensure the Cyrus administrator account has all access control rights to each user's mailbox. For more information about migrating from Cyrus IMAP servers, see "Step 1: Special migration instructions for Cyrus IMAP" in the GSMME Administration Guide.
- For Exchange IMAP migrations (not regular Exchange migrations)—Use the following syntax for the control CSV file: windowsdomain/exchangeadmin/sourceuser#adminpassword, destinationuser.
Example: email@example.com#VjJ8zTsm, firstname.lastname@example.org
In this example, the Active Directory® (Windows®) domain is solarmora, the administrator username is admin, and the administrator's password is VjJ8zTsm. The administrator is migrating email for the user email@example.com.
For Exchange Online (Office 365) IMAP migrations (not regular Exchange migration)—Use the following syntax for the control CSV file:
Example: firstname.lastname@example.orgemail@example.com#VjJ8zTsm, firstname.lastname@example.org
In this example, the Exchange Online administrator username is email@example.com, and the administrator's password is VjJ8zTsm. The administrator is migrating email for the user firstname.lastname@example.org.
IMAP migrations without the administrator's password
When you're using an IMAP server other than Cyrus, Mirapoint, or Microsoft Exchange, you must include the user's IMAP username, password, and G Suite username. The basic format is sourceuser-email#sourceuserpassword, destinationuser-email.
Example: email@example.com#fKz47MCb, firstname.lastname@example.org
Use the same username that the user enters in their IMAP email client to check their email. Some IMAP servers only require a username, whereas other IMAP servers require the full email address (for example, "email@example.com" rather than just "johnsmith"). When in doubt, use the full destination email address for the user.
The domain you specify in step 1 of the GSMME tool needs to be the primary G Suite domain you're migrating users to. If you're migrating mail to a G Suite account with secondary domains, the domain you choose might not be the same domain in the email address you’re migrating the users to.
If you're migrating data using Personal Storage Table (PST) files, the basic format for the control CSV file is: PST-folder-name, destinationuser.
Example: john-smith-pst-archive, firstname.lastname@example.org
For details, see Migrate from PST files.
In the following situation, you need a mapping CSV file as well as a control CSV file:
- You're migrating calendar data; and
- There are users or calendar resources in your organization whose email address in the G Suite domain is different from the email address in the source environment
Example: email@example.com and firstname.lastname@example.org
For details, see Create a mapping CSV file.