Google Workspace User Data Transfer: A Detailed Guide

If you are trying to transfer users from one Google Workspace to another, you need to set up Google Workspace Migrate. 

***Please note: you don’t need Google Workspace Migrate if you just want to transfer email or Google drive data. 

Also, you can’t transfer the users directly from one Google Workspace to another. But, you can create user accounts in the target Google Workspace (of the users that you want to migrate) and transfer their data from the source Workspace. 

Let’s dive in. 

What is Google Workspace Migrate

Google Workspace Migrate simplifies transferring large content volumes to a Google Workspace domain. It streamlines migration across multiple core services from one convenient location. 

You can run Google Workspace Migrate both in the cloud or on-premises. Admins can independently manage migration timing and destinations, making the process hassle-free.

Things You Need to Do Before Setting Google Workspace Migrate

Before diving into the migration process, it's essential to ensure you meet all the necessary requirements and have a clear grasp of the recommended practices for moving from Google Workspace. 

Migration Requirements 

Hardware Requirements

• Supported runtime: Microsoft .NET Framework 4.5 or later (except for the CouchDB server, which requires Microsoft .NET Framework 3.5).
• Recommended operating system: Microsoft Windows Server 2016 or 2019.
• Supported browser: Chrome Browser.
• Power plan: Set all Windows computers (virtual or physical) to the high-performance power plan.
• Platform Server: One Windows server with at least 4 cores, 16 GB of random-access memory (RAM), and 200 GB solid-state drive (SSD)
• Database Servers

• 2 Windows servers, each with at least 16 cores, 64 GB of RAM
• A separate performance (SSD) persistent disk for the database data. For the separate disk Google recommends approximately:

• MySQL—1 TB per 100 million objects that you want to scan and migrate
• CouchDB—1 TB per 40 million objects that you want to scan and migrate

• Node servers: At least one Windows server with a minimum of 4 cores, 32 GB of RAM, and 200 GB SSD.

Network Requirements 

• Make sure that both the platform and all node servers have network access to all the data sources. This connectivity is crucial for a seamless functioning of the system.
• Every server needs to establish connections with other servers within the same network. 
• It's important to have the servers in the network placed close to each other physically.
• To avoid any accidental server restarts during a migration, it's best to handle Windows updates separately, outside of the migration process. 

Port Requirements

Within your Google Workspace Migrate cluster, Google recommends:

• Outbound access to the internet to access software updates
• Intra-cluster Server Message Block (SMB) access (TCP (Transmission Control Protocol) port 445)
• Admin Remote Desktop Protocol (RDP) access to all servers using TCP port 3389

Keep the following ports open:

• TCP port 5131—Used to communicate bidirectionally
• TCP port 3306 (default)—Used to access the MySQL server
• TCP port 5984 (default)—Used to access the CouchDB server
• TCP port 443—Used to reach the target Google Workspace APIs

To reach the source APIs, open the following ports:

• Microsoft Exchange—Use Exchange Web Services on TCP port 443
• Microsoft SharePoint or OneDrive—Use SharePoint Client side Object Model (CSOM) API on TCP port 443
• File shares—Use TCP port 445 (additional network access might be required for older environments)
• Box—Use Box API on TCP port 443
• Google Workspace—Use Google APIs on TCP port 443

Google Workspace Requirements

• Make sure you have a super administrator account set up on your destination Google Workspace domain. 
• Google Cloud access
• Create a user account in your target Google Workspace domain for each person whose data you want to migrate.
• A user license for your users to start using Google products or services.

In the Google Admin console of your target domain, activate the Google Workspace services (e.g., Gmail, Google Calendar, Google Drive) for both users and the super administrator. 

If you're migrating from another Google Workspace, don't forget to enable the services in the source domain as well. For more information, go here.

Google Drive Requirements

• Activate the Drive and Docs service for all users, including the admin user, in the Admin console of your destination Google domain. To learn more, go here. 
• Make certain that your admin account possesses the necessary Drive and Docs privileges. The super admin role automatically includes these privileges by default.
• Verify that your target users, including the admin user, have access to Drive files through the Google Drive API. Similarly, if you're migrating from Google Workspace, ensure that your source users, including the admin user, also have the necessary access to Drive files through the API.

Detailed Step by Step Instructions

Step 1: Set Up a Connection

You need to add a source connection to enable Google Workspace Migrate to read, convert, and transfer data from the Google Workspace source environment to another.

Add a Source Connection

Create a Service Account (Optional)

You can use the service account that you set up earlier. But, if you want to create a new one, follow the below steps.

• Go to Google Cloud and click IAM & Admin
• Then, click on Service Accounts. 
• Go to “Create Service Account”. There, enter a name for Service account name and your service account ID is completed automatically.
• Click Service account description and enter a description to add your own description to the service account. (Optional) 
• Click Create and Continue.
• You don’t need a Service account and user permissions for Google Workspace Migrate. Click on “Done” to avoid these steps.
• Pick the email address linked to the service account you made.
• Next, click on “Keys” then “Add Key”, and then “Create new key”.
• Set the key type to JSON and click on “Create”.
• After creating the service account JSON key file, you will receive a message confirming its creation and download to your computer. Remember to take note of the file name as you will require it for future use.
• Click on “Close”.

Authorize the Service Account

• Sign in to Google Admin console using a super administrator account
• Navigate to Menu, then Security, then Access and data control, then API controls, and finally, Manage Domain Wide Delegation.
• Click on "Add new" and input your service account client ID.
• The client ID can be found in the JSON file downloaded during service account creation or in Google Cloud under IAM & Admin, then Service accounts, and the name of your service account.
• Copy and paste the following scopes for OAuth scopes

https://apps-apis.google.com/a/feeds/emailsettings/2.0/,

https://www.googleapis.com/auth/contacts,

https://www.googleapis.com/auth/admin.directory.group,

https://www.googleapis.com/auth/admin.directory.group.member,

https://www.googleapis.com/auth/admin.directory.orgunit,

https://www.googleapis.com/auth/admin.directory.resource.calendar,

https://www.googleapis.com/auth/admin.directory.user,

https://www.googleapis.com/auth/apps.groups.migration,

https://www.googleapis.com/auth/apps.groups.settings,

https://www.googleapis.com/auth/calendar,

https://www.googleapis.com/auth/drive,

https://www.googleapis.com/auth/drive.appdata,

https://www.googleapis.com/auth/drive.file,

https://www.googleapis.com/auth/gmail.modify,

https://www.googleapis.com/auth/migrate.deployment.interop,

https://www.googleapis.com/auth/tasks,

https://www.googleapis.com/auth/userinfo.email,

https://sites.google.com/feeds,

https://www.googleapis.com/auth/gmail.settings.basic,

https://www.googleapis.com/auth/gmail.settings.sharing,

https://www.googleapis.com/auth/admin.directory.customer.readonly,

https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly

Next, click on authorize. 

• Click on the new client ID and select "View details" to ensure that all scopes are listed. If any scope is missing, click "Edit," add the missing scope, and then click "Authorize." Please note that you cannot directly edit the client ID.
• Next, go back to Google Cloud and then click on “Save”.
• You may encounter the error message "Client is not authorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested."
• Repeat “step 2” and authorize the service account again. Now, double-check that you are using the correct client ID by comparing it with the one in the JSON file. If the error persists, you might need to wait for the authorization process to complete, which typically takes a few minutes but could extend up to 24 hours. 

Create a Source Connection for Google Workspace

• Click "New" and then "Connection" in the Google Workspace Migrate platform.
• Enter a connection name in the "Name" field.
• Select "Google Workspace" as the connection type.
• Provide the email address of a super administrator from your source Google Workspace domain in the "Admin email" field.
• Choose an option for the "Account":

• Select an existing Google Workspace account, then move to step 8.
• Select "Add a new account," then move to step 6.

• Locate the JSON key file for the Google service account on the source domain.
• Click "Upload file" under "Service certificate," navigate to the downloaded JSON private key, and click "Open." Alternatively, drag the JSON file to the designated box.
• Click "Create" to complete the process.

Generate a List of Sharding Users (Optional)

When transferring over 400,000 files from Google Workspace to Google Drive, it's essential to create a sharding users list. This list helps spread the content across multiple creator accounts, regardless of whether you plan to migrate it to several shared drives. However, if you're migrating fewer than 400,000 files to a single user's Drive account, you can skip this particular step and proceed to create a scoped view.

If you're moving less than 400,000 files to a single user's Drive account, you can proceed directly to creating a scoped view, skipping this step.

What is a Sharding List?

A sharding users list is a CSV file containing email addresses from your target account. These email addresses correspond to user accounts responsible for writing objects to either a user's My Drive or a shared drive. 

Utilizing this list helps distribute the migration load among a larger group of users, preventing API bottlenecks and congestion in the Drive service.

Create Temporary Users

To track user accounts in the sharding list, check the Drive audit log for migrated files, showing details like the file creator. To avoid confusion with active users, set up temporary Google Workspace users with easily identifiable usernames (e.g., shard-user1) for the sharding list and delete them after completing the migration.

To calculate the number of user accounts to include in the sharding users list, compare two options and choose the larger value.

• Include one user account for every 400,000 files being migrated to Drive.
• 10 accounts per node

Later, ensure that the temporary users meet the following criteria:

• Have a license that matches the highest version of the Google Workspace edition assigned to your target domain for the migration period.
• Have access to the Google Workspace services being migrated, such as Gmail and Drive.
• Can access Drive files through the Drive API.

Create CSV File

Generate the list in a spreadsheet program with each entry on a separate line, and there's no need for headers. Save the spreadsheet as a CSV file, ensuring the character encoding is set to UTF-8.

Image Credits

Add the list

In the Google Workspace Migrate platform, click "New" and then "List." 

• Provide a name for the list. 
• Under "Type," select "Users." 
• Upload a CSV file by clicking "Upload CSV file" or dragging a file to the designated box. 
• Finally, click "Create." 

This list can be chosen while creating a bridge.

Create a scoped view

A scoped view is used to specify the source data accessed during a scan. These entries remain effective even if you change the source data.

Add Multiple Entries by Creating a CSV file  

To include multiple entries in a scoped view, use a comma-separated values (CSV) file. The CSV file should consist of 

• a header row indicating the object type
• rows beneath the header
• indicating locations for the specified types. 

A scoped view can comprise several columns, each with a type-name header. If a column has no value, it is ignored for that particular row. Ensure that the CSV file's character encoding is set to UTF-8.

Create a Scoped View

• In the Google Workspace Migrate platform, access the Connections section, which may require clicking on the Menu first. 
• Select "Scoped views" next to your connection. 
• Click "Add" in the top-right corner
• Provide a name for your scoped view 
• Upload a CSV file by clicking "Upload CSV file" or dragging it to the designated box. 
• Finally, click "Create" to complete the process.

To learn how to update & validate a scoped view, go there. 

Verify the Connection

Ensure that the connection has been properly established before you continue by examining the connection tree.

In the Google Workspace Migrate platform, access the Connections section. If necessary, click on the Menu first. You have two options to view the connection details:

• To view the complete scope of the connection, hover over your connection, click on "More," and then select "Tree view."
• For a limited or scoped view, hover over your connection, choose "Scoped views," and then select the specific scoped view you want. After that, click on "More" and choose "Tree view."

Please keep in mind that using a scoped view might restrict access to certain data. If you don't see some of the expected data, it could be because of your scoped view configuration.

Step 2: Scan

Create Run a Scan

For the next step, you need to perform a comprehensive scan of all data for migration. 

The scan evaluates the amount and type of source data and identifies issues with the data. It helps with workload assessment during the bridge phase. Later, you need to organize data into phases and conduct phase-wise rescans. The initial scan covers the entire dataset.

Create a Scan

• Click on "New" and then select "Scan."
• Provide a name for the scan.
• Choose your source connection.
• Select "Full scan" under Scan scope.
• (Optional) For advanced scan settings, click "More options," and proceed to step 2 below.
• (Optional) To select specific reports, check or uncheck the boxes next to the desired report types under Report types.
• By default, all reports are generated. For more information on each report and additional specifications, refer to "Understand scan reports."
• Click on "Create" to initiate the scan.

Advanced Scan Settings (Optional) 

• Under Crawl rules, choose one of the following options:

• Domain discovery: Crawls content owned by the user and any shared drives they can access.
• User Drive discovery: Crawls each user's Google Drive hierarchically, locating all objects within their folders. Proceed to step 5.

• Select the Crawl approach for the scan:

• All owned content: Discovers all objects owned by users within the domain.
• All content in My Drive: Discovers all objects within each user's Drive folders on the domain, including files and folders owned by external users.

• Under Generator rules, choose an option:

• Scan Calendar Resources: Scans all calendar resources on the domain.
• Scan Groups: Scans all Groups on the domain.

Note: To ensure correct object totals in the reports, one or both options must be checked.

• Click on "Create" to initiate the scan configuration.

Run a Scan

• In the Google Workspace Migrate platform, access the Scans section. If necessary, click on the Menu first. 
• Then, select the scan you wish to execute and click on the "Run" button.

Delete a Scan

Scans offer valuable data for bridges, so it's recommended to delete a scan only after completing the data migration process.

To delete a scan, follow these steps in the Google Workspace Migrate platform:

• Access the Scans section. If necessary, click on the Menu first.
• Find the scan you wish to delete.
• Click on "More," then select "Delete," and confirm the action by clicking "Delete" again.

Analyze Your Scan

After a scan is finished, it will display "Completed" status. You can then access the scan summary and download the generated reports. Utilize the information from the scan summary and reports to:

• Identify any notable errors or issues encountered during the scan.
• Understand the volume of data in the source domain and its organizational structure.
• Determine the most suitable approach for migrating the data effectively.

View the Summary & Reports

The scan summary organizes data into categories like users, source types, and errors. You can group the summary based on one or multiple categories. By clicking through the log entries, you'll get detailed information.

This summary helps you pinpoint potential bottlenecks among users and source types in the source domain. For instance, if you notice a high count of a specific error, clicking on it will reveal the details and a list of affected users. You can then group by source type to identify where the error occurred. It's a handy way to analyze and address any issues during the scanning process.

To access the scan summary, follow these steps in the Google Workspace Migrate platform:

• Go to the Scans section. If necessary, click on the Menu first.
• Select the scan you wish to view, and then click on "Logs," followed by "Scan summary."
• If you want to change how the data is grouped, click the Down arrow and choose one of the options:

• Group by identity (default): View the data by user or identity.
• Group by source type: View the data by item type.
• Group by error code: View the data by error code.

• For additional information, you can click on "Details." This will provide more insights into the scan results.

To download the reports, follow these steps:

• Access the Scans section. If necessary, click on the Menu first.
• Select the scan you wish to view, then click on "Logs," and choose "Reports."
• Check the box next to each report you want to download.
• Click on "Download."

The reports will be downloaded as a zip file onto your computer.

Analyze Scan

Before proceeding with the migration, analyze the scan summary and reports to gain insights into your data:

• Troubleshoot errors: If significant errors are reported, address and resolve them before moving forward. Ensure you conduct a rescan of the data after troubleshooting.
• Understand the source data: Analyze the scan results to understand how your source data is structured. Decide whether you want to replicate the same data structure in your new Google Workspace domain or if modifications are necessary.
• Identify data-heavy users: Utilize the object totals report to identify users with a substantial amount of data ownership and permissions. Consider organizing these data-heavy users into different migration phases to distribute the workload effectively.

If you make substantial changes to your project, it is advisable to perform a rescan of the data before proceeding with the migration process. This will ensure that you have up-to-date information to guide your migration decisions.

Step 3. Create a Google Workspace Target Connection

Create a Service Account

No need to create a new service account; you can utilize the service account you set up earlier. 

If you still want to create a new one, follow the below steps. 

You can use the service account that you set up earlier. But, if you want to create a new one, follow the below steps.

• In Google Cloud, access IAM & Admin, and then Service Accounts. You may need to click on the Menu first.
• Click on "Create Service Account."
• Enter a name for the service account. The ID (for the service account) will be generated automatically.
• (Optional) If desired, add a description to the service account.
• Click "Create and Continue."
• For Google Workspace Migrate, service account and user permissions are not required, so click "Done" to skip these steps.
• Select the email address of the account (service account) you just created.
• Click on "Keys," then "Add Key," and choose "Create new key."
• Ensure the key type is set to JSON, and then click "Create."
• You will receive a message confirming that the service account JSON key file has been created and downloaded to your computer. Remember the name of this file as you'll need it later.
• Click "Close."

Authorize the Service Account

• Sign in to your Google Admin console using an account with super administrator privileges (not your current account rajnishdas16@gmail.com).
• In the Admin console, click on "Menu," then select "Security," followed by "Access and data control," "API controls," and finally "Manage Domain Wide Delegation."
• Click on "Add new" and provide the service account client ID.
• The client ID can be found in the JSON file you downloaded during the service account creation or in Google Cloud (navigate to IAM & Admin, then Service accounts, and find the name of your service account).
• Copy and paste the following scopes for OAuth scopes

https://apps-apis.google.com/a/feeds/emailsettings/2.0/,

https://www.googleapis.com/auth/contacts,

https://www.googleapis.com/auth/admin.directory.group,

https://www.googleapis.com/auth/admin.directory.group.member,

https://www.googleapis.com/auth/admin.directory.orgunit,

https://www.googleapis.com/auth/admin.directory.resource.calendar,

https://www.googleapis.com/auth/admin.directory.user,

https://www.googleapis.com/auth/apps.groups.migration,

https://www.googleapis.com/auth/apps.groups.settings,

https://www.googleapis.com/auth/calendar,

https://www.googleapis.com/auth/drive,

https://www.googleapis.com/auth/drive.appdata,

https://www.googleapis.com/auth/drive.file,

https://www.googleapis.com/auth/gmail.modify,

https://www.googleapis.com/auth/migrate.deployment.interop,

https://www.googleapis.com/auth/tasks,

https://www.googleapis.com/auth/userinfo.email,

https://sites.google.com/feeds,

https://www.googleapis.com/auth/gmail.settings.basic,

https://www.googleapis.com/auth/gmail.settings.sharing,

https://www.googleapis.com/auth/admin.directory.customer.readonly,

https://www.googleapis.com/auth/admin.directory.rolemanagement.readonly

Next, click on authorize. 

• To ensure all scopes are listed, point to the new client ID and click "View details." If any scope is missing, click "Edit," enter the missing scope, and then click "Authorize." It's important to note that you cannot edit the client ID itself. 
• Once you've made the necessary adjustments, go back to Google Cloud and click "Save" to save the changes.

Troubleshoot

If you encounter the error "Client is not authorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested," follow these troubleshooting steps:

• Repeat step 2, which involves authorizing the service account as mentioned earlier.
• Double-check that you are using the correct client ID. Open the JSON file in a text editor to confirm that the client IDs match.
• If the error persists, you may need to wait for the authorization process to complete. Typically, it takes a few minutes, but in some cases, it could take up to 24 hours.

Setup the Target Google Workspace Connection

• In the Google Workspace Migrate platform, click on "New," then select "Connection."
• Provide a name for the connection.
• Choose "Google Workspace" as the connection type.
• Enter the email address of a super administrator for your target Google Workspace domain under "Admin email."
• Click on "Add new account" under "Account."
• For the service certificate, click on "Upload file," locate the downloaded JSON private key, and click "Open." Alternatively, you can drag the JSON file to the designated box.
• Finally, click on "Create" to complete the process.

Step 4. Set Up Your Migration

Plan Your Migration Phases

Create your migration plan based on the scan information including the timeline and user data migration approach. 

Many enterprises opt for phased migrations, serving two purposes: aligning with your timeline and managing data in manageable portions. 

Phases can prioritize core IT users and early adopters or break down large data volumes into manageable pieces. The number of phases depends on data size, complexity, user count, and the types of data being migrated.

How to Conduct the Migration

Consider the timeline for your transition to Google Workspace and the go-live date. Prioritize core IT users and early adopters as the initial groups to transition. Plan the phases to have key users first, followed by early adopters, and then other users. 

For the remaining users, you may need to organize them into phases, such as based on geography or teams, for a smoother transition process.

What Data to Migrate

• Types of data to migrate: Contacts, calendar events, and emails.
• Identify the largest data source and data-heavy users from scan summary and reports.
• Consider spreading data or users across multiple phases for better migration performance.
• Determine essential data needed for go-live date.
• Decide if non-essential data (e.g., archived files) can be migrated later or not at all.
• Use phases strategically to ensure essential data availability for users on the go-live date.
• Consider delta migrations for new content added before the go-live date.

Where Do You Want Your Data on the New Account?

• How is your data currently structured in the source account? Are you planning to keep the same data organization in the target account during migration? 
• Or do you intend to reorganize the data as part of the migration process?

How to Group the Data into Phases?

Once you've confirmed your migration phases, organize the data into these phases using a scoped view. Before running a migration for each phase, scan the data and ensure that the scoped view accurately defines the intended data for that specific phase. The scan will also identify any significant errors.

Please note: once you've established your migration phases, avoid moving users between phases during the migration process to prevent data duplication.

How to Map Data 

• Create a mapping to define the content to be migrated in each phase, verified by Google Workspace Migrate.
• Set up an identity mapping to link identities (e.g., users or calendar resources) from the source domain to the target domain.
• Prepare a settings template to determine what types of content will be migrated and how data will appear after migration. This template will be used in a later step of the migration process.

Create & Manage a Mapping

Before starting the migration process, make sure to review the Scoped view and mapping headers, and also familiarize yourself with the watchpoints and best practices for mapping shared drives.

Create a CSV file to Add Multiple Entries

• Use a CSV file to add multiple entries.
• The CSV file contains two scoped views: one for the source data and the other for its destination on the new domain.
• Precede source-connection column headers with "Source" and target-connection column headers with "Target."
• Format each entry based on the syntax requirements of the connection type.
• All entries in the mapping are case-sensitive.
• Ensure the CSV file's character encoding is set to UTF-8.

Do the Mapping

Using CSV file:

• Click on "New" and then select "Mapping" in the Google Workspace Migrate platform.
• Enter a name for the mapping.
• From the Source connection list, choose the source connection.
• From the Target connection list, select the target connection.
• Click on "Upload CSV file" or drag a file to the designated box.
• Finally, click on "Create."

Note: If you point to the mapping and click on "Entries," you might see "Imported entry requires validation" under Source validity and Target validity. You'll validate the entries in step 2.

Manually do the mapping:

• In the Google Workspace Migrate platform, click on "New" and select "Mapping."
• Provide a name for the mapping.
• Choose the source connection from the Source connection list.
• Select the target connection from the Target connection list.
• Click "Create."
• Point to the mapping name and click on "Entries."
• Click "Add" and then choose "Add entries manually."
• Use the Down arrow to expand your selection to the next level of hierarchy.
• Check the box(es) next to the source data you want to migrate.
• Click "Next."
• Expand your selection to the next level of hierarchy using the Down arrow.
• Check the box(es) next to the target location and click "Next."
• To migrate folder contents without the folder itself, enable "Map content only" under Map content only. (Optional) 
• Click "Add."
• To map data to a folder that doesn't exist in Drive, click "Custom," then "Add," enter the folder path, and click "Done." (Optional) 
• (Optional) Repeat the steps to add new entries to the mapping.

Validate a Mapping Entry

During the mapping validation process in Google Workspace Migrate, the tool verifies the existence of the source and target locations. However, it doesn't evaluate the logical correctness or functionality of the mapping for your data.

To validate the mapping

• Point to the mapping and click on "Entries." 
• Check all the entries and click "Validate." 
• Valid entries will have a green check, invalid ones will have a red cross with an associated error message, and expired entries will have a gray clock. 

Note that validation may take several minutes to complete.

Create & Manage an Identity Mapping

An identity mapping helps transfer identities, like users, calendar resources, and groups, from your source domain to your Google Workspace domain. This ensures a seamless transfer of permissions and other metadata, such as sharing rights, file creation and changes, and username references. 

In short, it ensures a smooth transition of user and group permissions in the migration process.

Create a CSV File to Add multiple Entries

• In the first column of the CSV file, enter the identity as it appears in the source environment. For groups, use their group name.
• In the second column, input the corresponding target domain identity. For groups, use the group's email address in Google Workspace.
• Ensure that the CSV file's character encoding is set to UTF-8 to avoid any encoding issues.

Tips for a successful identity mapping:

• Include all identities, even if not migrating all data at once, as they might be referenced in non-user specific data.
• Avoid mapping a source identity to multiple target identities to prevent issues, like breaking calendar events.
• For organization-wide sharing permissions, add an entry mapping the source domain to the target domain.
• If external event organizers are involved in calendar events, map their email address in the identity mapping.
• Check your settings template for more identity mapping options.

Image Credits

Create an Identity Mapping

• In the Google Workspace Migrate platform, click on "New" and then select "Other mapping."
• Enter a name for the mapping.
• Under Type, choose "Identities."
• Click on "Upload CSV file" or drag a file to the designated area.
• Finally, click on "Create."

Update an Identity Mapping

Use a CSV file to update an identity mapping:

• Go to "Mappings" in the platform.
• Under the "Other mappings" section, point to the mapping name and click on "Entries."
• Click on "Add."
• Upload the CSV file or drag it to the designated area.
• Click on "Import."

Manually Include Entries in an Identity Mapping:

• In the Google Workspace Migrate platform, click on "Mappings."
• Under the "Other mappings" section, point to the mapping name and click on "Entries."
• Click on "Add" and then select "Add entries manually."
• Enter the source and target values.
• To add more values, click on "Add" and enter the new values.
• After entering all the new values, click on "Add."

Modify Individual Entries in a Mapping:

• In the "Other mappings" section, locate the mapping name and click on "Entries."
• Point to the entry you want to update and click on "Edit."
• Make the necessary changes to the source or target value.
• Click on "Save" to save your modifications.

Next step is optional; it’s setting up a calendar resource migration. To learn more, go here. 

Set Up or Select a Settings Template

A settings template helps define content migration and appearance after the process. Use the default template or customize one. Avoid modifying the template during a bridge to prevent inconsistent migration outcomes.

Details About Settings Template

A default settings template offers common migration options for your data source. Choose the template that aligns with your connection and migration target, such as migrating My Drive to shared drives. 

Note that in a single bridge, you can migrate either to users' My Drive or shared drives, but not both. Alternatively, create a custom template by modifying a default one to suit your specific data migration preferences and appearance in the target domain.

Select/Customize a Default Settings Template

• In the Google Workspace Migrate platform, access "Settings templates" (you might need to click on "Menu" first).
• Point to the settings template and click on "Template."
• Review the default settings template and choose:

• If you don't modify any settings, click "Cancel."
• If you make changes to the settings, click "Create new template," enter a name, and click "Create."

How to Delete a Custom Settings Template

You cannot delete a default template or one linked to an existing bridge.

To delete a custom template:

• Click on "Settings templates" (you might need to click on "Menu" first).
• Under "Custom," check the box next to the template you want to delete.
• Click on "Delete" and then confirm the action by clicking "Delete."

Step 5. Run a Migration

Bridges are used to migrate data from a source to Google Workspace. They involve specifying connections, templates, mappings, and lists.

So, begin this process by creating a bridge.

Create & Run a Bridge

Create a Bridge

• In the Google Workspace Migrate platform, click on "New" and then select "Bridge."
• Provide a name for the bridge.
• Fill in the required details:

• Source connection
• Target connection (choose the service account used to connect to Google Workspace)
• Settings template (default or customized)
• Mapping
• Identity mapping

• (Optional) To include a sharding users list, click on "More options" and choose the mapping or list.
• Finally, click on "Create" to create the bridge.

Run a Bridge

• In the Google Workspace Migrate platform, access "Bridges" (you might need to click on "Menu" first).
• (Optional) To modify the bridge, click on "Settings."
• Click on "Run" and then select "Run" again to execute the bridge migration.

View Progress of a Bridge

• In the Google Workspace Migrate platform, click on "Bridges" to view the bridge progress.
• Real-time statistics are available for the following types of transactions:

• Completed
• Warning
• Failed
• Skipped
• Crawled

• The "Data migrated" number in a bridge indicates the size of binary data moved, including:

• Email messages (including attachments)
• Files with their revisions
• Calendar attachments
• Contact photos.

Modify What You See in a Bridge

• In the Google Workspace Migrate platform, access "Bridges" (you might need to click on "Menu" first).
• Click on any available filters to modify what you see during a running or completed bridge.
• Complete the required fields for the selected filter, then click on "Apply."
• The filters available are for:

• State (migration state)
• Source type (type of source connection)
• Name (bridge name)
• Source connection name (name of the source connection)
• Target connection name (name of the target connection)
• Started (start date of the migration)
• Completed (completion date of the migration).

• (Optional) To remove a filter, click on "Remove" next to the specific filter, or click "Reset" to clear all filters.

You might see some failed transactions once you run the bridge. You can retry the failed transactions if you have resolved the issues that caused the failures (or the issue was temporary). 

Monitor the Migration Progress

Once the bridge is running, you can track your migration progress in the Google Workspace Migrate logs. You also have the option to filter the data for more detailed insights, like specific warnings or failures. Additionally, you can check the nodes to observe their activity levels.

Open & Monitor the Logs

• In the Google Workspace Migrate platform, access "Bridges" (you might need to click on "Menu" first).
• Point to the bridge and click on "Logs," then choose a specific log.
• (Optional) If you want filtered log results, check "Filter Migration summary log results" and "Filter other log results" sections on the page.
• (Optional) To download the log and bridge settings CSV file (containing details about the settings template), click on "Download" and select "Download logs and details."

Download the Bridge Reports

• In the Google Workspace Migrate platform, access "Bridges" (you might need to click on "Menu" first).
• Point to the bridge, click on "More," and select "Download Bridge Reports."
• The zip file will contain migration summary, transaction, execution, and partition logs for the latest bridge execution.
• You can also review the bridge settings CSV file in the download.
• For more information about the logs, check out the "Types of logs" section below on the page.

Different Types of Logs

• Migration summary log
• Partition log
• Execution log
• Transaction log
• Execution history log
• Filter logs

Migration log summary:

In the migration summary log, you get an overview of the content migrated, including total transactions. The data is grouped into categories like identity, source type, and error code, which helps identify potential bottlenecks. For instance, an unexpectedly high error count can be spotted.

Here’s the process to view migration summary data:

• In the Google Workspace Migrate platform, go to "Bridges."
• Point to your bridge and click on "Logs," then select "Migration Summary."
• Click the downward arrow to choose a category for "Group by."
• Point to a record, click "More," and select "View logs" to see detailed transaction records, including stack traces and error codes.

Partition log:

Use the Partition log to see the created and executed partitions for the bridge.

To filter the log by partition states:

• Open the partition log.
• Click on "State" and choose the ones you want to view (e.g., Ready, Processing, Completed).
• Note that for detailed information about migrated data and its success, refer to the transaction and execution logs.

Execution log:

The Execution log shows operational errors and steps taken in the bridge. It lists the status of each component in the migration process. Bridge's failed transactions include errors from both the Execution and Transaction logs.

To view execution log entries for a partition:

• Open the execution log.
• Point to a row in the log, click on "..." and then select "Partition transaction log."
• (Note: This option is available only when the execution log entry is associated with a partition.)

Transaction log:

Use the transaction log to review details of all processed objects in the bridge. It might take time to load. Bridge's failed transactions include errors from both the transaction and execution logs. To see detailed data, point to a transaction and click "Details." To download the log, click "Download."

To view the transaction log in real time, follow the below steps:

• Open the transaction log.
• Click "Reset" to display all transactions.
• Choose an option (like State or Error) to filter the transactions.

To view all transaction log entries for a partition:

• Open the transaction log.
• Point to a row in the log, click on the "..." (three dots) icon, and select "Partition transaction log."

Execution history log:

To access the Execution history log and view all the logs for each bridge, including full and delta migrations, follow these steps:

• Point to the record of the bridge in the Execution history log.
• Click on the three dots ("..." ) icon and choose the specific log you want to view.

Filter logs:

• Open the migration summary log.
• Click the Down arrow next to "Refresh" and choose how to group the log (by identity, source type, or error code).
• Apply filters and boolean search operators to refine the log data.
• If grouped by identity, filter by specific identities, completed, warnings, queued, failed, or skipped transactions per identity.
• If grouped by source type, filter by type of source data, completed, warnings, queued, failed, or skipped transactions per source type.
• If grouped by error code, filter by error code and count per error code.
• To download a filtered report, apply the filter and click "Download reports."
• To reset a filter, click "Remove" next to the filter. To reset all filters, click "Reset."

To learn about filter other log results, read this. 

Monitor Node Status:

To view nodes, URLs, and status, go to Servers in the Google Workspace Migrate platform.

Nodes may seem underused during a large migration due to factors like CPU, RAM, and scanned data per partition.

If a node becomes inoperable, its partition rejoins the queue, and another node completes the task. Do not decommission nodes during migration.

Prepare to Go Live

Before going live in your new Google Workspace account, perform a delta migration to transfer any recently added or modified content. This step ensures that all the latest data is migrated before completing the migration to Google Workspace.

Delta Migration

A delta migration is performed after the main migration, just before transitioning to Google Workspace. It identifies and migrates new or modified content efficiently, avoiding duplicates and reducing the load on target APIs. Unlike retrying failures, delta migrations include a step to retry failed transactions, making it unnecessary to do so separately.

What type of content is migrated in a delta?

• Non-Google content (.docx, .pdf, and so on)
• Google content (Google Docs, Sheets, Slides, and so on)

How to Run a Delta Bridge

Ensure you use the same bridge for data migration. 

• In the Google Workspace Migrate platform, click Bridges
• On the bridge you've already run or partially run, click Run and then select Run delta.

Clean Up Steps

• After completing the migration, uninstall Google Workspace Migrate and its components.
• Decide on the retention period for migration data in MySQL and CouchDB based on organizational policies or regulations.
• Uninstall the software, databases (MySQL and CouchDB), and all nodes.
• Securely delete all data from the Microsoft Windows instances where the software was running.
• Decommission the Windows instances.
• Remember that deleting migration data permanently removes it, and it cannot be recovered.

Frequently Asked Questions

What happens to my user settings, domain aliases, email preferences, and other Google Workspace settings when I transfer my account?

When you migrate Google Workspace to another Workspace account, user settings, domain aliases, email preferences, and other Google Workspace settings will need to be manually reconfigured in your new account. The Google Workspace migration tool focuses primarily on transferring data like emails, contacts, calendar events, and documents. Settings and configurations like domain aliases and email preferences are not automatically transferred and must be set up again in the new Google Workspace account to ensure continuity of service and customization.

If I transfer my account, do I have to edit my DNS settings (MX, SPF, service URLs)?

Yes, when you transfer Google Workspace to another account, you will need to edit your DNS settings, including MX records, SPF records, and service URLs. This is essential to ensure that your email and other services work correctly with the new Google Workspace account. Updating these settings will help direct your email traffic to the new account and maintain your domain's security and email deliverability.

How do I add and manage users?

To add and manage users in Google Workspace after you migrate your account, follow these steps:

1. Log in to your Google Workspace admin console.
2. Navigate to Users.
3. Click on Add a user to create a new user account or select an existing user to manage.
4. Fill in the user details or modify existing user settings according to your requirements.
5. Click Save to apply the changes.

This process allows you to efficiently manage user accounts, including adding new users or editing settings for existing ones, ensuring everyone in your organization has access to the necessary services and data.

I transferred my account to Google Workspace. Why do I get a message that my account has been suspended?

Receiving a message that your account has been suspended after transferring to Google Workspace could be due to several reasons such as billing issues, terms of service violations, or problems during the migration process. It's essential to check the specific reason mentioned in the suspension notice. You can also contact Google Workspace support for clarity and guidance on resolving the issue. Ensuring that all billing information is updated and that you comply with Google's terms of service can help prevent such issues from occurring during or after the migration process.