Hybrid Exchange Management System - Batching

This article provides an overview of the batching mailbox process for Hybrid Exchange migrations and is intended to be used with the other guides in this section. 

Batching Mailboxes

Mailbox batching can be performed via three different methods. 

  1. Exchange Agent discovery
  2. Importing via CSV file. (Important: 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 foundhereto upload users and settings.)
  3. Moving mailboxes in the console 

For the Exchange Agent, there are many ways to group the users into batches, 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. 

Start Discovery

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.  

  1. Download the Hybrid Agent file.
  2. Log in to a workstation/server that is equipped with Exchange Management Tools using an account that has at least 'View Only' access privileges into the Exchange organization. This machine must have internet access.
  3. Copy the Hybrid Agent file on to the machine so it can be run locally.
  4. Execute MigrationWizHybridAgentSetup.msi to install the agent on the machine.

Once this has been done, run the Hybrid Agent on that machine. This should be executed as an Administrator. The following information will need to be entered on the first screen to allow the agent to connect to MigrationWiz.  

  1. Enter MigrationWiz Username – This is your MigrationWiz console login address. 
  2. Enter your password – This is your MigrationWiz password.

 Following this, you are presented with four options before the process starts

  1. Select Action - The default option here is to "Start Discovery and send the CSV to Migration Wiz". However if the agent has been previously run and you wish to pick up an older CSV file and resend it to Migration Wiz, then the second option in the drop down, "Send to Migration Wiz Only" is the option to select. 
  2. Specify Smart Batching Options - The options that you can use for Primary and Secondary batch names are; City, Company, Country,Department, Manager, Office, Organizational Unit, Postal Code, State, CustomAttributes1-15. If you select a secondary item then that item is appended to the batch name.
  3. Select WorkGroup - If you have multiple WorkGroups, you will be asked to select which one to use.
  4. Select Hybrid 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. 

The agent will look as below.


The mailboxes will now be discovered and uploaded to MigrationWiz. Once finished you will be able to click on the 'Done' button whereby the Agent will close. 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. 

Delegate Types

The Delegate Options now have three checkboxes to enable the import to capture all types of delegates. The way the delegates are handled in the system are exactly the same, as it simply knows that mailboxes have 'delegates' or are 'delegates of'. This selection box is the way to determine the level of rights that are captured.


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. 

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 changing Smart Batching options or they are moved manually into other batches, then rerunning the Exchange Agent will have the following effects: 


Import CSV

If the mailboxes are to be uploaded into the MigrationWiz system without the use of the Exchange Agent (Only Exchange 2013+ is supported for using the Exchange agent for import), 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. 

UserPrincipalName - The UPN of the mailboxes.

RecipientTypeDetails - Details of whether the mailbox is User/Shared/Room/Resource.

MailboxSize - The size in MB of the mailbox

MailboxItemCount - The number of items in 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. 

Batch Name 

Mailbox is Batched According To 

Populated with a Batch Name 

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.

  1. The upload is required to be performed manually in the MigrationWiz console. 
  2. The file can be edited before the upload to allocate batches to certain users if you require this. 
  3. 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 that the CSV file has been written.

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

When the import process is triggered, underneath the delegate options there is a choice of how the import will affect everything that is currently already in the system.


These options affect the handling of the import in the following ways, for both the Agent Import and the CSV Import.

Do not make changes to mailboxes currently batched in the system, only batch new mailboxes.

Mailboxes that have not been imported already will be imported and batched based on the corresponding batch name in the file. In other words, previously imported mailboxes will be left alone.

Update batches for all mailboxes that are in a ‘Not Submitted’ state.

Mailboxes that are already in the system, but in the Not Submitted state will be updated. They are moved to new batches if that is what the Import file is performing. Any mailbox that has not been synced will be re-imported and subject to changes

Only update mailboxes that are in ‘Unbatched’ mailboxes.

Previously imported mailboxes that are in “unbatched” state will be batched according to the corresponding batch name provided in the new Import file. Only these mailboxes are updated. Note that in this scenario, if there are new mailboxes in the import that have not 


Discovery Events Reference - Agent Import

Note that the events below only affect mailboxes that are not in a Syncing State other than 'Not Submitted'


Option Selected

Resultant Batching 

Mailbox that is in a normal batch is captured by a different Smart Batch option, then re-discovered with the Agent. 

Update batches

Mailbox moves to the new batch.

Mailbox moved to ‘Unbatched Mailboxes’ manually, then re-discovered with the Agent. 

Only update mailboxes in Unbatched / Update batches

Mailbox moves to the batch corresponding to the Agent.

Mailbox moved to another batch manually, then re-discovered with the Agent. 

Update batches

Mailbox moves back to the batch based on the Agent.

Mailbox deleted from system then re-discovered with the Agent. 


Users currently CANNOT be deleted from MigrationWiz 

Mailbox that is in Unbatched mailboxes is captured by a different Smart Batch, then re-discovered with the Agent. 

Only update mailboxes in Unbatched / Update batches

Mailbox moves to the batch corresponding to the Agent.


Discovery Events Reference - CSV Import

Note that the events below only affect mailboxes that are not in a Syncing State other than 'Not Submitted'


Option Selected

Resultant Batching 

Mailbox previously imported via Exchange Agent is re-imported by the CSV with a new Batch Name field defined in the content. 

Update batches

Mailbox is moved to the new batch.

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.

Only update mailboxes in Unbatched / Update batches

Mailbox moves to the correct batch.

New Mailbox in CSV, batched in batchname field.

Any Selected

The mailbox will appear in the batch labelled with the Batch Name.

Rebatch Entire System

There are times in the batching process whereby you wish to just 'start again'. This can be for multiple reasons. Perhaps you are changing the smart batching options or have simply just over complicated your batches. Either way, there is an option in the system to take all batches that are in a 'Not Submitted' state and remove them. This will take all the mailboxes and place them in the Unbatched Mailboxes area.

Note that any batch or mailbox that has a different status than 'Not Submitted' is not affected. This means that if you have already run some Pilots or Proof Of Concept batches then they will stay.

To trigger the rebatch process the option is located in the top right menu, as below.


You will be presented with a dialog box that will ask you to confirm the rebatch.


Once this is done, the change cannot be reverted. You can then continue with the normal batching process again of either running the Agent or by importing by CSV.


Was this article helpful?
1 out of 2 found this helpful