Set up and run link remediation

Updated September 30, 2026 07:16

Link remediation repoints the links inside your migrated documents at the migrated copies. This article covers what to set up first, and how to run the pass. For what it does and does not fix, see Link remediation.

Link remediation runs as a separate pass, after your documents have migrated. It cannot run at the same time as a document migration, and the option to do so is not offered. Plan for two passes.

Before you start

Your destination is Google Workspace, and your source is Google Workspace or Microsoft 365.
Your document migration has finished for the users you want to remediate. Link remediation matches each link against the records the document migration writes, so a user with no migrated documents has nothing to match against and is failed at the start of the pass.
You are on CloudM Migrate 5.2 or later.
Your Google service account has the three additional scopes below, and the three additional APIs are enabled.

Add the Google API scopes and enable the APIs

Link remediation edits the contents of Google Docs, Sheets and Slides, which uses three Google APIs that CloudM Migrate does not otherwise need. Drive access on its own is not enough. If you skip this step, every document fails with an authorisation error.

Enable the APIs

In the Google Cloud project holding your service account, enable:

APIs to enable

docs.googleapis.com
sheets.googleapis.com
slides.googleapis.com

Add the scopes to domain-wide delegation

In the Google Admin console, open your existing domain-wide delegation entry for the CloudM Migrate service account and add these scopes to the ones already there. Do not replace the existing list.

Scopes to add

https://www.googleapis.com/auth/documents
https://www.googleapis.com/auth/spreadsheets
https://www.googleapis.com/auth/presentations

These scopes are needed on your destination connection. If you are migrating from Google Workspace to Google Workspace, they are only required on the destination tenant.

For the full setup, see Setting up the Service Account and enable the APIs within Google Workspace for CloudM Migrate.

Check it worked

Run Test Connection on your Google destination connection. Three checks cover this step: Docs (Link Parser), Sheets (Link Parser) and Slides (Link Parser). All three should pass before you run a pass.

If a scope or an API is missing, these checks report a warning rather than a failure, and the warning repeats the scopes and APIs to add. The connection is still usable for every other kind of migration, which is why it is not treated as a failure. If you do not intend to use link remediation, the warning can be ignored.

Check your Microsoft 365 permissions

This section only applies if your source is Microsoft 365.

Link remediation reads the user's OneDrive and the SharePoint document libraries selected in your migration, using the same Azure AD application as the rest of your migration. If that application uses the Sites.Selected role, it needs access granted for each site you want remediated. A site the application cannot read is reported as a failure against the user, with the reason given.

Run the pass

Link remediation is a migration item type, called Link Parser, alongside mail, drive, calendar and the rest.

Confirm your document migration has completed for the users you want to remediate.
Open the batch you want to work with, or create a new one for the remediation pass.
In Items to Migrate, add or select the users you want to remediate.
Enable the Link Parser item type for those users. Every other item type clears automatically when you do, and enabling any other item type clears Link Parser. This is expected, and it is covered below.
Make sure Migrate is enabled for each item, as you would for any other pass.
Start the migration.

If the Link Parser column is not visible in your item list, enable it from the column options. Column visibility is remembered per user.

Why Link Parser cannot be combined with other item types

Link remediation matches links against a record of what has already migrated. If it ran alongside the document migration, it would be matching against a list that was still being written, so links to documents that had not moved yet would be missed. Running it as its own pass is what makes the results complete and repeatable.

The practical effect is that a full migration is two passes over the same users: one for content, then one for links.

Running it across multiple servers

If you are running a multi-server migration, let the document migration finish across the whole environment before you start link remediation. Each server builds its list of migrated files once, at the start of the pass, and reuses it for the whole run. Documents that land after that point are not in the list, so links to them are not remediated on that server.

Re-running

You can run link remediation again over the same users as often as you like. Links that already point at the destination are recognised and left alone, so nothing is double-rewritten and no document is damaged by a second pass.

Your statistics will look different on the second run, because links that were replaced the first time are counted as already replaced rather than replaced. See Link remediation results and troubleshooting for how to read this.

Re-running is the right response to any of these:

You migrated more documents after the first remediation pass, so more links can now be matched.
A user failed the pass for a reason you have since fixed, such as a missing scope or a SharePoint site the application could not read.
You added more users to the migration.