Matching mailboxes

For the migration to occur, each source mailbox needs to be paired with a target mailbox. The purpose of the matching process is to create associations between source and target mailboxes.

The matching process takes place in the Match mailboxes window and can be done automatically or manually.

This article covers the following aspects of the matching process:

• Selecting source mailboxes to be matched
• Matching mailboxes automatically
• Matching mailboxes manually
• Matching public folders
• Matching shared mailboxes
• Creating target users and mailboxes
• Viewing summary information
• Saving the configuration

Selecting source mailboxes to be matched

The Match mailboxes window is where you determine which source mailboxes will be matched to the target ones and based on what matching patterns.

There are two ways to open the Match mailboxes window:

1. From the migration job wizard by clicking the Match mailboxes button in the Match mailboxes step.

   If you choose this option, all the mailboxes selected in the Source mailboxes step of the wizard will already be listed in the Match mailboxes window.

2. From the Jobs tab by either:

   • clicking the Match button on the toolbar and selecting either Match all mailboxes or Match selected mailboxes from the drop-down menu, or

   • right-clicking anywhere in the mailboxes list and choosing Match target mailboxes option from the drop-down menu.

     If you do not want to match all listed mailboxes, select the ones that you want matched from the list before opening the Match mailboxes window.

The Match mailboxes window (Fig. 1.) is divided into three parts:

1. top menu,
2. summary section, where you can monitor the matching process. Learn more
3. mailboxes list.

Fig. 1. Main parts of the Match mailboxes window.

By default, mailboxes in the Match mailboxes window are listed alphabetically, based on the source email address. To arrange mailboxes by other criteria, click a corresponding column header. For example, to list mailboxes by the user’s last name, click the Last name column header.

Matching mailboxes automatically

We recommend matching as many mailboxes as possible automatically. Use the manual matching option only for those mailboxes that weren’t matched automatically despite several attempts or to match a primary mailbox with an archive mailbox (or vice versa).

To start the automatching process, click Automatch > Automatch all mailboxes or select the mailboxes that you want to match and click Automatch > Automatch selected mailboxes. This will open the Automatch window (Fig. 2.).

Fig. 2. The default automatching settings.

You can now either:

• use the default settings, or
• modify the automatch mechanism

Matching mailboxes using the default automatch pattern

By default, the program matches mailboxes based on the first and last name or the display name of the source and target users. If these two patterns are not sufficient to pair every mailbox, click the Change button to modify the default settings of the automatch mechanism or click the Browse button to upload a CSV file listing mailbox pairs. Learn more

If the automatch feature does not find a corresponding mailbox in the target environment, you can set the program to:

• create a new user together with a mailbox in the target environment, or
• create a mailbox for existing target user if the program finds a target user without a mailbox.

To enable this option, mark the Create target users/mailboxes if they don’t exist checkbox. If you want to change the default settings concerning the creation of users and mailboxes, click the Settings button.

Learn more about creating users and mailboxes on the target server

When your configuration is ready, click the Automatch button to run the process. The result will be visible immediately after its completion (Fig. 3.).

Fig. 3. Example summary after matching mailboxes automatically.

If some of the mailboxes were not matched in the first run, you can check the Automatching details column for more information (Fig. 4.).

Fig. 4. Checking the automatching details of a mailbox.

If there are many mailboxes left unmatched, change the matching settings and try again. Mailboxes that were matched in the first run will not be unmatched. However, if you make any changes in the mailbox settings after the initial run and you wish to apply these changes also to the mailboxes matched in the previous run, mark the Automatch again mailboxes that are already matched checkbox. When you start the migration jobs, the already matched mailboxes will be unpaired and rematched in accordance with the current settings.

If not all the mailboxes were matched after several runs, match the remaining mailboxes manually.

Modifying the automatch mechanism

To modify the automatch mechanism, click the Change button in the Automatch window (Fig. 3. above). This will open the Automatch pattern window (Fig. 5.) where you can:

• use different matching patterns, or
• import a CSV file with already matched mailboxes.

Fig. 5. Automatching modification options.

Using patterns

A pattern is a set of conditions that need to be met when comparing a source and a target mailbox information. You can:

• use the default patterns, as displayed in the Automatch window,
• use one of the predefined patterns, or
• create your custom pattern

Predefined patterns

The program contains three additional built-in patterns that should be sufficient for most environments. To access them, click Add in the Automatch pattern window (Fig. 5. above) and then choose Predefined pattern. In the Add a predefined pattern window (Fig. 6.), select one of three available patterns and click OK.

Fig. 6. Selecting one of the predefined patterns.

To select more than one built-in pattern, open the Add a predefined pattern window again, select another pattern and click OK.

Custom patterns

If none of the built-in patterns meets your requirements, you can create a pattern of your own. To do so, click Add in the Automatch pattern window (Fig. 5. above) and choose Custom pattern. This will open the Add a custom pattern window (Fig. 7.). Use the top two drop-down menus to select which mailbox fields from the source server (left menu) will be paired to which fields on the target server (right menu). There are several fields to choose from. If you choose Email / Login or Display Name, additional drop-down menus will appear.

Fig. 7. Creating a custom pattern.

Example:

Let’s assume that you decided to match the source email address to the target email address. You want the program to pair all the source email addresses that follow the {FirstName}.{L}@source.com format to target addresses that follow the {F}.{LastName}@target.com format. For example, the source email address is [email protected] and you want to pair it with [email protected].

To achieve this result, choose Email / Login from the top Match this source mailbox field drop-down menu. Since the {FirstName}.{L}@source.com format is not readily available, in the Email / Login format menu choose Custom (Fig. 7. above).

The Custom Email / Login field format window (Fig. 8.) that opens, allows you to specify your own email address format by typing a string of text or adding placeholders.

Fig. 8. Defining a custom source email address format. 

Set the target mailbox field accordingly. Your final configuration should look like in the figure below (Fig. 9.).

Fig. 9. Final custom pattern configuration.

Using a CSV file

You can modify the automatch mechanism also by importing a properly formatted CSV file. To import the file, click the Browse button in the Automatch pattern window (Fig. 5. above) and navigate to the CSV file location.

The CSV file must include pairs of source and target mailboxes. Every entry should contain at least the source email and target email fields. Additionally, you can add the first and last name of each source mailbox user. Also, if you intend to match archive mailboxes or both primary and archive mailboxes, you need to include information about the mailbox type(s) (Primary or Archive).

For example, let us assume you have the following user:
Display Name: Oneida Riddle
Source email address: [email protected]
Target email address: [email protected]
Mailbox Type: Archive

A valid CSV entry created in a text editor (e.g. Notepad) would be:

"[email protected]";"Oneida";"Riddle";"Archive";"[email protected]"

Further information on importing CSV files to the program is available here.

Matching mailboxes manually

We recommend using the manual matching option if only few source mailboxes were not matched to their target equivalents despite several attempts. To do so, select the row and in the Target user mailbox column right-click the Click to match target link to open a drop-down list with the matching options (Fig. 11.).

Fig. 11. Manual matching options.

The following options are available:

• Create a new user – read more about creating target users in this section.

• Choose an existing user from the list – this will open the list of all users that already exist in the target environment, even those without an active mailbox (Fig. 12.).

Fig. 12. Selecting an existing target user.

• Choose an existing archive mailbox from the list – this will open the list of all archive mailboxes that exist in the target environment.

• Manually enter existing mailbox address / Manually enter existing archive mailbox address – allows you to type in the target email address yourself (Fig. 13.). This option is available only for mailboxes (primary or archive) that already exist in the target environment. If you provide an email address of a mailbox that does not yet exist, the program won’t be able to migrate the source mailbox properly. Use this option only as a last resort, when the program cannot list target mailboxes. To check if the email address that you typed in is correct, click the Verify button.

  
  Fig. 13. Entering the target email address.

• Edit – this option is only available if you cleared the Use default settings box in the Create a new user window. It lets you manually change the details of the target user.

• Unmatch – this will exclude the source mailbox from the migration process.

Matching public folders

Public folders can be matched by using the automatch mechanism. They are matched independently of user mailboxes, regardless of the selected matching pattern. However, for this to work, public folders must exist in the target environment. Instructions on how to create public folders are available in this article.

To match public folders manually, click the drop-down arrow () in the Target user mailbox column, and then select Choose an existing user from the list, as shown in Fig. 14.

Fig. 14. Matching public folders manually.

Proceed to choose Public Folders from the list in the Match target user/mailbox window (Fig. 15.).

Fig. 15. Selecting target public folders.

To learn more about migrating public folders, read this article.

Matching shared mailboxes

Shared mailboxes are matched similarly to user mailboxes but in most cases they require creating a different matching pattern or manual matching. However, to be able to match mailboxes of this type, you must first create shared mailboxes in the target environment. This is demonstrated in this article.

To match a shared mailbox manually, click the drop-down arrow () in the Target user mailbox column, and then select Choose an existing user from the list, as shown in Fig. 16.

Fig. 16. Matching a shared mailbox manually.

Proceed to choose the shared mailbox from the list in the Match target user/mailbox window (Fig. 17.).

Fig. 17. Selecting target shared mailbox.

If the shared mailbox cannot be found on the user list, select Manually specify the mailbox address and enter the shared mailbox address (see Fig. 13.).

You can also use shared mailboxes as targets for migrating your public folders data. This e.g. gives users easier access to data collected in public folders from mobile devices. To learn more, read this article.

Creating target users and mailboxes

For the matching process to succeed, mailboxes must exist in the target environment. You can create them together with corresponding users either directly on your Exchange server or allow CodeTwo Exchange Migration to do it for you.

Note that target public folders need to be created directly on the Exchange Server. Instructions how to create public folders are available here.

To specify how the program should create target users and mailboxes, open the Create target users/mailboxes settings window (Fig. 18.):

• by clicking Create user settings in the top menu of the Match mailboxes window, or
• by clicking the Settings button in the Automatch window (see Fig. 2. above).

The Create target users/mailboxes settings window will also open if you choose the Create a new user option for the first time.

Fig. 18. The Create target users/mailboxes settings
window when migrating between Exchange servers.

In the Create target users/mailboxes settings window, you can:

• change the email address format or the display name format. If the default options suggested by the program do not meet your needs, click the Change button to open a separate window, similar to the one shown in Fig. 8. above. Depending on which Change button you choose, you can specify your SMTP address, the user principal name or the display name format. You can type in a string of text or use a range of placeholders.

• set the password for your target users. All the newly created target users will receive the same password. The password needs to meet AD requirements.
   
• select which AD source attributes you want the program to copy to the target environment (not available when migrating from IMAP). Attributes are migrated when the job is running, not at the configuration stage.

Once you have configured all settings, click OK to save changes. These settings apply only to the current job and only if new users are created by the program (e.g. during the automatching process).  

Target users can also be created in the Create new user window (Fig. 19.) that becomes available under the Create a new user link when the user password has been set. The window opens with the default data already in place. To manually enter the details of the target user, clear the Use default settings checkbox. To change the default settings, click the Default settings button. This will open the Create target users / mailbox settings window described above.

Fig. 19. Creating a new user in the target environment.

Note that all the users created manually with custom settings will be marked by   icon on the mailbox list.

Viewing summary information

The upper part of the matching window (Fig. 20.) displays:

1. the results of the matching process, and
2. a list of actions that will be taken by the program when you start the migration job.

Fig. 20. The summary of the mailbox matching process.

To export this information from the program, you can generate an HTML report.

Mailboxes matching summary

This card of the Match mailboxes window lets you check how many mailboxes were matched, how they were matched (automatically or manually) and how many remain unmatched.

Actions summary

The Match mailboxes window will contain a summary of all actions to be taken by CodeTwo Exchange Migration when the job starts:

• Create new user with mailbox and migrate – the program will create a new user in the target environment along with a new mailbox. Target users and mailboxes will be created based on the settings provided in the Create target users/mailboxes settings window or the CSV file. 
   
• Enable mailbox for existing user and migrate – if the program detects that a target user together with the associated mailbox already exists in the target environment, but that mailbox is not active, the program will enable such a mailbox. Enabling a mailbox will not result in any changes to the user’s settings: the user's password and other details will remain unchanged.
   
• Migrate to existing mailbox – after successfully matching source and target mailboxes (automatically or manually), the program will simply migrate data between them. This will happen if a mailbox already exists in the target environment and is active. The program will not make any changes to the user or the corresponding mailbox. Migration of that user’s data will start immediately.
   
• Don't migrate – the program will ignore any source mailboxes included in the job that were not matched with mailboxes existing on the target server.

To see what action will be performed for a particular mailbox, have a look at the Actions to perform/performed column (Fig. 21.).

Fig. 21. Checking what action will be performed
for a mailbox when the migration starts.

HTML Report

The HTML Report button lets you generate an HTML file that contains comprehensive information on the matching process and can be easily shared with others. Learn more

Saving the configuration

To save your current configuration, remember to click the Save button before closing the window. You will be prompted to do so by the program if you try to close the Match mailboxes window without saving your work.

The program will inform you of any changes in the matching process by displaying (modified) in the title bar.