When documents move to Google Workspace, the links inside them still point at the source. A Google Doc that linked to a colleague's spreadsheet now links to the copy in the old tenant, and a Word document that linked to a SharePoint file still links to SharePoint. Once the source is decommissioned, those links stop working.
Link remediation finds those links in your migrated documents and repoints them at the migrated copies.
Link remediation is available in CloudM Migrate 5.2 and later. It runs as a separate migration pass after your documents have migrated, not as part of the document migration itself. See Set up and run link remediation.
What you need before you start
Three things have to be true, or the pass will not do anything useful:
- Your destination is Google Workspace. Link remediation only rewrites links into Google Drive, so a migration to Microsoft 365 is not supported.
- Your source is Google Workspace, or Microsoft 365 (SharePoint and OneDrive). No other source platform is supported.
- The document migration has already finished for the users you want to remediate. Link remediation matches source files to their migrated copies using the records the document migration writes, so it has nothing to work with until documents have moved.
You also need three additional Google API scopes and three additional APIs enabled on your service account. The full list is in Set up and run link remediation.
What a remediated link looks like
| Source | What happens to the link |
|---|---|
| Google Workspace | The link keeps its original shape and only the file ID changes. A link to https://docs.google.com/document/d/SOURCEID/edit#heading=h.abc becomes https://docs.google.com/document/d/DESTINATIONID/edit#heading=h.abc, so bookmarks and anchors inside the link survive. |
| Microsoft 365 | The SharePoint or OneDrive URL is replaced with the Google Drive equivalent, in the form https://drive.google.com/open?id=DESTINATIONID. There is no way to preserve the shape of a SharePoint URL once the file lives in Drive. This includes the sharing links the Share or Copy link buttons produce, such as https://tenant-my.sharepoint.com/:w:/g/personal/.... These carry a sharing token rather than a file identifier, so CloudM Migrate resolves them back to the file they point at before matching. |
Link remediation changes where a link points, not the words someone wrote. A link reading 2025 budget still reads 2025 budget afterwards.
Where the visible text is a URL, the text is usually updated as well, so that what you read and where you land agree. There is one exception, in Google Sheets.
Google Sheets: a single URL inside a sentence
If a Sheets cell contains one Drive URL inside a sentence, and you have not applied a hyperlink to it yourself, the visible text keeps the original address. For example:
See https://drive.google.com/file/d/SOURCEID/view for details
After remediation that sentence still reads SOURCEID, but the cell links to the migrated file, so clicking it opens the right document. Nothing is broken. The address you read is the old one and the address you land on is the new one.
Every other shape is updated in both places:
| What the cell contains | Visible text | Where it links to |
|---|---|---|
| A URL on its own | Updated | Migrated file |
| Two or more URLs in a sentence | Updated | No link is set, as one cell cannot link to two files |
| A single URL in a sentence | Not updated | Migrated file |
| Text you have hyperlinked yourself | Unchanged, as intended | Migrated file |
This applies to Google Sheets only. In Google Docs and Google Slides, a URL written into a sentence is updated in the text as well as behind the link.
Which files are checked
Link remediation opens the migrated documents in your Google Workspace destination and looks for links inside them.
| Source | Files opened and checked |
|---|---|
| Google Workspace | Google Docs, Sheets and Slides. Files the migrating user owns, plus the content of any shared drives included in the migration. |
| Microsoft 365 | Word, Excel and PowerPoint files from the user's OneDrive and from the SharePoint document libraries selected in the migration. |
Links pointing at other file types are still remediated. A link to a PDF or a folder inside a Google Doc is updated normally. It is the file being opened and searched that has to be one of the types above.
Because only these types are opened, a link remediation pass processes far fewer items than the document migration it follows. Everything else in the drive is skipped when the pass lists what to work on, so it never reaches the item count. Expect the two numbers to differ by a wide margin.
Where links are found inside a file
Google Docs
- Hyperlinks and plain text URLs
- Headers, footers and footnotes
- Table cells
- All tabs in a multi-tab document, not just the first
Google Sheets
- Cell hyperlinks, including links applied to part of a cell's text
-
=HYPERLINK()formulas - URLs inside other formulas, such as
=IMPORTRANGEand=IMAGE - Smart chips that point at Drive files
- Plain text URLs typed into cells
Google Slides
- Hyperlinks and click actions on shapes, images and lines
- Plain text URLs
- Table cells and grouped shapes
- Speaker notes
- Layouts and masters, so a link on a template applied to many slides is fixed once
Word, Excel and PowerPoint files
This applies when you migrated from Microsoft 365 and chose not to convert documents to Google format, so the files are still .docx, .xlsx and .pptx in Drive.
- Hyperlinks and plain text URLs
- Field codes and formulas
- Comments
- In PowerPoint, slides, speaker notes, layouts and masters
What is not remediated
These links are left exactly as they are. Nothing is broken by leaving them, but they will still point at your source after the migration, so you may want to fix the important ones by hand.
| Link or file type | Why |
|---|---|
Google published-to-web links, in the form /document/d/e/.../pub
|
A published link points at a published snapshot rather than the file itself, and the snapshot has no equivalent in your destination. |
| Drive chips in Google Docs | Google's API does not allow the target of an inline chip to be changed. These are listed individually in your report so you can replace them. |
| Smart chips in Google Sheets that are not Drive files, such as YouTube, Maps and Calendar chips | Google's API only allows Drive files to be written as chips. These are also listed in your report. |
| Click actions on videos in Google Slides | Google's API does not expose the link on a video element. |
Macro-enabled and older Office files at the destination, such as .docm, .xlsm, .doc and .xls
|
Only .docx, .xlsx and .pptx can be rewritten in place. These files are reported as skipped, with the file type given. |
| Links inside file types that are not opened, such as PDFs and plain text files | See "Which files are checked" above. |
| Files a user does not own, on personal drives | A file shared into someone's Drive belongs to whoever owns it, and is remediated when that person is migrated. If the owner is not in your migration, the file is not remediated. Shared drives are not affected by this, because ownership there is collective. |
Things worth knowing
File dates are preserved. Rewriting a link would normally update a file's last modified date. Link remediation captures the date before it makes a change and restores it afterwards, so your users' documents do not all appear to have been edited on migration day. This follows the Preserve Modified Date setting, which is on by default.
Running it twice is safe. Links that already point at the destination are recognised and left alone. Your report will look different on a second run, because most links will be counted as already replaced rather than replaced. See Link remediation results and troubleshooting.
It is called Link Parser in the migration item grid. The migration item type is Link Parser. The statistics and the report section are called Link Remediation. They are the same feature.