Before you migrate your data using Google Workspace Migration for Microsoft Exchange (GWMME), create a control comma-separated values (CSV) file to ensure your legacy data correctly maps to your new Google Workspace user accounts.
Note: GWMME uses 2 files: a control CSV file and a mapping CSV file. This article is about creating and using a control CSV file. For details about creating and using a mapping CSV file, go to Create a mapping CSV file.
How to create the control CSV file
- Create the control CSV file in a spreadsheet program with one entry per line.
- Headers are not required.
- Make sure your CSV file is correctly formatted, or the migration won't run successfully.
- We recommend you make a copy of the final file and save it in a text editor as a CSV file so 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.
- If you plan to use multiple client machines, you need a separate CSV file for each client. Each CSV file must contain a unique set of users and calendar resources.
- We recommend you don’t exceed 1,000 users and calendar resources in a single CSV file.
- Verify whether you also need a mapping CSV file. For details, go to When do I also need a mapping CSV file?
Format of the control CSV fileMigrating email, contacts, and calendars for user accounts
The general structure of the control CSV file is sourceuser, targetuser. If the addresses in your Exchange source domain environment are different from the addresses in your Google Workspace target domain environment, you need 2 addresses per line in the CSV file—the source user address followed by the target user address.
Example: firstname.lastname@example.org, email@example.com
If the the sourceuser is identical to the targetuser, you can exclude the targetuser.
If you're migrating calendar resources as well as users, you need to add the calendar resources to the same control CSV file. The format for adding calendar resources to the control CSV file is source-resource-email, googleworkspace-target-resource-email.
Example: firstname.lastname@example.org, email@example.com
To find the Google Workspace calendar resource email:
From the Admin console Home page, go to AppsGoogle Workspace Calendar.
- Click Resources.
- On the Resources page, click a calendar resource name (for example, NYC-14-12-Boardroom-15) to view its details.
For more information on calendar resource naming conventions, go to Resource naming recommendations.
- Next to Resource email, copy the Google Workspace calendar resource email.
For example, firstname.lastname@example.org.
Note: When you're migrating calendar resources, you will also need a mapping CSV file. For details, go to Create a mapping CSV file.
Variations on the control CSV fileMigrating from an Exchange server
If you're migrating from an Exchange server, we recommend you use the same usernames in Google Workspace 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.
In the example, the sourceuser email@example.com is identical to the targetuser, so you can exclude it.
If the addresses in your Exchange source domain environment are different from the addresses in your Google Workspace target domain environment, you need 2 addresses per line in the CSV file—the source user address followed by the target user address.
In the example, the sourceuser firstname.lastname@example.org in Exchange is migrated to the targetuser email@example.com in Google Workspace.
Some IMAP servers can migrate data using an administrator's username and password. You don't have to include the password for every user.
Google Workspace IMAP migrations
Note: These instructions apply if you're migrating data from Google Workspace, not personal Gmail accounts (for example, a @gmail.com account).
Before starting a Google Workspace IMAP migration, you need to authorize GWMME. For details, go to Authorize GWMME 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, go to 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 GWMME 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, go to "Step 1: Special instructions for Cyrus IMAP" in the GWMME 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 Google Workspace, Cyrus, Mirapoint, or Exchange, you must include the user's IMAP username, password, and Google Workspace username. The basic format is sourceuser-email#sourceuser-password, destinationuser-email.
Example: firstname.lastname@example.org#fKz47MCb, email@example.com
Use the same username 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 "jensmith"). When in doubt, use the full destination email address for the user.
Note: The domain you specify in step 1 of the GWMME tool must be the primary Google Workspace target domain environment you're migrating users to. If you're migrating mail to a Google Workspace account with secondary domains, the target domain you choose might differ from the domain in the email addresses you’re migrating.
If you're migrating data using Personal Storage Table (PST) files, the basic format for the control CSV file is: user-folder-name, destinationuser.
Example: jen-smith-pst-archive, email@example.com
For details, go to Migrate data from PST files.
In the following situation, you need a mapping CSV file, in addition to a control CSV file, if:
- You're migrating calendar data; and
- Any addresses for your organization's users in your Exchange source domain environment are different from the addresses in your Google Workspace target domain environment.
Example: firstname.lastname@example.org, email@example.com
Note: When migrating calendar resources, source domain and target domain addresses are always different.
When the differing domain addresses are attendees in calendar events in other people's calendars you're migrating. Use the mapping CSV file to list all user accounts and calendar resources—even if some of the users aren’t migrated at this time.
For details, go to Create a mapping CSV file.
Google, Google Workspace, and related marks and logos are trademarks of Google LLC. All other company and product names are trademarks of the companies with which they are associated.