This article outlines the steps required to migrate direct messages in Google Chat between Google Workspace tenants. This article assumes that you have already followed the steps in the below article to set up a Google Workspace to Google Workspace project and added your users migration batch.
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 Chat migration.
Migration Scope
Understanding what data is included is critical for setting expectations.
What is Migrated?
- All Messages: All messages within DM or Group Chat conversations 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 Chat 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.
- 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.
-
Content from Non-Migrating Users:
-
Messages: Messages from users not being migrated will be posted to the destination chat 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 folder will be created in the migrating users My Drive named "Migrated Chat Attachments" and the attachments will be migrated here. A link to the file will then be posted in the chat.
-
Messages: Messages from users not being migrated will be posted to the destination chat by the Chat App. The message will be prefixed with the original sender's email address, e.g.,
- External Chats: External chats are migrated, however, due to API limitations, the chat will be named "Empty Group" at the destination.
-
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 user attachments: Attachments from external users 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.
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. 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 Chat is placed into Import Mode.
- Visibility: While in this mode, the Chat is not visible to end-users in the destination. Only the migration service can add content.
- Finalization: To make the Chat visible and usable, you must run a final delta migration with the Finalize Spaces import mode migration option enabled.
- Consequences of Finalization: Once a Chat 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 Chat migration.
1. Adding Items to Migrate
When preparing to migrate users to corresponding accounts at the destination, follow the format below:
- Export Type: User
- Export Name: Source primary email address
- Import Type: User
- Import Name: Destination primary email address
- Given Name: User's first name at the destination (leave blank if the user already exists at the destination)
- Family Name: User's surname at the destination (leave blank if the user already exists at the destination)
Further instructions on adding entities to your batch can be found here: Adding Items to a migration batch
For each entity added, you can select the specific data types you wish to migrate. Ensure the 'Migrate' checkbox is enabled for all entities you intend to include in the migration run.
2. Configuration Settings
General Settings
In the General Settings section, ensure all domain mappings are configured correctly to facilitate replacing the source domain with the destination domain during the migration.
Date range filters cannot currently be applied to this migration type.
Source Settings
For this type of migration, it is recommended to keep the source settings as default.
For more detailed information on each available source setting, please review the below article.
Google Workspace - Source Settings
Destination Settings
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
For a straightforward user-to-user migration, most advanced settings can remain at their default values. However, consider the following:
- Address Replacement: It is highly recommended to upload an address replacement CSV that maps source users to their corresponding destination users. This ensures permissions are correctly migrated. For more information, please refer to the Address Replacements article.
Additional settings are outlined here: Advanced Settings
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 Chats accessible to your destination users.