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 user accounts.
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: firstname.lastname@example.org, email@example.com
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: firstname.lastname@example.org, email@example.com
To find the G Suite calendar resource email:
From the Admin console Home page, go to AppsG SuiteCalendar.
- Click Resources.
- Point to the calendar resource and click Edit .
- Next to Resource 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: firstname.lastname@example.org, email@example.com
Some IMAP servers can migrate data using an administrator's username and password. You don't have to include the password for every user.
G Suite IMAP migrations
Note: These instructions apply if you're migrating data from G Suite, not personal Gmail accounts (for example, an @gmail.com account).
Before you do a G Suite IMAP migration, take some set-up steps when authorizing GSMME. See Authorize GSMME for your account.
Use the following syntax for the control CSV file: firstname.lastname@example.org, email@example.com.
Or, you can use a CSV file that contains users' passwords. For details, see Migrating from other IMAP servers. If you choose to include the passwords, you must give the source account access to less secure apps before you migrate data.
Cyrus or Mirapoint IMAP migrations
Enter the administrator username and password in step 1 of the GSMME tool. Use the following syntax for the control CSV file: firstname.lastname@example.org, email@example.com.
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.
Exchange IMAP migrations (not regular Exchange migrations)
Use the following syntax for the control CSV file: firstname.lastname@example.org#adminpassword, email@example.com.
Example: firstname.lastname@example.org#VjJ8zTsm, email@example.com
In this example, the Windows® Active Directory® domain is solarmora, the administrator username is admin, and the administrator's password is VjJ8zTsm. The administrator is migrating email for the user firstname.lastname@example.org.
Exchange Online (Office 365) IMAP migrations (not regular Exchange migrations)
Use the following syntax for the control CSV file:
Example: email@example.comfirstname.lastname@example.org#VjJ8zTsm, email@example.com
In this example, the Exchange Online administrator username is firstname.lastname@example.org, and the administrator's password is VjJ8zTsm. The administrator is migrating email for the user email@example.com.
When you're using an IMAP server other than G Suite, Cyrus, Mirapoint, or Exchange, you must include the user's IMAP username, password, and G Suite username. The basic format is sourceuser-email#sourceuserpassword, destinationuser-email.
Example: firstname.lastname@example.org#fKz47MCb, email@example.com
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, "firstname.lastname@example.org" 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, email@example.com
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: firstname.lastname@example.org and email@example.com
For details, see Create a mapping CSV file.