Create a control CSV file for user accounts

G Suite Migration for Microsoft Exchange

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 file

Migrating 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: jsmith@solarmora.com, johnsmith@solarmora.com

Migrating email, contacts, and calendar resources

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: board-room-1@solarmora.com, solarmora.com_37r2903631@resource.calendar.google.com

To find the G Suite calendar resource email: 

  1. Sign in to your Google Admin console.

    Sign in using your administrator account (does not end in @gmail.com).

  2. From the Admin console Home page, go to Appsand thenG Suiteand thenCalendar.
  3. Click Resources.
  4. Point to the calendar resource and click Edit Edit.
  5. 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 format

Migrating 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.

Example: jsmith@solarmora.com

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: jsmith@solarmora.com, johnsmith@solarmora.com

Migrating from G Suite, Cyrus, Mirapoint, or Exchange IMAP servers

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: user1@gsuite-domain1.com, user1@gsuite-domain2.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: user1@cyrus-domain.com, user1@gsuite-domain.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: windowsdomain/exchangeadmin/user@exchange-domain.com#adminpassword, user@gsuite-domain.com.

Example: solarmora/admin/johnsmith@solarmora.com#VjJ8zTsm, johnsmith@solarmora.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 johnsmith@solarmora.com.

Exchange Online (Office 365) IMAP migrations (not regular Exchange migrations)

Use the following syntax for the control CSV file:
admin@exchange-domain.com/user@exchange-domain.com#adminpassword, user@gsuite-domain.com.

Example: admin@solarmora.com/johnsmith@solarmora.com#VjJ8zTsm, johnsmith@solarmora.com

In this example, the Exchange Online administrator username is admin@solarmora.com, and the administrator's password is VjJ8zTsm. The administrator is migrating email for the user johnsmith@solarmora.com.

Migrating from other IMAP servers

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: johnsmith@solarmora.com#fKz47MCb, johnsmith@solarmora.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, "johnsmith@solarmora.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.

Migrating from PST files

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, johnsmith@solarmora.com

For details, see Migrate from PST files.

When do I also need a mapping file? 

In the following situation, you need a mapping CSV file as well as a control CSV file: 

  1. You're migrating calendar data; and 
  2. 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: jsmith@solarmora.com and johnsmith@solarmora.com

For details, see Create a mapping CSV file.

Was this helpful?
How can we improve it?