This article will guide you through the steps for migrating one Google Shared Drives instance to a different Google Shared Drives instance. This migration scenario uses the Shared Document License type. There are a number of additional tools and resources that will also be helpful for this process. These are linked throughout the migration guide.
First migration?
If this is your first time performing a migration, we have created a Migration Planning & Strategy Guide to walk you through planning, set-up, and general migration best practices.
MigrationWiz
MigrationWiz is a migration tool, not a syncing tool. If changes are made at the source after migration, they will not sync to the destination, nor will changes made at the destination sync to the source. We do not have “live” monitoring of changes (as with a sync agent) and we cannot handle scenarios such as conflict resolution without user interaction.
MigrationWiz supports the capability to share migration projects across a Workgroup. When the Project Sharing feature is turned on, all Agents besides those who are Inactive can view all migrations projects.
We are not able to support migrations with two-factor or multifactor authentication.
The maximum file size for migration through MigrationWiz varies by migration type and environment, but may never exceed 60GB.
Which Items Are and Are Not Migrated
Some item types are not migrated. We are constantly working to create a better migration experience for you, so these items may change.
- Files
- Folders
- Permissions
- Versions (up to 25)
- Metadata
- File/Folder name
- Modified date time
- Created date time
- Description
- Shortcuts are migrated if the target file exists within same shared drive and if the target file has been successfully migrated to destination.
- Shortcuts are to be migrated as a subsequent migration step, after migrating all relevant documents & permissions.
- Shared Drive settings are migrated with advanced option MigrateSharedDriveSettings=1
- Google Sites, Maps, Forms, Drawings, Jam board and Apps Script files are not migrated.
- For some Google proprietary format files (e.g. Docs, Sheets, Slides), Google allows you provide a custom name for a version of the file. Such version names are not migrated.
- Minor revisions available for Google proprietary format files are not migrated.
- Shortcuts will not be migrated if target file doesn’t exist at the destination or if the target file is not located within same shared drive.
- Metadata limitations:
- Creator & Modified by metadata are not migrated. Impersonated user for destination will be reflected as creator & last modifier
- Timestamps for the versions of google proprietary files are not migrated
- Link sharing / Tenant level sharing permissions are not migrated
-
MigrationWiz project line item setup currently doesn’t support shared drives name with emojis (source or destination). Such shared drives, even if they are imported through our Autodiscover feature will not reflect the emojis on line item. Such line items will fail migration in verify credentials.
-
We recommend to rename such shared drives (removing emojis) before setting up line item in MigrationWiz project.
-
Prepare the Source Environment
Set up the Google service account and API scopes for Source
Create a Google Project
- Go to the Google Cloud Platform (GCP) Console and sign in as a super administrator (Source tenant). Choose one of the options below:
- If you haven't used the Google Cloud Platform Console before, agree to the Terms of Service and click Create Project.
- If you have used Google Cloud Platform Console before, at the top of the screen next to your most recent project name, click Down to open your projects list. Then, click New Project.
- Enter a project name and click Create.
If you are not able to create a project here, it may be that the ability to create projects has been disabled for your tenant. To check this, navigate to the Google Admin Center and click on Apps > Additional Google Services and select the Google Cloud Platform. Once there, you should see a setting that can be toggled in order to allow users to create projects.
Enable APIs for the Service Account
- From the Google Cloud Platform Console, click Menu > APIs & Services > Library.
- Enable the following APIs by selecting the specific API and clicking Enable.
Repeat for each API listed below: - Google Drive API
- Admin SDK
Create the Customer Tenant Service Account
- From the Google Cloud Platform Console, click Menu.
- Click IAM & Admin.
- Click Service accounts.
- Click Create Service Account and enter a name.
- Assign the role of Owner to the new Service Account by selecting Owner from the Role dropdown menu.
- Click Done to complete the service account creation.
- On ‘Service accounts' page, click the vertical ellipsis under 'Actions’ column for the service account created above.
- Click Create key.
- Make sure that JSON is selected and click Create.
- Make sure that you download the key as a JSON file and make a note of the name and location of the file. This JSON file will be used when setting up the source endpoint in the migration project.
- The JSON file must contain information in the following fields: “type”, “private key”, and “client email”. If these mandatory fields are empty, the file upload during the endpoint creation process will fail.
Setting the Scopes for the migration
- From the Google Cloud Platform Console, click Menu.
- Click IAM & Admin.
- Click Service accounts.
- Find the service account that was set up previously.
- Find the Unique ID field for that service account and copy the ID number. This is the Client ID number that will be used in a later step.
- This field often needs to be added to the view. Click on the Column display options button and add a checkmark to Unique ID, then click OK.
- This Client ID should be considered as confidential as Administrator account passwords and handled securely.
- Log in to the Source G Suite admin page at admin.google.com
- Click on Security > Access and Data Controls > API Controls
- On the API Controls page, locate section Domain-wide delegation.
- Click Manage domain-wide delegation.
- Click Add new.
- In the Client Name field, enter the Service account Unique ID.
- For OAuth scopes, enter the scopes listed below:
- https://www.googleapis.com/auth/drive
- https://www.googleapis.com/auth/admin.directory.group.readonly
- https://www.googleapis.com/auth/admin.directory.user.readonly
- https://www.googleapis.com/auth/admin.directory.domain.readonly
- Click Authorize.
Source Shared Drive membership permission requirements:
- Ensure that the source Shared Drives have an active member on the source tenant with a permission role above Viewer/Commenter.
- For best results, we recommend at least one active member of the source tenant should be member of the Shared Drive with a permission role of Manager.
Prepare Destination Environment
Set up the Google service account and API scopes for Destination
Create a Google Project
- Go to the Google Cloud Platform (GCP) Console and sign in as a super administrator (Destination tenant). Choose one of the options below:
- If you haven't used the Google Cloud Platform Console before, agree to the Terms of Service and click Create Project.
- If you have used Google Cloud Platform Console before, at the top of the screen next to your most recent project name, click Down to open your projects list. Then, click New Project.
- Enter a project name and click Create.
If you are not able to create a project here, it may be that the ability to create projects has been disabled for your tenant. To check this, navigate to the Google Admin Center and click on Apps > Additional Google Services and select the Google Cloud Platform. Once there, you should see a setting that can be toggled in order to allow users to create projects.
Enable APIs for the Service Account
- From the Google Cloud Platform Console, click Menu > APIs & Services > Library.
- Enable the following APIs by selecting the specific API and clicking Enable.
Repeat for each API listed below: - Google Drive API
- Admin SDK
Create the Customer Tenant Service Account
- From the Google Cloud Platform Console, click Menu.
- Click IAM & Admin.
- Click Service accounts.
- Click Create Service Account and enter a name.
- Assign the role of Owner to the new Service Account by selecting Owner from the Role dropdown menu.
- Click Done to complete the service account creation.
- On ‘Service accounts' page, click the vertical ellipsis under 'Actions’ column for the service account created above.
- Click Create key.
- Make sure that JSON is selected and click Create.
- Make sure that you download the key as a JSON file and make a note of the name and location of the file. This JSON file will be used when setting up the destination endpoint in the migration project.
- The JSON file must contain information in the following fields: “type”, “private key”, and “client email”. If these mandatory fields are empty, the file upload during the endpoint creation process will fail.
Setting the Scopes for the migration
- From the Google Cloud Platform Console, click Menu.
- Click IAM & Admin.
- Click Service accounts.
- Find the service account that was set up in Step 3.
- Find the Unique ID field for that service account and copy the ID number. This is the Client ID number that will be used in a later step.
- This field often needs to be added to the view. Click on the Column display options button and add a checkmark to Unique ID, then click OK.
- This Client ID should be considered as confidential as Administrator account passwords and handled securely.
- Log in to the Destination G Suite admin page at admin.google.com
- Click on Security > Access and Data Controls > API Controls
- On the API Controls page, locate section Domain-wide delegation.
- Click Manage domain-wide delegation.
- Click Add new.
- In the Client Name field, enter the Service account Unique ID.
- For OAuth scopes, enter the scopes listed below:
- https://www.googleapis.com/auth/drive
- https://www.googleapis.com/auth/admin.directory.group.readonly
- https://www.googleapis.com/auth/admin.directory.user.readonly
- https://www.googleapis.com/auth/admin.directory.domain.readonly
- Click Authorize.
Destination Shared Drive membership permission requirements:
- MigrationWiz expects destination shared drive to be available with at least 1 active member from destination tenant with Manager role. Without this migration will not succeed.
- If your destination doesn’t have an active member with manager role, you may consider using advanced option SetDestinationAdminAsSharedDriveManager=1.
- When this advanced option is used, MigrationWiz will use the admin ID from the destination endpoint and set it as manager member for destination shared drive.
MigrationWiz Steps
Licenses
This migration scenario uses the Shared Document License type.
- One license per line item in project (i.e. Google Shared Drive to Google Shared Drive migration)
- Data limit: 50 GB per license
- Sign in to your BitTitan account.
- In the top navigation bar, click Purchase.
- Click the Select button and choose the license type you need.
- Enter the number of licenses you want to purchase. Click Buy Now.
- Enter a Billing address if applicable.
- Click Next.
- Review the Order Summary and enter a payment method.
- Click Place Your Order.
Licenses are released once payment has been received.
- If you purchase via credit card, licenses will be available immediately upon payment.
- If you purchase via wire transfer (100+ licenses), licenses will be available once payment has been received and accepted.
Set up a Document Migration project
- Sign in to your MigrationWiz account.
- Click Go To My Projects.
- Click Create Project.
- Click on Document Project to create new project.
- Click Next Step.
- Enter a project name and select a Customer.
- Click Next Step.
- Select a Source Endpoint from the endpoint dropdown menu.
- If you have not already added the source endpoint, you will need to click New to create the source endpoint. Fill in the fields below to set up a new source endpoint:
- Name: Type any name you want for the endpoint.
- Endpoint Type: Select “Google Shared Drives” from the source endpoint type drop-down list.
- Service account credentials: Select the JSON file created for the source service account.
- Super Administrator Username: Enter the email for the super administrator for source tenant.
- Click Add.
- Click Next Step.
- Select a destination endpoint from the endpoint dropdown menu.
- If you have not already added the destination endpoint, you will need to click New to create the destination endpoint. Fill in the fields below to set up the destination endpoint:
- Name: Type any name you want for the endpoint.
- Endpoint Type: Select “Google Shared Drives” from the destination endpoint type drop-down list.
- Service account credentials: Select the JSON file created for the destination service account.
- Super Administrator Username: Enter the email for the super administrator for destination tenant.
- Click Add.
- Click Save and Go to Summary.
- Click Save Project.
Add Line Items
There are three options for adding items. Choose which one you will use, then follow the steps below.
Autodiscover
The Autodiscover option can be used to discover Shared Drives available from the Source environment. Once discovered, these can be imported to your project as line items. Associated Source Shared Drive IDs will also be linked to the line item.
The endpoint Administrator account on the source needs to be assigned the appropriate GSuite license in order for MigrationWiz to access Google Drive or Google Shared Drives for the Auto Discovery process.
Naming line items
Line items imported using Autodiscover will set the destination shared drive name with the same value as that of source shared drive name. Make sure to edit the line items, destination shared drive names and shared drive ID with appropriate values.
Bulk Add
This option allows you to add multiple line items at once by copying and pasting from a spreadsheet or by importing a CSV file.
Quick Add
This option allows you to add items one at a time. For each line item, you have to enter Source Shared Drive name and drive ID for both, source & destination.
Note:
- Drive ID field is optional. However, the drive ID must be entered correctly if the source or destination has duplicate shared drive name.
- Google allows you to create multiple shared drives with same name. In such case, the Drive ID helps us uniquely identify the source and/or destination shared drives set in the line item.
- Shared Drive ID can be captured from drive URL.
- Example of drive url: https://drive.google.com/drive/folders/0BNYowieKW7VaPx4MNB
In the above example, drive id is 0BNYowieKW7VaPx4MNB
Set the Project Advanced Options
The following support and advanced options may be useful for your migration.
Advanced options under Support tab
-
ImportFailedGoogleFilesInMSOfficeFormat=1
-
This option is to handle the failed cases of Google file formatted documents which cannot be imported to the destination in a Google Shared Drive to Google Shared Drive project.
-
Google proprietary files which cannot be imported in Google format will be converted to the respective Microsoft Office format:
-
Google Spreadsheets to Microsoft Excel
-
Google Documents to Microsoft Word document
-
Google Presentations to Microsoft PowerPoint
-
-
Files which are successfully migrated with this option cannot be opened using Google Sheets, Docs, or Slides web apps. They must be downloaded at the destination and opened using the appropriate Microsoft Office product.
-
- InitializationTimeout=8 This increases the initialization timeout window to eight hours. This value is in hours, up to a maximum of 100 hours. Values above 100 are in milliseconds. This is useful for large migrations. For example:
- InitializationTimeout=2 will increase the timeout to 2 hours.
- InitializationTimeout=8 will increase the timeout to 8 hours.
- InitializationTimeout=14400000 will increase the timeout to 4 hours.
- InitializationTimeout=21600000 will increase the timeout to 6 hours.
- UserMapping="abc_user1@source-domain.com->pqr_user5@destination-domain.com"
- UserMapping="groupS1@source-domain2.com->groupD5@destination-domain3.com"
- UserMapping="@source-domain2.com->@destination-domain3.com"
- Here are some more examples of how UserMapping can be used in this project:
- UserMapping advanced option should be used when you want to customize the permission mapping
- Please note that the destination users/groups (e.g. pqr_user5@destination-domain) must be active for destination before migration.
Permission Mapping Behavior
- By default MigrationWiz will map permission for users/groups by changing source domain to destination domain.
- Domain from the admin emails, set by you for source and destination endpoints respectively, will be used for default permission mapping by MigrationWiz.
- Permissions for users/groups with other domains (even if they belong to source tenant) are considered external by default. External permissions are not migrated by default.
- If your source has multiple domains then we strongly recommend use of UserMapping advanced option to set desired mapping for permissions
- MigrateExternalUserPermissions=1
- Use this advanced option to migrate external user/group permissions from source.
- External permissions are not migrated by default.
- MigrateSharedDriveSettings=1
-
- When this advanced option is used, source shared drive settings will be migrated and applied to respective destination shared drive.
- Before migration, please ensure that your destination tenant doesn’t restrict these shared drive setting.
- SetDestinationAdminAsSharedDriveManager=1
- For successful migration, your destination shared drive must have an active member from destination tenant with Manager role. If your destination drives do not have any valid member with manager role, then you choose to use this advanced option as an alternative.
- When this advanced option is used, MigrationWiz will use the admin id from destination endpoint and set it as manager member for destination shared drive.
Advanced options under Source/Destination tab
- As per your project’s requirements, set the number of versions to be migrated.
- This setting is applied for entire project
- Minimum value for number of versions to migrate is 1
- Maximum value for number of versions to migrate is 25
- Default value for the number of versions to migrate is set as 1.
Advanced options under Licensing tab
- Each line item in the project requires an independent license. Once the transfer limit has been reached, another license will be required to continue the migration.
- By default, MigrationWiz will only consume a single license per item. This means that when you reach the transfer limit, the migration will stop, and you will have to resubmit your migration with an additional license.
- To allow line items in a project to consume more than one license, please update the maximum number of licenses that can be consumed per line item and save.
Note:
- Once this advanced option is set, all line items in the migration project will have permission to consume more than a single license.
- This number is applied per item in a single project. This means that if you submit two items for migration, both of the submitted items will be allowed to automatically use the additional license when transfer limit is reached.
- If you increase the licensing count number to be, for example, 2, and you submit a line item migration which has less than 50GB, you will only consume one (1) license, regardless of the fact that the licensing count has been set higher.
Verify Credentials
You may verify the credentials of the endpoint and any items in the MigrationWiz project without migrating data or consuming any licenses.
- Open the project containing the line items you wish to validate.
- Select the items you wish to validate.
- Click on the Start button in your dashboard.
- Select Verify Credentials from the drop-down list.
- Once complete, the results of the verification will be shown in the Status section.
Perform a Full Migration
To initiate the migration of document libraries:
- Open the project containing the items you wish to migrate.
- Select the line items to migrate.
- Click on the Start button in your dashboard.
- Select Full Migration from the drop-down list.
- Ensure that the Documents and Permissions checkboxes are selected.
- Click Start Migration.
- Once complete, the results of the migration will be shown in the Status section.
- Migrating Shortcuts:
- To migrate shortcuts to the destination, run another pass following the full migration steps above, this time with ‘Step 2’ selected.
- Step 2 should be run only after all relevant documents and permissions have been migrated.
- Please note Step 2 is not mandatory. This is should be run only if you wish to migrate shortcuts to the destination.
Known Behavior & Limitations
Shared Drive memberships requirements
Shared Drives will not be migrated if the source shared Drive doesn’t have at least one active member from source tenant.
Migration of restricted files
Google Shared Drive allows settings which can restrict downloading files for users with Viewer and Commenter permissions. In order for such files to be migrated, the shared drive must have an active member of the source tenant with permissions higher than Viewer/Commenter.
Permission role mapping
Source |
Destination |
Manager |
Manager |
Content Manager |
Content Manager |
Contributor |
Contributor |
Editor |
Editor |
Commenter |
Commenter |
Viewer |
Viewer |
Folders names with Emoji characters
Folders with emojis in name are migrated to destination, however the emojis will not be retained at the destination. These line items will also fail to verify credentials. We recommend renaming shared drives without their emojis.
Direct permissions & Shared Drive membership permissions
MigrationWiz will migrate the Shared Drive membership permissions to destination shared drive. These shared drive membership permissions are inherited by all files & folders within shared drive at destination.
Direct permissions associated with files & folders are also migrated to destination.
Multi-pass behavior
- During the first migration pass/run, a file and its associated versions (depending on #versions set in advanced option) will be migrated to the destination. In subsequent passes, the destination files will be updated if the corresponding source file has a new version.
- Changes to source files will not migrate if the corresponding destination file has been modified after the initial pass.
- Permission changes such as downgrade or removal of access level for shared drive members are not migrated. However, new permissions or upgrade of access level for shared drive members are migrated.
Intermittent issue with modified dates for google proprietary files
We have seen an intermittent issue which may cause modified dates of Google proprietary files to not be updated when new versions are migrated in multi-pass scenarios. There is no fix for this issue at this time.
Drive membership not migrated with folder filtering
When folder filtering is used to migrate only specific folders from source shared drive to destination, Drive membership permissions are not migrated to destination.
Invalid Shortcuts when target files are updated
- After completing a full migration for documents/permissions and shortcuts, if any further changes to the source files are migrated by running another migration pass, then the destination files are overwritten and are updated with latest versions (where applicable).
- In such scenarios, the destination file ID gets updated and the previously migrated shortcuts (with reference to original target file ID) no longer remain valid.
- We recommend that you run shortcut migration only after completing all required migration runs for documents/permissions to avoid this issue.