Domain & Address Replacements

There are a number of options which control how replacements are performed. It is important to understand how these applied, in which order and under which conditions. It is possible to end up with incorrect email addresses if the options are not fully understood.

• Replace Usernames – Replace any re-mapped usernames from the users tab, when migrating the items specified in 'Domain Replacement Types' in Common settings. If this option is disabled and replacements are required, explicit mappings for email addresses and domain names should be provided via the other settings in this section. Only addresses that belong to source domains are automatically mapped. When migrating from Google Workspace, the source domains are automatically identified, but when migrating from other sources you should specify the domains in the next setting: Address Domain Replacements
• Address Domain Replacements - If migrating from one domain name to another, specify the domain names that should be replaced and the value with which they should be replaced with.  For example, when migrating from example.com to domain.com, you should provide example.com and domain.com in this setting. If migrating from one Google Workspace domain to another, domain replacements are performed automatically unless Replace CSV Addresses Only is selected and you have not provided the domain mappings within the file.
• Address Replacements (File) – Use this option to provide an explicit list of email addresses to be mapped as part of a migration. If performing domain consolidation or if you have other specialized requirements then this option can be used to map any source email address to any other address. Addresses should be mapped using a simple CSV file containing two columns, the first for the address to be replaced and the second the replacement address.
  • A check will be performed on the Address Replacements list, and, if a duplicate file is identified, you will see a notification highlighting where the issue is (e.g. Line number 6 is invalid).

• Replace CSV Addresses Only - Perform email addresses and domain replacements from the CSV file specified in Address Replacements (File) and do not attempt to perform replacements using any other method. This can be useful when partially migrating users from a source domain and only those specified in the CSV file should be replaced. Note that if you use this option you should be careful to specify all replacements, including domain names and group addresses in the CSV file. If an address or domain is not matched from the CSV and you have this option on, the address from the source will be left unchanged.
• Non Matched Address Replacement Behaviour - When 'Replace Usernames' is enabled, and when a CSV has been provided for address replacements, set the behavior when an address has not been matched (and therefore replaced) from either the CSV file or from the users specified on the users tab. Either replace the domain name based on any domain mappings provided (or to the destination domain in the case of Google to Google), or leave the original address unchanged.

The rules for domain replacements are applied in the following order:

1. Check to see if the domain replacement for the type of item being migrated is enabled (see Domain Replacement section in Advanced Settings (Config Settings)). If the type is not configured, do not perform any replacements. When migrating Drive/Documents, domain replacements are always performed
2. Check to see if a direct replacement has been specified in a CSV file in Address Replacements (File). If its been specified, apply the replacement and perform no further actions.
3. If the option Replace CSV Addresses Only has been set, do not perform any more replacements.
4. Check to see if the name part of an address has been changed according to the user list within CloudM Migrate. If there is a matching name part of an email address in export name in the address list, change it to the import name. This is only applied if the address being processed is from a source domain. When migrating from Google Workspace the source domains are automatically identified, but when migrating from other sources you should specify the domains Address Domain Replacements
5. If a CSV file was provided and there was no match and when a match was not found in the user list, then check to see if the original address should be left, or the domain name replaced. This check is performed based on the setting: Non Matched Address Replacement Behaviour. Note that if a CSV file was provided and no match was found in the CSV file or the user list and the value of Non Matched Address Replacement Behaviour is set to Retain Original then no more address replacements will be made, including for domain names.
6. Apply any other domain name replacements configured within Address Domain Replacements.

Domain Replacements

For Google Drive to Google Drive migrations domain permissions are normally mapped automatically. However, if you have provided a CSV file for Address Replacements (File) and have selected Replace CSV Addresses Only then unless you have mapped the domain name, it will not be mapped when domain wide permissions are transferred and the source domain will be shared on the migrated items. To ensure domain wide permissions are replaced correctly then include the mapping in the CSV file in the format:

sourcedomain.com,destinationdomain.com

Manipulating Global and Domain Permissions

Address Replacements (File) can also be used to map global and domain permissions to other permission scopes in Google Drive migrations

domain,my-user@domain.com:user
anyoneWithLink,my-group@domain.com:group
anyone,domain.com:domain
domainWithLink,my-group@domain.com

Best Practice

Generally, to remove confusion, if you are using a CSV file to provide mappings, then you should ensure that all addresses, groups and domains are included in the CSV file.  This removes any ambiguity about what will be replaced, although the rules described above apply. 

If none of your users or groups are changing names, and you have no need to map users from one account to another then you do not need to provide a CSV file.

If you are using a CSV file only to map certain users or groups and you wish to change the domain name of other users, groups and domains who are not explicitly listed then you must ensure that the setting Non Matched Address Replacement Behaviour is set to Replace Domains.