Edit

Share via

Use PowerShell to perform a cutover migration to Microsoft 365

  • Article

This article applies to both Microsoft 365 Enterprise and Office 365 Enterprise.

You can migrate the contents of user mailboxes from a source email system to Microsoft 365 all at once by using a cutover migration. This article walks you through the tasks for an email cutover migration by using Exchange Online PowerShell.

By reviewing the article What you need to know about a cutover email migration to Microsoft 365, you can get an overview of the migration process. When you're comfortable with the contents of that article, use this one to begin migrating mailboxes from one email system to another.

Note

You can also use the Exchange admin center to perform a cutover migration. See Perform a cutover migration of email to Microsoft 365.

What do you need to know before you begin?

Estimated time to complete this task: 2-5 minutes to create a migration batch. After the migration batch is started, the duration of the migration will vary based on the number of mailboxes in the batch, the size of each mailbox, and your available network capacity. For information about other factors that affect how long it takes to migrate mailboxes to Microsoft 365, see Migration Performance.

You need to be assigned permissions before you can perform this procedure or procedures. To see what permissions you need, see the "Migration" entry in a table in the Recipients Permissions article.

To use the Exchange Online PowerShell cmdlets, you need to sign in and import the cmdlets into your local Windows PowerShell session. See Connect to Exchange Online PowerShell for instructions.

For a full list of migration commands, see Move and migration cmdlets.

Migration steps

Step 1: Prepare for a cutover migration

  • Add your on-premises Exchange organization as an accepted domain of your Microsoft 365 organization. The migration service uses the SMTP address of your on-premises mailboxes to create the Microsoft Online Services user ID and email address for the new Microsoft 365 mailboxes. Migration will fail if your Exchange domain isn't an accepted domain or the primary domain of your Microsoft 365 organization. For more information, see Verify your domain.

  • Configure Outlook Anywhere on your on-premises Exchange server. The email migration service uses RPC over HTTP, or Outlook Anywhere, to connect to your on-premises Exchange server. For information about how to set up Outlook Anywhere for Exchange 2010, Exchange 2007, and Exchange 2003, see the following:

  • Verify that you can connect to your Exchange organization using Outlook Anywhere. Try one of these methods to test your connection settings:

    • Use Microsoft Outlook from outside your corporate network to connect to your on-premises Exchange mailbox.

    • Use the Microsoft Exchange Remote Connectivity Analyzer to test your connection settings. Use the Outlook Anywhere (RPC over HTTP) or Outlook Autodiscover tests.

    • Run the following commands in Exchange Online PowerShell.

    $Credentials = Get-Credential

    Test-MigrationServerAvailability -ExchangeOutlookAnywhere -Autodiscover -EmailAddress <email address for on-premises administrator> -Credentials $credentials

  • Assign an on-premises user account the necessary permissions to access mailboxes in your Exchange organization. The on-premises user account that you use to connect to your on-premises Exchange organization (also called the migration administrator) must have the necessary permissions to access the on-premises mailboxes that you want to migrate to Microsoft 365. This user account is used to create a migration endpoint to your on-premises organization.

    The following list shows the administrative privileges required to migrate mailboxes using a cutover migration. There are three possible options.

    • The migration administrator must be a member of the Domain Admins group in Active Directory in the on-premises organization.

      Or

    • The migration administrator must be assigned the FullAccess permission for each on-premises mailbox.

      Or

    • The migration administrator must be assigned the Receive As permission on the on-premises mailbox database that stores the user mailboxes.

  • Disable Unified Messaging. If the on-premises mailboxes you're migrating are enabled for Unified Messaging (UM), you have to disable UM on the mailboxes before you migrate them. You can then enable UM on the mailboxes after the migration is complete.

  • Security Groups and Delegates The email migration service can't detect whether on-premises Active Directory groups are security groups or not, so it can't provision any migrated groups as security groups in Microsoft 365. If you want to have security groups in your Microsoft 365 tenant, you must first provision an empty mail-enabled security group in your Microsoft 365 tenant before starting the cutover migration. Additionally, this migration method only moves mailboxes, mail users, mail contacts, and mail-enabled groups. If any other Active Directory object, such as user that isn't migrated to Microsoft 365, is assigned as a manager or delegate to an object being migrated, they must be removed from the object before you migrate.

Step 2: Create a migration endpoint

To migrate email successfully, Microsoft 365 needs to connect and communicate with the source email system. To do this, Microsoft 365 uses a migration endpoint. To create an Outlook Anywhere migration endpoint for cutover migration, first connect to Exchange Online.

For a full list of migration commands, see Move and migration cmdlets.

Run the following commands in Exchange Online PowerShell:

$Credentials = Get-Credential

The example uses the Test-MigrationServerAvailability cmdlet to obtain and test the connection settings to the on-premises Exchange server, and then uses those connection settings to create the migration endpoint called "CutoverEndpoint".

$TSMA = Test-MigrationServerAvailability -ExchangeOutlookAnywhere -Autodiscover -EmailAddress administrator@contoso.com -Credentials $credentials

New-MigrationEndpoint -ExchangeOutlookAnywhere -Name CutoverEndpoint -ConnectionSettings $TSMA.ConnectionSettings

Note

The New-MigrationEndpoint cmdlet can be used to specify a database for the service to use by using the -TargetDatabase option. Otherwise a database is randomly assigned from the Active Directory Federation Services (AD FS) 2.0 site where the management mailbox is located.

Verify it worked

In Exchange Online PowerShell, run the following command to display information about the "CutoverEndpoint" migration endpoint:

Get-MigrationEndpoint CutoverEndpoint | Format-List EndpointType,ExchangeServer,UseAutoDiscover,Max*

Step 3: Create the cutover migration batch

You can use the New-MigrationBatch cmdlet in Exchange Online PowerShell to create a migration batch for a cutover migration. You can create a migration batch and start it automatically by including the AutoStart parameter. Alternatively, you can create the migration batch and then manually start it afterwards by using the Start-MigrationBatch cmdlet. This example creates a migration batch called "CutoverBatch" and uses the migration endpoint that was created in the previous step.

New-MigrationBatch -Name CutoverBatch -SourceEndpoint CutoverEndpoint -AutoStart

This example also creates a migration batch called "CutoverBatch" and uses the migration endpoint that was created in the previous step. Because the AutoStart parameter isn't included, the migration batch has to be manually started on the migration dashboard or by using Start-MigrationBatch cmdlet. As previously stated, only one cutover migration batch can exist at a time.

New-MigrationBatch -Name CutoverBatch -SourceEndpoint CutoverEndpoint

Verify it worked

To verify that you've successfully created a migration batch for a cutover migration, run the following command in Exchange Online PowerShell to display information about the new migration batch:

Get-MigrationBatch | Format-List

Step 4: Start the cutover migration batch

To start the migration batch in Exchange Online PowerShell, run the following command. This will create a migration batch called "CutoverBatch".

Start-MigrationBatch -Identity CutoverBatch

Verify it worked

If a migration batch is successfully started, its status on the migration dashboard is specified as Syncing. To verify that you've successfully started a migration batch using Exchange Online PowerShell, run the following command:

Get-MigrationBatch -Identity CutoverBatch |  Format-List Status

Step 5: Route your email to Microsoft 365

Email systems use a DNS record called an MX record to figure out where to deliver emails. During the email migration process, your MX record was pointing to your source email system. Now that the email migration to Microsoft 365 is complete, it's time to point your MX record at Microsoft 365. This helps make sure that email is delivered to your Microsoft 365 mailboxes. By moving the MX record, you can also you turn off your old email system when you're ready.

For many DNS providers, there are specific instructions to change your MX record. If your DNS provider isn't included, or if you want to get a sense of the general directions, general MX record instructions are provided as well.

It can take up to 72 hours for the email systems of your customers and partners to recognize the changed MX record. Wait at least 72 hours before you proceed to the next task: Step 6: Delete the cutover migration batch.

Step 6: Delete the cutover migration batch

After you change the MX record and verify that all email is being routed to Microsoft 365 mailboxes, notify the users that their mail is going to Microsoft 365. After this, you can delete the cutover migration batch. Verify the following before you delete the migration batch.

  • All users are using Microsoft 365 mailboxes. After the batch is deleted, mail sent to mailboxes on the on-premises Exchange Server isn't copied to the corresponding Microsoft 365 mailboxes.

  • Microsoft 365 mailboxes were synchronized at least once after mail began being sent directly to them. To do this, make sure that the value in the Last Synced Time box for the migration batch is more recent than when mail started being routed directly to Microsoft 365 mailboxes.

To delete the "CutoverBatch" migration batch in Exchange Online PowerShell, run the following command:

Remove-MigrationBatch -Identity CutoverBatch

Section 7: Assign user licenses

Activate Microsoft 365 user accounts for the migrated accounts by assigning licenses. If you don't assign a license, the mailbox is disabled when the grace period ends (30 days). To assign a license in the Microsoft 365 admin center, see Assign or unassign licenses.

Step 8: Complete post-migration tasks

  • Create an Autodiscover DNS record so users can easily get to their mailboxes. After all on-premises mailboxes are migrated to Microsoft 365, you can configure an Autodiscover DNS record for your Microsoft 365 organization to enable users to easily connect to their new Microsoft 365 mailboxes with Outlook and mobile clients. This new Autodiscover DNS record has to use the same namespace that you're using for your Microsoft 365 organization. For example, if your cloud-based namespace is cloud.contoso.com, the Autodiscover DNS record you need to create is autodiscover.cloud.contoso.com.

    If you keep your Exchange Server, you should also make sure that Autodiscover DNS CNAME record has to point to Microsoft 365 in both internal and external DNS after the migration so that the Outlook client will to connect to the correct mailbox.

    Note

    In Exchange 2007, Exchange 2010, and Exchange 2013 you should also set Set-ClientAccessServer AutodiscoverInternalConnectionURI to Null.

    Microsoft 365 uses a CNAME record to implement the Autodiscover service for Outlook and mobile clients. The Autodiscover CNAME record must contain the following information:

  • Decommission on-premises Exchange servers. After you've verified that all email is being routed directly to the Microsoft 365 mailboxes, and you no longer need to maintain your on-premises email organization or don't plan on implementing a single sign-on (SSO) solution, you can uninstall Exchange from your servers and remove your on-premises Exchange organization.

    For more information, see the following: