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.
- Azure AD 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. 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
2. Create 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.
3. 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 which has the appropriate rights to read the information. More in depth information on this agent are found later in this documentation. This is then used to send the mailbox data into the MigrationWiz console. Discovery options are:
4. 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.
5. Sync the Mailboxes
In the main batch view, click the button labelled Start Sync. This provides you a number of options to control how the Sync process works. The first item reports on whether or not there are any Delegates in the project that 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 an Microsoft 365 license to the mailboxes here, as well as selecting the MRS endpoint to use and setting the error tolerance.
Note that the assigning of an 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 '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.
6. Finalize the Mailboxes
The last step in the migration is to Finalize the mailboxes and cutover 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 a number of 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.
- 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.
- 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.
Note: The rights at the On Premises Exchange Server are provided during the creation of the Hybrid Endpoint and are not needed 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 which access the tenant as part of the Recipient Address Policy, as per normal native Hybrid migrations.
Note that it 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.
Please refer to the Batching Mailboxes section here for full details around 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 mailboxes to 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.
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 were they were imported into, whether it be by the Exchange Agent or by the CSV file. However, as it is important that the delegates do 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.
To easily display the delegates of a mailbox, click on the delegate icon that is located next to mailboxes SMTP address. If a mailbox does not have delegates then this icon will not be displayed. The output on the fly out shows as 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 delegates 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.
Moving Delegates as a Sync starts
When a batch is started, the system checks for delegates, asks if any delegates which are part of the batch should also be synced in this batch. The toggle 'Show Delegates' will display the list of Delegates that would 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
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, applies all mailbox attributes to the user as configured in the Advanced Options.
Finalization has completed successfully. The user's mailbox has been cutover to Microsoft 365, all pre-configured settings have been applied, and user is now using the Microsoft 365 mailbox instead of the Hybrid Exchange mailbox.
The process failed for some reason. The syncing or finalization process has been terminated.
The sync is being manually stopped by the user, syncing has been interrupted. The batch may not be moved or edited during this phase.
The sync has been manually interrupted by the user via the Stop Sync button.
The sync is scheduled to run at a future date/time. Hover over the status to check the date/time.
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 synchronization a batch of mailboxes on to Microsoft 365, click the button labelled Start Sync on the migration console.
The time to process the batches to 95% will be determined by a number of 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 a number of 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 mail 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.
Note: 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 cutover 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 to use Outlook Web Access for mail box viewing.
- ActiveSync - If the mailbox is allowed to 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.
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 in 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.
Inside each batch there are logs that 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 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 pertaining to 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 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.
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 though 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.