Configuring a migration job
This article describes how to configure a migration job step by step. A simple wizard will help you define all crucial aspects of the migration, for example selecting a target server, range of mailboxes and necessary time and folder filters. Use the links below to learn how to:
- Create a new migration job
- Specify types of mailboxes you want to migrate
- Choose mailboxes to be migrated
- Select a target server
- Match source mailboxes with target mailboxes
- Migrate mailboxes using a CSV file
- Schedule a migration job
- Set up time and folder filters for migrated items
- Configure other settings
- Review the configuration of your job
- Start a migration job
- Edit job settings
Create a new migration job
You can create a new migration job from the How to start card on the Dashboard (Fig. 1.). Alternatively, go to the Jobs tab and click New on the menu toolbar.
Fig. 1. Creating a new migration job.
Now you need to select the type of your source server (i.e. the server you will be migrating from). You can choose between Exchange Server, Office 365 and IMAP server.
The available configuration options (wizard steps) may differ slightly, depending on your source server type. In this article, we will show you a job configuration for Exchange Server, but the differences for Office 365 and IMAP will be highlighted.
After you select a source server type, the migration job wizard will open. The first step (General) allows you to set the name of your job (Fig. 2., item 1). The name should be brief and unique.
Fig. 2. The General step allows you to name a job, specify program installation location, and select mailbox migration method.
A job name cannot contain the following special characters: \ / : * ? < > |
Next, use the options shown in Fig. 2., item 2, to indicate where CodeTwo Office 365 Migration is installed:
- inside the source Exchange server domain (which means you have access to the source Exchange server),
- outside the source Exchange server domain (e.g. if source mailboxes are located on an Exchange server hosted by a third-party vendor).
These options are not available when migrating from Office 365 or an IMAP server.
Lastly, if you would like to perform a migration by using data from a CSV file, select the Migrate mailboxes using a CSV file containing a list of already matched source and target mailboxes checkbox, as shown in Fig. 2., item 3. When you select this checkbox, the Source mailboxes, Target mailboxes and Match mailboxes steps in the wizard will be replaced by the Mailboxes step, where you will import the CSV file. Click here to go directly to the section of the manual where this process is discussed.
If you are not using a CSV to migrate mailboxes, proceed to the Source mailboxes step instead.
Specify types of mailboxes you want to migrate
This step is not available if you’ve chosen IMAP server as your source server type. In such a case, proceed to this section instead.
The Mailbox types step lets you decide which types of mailboxes you want to include in your migration job (Fig. 3.). If you don't use archive mailboxes in your source environment, choose Migrate primary mailboxes. If archive mailboxes are enabled on your source server, you can choose to migrate only them or migrate them together with primary ones.
To successfully migrate archive mailboxes, you need to first enable them in the target environment for the same users who use them in your source environment.
Keep in mind that modifying this setting and saving the change after you’ve matched source and target mailboxes will result in resetting some of your job settings, e.g. the mailbox matchings.
You can migrate archive mailboxes larger than 100 GB only if auto-expanding archiving is enabled in your target Office 365 tenant. Bear, however, in mind that the storage expansion is done automatically and incrementally by Microsoft Purview and might take up to 30 days. Consequently, your migration job might come to a standstill for some time, until the required amount of space is added. Learn more
Fig. 3. Choosing which mailbox types you want to include in your migration job.
Choose mailboxes to be migrated
The Source mailboxes step is where you to define which mailboxes should be included in the migration job. The configuration depends on the type of your job:
If there are no source connections defined in the program, expand the Source server drop-down menu and click Add new source connection. Use the links below to configure a connection to a source:
If you selected to import the matched source and target mailboxes from a CSV file, go here.
Exchange Server / Office 365 migration job
The Source mailboxes step is similar for migrations from Exchange Server and Office 365. You can add and remove your source mailboxes by using various filters. You can select users whose mailboxes you want to migrate in two ways (Fig. 4.):
- select which mailboxes are to be included in the job (the Migrate mailboxes fulfilling the following conditions section) - this list should be considered as conditions;
- select which mailboxes should be excluded from the job (the Don't migrate mailboxes fulfilling the following exceptions section) - this list should be considered as exceptions. The exceptions are effective in the case of a conflict with the conditions defined in the upper list.
Fig. 4. Selecting source mailboxes for migration.
For example, let us say you have three users: user1, user2 and user3, who are members of the group named Initial migration. You have set the program to migrate the Initial migration group, but also excluded the user3. Consequently, the program will add user1 and user2, since they are members of the mentioned group. The user3 will not be migrated, despite the membership, as this account has been defined in the exceptions list.
When migrating from Exchange Server via MAPI:
- You can migrate mailboxes only from the domain and subdomains under which the software is running. Migration of data located in another domain on the same level is not supported.
- You cannot migrate archive mailboxes, even if you've chosen an appropriate option here.
If you use the Active Directory group filtering option (migration from Exchange Server), group membership information can only be refreshed by restarting the program’s Administration Panel. So, for example, when you started a migration job and added a new user to an AD group defined in your migration job in the meantime, you need to restart the panel. Also, remember to match the newly added mailbox(es) with target mailbox(es) afterwards, as discussed later in this article.
When migrating from Office 365, the program lists only active source mailboxes. This means that only source users with a valid Office 365 license will be displayed. The exception to this rule are resource and shared mailboxes, which are listed even if no Office 365 license is assigned to them.
Public folders are selected for the migration by default. Before you start migrating them, make sure the following requirements are met. For more detailed steps on how to migrate public folders, read this article.
Learn more about defining the list of included and excluded mailboxes
IMAP migration job
In the case of an IMAP migration job, the Source mailboxes step looks a little different (Fig. 5.). Here, you need to select a source server from the drop-down list (you can also define a new connection) and import a CSV file that includes information about your source mailboxes. The application requires providing at least the email address and password of every mailbox you want to migrate. You can also include the first and last name as well as the display name, as these fields may prove useful later.
Fig. 5. Importing IMAP mailboxes.
You want to migrate the following user:
Display Name: Oneida Riddle
Email address: [email protected]
Password/App password*: D10XDZG9
A valid CSV file created in a text editor (e.g. Notepad) can have the following entry:
"[email protected]";"D10XDZG9";"Oneida";"Riddle";"Oneida Riddle"
If you prefer using Excel instead, one way of creating a valid CSV file is shown in Fig. 6. below.
Fig. 6. An example of a correctly formatted CSV file created in Excel.
To successfully migrate from Gmail or Google Workspace via IMAP, it is required to open the Google account security settings, enable 2-step verification and generate a 16-character app password for each migrated mailbox (learn more). The generated passwords are to be provided in the CSV file instead of the standard mailbox passwords.
To import the data, use the Import from CSV button. After choosing a file, you will see the CSV mapping window (Import mailboxes). If everything looks correct, you can continue by clicking the Import button. In the case any mailbox failed to be imported, the program will display all necessary information.
Learn more about importing data to the program from a CSV file
Select a target server
In the Target mailboxes step, you can configure the connection with a target Office 365 environment. You will need to provide your Office 365 admin account credentials, including the User Principal Name. Keep in mind that this account needs to have appropriate roles assigned.
To select a source server, expand the Target server drop-down list and choose a desired entry (Fig. 7.). Click Next to proceed.
If you are running the migration job wizard for the first time, there will be no connections defined yet. In that case, choose Add new target connection and follow this article to learn how to create a target server connection.
Fig. 7. Choosing a target connection.
Match source mailboxes with target mailboxes
In the next step of the wizard, click the Match mailboxes button. This will open the Match mailboxes window (Fig. 8.), where you will see all mailboxes fulfilling the conditions defined in the Source mailboxes step along with the information about their type.
If you are using a CSV file to import matched source and target mailboxes, this step does not apply. Go directly to this section.
Fig. 8. The Match mailboxes configuration window.
If you want to migrate all listed mailboxes, click Automatch > Automatch all mailboxes. To migrate only some of the mailboxes, select them from the list (use the Ctrl to select mailboxes one by one or Shift to select multiple neighboring rows) and click Automatch > Automatch selected mailboxes. The automatch feature is designed to automatically search the target environment and find mailboxes that correspond to the mailboxes in your source environment. This feature also works for archive mailboxes and public folders.
If the automatch mechanism does not find mailboxes in the target Office 365 tenant, you can set the program to create them (learn more). Keep in mind that this feature is not available for archive mailboxes, which must be enabled in the target environment using the native methods.
For those mailboxes that couldn’t be matched automatically, for example due to an unusual email address format, there’s an option of manual matching. Learn more
The summary of the matching process is displayed in the upper part of the Match mailboxes window (Fig. 9.). A detailed description of what information is shown in each section is available here.
Fig. 9. The summary of the matching process.
Migration of public folders is possible only if any public folders already exist in the target environment. For more information on how to create public folders, click here. Note that it may take a few minutes for public folders to become visible in the program after they have been created.
Migrate mailboxes using a CSV file
If you are not using a CSV file to import matched source and target mailboxes, this step does not apply. Proceed to this section.
In the Mailboxes step, first use the drop-down lists to select existing source and target server connections (Fig. 10., item 1). If you haven’t configured such connections yet, create new ones.
Fig. 10. The Mailboxes step is where you import a CSV file containing matched source and target mailboxes.
Click Import from CSV to open your CSV file containing mailbox pairs (Fig. 10., item 2). A new window opens where you need to map the data from your CSV file with the parameters used by the program (Fig. 11.).
Fig. 11. The Import matched mailboxes window is used to prepare the CSV file for import.
In Step 1, adjust the formatting options (file encoding, fields delimiter and text qualifier) to match the formatting used in you CSV file. The data shown in Step 2 needs to be displayed correctly in columns. If your CSV files contains headings for each column, select the First line contains column headers checkbox. If the headings are recognized, the column names in the preview will change from Column 1, Column 2 etc. to column names specified in your file.
To migrate a mailbox of user Megan Bowen, you need to include the following data in a CSV file:
Source mailbox email address*: [email protected]
Source mailbox ID*: 5ds8a4ds-hfdf-6sd5-98nt-cmrj3a92n26c
Source mailbox first name: Megan
Source mailbox last name: Bowen
Source mailbox display name: Megan Bowen
Source mailbox Type**: Primary or Archive
Target mailbox Type***: Primary or Archive
Target mailbox email address*: [email protected]
Target mailbox ID*: fn378c2b-1bgb-14cb-7vmw-0m38128nv418
* mandatory fields
** mandatory field only when you migrate primary and archive mailboxes (learn more)
*** mandatory field only when you migrate archive mailboxes or primary and archive mailboxes (learn more)
The mandatory CodeTwo data fields use the following Office 365 property values:
- Source/Target mailbox email address = UserPrincipalName
- Source/Target mailbox ID = ExternalDirectoryObjectId
and the following on-premises Exchange property values:
- Source mailbox email address = UserPrincipalName
- Source mailbox ID = ExchangeGuid****
**** When migrating from a hosted Exchange server, you may need to ask your service provider to supply you with the necessary GUIDs.
A valid entry in a CSV file created in a text editor will look like this:
"[email protected]";"5ds8a4ds-hfdf-6sd5-98nt-cmrj3a92n26c";"Megan";"Bowen";"Megan Bowen";"Archive";"Archive";"[email protected]";"fn378c2b-1bgb-14cb-7vmw-0m38128nv418"
A valid CSV file created in Excel is shown below (Fig. 12.). This example includes the mandatory data only and contains column headings.
Fig. 12. A correctly formatted CSV file, viewed in Excel.
Learn more about importing data to the program from a CSV file
Read this article and use the scripts provided to create a valid CSV file for migration
Once you verify that the data is displayed correctly in the preview, match the columns in your CSV file to data fields required by our migration tool by using the drop-down lists in Step 3. Make sure to match all the mandatory fields marked with an asterisk (*), otherwise you will not be able to proceed.
Click Import to close the window and return to the migration job wizard. If no problems were detected, click Next to proceed to schedule your migration job (Fig. 13.).
Fig. 13. Data import from the CSV file completed with no errors.
If any problems were detected during this step, read this article and decide whether to fix the errors or ignore them at this time and continue the migration job configuration.
Mailboxes re-import options
The Re-import mailboxes checkbox is used to control how the program processes additional CSV files imported for a given job:
- If the checkbox is unselected, the program will add the entries from the new file to those already imported. If the new file contains identical entries that have already been imported, the program will not create duplicates. This allows you to update the mailbox pairs e.g. if you had to fix missing data in the CSV file.
- If the checkbox is selected, the program will remove the previously imported mailbox pairs and only add mailbox pairs from the most recent file.
Schedule a migration job
Every defined job can be controlled manually or automatically. Using the Scheduler feature (Fig. 14.) you can set the program to automatically run the full data or delta migration job at desired periods. This functionality may be extremely helpful, considering the fact that the best performance of the migration process is achieved when users are not using their mailboxes. You can define either a weekly recurrence or select individual weeks. No matter which option is used, you need to select on what particular days and hours the migration job should be active. The smallest possible unit is one hour.
Fig. 14. Scheduling a migration job.
Learn more about the Scheduler
Set up time and folder filters for migrated items
In addition to the conditions you have set in the Mailboxes step, you can apply additional filters regarding your items (e.g. emails, calendar events, etc.).
Thanks to the Time filter step (Fig. 15.) you can decide whether you like to migrate items that are older/newer than a certain point in time or if you want to migrate everything regardless of their age. What is more, the calculations are based on end/due dates (this concerns calendar items, tasks and journals) and delivery time (messages). If those properties are missing, the program will use the last modification date.
Fig. 15. Setting up a time filter.
Learn more about the Time filter
Moreover, you can define which folder types will be migrated in the Folder filter step. For example, you can decide to exclude folders like Junk Email (Fig. 16.).
Fig. 16. Setting up folder filters.
Learn more about the Folder filter
Configure other settings
The program can migrate more than one mailbox at the same time. The number of mailboxes migrated simultaneously depends on the job type (Exchange/Office 365/IMAP) and its optimum value is set automatically in the Advanced settings step (Fig. 17.). You can change this setting, but keep in mind that the main bottleneck of the migration may be the upload bandwidth and inappropriate modification of this value might result in performance losses. This step also allows you to set the maximum size of items to be migrated.
Learn more about the Advanced settings step and what affects the migration speed
Review the configuration of your job
In the very last step - Job summary - you will be able to check if all preferences are properly set (Fig. 18.). When you are done, click Finish. Keep in mind that you can always edit the migration job settings later.
Start a migration job
Once you finish the migration job wizard, you will be redirected to the Jobs tab. Use the Start button (Fig. 19.) to begin your migration job. Keep in mind that the Administration Panel needs to be open in order for the migration job to run. In addition, if you have scheduled your migration to start at some other point in time, make sure that the Administration Panel will be also open then. Otherwise, the migration will not begin. Once the migration starts, you can see the progress in the main pane - either on the list of Mailboxes or on the Job migration progress card.
Fig. 19. Starting the migration process.
There can be only one migration job running at a time. All other jobs are queued according to the order presented on the list.
As users are usually still working on their source mailboxes during the migration process, new items are constantly created. To include the newly created items in your job, you can restart the migration process at any point by clicking the Run delta migration button on the top menu of the Administration Panel. The program will rescan the already migrated mailboxes on the source server and migrate new items only.
Learn more about the delta migration process
Editing job settings
To edit an existing migration job, go to the Jobs tab, select the migration job you want to edit (the job needs to be paused or otherwise inactive) and click Edit on the top menu (Fig. 20.). The same job configuration wizard will open that you used to configure the migration job in the first place. Editing the time or folder filters in a migration job is essential when performing staged migrations.
Once you start a migration job, you cannot change the source and target server connections for the given job (Fig. 20.). If you want to perform the migration between another pair of servers, you need to configure a new migration job.
Fig. 20. You cannot change server connections once the migration job has been started.
However, in case you need to change the server connection e.g. because you’ve changed the domain name in your source and/or target environment, follow these steps to learn how to do so.
Additional migration options - learn about supplementary migration options for individual mailboxes.