Skip to main content
  1. CloudM
  2. Migrate
  3. Perform a Migration
  4. Configure your Connections
  5. Batch Configuration Settings
  6. Advanced Settings

Domain and Email Address Mapping in CloudM Migrate

Updated

This article explains how to correctly handle domain and email address mapping, a crucial process for ensuring data integrity during migrations. Correct mapping ensures that user addresses in calendar attendee lists, folder and file permissions, and other data types are preserved and correctly updated on the new platform.

1. Key Mapping Concepts

When performing a migration, it's essential to understand how CloudM Migrate handles different addresses and domain names.

  • Mapping vs. Replacement:
    • Mapping is a comprehensive process that defines how source email addresses or domain names correspond to target ones.
    • Replacement is a specific type of mapping focused on substituting a source address for a target address.
  • Default Domain Name: This is the primary domain that CloudM Migrate assumes for all users. This value is set in the source and destination Connection Setup in the Domain name field and dictates the initial user mapping.
  • The Items to migrate List: This list defines the primary, one-to-one mapping of source users to destination users for the migration itself.

2. Recommended Approach for Mapping

For a successful migration, you must define how source and destination addresses are mapped. While the default settings are often sufficient for straightforward migrations, we highly recommend a hybrid approach for a seamless transition. This involves a combination of automated and manual mapping methods.

  • Domain Mapping: Domains should always be mapped within the CloudM Migrate tool via Configuration General Review domain names. The default source and destination domain names are automatically populated. This ensures the migration process correctly handles all email addresses and other user data that reference the old and new domains.
  • Address Replacements CSV (Highly Recommended): We highly recommend uploading an Address Replacements CSV file. This explicit mapping is crucial for preserving permissions, calendar attendee lists, and other references.

3. Understanding CloudM Migrate's Mapping Hierarchy

The following settings control how CloudM Migrate performs address and domain mapping. They are applied in a specific, sequential order.

Mapping and Replacement Options

  • Configuration General Review domain names
    • Function: This setting allows you to manually specify which source domains correspond to which destination domains. The default domains for your migration are automatically populated, but you can add other domains that exist on both the source and destination platforms.
    • Best Practice: You should review this list to ensure all source domains you intend to migrate are correctly mapped to their corresponding destination domains. This step is particularly important for more complex scenarios involving multiple domains or aliases.
  • Configuration Advanced Address replacement
    • Replace usernames:
      • Function: Replaces usernames from the Items to migrate list. This setting is enabled by default.
      • Best Practice: Keep this enabled to automatically map addresses from the user list. If disabled, you must provide a comprehensive Address Replacements CSV.
    • Address Replacements (.CSV):
      • Function: Allows you to upload an explicit list of email addresses to be mapped in a CSV file. The file should have two columns: source_address and replacement_address.
      • Example: old.user@source.com, new.user@destination.com
    • Non Matched Address Replacement Behavior:
      • Function: Defines how CloudM Migrate handles addresses that are not found in the user list or a provided CSV file.
      • Options: Replace Domains or Retain Original.
        • Replace Domains: For addresses not found in the CSV, attempts to replace domains based on the Review domain names setting.
        • Retain Original Address: For addresses not found in the CSV, retains the original address.
    • Replace CSV Addresses Only:
      • Function: Forces CloudM Migrate to perform replacements exclusively from the CSV file, ignoring all other methods.
      • Use Case: This is useful for subset or partial migrations, where only a subset of users or other entities needs to be remapped, rather than the entire source domain.
      • Note: When this setting is enabled, you must include domain name replacements within the CSV file as well. For example, to map source.com to destination.com, you would add a row to your CSV with source.com, destination.com.
  • Configuration Advanced Domain replacement
    • Function: Replaces a source domain name with a target domain name (e.g., example.com to domain.com) for specific item types. The following sub-settings control which item types have domain replacement applied:
      • Email: Off by default. Applies domain replacements to all email addresses (To, CC, and From) within migrated emails.
      • Appointments: On by default. Applies domain replacements to all email addresses in appointments.
      • Contacts: On by default. Applies domain replacements to all email addresses in contacts.
      • Users: On by default. Applies domain replacements to all email addresses for delegated users and other permissions.
      • Tasks: On by default. Applies domain replacements to all email addresses in tasks.
    • Best Practice: It is recommended to leave these settings at their default values. This ensures that the most common and critical item types, such as permissions and calendar entries, are correctly mapped while preserving the original content of emails. For example, leaving Email set to Off will not change historical email addresses within the body or headers of messages.

Order of Operations: How Replacements Are Applied

CloudM Migrate applies domain and address replacement rules in this sequential order:

  1. CSV Match Check: If a CSV has been uploaded, CloudM Migrate looks for a direct replacement in the Address Replacements CSV. If a match is found, the replacement is applied, and no further actions are taken for that address.
  2. CSV-Only Enforcement: If Replace CSV Addresses Only is enabled, the process stops here if no CSV match was found.
  3. User List Check: If Replace Usernames is enabled, the tool checks the Items to migrate user list for a match and applies the replacement.
  4. Non-Matched Behavior: If an address is still unmatched, the Non Matched Address Replacement Behavior setting is applied.
  5. Final Domain Replacement: Any remaining domain replacements configured in the Domain replacement settings are applied based on Review domain names.

4. Special Considerations

Best Practices for Master Address Replacements CSV

For any migration that is split into multiple batches, we recommend using a single, master Address Replacements CSV file. This ensures consistent and accurate mapping across the entire project.

  • What to Include: A master CSV should include all entities with an email address that requires replacement for data integrity. This covers:
    • Users: All users being migrated.
    • Groups: Different platforms have unique requirements for migrating and mapping groups. You should include all relevant groups in your CSV, whether they are email-enabled or identified by a name. Here are some examples:
      • Google Workspace: Google Groups.
      • Microsoft: Microsoft 365 Groups (including Microsoft Teams), Microsoft Security Groups, and Distribution Lists. While Security Groups and Distribution Lists can't be migrated, you should still include them in the CSV for permission mapping.
      • Box & Dropbox: These groups should be mapped by their group name as they do not have an email address.
    • Resources: Anything with an email address, such as conference rooms or shared equipment.
  • Application: The master CSV should be applied to every batch. This guarantees that references to users or other entities in other batches are correctly resolved.

Mapping Specifics for Google Migrations

CloudM Migrate's behavior for Google Workspace migrations is unique compared to other platforms. Understanding these specifics will help you manage mapping settings correctly and avoid common pitfalls.

  • Automatic Domain Replacement
    For standard Google-to-Google migrations, CloudM Migrate often handles domain replacements automatically for secondary references. The tool’s default behavior correctly updates addresses in calendar attendee lists, file sharing permissions, and other items without requiring manual intervention.
  • The Exception: When to Use the CSV
    This automatic behavior is bypassed when you enable the Replace CSV Addresses Only setting. When this option is selected, CloudM Migrate will ignore its built-in domain replacement logic and rely exclusively on your provided CSV file for all mapping information. Therefore, for subset migrations or any time you use the Replace CSV Addresses Only setting, you must include a row in your CSV that explicitly maps the source domain to the destination domain. Example CSV Entry: sourcedomain.com,destinationdomain.com
  • Why This Matters for Permissions
    This explicit domain mapping is especially important for preserving permissions and attendee lists. Without the domain-to-domain entry in the CSV, domain-wide permissions (e.g., a file shared with "everyone at olddomain.com") and calendar attendee lists (e.g., a calendar invitation sent to "all staff at olddomain.com") will not be correctly remapped and will remain pointed at the original domain after migration.

Mapping Specifics for Microsoft Migrations

Unlike Google Workspace, Microsoft 365 migrations often require more explicit mapping due to platform differences in handling permissions and addresses.

  • Manual Domain Mapping is Key
    For migrations involving Microsoft, it's a standard and expected practice to manually specify domain mapping. You should use the Domain replacement settings to ensure that source domains (e.g., source.com) are correctly mapped to destination domains (e.g., destination.com).
  • Explicit Mapping is Recommended
    While CloudM Migrate automates much of the process, providing a comprehensive Address Replacements CSV is the best practice for all Microsoft migrations. This ensures that permissions, calendar attendee lists, and other references are correctly updated, as the tool does not automatically handle every possible permutation of addresses.

Mapping Global and Domain Permissions

You can use the Address Replacements CSV to map special global permissions (e.g., domain, anyone) to other permission scopes. This is useful for remapping permissions that apply to a broad group rather than a specific individual.

The CSV uses a two-column format: special_value, new_permission_target.

Example CSV:

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

Note: The second column can also specify the target type (e.g., :user, :group, :domain), but this is optional as the tool can often infer the correct type from the address.

Note: This is not Supported where Microsoft 365 is the source platform.

Related Articles

Related to:

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