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.
A configured and working Hybrid configuration must be in place between your source Exchange environment and the Office 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 Office 365 tenant with domain (Namespace) configuration is completed.
- Azure AD Connect is set up and configured to include all OU's 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 Office 365, meaning that a test of a single mailbox into the Office 365 tenant has been completed.
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 Office 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 as an executable file from the Start Discovery flyout in MigrationWiz and run it on a server/workstation in an Exchange environment which has the appropriate rights to read the information. 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 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 Office 365 license to the mailboxes here, as well as selecting the MRS endpoint to use and setting the error tolerance.
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 Office 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.
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.
When starting a Hybrid migration project with MigrationWiz, there are a number of prerequisites that need to be completed in your environment before launching the migration. These prerequisites relate to the health and setup of the Exchange and Office 365 tenant and ensure that the system can connect and migrate effectively.
1. The Office 365 Tenant has been created and a valid domain/namespace has been configured.
The Office 365 tenant should have been created and set up with the correct domain name, which should match the on premises system. Tenant configurations can vary greatly depending on the type of implementation you are performing, but the base configuration should be in line with the on-premises Exchange environment that you are migrating from.
2. Azure AD Connect is installed and syncing identities to the Office 365 tenant.
Having valid identities inside the Office 365 tenant is a vital step in the process as it provides the linkage between the on premises and the cloud-based implementation. For details on how the Azure AD Connect is set up and configured, check the Microsoft documentation.
3. Hybrid Configuration Wizard has been run and completed successfully.
4. Access to the MRS (Mailbox Replication Service) endpoints is configured and working.
The MRS endpoint configuration is performed during the Hybrid Configuration Wizard process. Once this is created, and you have connected to the Office 365 tenant PowerShell, it can be tested with the following instructions.
Run the Test-MigrationAvailability cmdlet, specifying the endpoint as your configured version.
Test-MigrationServerAvailability -Endpoint "Hybrid Migration Endpoint - EWS (Default Web Site)"
The output will respond back with a Success/Failure message similar to below.
RunspaceId : 785717df-80ce-4148-baff-2b6aad962bfb
Result : Success
SupportsCutover : False
TestedEndpoint : Hybrid Migration Endpoint - EWS (Default Web Site)
IsValid : True
ObjectState : New
In the event of a failed state, the Hybrid Troubleshooting steps on the Microsoft site are useful in ascertaining the issue.
5. A test migration of a single mailbox has been completed successfully using the native toolset.
To confirm that everything is indeed working exactly as expected, we recommend performing a single mailbox migration, using a test or pilot mailbox, can be run manually against the infrastructure. This checks that the entire end-to-end Hybrid environment that has been set up is migrating data, performing look-ups for Free/Busy status, providing correct mail flow, and verifying address book look-ups.
Create New Project
To create a new project in the Migration Wiz console, start by selecting the + Create Project selector, then click on 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 Office 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 Migration Wiz 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. Therefore it is a recommendation that the tenant name be used, as in the example below.
Mailbox batching can be performed via three different methods.
- Exchange Agent discovery based on OUs
- Importing via CSV file
- Moving mailboxes in the console
Note: For the Exchange Agent, the only batching option currently is for the Organizational Units, whereas the Import CSV option allows for specific Batch Names to be provided in the import file.
During the import of the CSV file, either from the Exchange Agent or directly from the Import CSV option, a notice will pop up during the process, saying that all batch work on the project on the front end is unavailable. This will look like this:
Once the process is complete, normal operation will resume.
Once the Hybrid project is created, you will see a blank batch screen with no mailboxes listed. You will now need to perform a discovery of your Exchange environment to find all Hybrid-compatible mailboxes. The mailboxes can then be added to the system via CSV or automated discovery by an Exchange Agent, which collects the information and moves it to your project.
- Download the Hybrid Agent file
- Log in to a workstation/server that is equipped with Exchange Management Tools using an account that has 'View Only' access privileges into the Exchange organization. This machine must have internet access.
- Copy the Hybrid Agent file on to the machine so it can be run locally
- Execute MigrationWizHybridAgentSetup.exe
Once this has been done, the following information will need to be entered to allow the agent to connect to MigrationWiz.
- Enter MigrationWiz Username – This is your MigrationWiz console login address.
- Enter your password – This is your MigrationWiz password.
- Enter path for agent working files – This is a local directory where the logs and CSV files will be created. Leave blank for the ‘workspace’ path underneath the current Exchange Agent directory.
- Start Discovery - From the menu, select Start Discovery and Send CSV to MigrationWiz. This option starts the discovery process and uploads the data to the MigrationWiz system.
- Select WorkGroup - If you have multiple WorkGroups, you will be asked to select which one to use.
- Select Customer/Project – This presents a list of the available Customers and Hybrid Migration projects you have configured inside MigrationWiz. The items displayed will show both customer name and available projects.
- Enter the OU (Organizational Unit) that you wish to discover - This can be appended with a comma for multiple entries or leave blank to discover all OUs. The OU can be simplified by using the words 'Finance' rather than the entire LDAP version.
The mailboxes will now be discovered and uploaded to MigrationWiz. At this point, navigate back to the MigrationWiz Hybrid project, whereby you will be presented with a screen asking how you want to handle the Delegate structure.
Discovered delegates are handled in three ways.
One Level Up/Down - Only delegates with a direct relationship up/down are processed in the system.
Tree/Full Hierarchy – The entire hierarchy of delegates is processed. This is the most complex option but means that ALL delegates of delegates stay together.
None – No Delegate relationships are processed.
The mailboxes are all batched based on the OU that they reside in. Once the mailboxes have been discovered and are present in the system, they can be moved to different batches within the MigrationWiz console. If the mailboxes have certain activities performed on them, like moving OUs or they are moved manually into other batches, then rerunning the Exchange Agent will have the following effects:
Mailbox that is in a normal batch is moved to a different OU in the local Active Directory, the re-discovered with the Agent.
Mailbox moves to the new batch.
Mailbox moved to ‘Unbatched Mailboxes’ manually, then re-discovered with the Agent.
Mailbox moves to the batch corresponding to the OU in AD.
Mailbox moved to another batch manually, then re-discovered with the Agent.
Mailbox moves back to their original batch based on their OU.
Mailbox deleted from system then re-discovered with the Agent.
Users currently CANNOT be deleted from MigrationWiz
Mailbox that is in Unbatched mailboxes is moved to a different OU in the local Active Directory, then re-discovered with the Agent.
Mailbox moves to the batch corresponding to the OU in AD.
If the mailboxes are to be uploaded into the MigrationWiz system without the use of the Exchange Agent, the import CSV file option can be used. To perform this operation, click on the Import CSV item in the top right corner of the project view.
This option will provide two links that contain a sample CSV and the PowerShell script needed to obtain a full list of mailboxes from the Exchange Server. You can download these two to prepare the mailbox list for importing. For reference, the link to the PS1 file is in the Import CSV flyout:
The fields required in the CSV are:
SMTPAddress - The primary SMTP address of the mailbox.
OrganizationalUnit - The Organizational OU the mailbox AD account belongs to.
BatchName – This is an override of the OU name for batching requirements; if completed for each line, the mailboxes will use this field for batching instead of the OU.
IMAP – TRUE/FALSE field determining if the mailbox is to be IMAP-enabled in the target.
POP – TRUE/FALSE field determining if the mailbox is to be POP-enabled in the target.
OWA – TRUE/FALSE field determining if the mailbox is to be OWA-enabled in the target.
ActiveSync – TRUE/FALSE field determining if the mailbox is to be ActiveSync-enabled in the target.
Delegates – The SMTP address of any delegates on this mailbox, separated by a ‘|’ symbol.
The mailboxes are batched according to the details in the fields Organizational Unit and Batch Name. It is important to note the behavior of these fields and the impact on the batching process.
Mailbox is Batched According To
Populated with an OU
Populated with an OU
Populated with a Batch Name
Populated with a Batch Name
Not Batched – Placed in Unbatched Mailboxes
Create a CSV via PowerShell
If you do not wish to use the Exchange Hybrid Agent to extract the data from the Exchange environment then we have provided a PowerShell script that will perform the same function in the way of a CSV file. There are a number of key differences, however.
- There is no limiting of OUs in the PowerShell, as it creates a CSV with every mailbox in it.
- The upload is required to be performed manually in the MigrationWiz console.
- The file can be edited before the upload to allocate batches to certain users if you require this.
- You can remove a lot of the data and just import small portions at one time.
The script can be found in the Import CSV flyout from the MigrationWiz screen.
The CSV import does not provide the same option as the Exchange Agent to adjust the delegate handling during the import phase. These are instead set in the Project Advanced Settings and perform the same function as the settings in the Exchange Agent.
To run the script, download it to an Exchange Server from the Migration Wiz console and place it on an Exchange Server or a server that contains the Exchange Management Tools. The best option is to run within an Exchange PowerShell Command window, as shown below.
As the script is downloaded from the internet, depending on the version of Windows and Exchange that you are running, you may be presented with a message starting that the PS1 file has not been digitally signed. This is because your server has not been given the ability to run these types of scripts locally. To resolve this issue, one simple command will work.
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
By doing this, it allows the running of externally provided scripts. We do recommend that you fully read and understand the script so you can confirm that the code is in line with normal Exchange mailbox analysis. We do NOT make any changes to the system with this script and purely read the information into the CSV.
The script will ask for two items of input. First, the location of the CSV file that it is creating and second, the prefix to the Office 365 tenant name. ie. testtenant where the tenant is testtenant.onmicrosoft.com. Part of the process is to validate that the Address Policy has been applied correctly to the users you are importing. If not, those users will fail migration. Microsoft has more information on this process.
The initial script:
While in progress, the bar will show the mailbox count and the name of the mailbox as a reference.
Once completed, a status will show how many mailboxes were exported to the CSV file.
A sample output of the CSV file is shown here in text format; using Excel to edit the file and then importing it into the MigrationWiz console is perfectly acceptable.
Update Existing Mailboxes
With the option to Update existing mailboxes that have not yet synced, any mailbox that has not been synced will be re-imported and subject to changes.
Import CSV using the Batch Name option will move the user into a new batch. During the import process, if a mailbox is in a particular OU batch, and is moved in AD and then re-imported, the mailbox will reside in the original location it was imported to.
Once they have been processed by the MigrationWiz system, they will appear as batched entries according to the OU structure.
To add additional OUs and more mailboxes, follow the steps above and run the Exchange Agent again. Any mailbox that is already imported will not be affected by the rediscovery process, but once again, using the Import CSV option and specifying a new Batch Name will achieve this function.
If a mailbox is already batched and imported, re-importing them into the system and choosing the option Select to update any previously imported mailboxes will perform updates on where the mailboxes are batched. If this is not selected, then only new items will be processed.
The following events have the corresponding outcomes.
Mailbox previously imported via Exchange Agent is re-imported by the CSV with a new OU field defined in the content.
Mailbox does not move batches but stays in the original batches OU.
Mailbox previously imported via Exchange Agent is re-imported by the CSV with a new Batch Name defined in the content.
Mailbox is moved to the new batch if the Select to Update option was turned on.
Mailbox previously imported via CSV Import is re-imported by the CSV with a new OU field defined in the content.
Mailbox does not move batches but stays in the original batches OU.
Mailbox previously imported via CSV Import is re-imported by the CSV with a new Batch Name field defined in the content.
Mailbox is moved to the new batch provided the ‘Select to Update’ option was turned on.
Mailbox deleted from system then re-imported by the CSV.
Users currently CANNOT be deleted from MigrationWiz .
Mailbox in unbatched mailboxes is re-imported by the CSV.
Mailbox moves to the correct batch.
New Mailbox in CSV, batched in either OU or batchname field.
The mailbox will appear in the batch labelled with an OU unless the batchname is specified in which case it is used instead.
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.
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.
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.
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.
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 Office 365, all pre-configured settings have been applied, and user is now using the Office 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.
Starting Sync Process for Mailboxes
When you are ready to synchronization a batch of mailboxes on to Office 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 Office 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 Office 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
Select Office 365 License Type - Select the license to apply to the mailbox (optional)
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
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.
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 Office 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 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.
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 Office 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.