This guide details the process for migrating conversations, members, and content from a Google Workspace Space to another Google Workspace Space using CloudM Migrate. It covers what is and is not migrated, essential prerequisites, and a step-by-step guide to configuration and execution.
Prerequisites
Before you begin your migration, ensure you have completed the following essential setup steps:
- CloudM Project Setup: You must have already configured your CloudM Migrate project following the Migration Guide and added your Spaces batch.
- Google Chat API: The Google Chat API must be enabled and correctly configured for the destination environment. Please follow the instructions in our Enable and Configure the Google Chat API guide.
- User Licensing: All migrating users must have an active Google Workspace license and the Google Chat service enabled in the destination.
- Drive Migration: To ensure all supported attachments migrate correctly, you must first migrate all user and shared drive documents with Record Document Mappings enabled. This step must be completed before you begin the Spaces migration.
- Migrate Licensing: Each destination Google Space (unique import name) will require a CloudM Migrate license.
Migration Scope
Understanding what data is included is critical for setting expectations.
What is Migrated?
- All Messages: All messages in a Space conversation within the specified chat date ranges.
- Replies: Replies within message threads are maintained.
-
Attachments: Attachments from migrating users will be migrated.
- It is important that you migrate Google Drive for all migrating users and Shared Drives with document mappings enabled prior to performing the Spaces migration. This will ensure we have the appropriate mappings to post the correct attachments in the destination spaces.
- Messages with multiple multimedia files: Google Chat messages can now include multiple multimedia files in a single message. These messages and files are migrated.
- Internal Members: Users who exist in both the source and destination environments will be added to the destination Space.
- Unordered Lists: Unordered and nested unordered lists are migrated.
- GIFs & Custom Emojis: Supported media like GIFs and custom emojis are included.
- Reactions: Reactions from migrating users are preserved.
- Quoted Messages: Migrated as quoted messages as they appear at the source.
-
Bot Messages: Messages posted by a bot/chat application at the source.
-
Messages: Messages from external users are migrated, however, the message will appear in the below format.
"Original sender: External/Anonymous User"message content"
-
Messages: Messages from external users are migrated, however, the message will appear in the below format.
- Space Type: If the source Space has been set up as an announcement or collaboration Space, the destination Space will reflect this.
-
Content from Non-Migrating Users:
-
Messages: Messages from users not being migrated will be posted to the destination Space by the Chat App. The message will be prefixed with the original sender's email address, e.g.,
Original Sender: user@source.com"message content". -
Attachments: A Shared Drive, named
[ImportName]_Space_Attachments, will be created in the destination. Attachments from non-migrating users are uploaded to this drive in a folder named "Migrated Chat Attachments", and a link to the file is posted in the Space conversation.- Important: If the destination's Google Workspace license does not permit the creation of Shared Drives, attachments from non-migrating users will not be migrated.
-
Messages: Messages from users not being migrated will be posted to the destination Space by the Chat App. The message will be prefixed with the original sender's email address, e.g.,
-
Content from External and Anonymous (Deleted) Users:
-
Messages: Messages from external users are migrated, however, the message will be prefixed with the below.
"Original sender: External/Anonymous User"message content"
-
Messages: Messages from external users are migrated, however, the message will be prefixed with the below.
What is Not Migrated?
- External Members: Users who are not part of your Google Workspace organization will not be added to the destination Space.
- External Members attachments: Attachments from external members are not migrated.
- Reactions from Non-Migrating and External Users: Reactions from users who are not part of the migration scope will not be migrated.
- Ordered Lists: Numbered lists will be converted into unordered (bulleted) lists due to a Google Chat API limitation.
- Document Spaces Permissions: When users share a document within a Google Space, they can grant access permissions directly to the Space as a whole. Please be aware that this specific type of Space-level permission is not migrated. This means that after migration, if a user in the destination Space relied solely on their membership for access, they will need to re-request it for that document. Access will only be preserved for users who were shared on the document directly or as part of a Google Group provided you have already performed the Drive migration.
Watchpoints
There are a few things to consider when planning this type of migration.
- When migrating bold text formatting, if there is a trailing or leading space around the bolded text, both the text and the space may lose their bold formatting at the destination, appearing as follows:
- *text *
- * text*
- Import mode can last up to 90 days, after that, data is deleted by Google. However, we recommend finalising the destination space before the 89th day to avoid having the destination data purged by Google, which would require you to remigrate all of the source data.
Understanding Google's "Import Mode"
This migration process uses Google's "Import Mode", which has specific behaviors you must understand.
- Activation: When the migration begins, the destination Space is placed into Import Mode.
- Visibility: While in this mode, the Space is not visible to end-users in the destination. Only the migration service can add content.
- Finalization: To make the Space visible and usable, you must run a final delta migration with the Finalize Spaces import mode migration option enabled.
- Consequences of Finalization: Once a Space is finalized, you can no longer migrate historical messages to it. Only messages created after the finalization time can be migrated in subsequent deltas. This step is irreversible.
The below diagram represents this further.
Migration Process
As mentioned above, please ensure you have migrated your users and shared drives to ensure all supported attachments are migrated.
Follow these steps to configure and run your Spaces migration.
1. Add Items to Your Migration Batch
- Navigate to your migration batch in CloudM Migrate.
- Add the Spaces you wish to migrate using the following format:
-
Export Type:
Google Space - Export Name: The ID of the source Google Space.
-
Import Type:
Google Space - Import Name: The desired name for the destination Google Space. (Note: You cannot migrate to a Google Space that was created outside of CloudM Migrate)
-
Export Type:
- For detailed instructions on this process, see Adding Items to a Migration Batch.
- Ensure the 'Migrate' checkbox is selected for all items you want to include in the migration run.
2. Configuration settings
Navigate to the Configuration section for your project.
General Settings
- Review domain names: Ensure all necessary domain replacements are configured to correctly map source domains to destination domains.
- Date Filters: Apply Chat date range filters using the if you only need to migrate data from a specific period.
Important: Messages must be migrated in chronological order, from oldest to newest. Using a date filter to migrate recent messages before older ones is not supported and will result in an incomplete migration.
Source Settings (Google Workspace)
For this migration type, you can typically leave the source settings at their default values. For details on all available options, refer to the Google Workspace - Source Settings article.
Destination Settings (Google Workspace)
This setting is critical for completing the migration:
-
Finalize Spaces import mode migration:
- Leave this DISABLED for your initial migration pass and any intermediate delta passes.
- Enable this ONLY for the final migration pass. This action takes the Spaces out of Import Mode, makes them visible to users, and completes the migration process.
For more detail on other destination settings, review the Google Workspace - Destination Settings article.
Advanced Settings
- Address Replacements: It is highly recommended to upload an address replacement CSV to map all source user email addresses, aliases, and groups to their destination counterparts. This ensures that memberships and message ownership are correctly assigned. The below article details this further.
- Record Document Mappings: Enable this option under the Reporting section to ensure that attachments are migrated where supported.
Note: If CloudM Migrate cannot map a user from the source to an existing user in the destination (via address replacement), this user will be treated as a non-migrating user and their content migrated as described in the "What is Migrated" section of this article.
3. The Migration Process
- Initial & Delta Migrations: For the first pass and any subsequent deltas (to migrate new content created during the migration period), run the migration with the Finalize Spaces import mode migration setting turned OFF.
- Final Migration: When you are ready to cut over, run one last delta migration with the Finalize Spaces import mode migration setting turned ON. This will migrate the last remaining items and make all the migrated Spaces accessible to your destination users.
IMPORTANT: Migrating Google Spaces After Google Domain Transfer
Migrating Google Spaces after a Google Workspace Domain Transfer is a complex process that requires a serviced migration handled by our Professional Services team.
This ensures that user identities are correctly mapped and conversation history is preserved with full integrity. Self-service migration is not supported for this scenario.
To discuss your project and get started, please contact our team.