Applies to: Office 365 for enterprises, Live@edu
Topic last modified: 2013-01-15
You can use Windows PowerShell and a CSV file to migrate the contents of user mailboxes from an on-premises IMAP messaging system to the cloud-based service. Here's how:
To prepare for the email migration:
- Create a cloud-based mailbox for each user that you will migrate Before you can migrate data from a user's on-premises mailbox, the user has to have a cloud-based mailbox and Windows Live ID. You include the user's Windows Live ID in the CSV migration file. Here's how to create new mailboxes:
- Decide how to divide a large migration into multiple batches The CSV migration file contains the user information required for the migration process. It can contain up to 50,000 rows, one row for each user, but it's a good idea is to migrate users in several smaller batches. If you plan to migrate lots of users, decide which ones to include in each batch. For example, if you have 10,000 accounts to migrate, you could run four batches with 2,500 users each, or you could divide the batches alphabetically, by user type, such as faculty, students and alumni, by year, such as first, second, third and fourth, or in other ways that meet your organisation's needs.
- Decide which credentials to use to access on-premises mailboxes In the CSV migration file, you have to provide the username and password for the user's on-premises account. This enables the migration process to access the account during the migration process. There are two ways to do this:
- Use end-user credentials in the CSV file This requires that you obtain users' passwords or that you change their passwords.
- Use super-user or service account credentials in the CSV file This requires that you use a super-user account or service account that has rights to access all on-premises mailboxes. In the CSV migration file, you use the credentials for this account for each user. To learn whether your IMAP server supports this approach and how to enable it, see the documentation for your IMAP server.
Tip We recommend using super-user credentials because it doesn't affect or inconvenience users.
- Use end-user credentials in the CSV file This requires that you obtain users' passwords or that you change their passwords.
- Install and configure Windows PowerShell and connect to the cloud-based service Use Windows PowerShell on a local computer to connect to your cloud-based organisation and perform the migration. The CSV migration file has to be located on the same computer. To set up Windows PowerShell, see Use Windows PowerShell.
Here are the required attributes for each user:
- EmailAddress specifies the Windows Live ID for the user's account in the cloud.
- UserName specifies the user logon name for the user's on-premises account.
- Password is the password for the user's on-premises account.
The migration request will fail if any one of these attributes isn't included in the header row of the CSV migration file. Also, type the attributes exactly as they are shown. Attributes can't contain spaces. They must be a single word. For example, Email Address is invalid. You must use EmailAddress.
Here's an example of the format for a CSV migration file. In this example, three users are migrated:
EmailAddress,UserName,Password terrya@contoso.edu,terry.adams,1091990 annb@contoso.edu,ann.beebe,2111991 chrisc@contoso.edu,chris.cannon,3281986
The first row, or header row, of the CSV file lists the names of the attributes, or fields, specified in the rows that follow. Each attribute name is separated by a comma.
Each row under the header row represents one user and supplies the information that will be used to migrate that user. The attribute values in each row must be in the same order as the attribute names in the header row. Each attribute value is separated by a comma.
Use any text editor, or an application like Microsoft Office Excel, to create the CSV file. Save the file as a .csv or .txt file.
Use the username and password of the super-user account in the UserName and Password fields for each row of the CSV migration file. For example, in the IMAP implementation for Microsoft Exchange, use the format Domain/Admin_UserName/User_UserName for the super-user credentials. For IMAP servers that support Simple Authentication and Security Layer (SASL), use the format Admin_UserName*User_UserName where the asterisk ( * ) is a configurable separator character. For more information about how to use super-user credentials, see the documentation for your IMAP server.
Note When you submit a new migration request, the CSV file is uploaded to the Microsoft datacentre over a Secure Sockets Layer (SSL) connection. The information from the CSV file is encrypted and stored on the Microsoft Exchange servers at the Microsoft datacentre.
Let's say you're migrating email from Microsoft Exchange for Terry Adams, Ann Beebe and Chris Cannon. You have an administrative service account, where the username is administrator and the password is Pa$$word1. Here's what your CSV file would look like:
Alternatively, let's say you're migrating those users' email from a Dovecot server, with an administrative service account (administrator and Pa$$word1). Here's what your CSV file would look like:
It's a best practice to run a test migration of a small batch of users before you migrate a large number of users. In the test migration, you can do the following:
-
Troubleshoot potential problems and minimise errors when you migrate a large batch of users.
-
Verify the format of the CSV file.
-
Verify the format of the super-user credentials, if applicable.
-
Test the following:
-
Connection settings to the remote IMAP server
-
The impact on your network performance based on the number of connections to the IMAP server. This is specified by the MaxConcurrentMigrations parameter on the New-MigrationBatch cmdlet.
-
The exclusion of folders
-
Security and authentication parameters
-
Migration status email messages
-
Connection settings to the remote IMAP server
Perform the following steps to migrate mailboxes to the cloud-based service:
- Test the availability of the remote IMAP server.
- Submit a new migration batch request.
- Start the migration batch.
- Submit and start additional migration batches.
- Configure your MX record to point to the cloud-based service.
- Complete the migration.
The first step in the migration process is to test the availability of your IMAP server and to verify the server's FQDN and the port used to receive the IMAP requests. Run the following Windows PowerShell command to test IMAP server availability:
Here's an example for an IMAP server named imap.contoso.edu using port 143, which is the port reserved for unencrypted IMAP communication:
The results of the command confirm whether you successfully connected to the IMAP server.
The next step is to use the New-MigrationBatch cmdlet to submit a new migration batch request. If a migration batch is already running, you can't submit a new one until the current batch is finished running. Use the Get-MigrationBatch cmdlet to determine if a migration batch is running.
The following syntax includes the required parameters:
New-MigrationBatch -Imap -Name <name for the migration batch> -CSVData ([System.IO.File]::ReadAllBytes(<path of the CSV migration file>)) -MaxConcurrentMigrations <number between 1 and 10> -RemoteServer <server FQDN> -Port <port number> Timezone <timezone>
Here's an example:
New-MigrationBatch -Imap -Name MigrationBatch1 -CSVData:([System.IO.File]::ReadAllBytes("C:\Users\Administrator\Desktop\MigrationBatch_1.csv")) -MaxConcurrentMigrations 3 -RemoteServer imap.contoso.edu -Port 143 -Timezone "Pacific Standard Time" -ExcludeFolders "Deleted Items","Junk Mail"
Here's a description of the parameters used in this example.
| Parameter | Value | Description |
|---|---|---|
| Imap | None. No value is required. | The Imap parameter specifies IMAP as the migration type. In this release, IMAP is the only option. Future releases may include other messaging solutions, such as POP or Windows Live Hotmail. |
| Name | MigrationBatch1 | The Name parameter provides a name for the migration batch request. |
| CSVData | C:\Users\Administrator\Desktop\MigrationBatch_1.csv | The CSVData parameter provides the absolute path for the CSV migration file. The CSV file is located on the computer on which the administrator is running Windows PowerShell. |
| MaxConcurrentMigrations | 3 | The MaxConcurrentMigrations parameter specifies the number of connections to the IMAP server. Three connections means that three mailboxes will be migrated at any one time until all the rows in the CSV file are processed. |
| RemoteServer | imap.contoso.edu | The RemoteServer parameter specifies the FQDN of the IMAP server for the on-premises messaging system. |
| Port | 143 | The Port parameter specifies the port on the server used to receive the IMAP requests. |
| TimeZone | "Pacific Standard Time" | The TimeZone parameter specifies the time zone of the administrator who is submitting the migration batch. You can use Windows PowerShell to retrieve time zone names from the registry, for example: |
| ExcludeFolders (Optional) | "Deleted Items","Junk Mail" | The ExcludedFolder parameter specifies the folders that you don't want to migrate to the cloud. Folder names are relative to the IMAP root on the on-premises mail server. |
If the CSV file is validated and the availability of the IMAP server is verified, a migration job is created for the new migration batch.
Run the following command to start the migration batch:
Here's an example to start a migration and have the migration status email message sent to multiple recipients:
Start-MigrationBatch -NotificationEmails "super-user@contoso.edu","helpdesk@contoso.edu","CIO@contoso.edu"
By default, the migration status email message is sent to the administrator who runs the Start-MigrationBatch cmdlet, but you can include additional recipients by using the optional NotificationEmails parameter.
The message sent after the migration batch is finished running contains the following information:
-
Name of the CSV file used for the migration: in this case, MigrationBatch_1.csv
-
Date and time when the migration batch was started
-
Total time it took to complete the migration process
-
Number of mailboxes successfully migrated
-
Number of mailboxes that failed migration
-
An attached migration errors CSV file (named MigrationErrors.csv) if there were failed migrations
In the MigrationErrors.csv file attached to the migration status email message, use the information in the ErrorMessage column of each row to identify and fix the problem that caused the row to fail. Then resubmit the fixed rows in a new CSV file.
Repeat steps 2 and 3 to submit and start additional migration batches. Each migration batch has its own CSV migration file. The Name parameter for each migration batch must be unique. Only one migration batch can be active at any one time.
After you submit and complete all migration batches, the next step is to configure your MX record to route email sent to your organisation to the cloud-based service.
Until you change your MX record, email sent to users is still routed to their on-premises mailboxes. When a user mailbox is successfully synchronized, the on-premises mailbox and cloud-based mailbox are periodically synchronised until you complete the overall migration. This lets users use their cloud-based account to access email sent to their on-premises mailbox. After you configure your organisation's MX record, mail is sent directly to the cloud-based service.
Important It can take from 24 to 72 hours for the updated MX record to be propagated. Wait at least 24 hours after you change the MX record before you complete the migration. Be sure to verify that mail is being routed to cloud-based mailboxes before you complete the migration.
The final step in the migration process is to run the Complete-Migration cmdlet to finalise the migration process. When you complete the migration, Microsoft Exchange performs a final synchronisation for all migration requests.
Run the following command to complete the migration batch:
Here's an example that completes a migration and has the final migration status message sent to super-user@contoso.edu.
By default, the final status message is sent to the administrator who runs the Complete-Migration cmdlet.
You can get status on migration batches in progress or pending, and on the overall migration before it's completed.
Run this command to get status on the migration batch that's currently in progress or is pending:
This command returns the following information:
-
Status of the migration batch that's currently in progress or is pending
-
Start date and time
-
Connection settings for the migration batch
-
Number of migration requests in the batch
-
Number of mailboxes that have been migrated
-
Validation errors in the CSV migration file
-
Errors that occurred while processing the migration batch
-
Email addresses for migration status email messages
Run this command to get status on the overall migration:
This command returns the following information for the overall migration, which can consist of one or more migration batches:
-
Status of the overall migration
-
Number of mailbox migration requests from all migration batches
-
Number of mailboxes that have been migrated
-
Migration errors
Run this command to stop a migration batch that is being processed:
You can only stop migration batches that have mailboxes that are in the process of being migrated or are waiting to be migrated. Stopping a migration won't affect mailboxes that have been migrated. If all migration requests in a migration batch are either complete or failed, this command won't run. The migration of mailboxes that are being actively migrated is completed before the migration batch is cancelled.
The administrator receives a migration status email message that specifies how many mailboxes successfully completed migration before the batch was stopped. The email also has an attached migration errors CSV file that includes the rows that were in progress when the migration was stopped and the rows waiting to be migrated.
You can get help for the IMAP migration cmdlets at the Windows PowerShell command line. Use command-line help to identify the parameters that are used with each cmdlet and the appropriate syntax.
Command-line help can return different detail levels of information. Use the following commands to get more targeted help at the command line.
| Help command | Description | Example |
|---|---|---|
| Get-Help <cmdlet> | Provides information about the cmdlet usage and syntax. | |
| Get-Help <cmdlet> -Examples | Shows examples of common cmdlet usage. | |
| Get-Help <cmdlet> -Detailed | Provides the cmdlet description, syntax, a full list of parameters and their usage, and examples. | |
Learn more about the Get-Help cmdlet and associated syntax in the Microsoft Exchange Server help: Getting Help. Although this topic refers to Exchange Server 2007 for on-premises deployments, the content also applies to the cloud-based service and Windows PowerShell V2 with WinRM.
