Folder Filtering & Mapping in MigrationWiz

Folder Filtering

MigrationWiz allows folder exclusions and inclusions using the Regular Expressions (RegEx) syntax.

Filtering folders can reduce the time needed to index the items to be migrated.  MigrationWiz indexes all folder names on the source first, then applies any folder filters.  Then items in folders are indexed, so to adding folder filters will shorten the indexing time needed to identify all folders to be included in the migration.

Folder Normalization:

Here is how MigrationWiz normalizes folder names before applying a specified RegEx to decide if a folder should be skipped:

  • Case Sensitivity - Folder names are compared in a case-insensitive fashion.
  • Folder Separator - Regardless of the messaging system, all folder paths are separated with a forward slash (/) for the purpose of exclusion comparison, for example, Inbox/SubFolder.
  • Preceding Separator - Do not specify any preceding separator when referencing the folder, i.e., do not specify /Inbox/SubFolder but rather Inbox/SubFolder.
  • Trailing Separator - Do not specify any trailing separator when referencing the folder, i.e., do not specify Inbox/SubFolder/ but rather Inbox/SubFolder.
If your folder name is localized (example: "Postvak In" is "Inbox" in Dutch), make sure to use the localized name. 
Folder filters are based on the Source or export side, not the Destination or import side. Therefore, if the Destination has a different format than the Source, it is important for the filter to reflect the Source side. This is common in document migration projects, e.g., Google Drive to OneDrive for Business. For more information, refer to the example filterSyntax: ^(?!My Drive/Some/Folder/Path) in the table below.
^ indicates "match the beginning of the string", meaning that you should filter everything that matches the beginning of the string.
^(?!abc) indicates a negative look ahead , meaning that you only process folders that match the string that follows "^(?!".
Make sure you end the folder path with ")"
If the source is Google Drive, then the folder filter needs to include the root MyDrive in the filter.
Example: ^MyDrive/Folder A/Folder B
If the source is SharePoint or OneDrive, then the folder filter needs to include the root Documents or Shared Documents in the filter.
Example:
^Documents/Folder A/Folder B 
^Shared Documents/Folder A/Folder B

 

​FilterSyntax ​Description
^Inbox/ Do not migrate any subfolders under the Inbox.
(^Inbox$|^Inbox/) Do not migrate the Inbox or any subfolder of Inbox.
(^Folder1$|^Folder2$|^Folder3/) Do not migrate Folder1, Folder2 and any subfolder of Folder3. Note that subfolders of Folder1 and Folder2 are still migrated.
^(?!Inbox$) Migrate only the Inbox. All other folders will be filtered.
^(?!Inbox) Migrate only the Inbox and its corresponding subfolders. All other folders will be filtered.​​
​^(?!Foo/ABC) Only process folders starting with "Foo/ABC"
​^Foo/ABC ​ Skip folders starting with "Foo/ABC"
​^(?!.*Marketing)  Only process folders that have "Marketing" in their path
​^Deleted Items/Frequent Contacts  ​This folder filter will filter out the folder named Frequent Contacts, under the Deleted Items folder, so that it is not included in the migration
​^(?!Inbox/Foo|Inbox/Bar)     ​This inclusion filter means that only Inbox/Foo and Inbox/Bar folders will be migrated. Note: The parentheses are required!
​^(?!INBOX/james1|INBOX/james2|INBOX/samantha|INBOX/john)​ ​Filter everything except INBOX/james1, INBOX/james2, INBOX/samantha and INBOX/john. Therefore, only these four folders will be migrated.
​^(?!My Drive/Some/Folder/Path) ​Only export the subtree under Google Drive that matches: My Drive/Some/Folder/Path. Note: The filter is always based on the source. Therefore, if migrating to OneDrive for Business, then the default destination matching directory path would be "Documents/Some/Folder/Path"  - but the filter is not based off this path because that is the Destination, rather than the Source.

 

Configuring A Folder Filter For A Project:

  1. Sign in to your MigrationWiz account.
  2. Click the Projectstab if you do not see your Project listed.
  3. From the list, click on the name of your Project. Click on the Edit Project button​.​
  4. Click on the Advanced Options button.
  5. Under Filtering, specify a filter.
  6. Click Save.

A useful utility for testing RegEx is: http://regexhero.net/

Folder Mapping

Use the folder mapping support option to map a Source folder to a Destination folder. For example, when you want to map the "Inbox" folder on the Source to an "Old Inbox" folder on the Destination in a mailbox migration.

The folder mapping support option uses regular expression (regex) and is added to the Adding Support Options screen for individual items or for an entire migration project, which applies to all items in the migration project. This article provides detailed information about using the folder mapping Support Option for mailbox migrations and some examples of how the folder mapping support option can be modified to work for you.

Add folder mapping for a migration project

Follow these steps to add folder mapping to a migration project, which applies to all items in the migration project:

  1. From the MigrationWiz dashboard, click on the migration project that will have the folder mapping added.
  2. From the migration project page, click Edit Project and then select Advanced Options.
  3. In the Support Option section, add this support option:
    FolderMapping="^SourceFolder->DestinationFolder"
    Note: Replace "SourceFolder" and "DestinationFolder" with the names of the folders in the Source and Destination environments.
  4. Click the "+" sign to add the folder mapping.
  5. Click Save.

Add folder mapping for an individual mailbox

Important: If you are migrating an entire mailbox into a single subfolder of a Destination mailbox, then you must add additional advanced support options for calendar and contact items. Otherwise, you'll experience problems accessing migrated items at the destination. 

Follow these steps to add a folder mapping to an individual item in a mailbox migration project:

  1. From the MigrationWiz dashboard, click on the migration project that contains the item that will have folder mapping added.
  2. From the migration project page, find the item that will have folder mapping.
  3. Click the Edit icon (pencil icon) on the right side for that individual item to open its Advanced Options.
  4. In the Support Option section, add this support option:
    FolderMapping="^SourceFolder->DestinationFolder"
    Note: Replace "SourceFolder" and "DestinationFolder" with the names of the folders in the Source and Destination environments.
  5. Click the "+" sign to add the folder mapping.
  6. Click Save Item.

Folder mapping examples

Here are a few examples of folder mapping commands and processes, along with special notes for those specific mappings.

  1. FolderMapping="^Sent Emails->My Sent Items" This maps the "Sent Emails" folder to a folder named "My Sent items". 
  2. FolderMapping="^Inbox->Managed Folder" This maps the "Inbox" folder to a folder named "Managed Folder".
  3. FolderMapping="^.*$->DestinationFolder" This maps all files across all source folders into a single folder on the Destination.
    Notes: 
    • Replace "DestinationFolder" with the name of the folder in the Destination environment.
    • ^.*$: Is the regex version of "Select All". (^) Match beginning of string; (.*) Any characters; ($) Match end of string. 
  4. FolderMapping="^Documents->Documents/DestinationFolder" When migrating to OneDrive there is a hidden root level folder titled Documents.  This mapping this will map everything being migrated to the defined Destination folder, which will appear as a top level folder within OneDrive
    Note: Replace "DestinationFolder" with the name of the folder in the Destination environment. 
  5. FolderMapping="^->DestinationFolder/" This maps everything from the root level down into a single folder on the Destination, while maintaining the folder hierarchy within the Destination folder. Be sure to add the / (forward slash symbol) at the end of the folder name to tell MigrationWiz to create a new subfolder under that Destination folder. Be careful with this, as it will map system folders as well as regular folders (such as Google Drive's "Permissions" folder). WARNING: If migrating a mailbox to a specific Destination folder, this command can cause items to become inaccessible due to the order of migration.  Replace "DestinationFolder" with the name of the folder in the Destination environment. 
  6. FolderMapping="^Floor 5-A5-8-T4-\(AV\+TC\)->Calendar" This maps the "Floor 5-A5-8-T4-(AV+TC)" folder to the "Calendar" folder. The part to the left of "->" is regex, so special characters need to be escaped. In the above example, the special characters are escaped with a back slash before the special characters.

Additional information about folder mapping

The Source folders may be different (at the API level) from what is displayed in the user interface or Outlook. Therefore, when defining the folder mappings, pay special attention to the exact format of the folder name (e.g., [Gmail]/Sent for Sent).

We recommend that you use Regex Hero to test your regular expression code.

{%escape%}is a reserved word that must be avoided when creating folder mappings. If original folder names in the Source end with {%escape%}, they must be manually renamed before migration.

G Suite (GMail API) Limitations

For ‘GSuite (Gmail API) to GSuite (Gmail API)’ migrations only:

If you want to map multiple source labels into a single label on the destination, then the parent destination label must be created before starting the migration.

Example: If you wish to map three Source labels ('ABC', 'PQR', and 'XYZ') into one parent label ('DestinationLabel') at destination then you must create the parent label ('DestinationLabel') at destination mailbox before running the migration.

Escaping Special Characters

Example: FolderMapping="^Floor 5-A5-8-T4-\(AV\+TC\)->Calendar" This maps the "Floor 5-A5-8-T4-(AV+TC)" folder to the "Calendar" folder. The part to the left of "->" is regex, so special characters need to be escaped. In the above example, the special characters are escaped with a back slash before the special characters.
 
Here is a list of the common special characters that would need to be escaped and what each one does:
  • ^ matches the beginning of a string.
  • $ matches the end of the string.
  • {} are used as range quantifier.
  • () are used to group characters.
  • [] are used to create a character class that match a single character.
  • . matches any character except a new line.
  • * is a match 0 or more quantifier.
  • ? is the 0 or 1 quantifier.
  • | separate a series of alternatives.

Adding Recipient Mappings for User Name Changes

Recipient mappings are a useful way to ensure that:

  • All email remains replyable to, post-migration, even after a Full (Delta) Migration has occurred when performing a tenant to tenant migration while keeping the same domain name, or when changing domain names from Source to Destination.
  • Calendar ownership and display name match on the Destination when performing a tenant to tenant migration while keeping the same domain name, or when changing domain names from Source to Destination.
  • If a user name is changing, recipient mapping can also be used to rewrite message headers of the emails during migration to the Destination.

If you are using recipient mapping while migrating from one Source domain to multiple Destination domains, a project is required for each Destination domain.

User Prefix Changes:

If a user SMTP address is changing during the migration, Recipient Mapping can be used to ensure that message headers are rewritten with the new prefix. An example is if john.doe@sourcedomain.com was changing to john.doe2@destinationdomain.com. This is common during mergers, when migrating data to an existing Office 365 tenant and there are user name conflicts.

The following explains how to add a user prefix Recipient Mappings to your project’s Advanced Options.

Under Support/Support Options:

    • Recipient Mapping should be added into each project under Advanced Options/Support Options.
      • RecipientMapping="john.doe@abc.com->john.doe2@xyz.com"
    • Note that Recipient Mapping changes are made according to the order that the mappings are added to the Support Options. Ensure that the prefix mappings are at the top of the Advanced Options list so they are performed first and not superseded by the action of a domain level recipient mapping option, e.g., RecipientMapping="@abc.com->@xyz.com". Changes are made based on mappings added from the top down. Therefore, ensure that Recipient Mappings are noted in the correct order you wish them to be performed. 
    • If you have multiple projects in progress for the same migration (e.g., batches), make sure that these mappings are also in the other project.  
    • The SMTP rewrite is performed by MigrationWiz during the migration process. The Source and Destination SMTP addresses for the mailboxes in the project are simply to define the Source and Destination matching. It does not correlate to any changes made to email headers during the migration. This is why recipient mapping is mandatory; it ensures replyability.

Using the AutoRemapMigratingUser=1 option is not recommended, due to inefficiencies that will mean migrations are slowed down. It is better to use the RecipientMapping= switches to perform the translations.

Migrating a Mailbox to a Single Subfolder

It is possible to migrate a Source mailbox into a single subfolder of a Destination mailbox, but contact and calendar folders will need to reside under the root contacts and calendar folders.

These folder mapping support options ensure the folders are created at the correct location. Replace "DestinationFolder" with the name of the folder you want to use at the Destination.

First:

FolderMapping="^(?!Calendar$|Calendar/|Contacts$|Contacts/)->DestinationFolder/"

Second:

FolderMapping="^((Calendar)([/]?)|(Contacts)([/]?))->$2$4/DestinationFolder$3$5"

The support options above both need to be added in the Advanced Options for your project or for individual mailboxes.

To add for a single mailbox, click on the pencil icon to the far right side of the email address that you wish to edit.  

The folder mapping support options listed above must be added in the order shown. If they are not added in this order, some contents of the migrating mailbox may become invisible and inaccessible on the destination

Destination Language

The spelling of both 'Calendar' and 'Contacts' must also reflect the language of the folder name at the Destination mailbox, e.g., 'Calendar' will be 'Calendrier' in French and 'Contacts' will 'Contactpersonen' in Dutch.

G Suite (GMail API) Limitations

For ‘GSuite (Gmail API) to GSuite (Gmail API)’ migrations only:

If you want to map multiple source labels into a single label on the destination, then the parent destination label must be created before starting the migration.

Example: If you wish to map three Source labels ('ABC', 'PQR', and 'XYZ') into one parent label ('DestinationLabel') at destination then you must create the parent label ('DestinationLabel') at destination mailbox before running the migration.

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