Hybrid Exchange Management Guide

Starting out with the Hybrid Management Tool

This document serves as a migration guide for the Exchange Hybrid system when using the Hybrid Management Tool for MigrationWiz. From preparing the environment to performing the final cutover, all the necessary steps are covered below.


For this migration type, you will need MigrationWiz-Hybrid Exchange Management licenses. These may be purchased through our store or your usual sales channels. 

Getting Started - An Overview


A configured and working Hybrid configuration must be in place between your source Exchange environment and the Microsoft 365 tenant for a successful migration. To ensure these prerequisites are met, we suggest working through the following checklist. Once each question can be answered with "Yes," proceed to the next step in the guide.

  • Creation of Microsoft 365 tenant with domain (Namespace) configuration is completed.
  • Microsoft Entra Connect is set up and configured to include all Organizational Units where Mailbox accounts that will be migrated exist.
  • The Hybrid Configuration Wizard has been run successfully, meaning that all aspects of the connectors have been configured. This extends to the Mail Flow Connectors/Federation and MRS Endpoints.
  • Mail flow to the migrated account is working successfully, with an MX record pointing either into Exchange Online Protection or still On-Premises, depending on your desired cutover state.
  • The MRS EndPoint is accessible from inside Microsoft 365, meaning that a test of a single mailbox into the Microsoft 365 tenant has been completed.
  • The use of auto-discovery and upload process function requires a Source with Exchange 2013 and after. A system with Exchange 2010 will require the steps of importing a CSV file found here to upload users and settings.
  • Modern Authentication is now the default authentication method to be used with MigrationWiz and Exchange Online due to Microsoft discontinuing support for Basic Authentication in Exchange Online at the end of December 2022. The following Microsoft documentation outlines this change in more detail. Should you have additional questions on how this change may impact your tenant, please contact Microsoft to assist with providing that information: Deprecation of Basic authentication in Exchange Online

The full Prerequisites article offers more detail on how this can be achieved, with links to the various Microsoft articles that facilitate this. Hybrid Exchange Management System - Prerequisites


Please note that the use DeploymentPro system is not required in an Exchange Hybrid migration because the hybrid function inherently updates the Outlook profile in conjunction with the mailbox data migration.
However, it should be noted that DeploymentPro could still be useful in a non-hybrid migration scenario, where it could be used to automate the creation of a new Outlook profile.

Create a New Project

MigrationWiz now features a project type called Hybrid Migration Project. Once this option is selected, you will be asked to provide the name and the details of the customer it is allocated to. Note that only one Hybrid Project can be configured per customer. The other items needed are;

  • Source Settings - The name for the On-Premises Exchange endpoint. No other details are necessary here as the connection is established via the MRS endpoint configured in Hybrid Configuration.
  • Destination Settings - The details of the Microsoft 365 tenant. For full information on options, see Create New Project, below.
  • Advanced Settings - This controls how the delegates are handled by default. 

Discover the Mailboxes

Before any migration can occur, it is necessary to bring in all of the mailbox information. This is done either by the Exchange Agent or by Importing CSV. To use the Exchange Agent, download the tool from the Start Discovery flyout in MigrationWiz and install/run it on a server/workstation in an Exchange environment that has the appropriate rights to read the information. More in-depth information on this agent is found later in this documentation. This is then used to send the mailbox data into the MigrationWiz console. Discovery options are:

Mailbox Batches

The batching of mailboxes is handled automatically by the import (discovery) process. Mailboxes will be placed inside batches that are named after the OU they were residing in, or by way of the BatchName specified in the CSV file during the import. 

Once the mailboxes are in the system, they can be added to or moved to custom migration batches, which you will set up as part of the migration. The Update Existing Mailboxes section in the batching documentation provides more detail on exactly how mailboxes will behave in batches that are either rediscovered or re-imported.

Once your batches are ready to sync, continue to the next step.

Sync the Mailboxes

In the main batch view, click the button labeled Start Sync. This provides you with many options to control how the Sync process works. The first item reports on whether or not any Delegates in the project should be migrated alongside these mailboxes. This is a simple option that means that no delegates are left on-premises if their corresponding mailbox is being migrated ahead of them.

You may also assign a Microsoft 365 license to the mailboxes here, as well as select the MRS endpoint to use and set the error tolerance.

Note that the assigning of a Microsoft 365 license is an optional step and can be left in the default state to not assign a license.

The option to schedule a batch in the future is given here. Set a time that you wish the synchronization to begin. This is in the 'Local Time' of the user that is performing the task.

Once you've accepted these options, the batch moves into the Sync processing status. It will update on the main console once it has finished.

More details on this process can be found below

Finalize the Mailboxes

The last step in the migration is to Finalize the mailboxes and over the mailboxes into Microsoft 365. This function appears after a successful sync and is the 'Start Finalization' button. This process also provides additional functionality by way of enforcing settings such as IMAP/POP/OWA/ActiveSync on mailbox as well as a retention policy. You can also notify the users of the impending migration process.

Once again, there is a schedule option for the process to run at a later date.

Note that this is a final step in the process and the check box acknowledges that this is such a step.

More details on this process can be found here.

Create New Project

To create a new project in the Migration Wiz console, start by selecting the + Create Project selector, then click Hybrid Exchange Project.


As with normal MigrationWiz projects, you will be asked to select a project name and assign it to a customer. Remember that each customer can only have one Hybrid project assigned to them.

In the source settings, the only source available to select from is On-Premises Exchange. You can provide a name for this endpoint but the type will stay Hybrid Exchange.

The destination settings do contain several items that are critical to the success of the project: 

Endpoint Name - The name for this endpoint.

Endpoint Type - This can only be Microsoft 365 (Hybrid Migrations).

Administrator Email Address - Valid Tenant Account with rights to perform the following tasks:

  • Read mailbox information, such as proxy addresses
  • Lookup licensing information and apply to mailboxes
  • Start Synchronization and Finalization tasks
  • Lookup MRS endpoint information
  • Update mailboxes with POP/IMAP/OWA/ActiveSync/Retention Policies post migration

For this tenant admin account, the rights can be given as Global Admin, however, this is not a recommended practice. Instead, the rights required for the account are 'License Admin' and 'Recipient Management', both of which are added in two separate places.

  1. The License Admin right can be given in the Microsoft 365 User Admin screen. Under the Account options, select the 'Manage Roles' link. The License Admin can be located in the Identity section.
  2. The Recipient Management for Exchange Online can be given whilst inside the Exchange Admin Center. Navigate to 'Permissions', then 'Admin Roles'. Select the 'Recipient Admin' and edit the role. Inside the dialog box that appears is the option to apply explicit Members to this role. Note that it can take up to 30 minutes for a newly created account to show up in the selectable members list in this dialog box.


The rights at the On-Premises Exchange Server are provided during the creation of the Hybrid Endpoint and do not need to be entered into the MigrationWiz project.

Administrator Password - The password for the admin account.

Target Delivery Domain - This can be either the external namespace for the domain being used or the onmicrosoft.com namespace that is assigned to the tenant. It must be a namespace that is applied to ALL mailboxes that access the tenant as part of the Recipient Address Policy, as per normal native Hybrid migrations.

Note that it is preferred that the tenantname.mail.onmicrosoft.com be used now, as this is always an acceptable target delivery domain. There have been cases where the simple tenantname.onmicrosoft.com has not been provisioned by the HCW so we are now recommending the 'mail' to be included in the name.


This project creation process will not immediately validate your credentials. If information has been entered incorrectly, a project log will appear and you will not be able to select an endpoint to start the sync. Before creating the endpoint, verify that your credentials and target delivery domain are correct. 

Batching Mailboxes

Please refer to the Batching Mailboxes section here for full details about batching, both with the Agent and the Import CSV option.

Moving Mailboxes in the Console 

In the batch console view, any mailbox can be moved to a different batch that is in a not-submitted status. If the batch is in any other status (Sync, Syncing, Finalized, Failed), no mailboxes may be moved into it. This is achieved by checking (via checkbox) the mailboxeto be moved and selecting the Move Mailboxes button. From here you can select either the batch to move them to or unbatched mailboxes. 

Note that the batch needs to be created before you can move mailboxes into it. There is no function to create the batch in the move procedure.

When moving users to a new batch, as recommended in the console, please do not close the window. Allow it to complete the move and close the window automatically.

Delegate Processing

Delegation hierarchy batching is based on Full Access mailbox permissions only.  Send-As and Send-On-Behalf-Of permissions are not linked to the structure.

Delegates themselves are kept in the batches where they were imported, whether it be by the Exchange Agent or by the CSV file. However, as the delegates must get migrated along with the mailboxes that they are looking after, there are controls in the system to account for this.

A symbol that is placed next to a user to show that they are a delegate, or have a delegate. At a batch level, the symbol is also shown so that you know the batch contains mailboxes with delegates.

Showing Delegates

To easily display the delegates of a mailbox, click on the delegate icon that is located next to the mailbox's SMTP address. If a mailbox does not have delegates then this icon will not be displayed. The output on the fly-out is shown below. Notice how the Batch Name is also displayed next to the delegate mailbox, this is helpful to confirm that the mailbox exists in the same batch as if it does not, it will have a warning icon next to it.


Checking for Delegates in a Batch

When a batch view is open and displaying the mailboxes that are in that batch, there is an option to look at the rest of the system to see if there are any delegates that can be brought in. With this function, you can easily consolidate users that are delegated into the batch. 


Clicking this button will check for delegates that are linked to the mailboxes but not currently in the batch and give you the opportunity to bring them in.


Clicking on the 'Move Delegates' button in the flyout will bring these mailboxes into the current batch.

This button is disabled if the Delegates handling function is set to 'None' in the Advanced Options.

Moving Delegates along with Mailboxes

If the mailbox is moved to another batch, the system will check for delegates and ask if those delegates should be moved into the new batch as well. mceclip3.png

Moving Delegates as a Sync starts

When a batch is started, the system checks for delegates and asks if any delegates that are part of the batch should also be synced in this batch. The toggle 'Show Delegates' will display the list of Delegates that will be moved.


By doing this, we make sure that all delegates are processed together, if that is the desired option, or processed separately if needed.

Statuses in Hybrid Migrations

Not submitted

The batch has not been submitted for syncing. Users can still be moved into the batch in this state.


The batch has been submitted and syncing has started. Users can no longer be moved into the batch. Users can be moved out of the batch, which will delete any information migrated for the removed user. This process will sync 95% of the mailbox and the Microsoft license will be applied to the user in the Destination tenant.


The mailbox has been successfully synced to 95% and is now pending finalization. Mailboxes will continue to sync changes until Finalization is started.


The finalization process has been started. This process syncs the last 5% of the mailbox and applies all mailbox attributes to the user as configured in the Advanced Options.


Finalization has been completed successfully. The user's mailbox has been cutover to Microsoft 365, all pre-configured settings have been applied, and the user is now using the Microsoft 365 mailbox instead of the Hybrid Exchange mailbox.

Sync Failed

The process failed for some reason. The syncing or finalization process has been terminated.

Sync Stopping

The sync is being manually stopped by the user, syncing has been interrupted. The batch may not be moved or edited during this phase.

Sync Stopped

The sync has been manually interrupted by the user via the Stop Sync button.

Sync Scheduled

The sync is scheduled to run at a future date/time. Hover over the status to check the date/time.

Finalization Scheduled

The finalization is scheduled to run at a future date/time. Hover over the status to check the date/time.

Starting Sync Process for Mailboxes

When you are ready to synchronize a batch of mailboxes onto Microsoft 365, click the button labeled Start Sync on the migration console.

The time to process the batches to 95% will be determined by many factors.

  • Internet speed from the on-premises Exchange to the Microsoft 365 servers
  • Overall workloads on the Exchange server
  • The size of the mailboxes

It is a good idea to synchronize the mailboxes as far ahead of time as possible to ensure they finish on time. As the system is controlled by the Microsoft 365 backend, it is difficult to place actual timing on each batch. It is a good idea to run a small batch of users as a test candidate to see what throughput your organization can achieve before running the entire migration.

The batch will, at this point, check for any delegates that may need to be brought into the batch and then provide some options around the batch. These are shown below, filled in for reference.


Select Source Endpoint - The MRS Endpoint in the local Exchange server to connect to

Set User Location - Select the location of the user for correct location provisioning

Error Count - Select the maximum number of errors (large items/corrupt items) before the migration fails.

Scheduling - Here you can set a batch to start synchronizing at a future date.

Once you are ready with these options, select the Start Sync button to commence.

On the main project screen, you can see that they have started. Note that, because we moved the delegate with the mailbox it was associated with, we now have a batch with zero users in it, the PA batch.



Once a batch has been started, it will take a few minutes to 'Initialize' this process. Therefore if you wish to stop the batch very soon after the Start Sync has been actioned, it will need a few minutes before it can trigger the stop process. If you attempt to stop the batch before it has initialized then you will be presented with a notice telling you that the initialize process is yet to complete. Try again in a few minutes.

Finalizing the Migrations 

Once the batch has been successfully synced, it can live in that state for days/weeks if necessary but will always keep the mailbox synced up to 95%. When it comes time to go over the batch of mailboxes and make them live on Microsoft 365, click Finalize Mailboxes. This will present more options for the process, which are explained here.

With the Custom Batch Settings, you can specify if the users obtain access to certain items post-migration. These are;

  • IMAP - Access to the IMAP protocol for mail pickup on older devices
  • POP - Access to the POP protocol for mail pickup, once again on older devices.
  • OWA - If the mailbox is allowed use Outlook Web Access for mailbox viewing.
  • ActiveSync - If the mailbox is allowed use ActiveSync to retrieve email.


The remaining options are described below:

  • Select Microsoft 365 License Type - Select the license to apply to the mailbox (optional). Licenses will only appear in the dropdown if you have Microsoft 365 licenses available to apply. The additional check box here is to decide if you ONLY want to apply Exchange Online, instead of the entire license suite.
  • Select Retention Policy - Allows you to specify a retention policy that the mailbox will adhere to
  • Notify Users  - If you want the system to notify the user of the migration that is occurring.

The scheduling function is also available, to automatically finalize the batch at a set time. This is 'Local Time' for the logged-on user.

Lastly, the option must be selected that lets you know the process is final and cannot be undone. Select the Start Migration option when you are ready to proceed.

Unbatched Mailboxes

A user can be moved into the Unbatched Mailboxes area from inside any batch. This is essentially a holding area where the mailboxes can reside without a batch reference. They cannot be migrated to this state.

An important note that is referenced earlier is that if a mailbox is in the Unbatched Mailboxes area and a re-importing, via either the Exchange Agent or the CSV import, occurs, the user is moved from the Unbatched Mailboxes area into the batch that is referenced during the import. For this to happen, the Update Existing flag must be selected during the import process.

The Unbatched mailboxes area is a good place to put mailboxes that are being moved out of batches temporarily or put into a holding state so their future migration can be decided. It is not somewhere that they will live more permanently due to the possibility of them being moved out with a subsequent import.

To move a mailbox into this area, from within the batch select the mailboxes that are to be moved. Then click on the 'Move Mailboxes' button in the top right corner and select Unbatched Mailboxes as shown below.


The mailboxes will then be moved and no longer be associated with the batch reference.

Note that you cannot move mailboxes that have already been synced/finalized or are not in a stopped state.

Batch Logs

Inside each batch, some logs relate to any errors that have occurred with the migration process. These are key to understanding why an entire batch or a particular user has failed to get to the process.

As you can see from the screen below, we have an example of a failure relating to one of the mailboxes inside a particular batch. By clicking on the batch logs section, we can see the error on that mailbox.


In this example, the user looks like they already have a live mailbox in Microsoft 365, so the Hybrid engine is having difficulty taking the on-premises mailbox and migrating it. It will sit in a Pending state until we acknowledge the error as being resolved by clicking on the 'Resolved' check box.

If support is required to assist in any issue that appears in the batch logs, this information is important to submit along with the case.

Project Logs

The project logs are extremely useful when it comes to checking out the errors that may have occurred during certain tasks of a project. These can be found in the Project Logs section of the Batching View. In the example below, you can see there was an import error on a particular mailbox from a CSV file and this was reported through the logs.

They can be cleared easily enough by clicking the Resolved button, but until they have been worked through with Support, they should be kept there. They do not affect other items in the project that do not relate to the error.


Delete Mailboxes from Batches

To remove mailboxes from the project permanently, so they can no longer be viewed, use the trashcan icon in the batch after selecting the mailboxes you wish to delete.


This will only remove mailboxes from the project if they are in a Not Submitted state. If they are currently in a batch that is syncing, or in the finalization stage, then you will not be able to remove them.


Was this article helpful?
0 out of 0 found this helpful