Fix Broken Links After SharePoint Tenant-to-Tenant Migration
Tenant-to-tenant migrations are among the most complex SharePoint scenarios — they change both the base URL and SharePoint’s internal item IDs, breaking every embedded link in every Office document. This guide explains what breaks, why, and how ReplaceMagic repairs all three link types in bulk.
- Tenant migrations break ALL three link types: absolute URL links, relative path links AND SharePoint ID-based links
- Manual repair is not feasible at enterprise scale — even 1,000 documents with 10 links each = 10,000 manual edits
- ReplaceMagic handles all three link types automatically, including ID-based link conversion (based on user provided search/replace combinations)
Why Tenant-to-Tenant Migrations Break Document Links
When a company moves from one Microsoft 365 tenant to another — due to acquisition, merger, or divestiture — all SharePoint URLs change because the tenant domain changes (company.sharepoint.com becomes newcompany.sharepoint.com). Additionally, every SharePoint item has an internal ID that is unique to that tenant — these IDs do not carry over to the new tenant. The result is that every embedded link in every document is broken at the moment of cutover.
1. Absolute URL Links
These directly reference the old tenant domain (e.g. https://oldcompany.sharepoint.com/sites/Finance/...). After migration, the domain is invalid. Fix: replace old domain with new domain in all documents.
2. Relative Path Links
These reference documents using relative paths within the SharePoint site hierarchy. They may break if the site structure changes during migration. Fix: update the path components that changed.
3. ID-Based Links (most critical)
SharePoint stores some links as references to the item’s internal database ID (e.g. /sites/Finance/_layouts/15/Doc.aspx?sourcedoc={GUID}). These GUIDs are tenant-specific and do not exist in the target tenant. After migration, these links point to nothing. Fix: ReplaceMagic converts ID-based links to correct URL-based links, based on user provided search/replace combinatinos, before or after migration so they remain functional in the new tenant.
All changes - based on user provided search/replace rules
ReplaceMagic will make all changes based on search/replace rules provided by the user.
How ReplaceMagic Fixes All Three Link Types
Step 1 — Pre-Migration Scan
Run ReplaceMagic against the source tenant to build a complete inventory of all documents and all link types. Identify how many absolute, relative and ID-based links exist. This inventory feeds directly into your replacement rules and provides a baseline for post-migration verification.
Step 2 — Configure Replacement Rules
Set up the domain replacement (old URL → new URL). For ID-based links, ReplaceMagic can convert them based on user provided search/replace rules. All rule types are configured in a single import file and execute in one processing pass.
Step 3 — Preview and Validate
Run in Preview mode to see all proposed changes before committing. Verify the replacement rules cover all link variations found in the scan. Adjust rules if any edge cases are identified.
Step 4 — Execute
Run the replacement. ReplaceMagic processes all documents in parallel, updating all three link types in one pass without opening any file. SharePoint metadata (last-modified date, author) is preserved when running with Site Admin rights.
Step 5 — Post-Migration Verification
Re-scan on the target tenant to confirm all links now resolve correctly. Export a verification report for project sign-off and audit documentation.
What the Replacements Preparation Package Does
For complex tenant-to-tenant migrations with hundreds of path variations or large volumes of ID-based links, the ReplaceMagic team can prepare all replacement string combinations on your behalf. This service analyses your source tenant, identifies every unique link pattern, and delivers a ready-to-import replacement rules file. See the Replacements Preparation Package for details.
Key Considerations
- Timing: ideally run ReplaceMagic AFTER all documents have been migrated to the target tenant
- Permissions: Site Admin rights required on the target SharePoint tenant to preserve last-modified dates
- ID-based links: conversion should be validated on a sample before full execution
- Scope: Microsoft Teams and OneDrive for Business documents are covered (SharePoint backend)
