How to Use SmartMapper — Auto-Generate Link Repair Patterns

Traditional link repair asks you to provide the search and replace strings. SmartMapper inverts that workflow: you define simple Source → Target mapping rules and SmartMapper figures out every search/replace pattern automatically — resolving relative links, ID-based SharePoint DocIDs, PowerQuery paths and connection strings — and reports accuracy and coverage as two separate figures before a single document is touched.

When to use SmartMapper: any migration where you cannot enumerate all search/replace pairs by hand — SharePoint tenant-to-tenant moves, large file-share-to-cloud migrations, estates with ID-based or relative links, and any project where you need a sign-off report before go-live. For simple server renames where you already know the old and new paths, standard ReplaceMagic is sufficient.

The SmartMapper Workflow at a Glance

Seven-step pipeline

Scan

Populate link database from documents or SharePoint

→

Choose DB

SQL Server, SQLite or MySQL

→

Map Rules

Source → Target pairs

→

Generate

Auto-generate & score patterns

→

Review

Accept / modify / reject each pattern

→

Apply

Run replacement engine on real documents

→

Verify

Re-scan and export report

Step 1 Scan Your Documents

Before SmartMapper can generate patterns it needs a populated link database. Use the standard Scan Documents function to crawl your source storage — a local or network folder, a mapped drive, or a SharePoint library connected natively.

For file-server or network-share sources, point ReplaceMagic at the root folder and run a full scan. All discovered hyperlinks, OLE links, link sources, PowerQuery commands and connection strings are written to the database.
For SharePoint sources (including tenant-to-tenant projects), connect via the native SharePoint integration. It is critical to scan the source tenant while it is still live — SmartMapper resolves ID-based links against the document index, and those IDs cease to be resolvable the moment the source goes offline.
Select all relevant document areas in the scan settings: Hyperlinks, OLE links, Link Sources, Power Queries, Connections, VBA. Any area not scanned will be invisible to SmartMapper.

See How to scan documents and SharePoint native support guide for full scanning instructions.

Step 2 Choose a Database Backend

SmartMapper stores all scanned links, mapping rules, generated patterns and validation results in a relational database. Three backends are supported — identical schema, identical results:

SQL Server

Best for shared, enterprise-governed projects. SQL Server Express is sufficient for most migrations. Use this when multiple team members need access to the same pattern database.

SQLite

Best for single-machine or partner-led projects. One file, zero installation, no licence cost. Ideal for laptop-based migrations.

MySQL

Open-source alternative to SQL Server for environments that already have a MySQL infrastructure. Same schema as the other two backends.

Configure the backend in Configuration → SmartMapper tab → Database backend. You can switch backends between runs; the schema is identical so migrating data is straightforward.

Step 3 Define Source-to-Target Mapping Rules

Mapping rules are the only input SmartMapper needs from you. Each rule is a single Source → Target pair:

Example mapping rules for a file-share to SharePoint Online migration

Source (old path)	→	Target (new path)
\\ServerABC\Finance	→	https://company.sharepoint.com/sites/financenew
\\ServerABC\HR	→	https://company.sharepoint.com/sites/hr
\\OldNAS\Shared\Projects	→	https://company.sharepoint.com/sites/projects

Tips for writing effective mapping rules:

Map at the highest useful level — map \\Server\Finance rather than every individual sub-folder. SmartMapper consolidates sub-folder patterns automatically.
List rules from most specific to least specific.
For tenant-to-tenant migrations, add a rule for the old tenant base URL and one for the old tenant’s internal ID resolver URL. SmartMapper will resolve every ID-based link to an absolute path using the source document index before the source tenant is decommissioned.
Rules can be entered manually in the SmartMapper grid or imported from a CSV file (pipe | separated by default).

Step 4 Run SmartMapper Pattern Generation

Click Generate Patterns in the SmartMapper tab. For each link in the database, SmartMapper:

Detects the link type — Absolute, Relative, SharePointDocID, OneDriveID, PowerQuery, ConnectionString, OneNote, SharePoint-special.
Resolves every link to an absolute path — whatever form it took: relative, ID-based, or embedded inside PowerQuery commands (File.Contents, Folder.Files, Web.Contents) or connection strings (Provider=, DSN=, Data Source=, OPENROWSET).
Applies your mapping rule to produce the new target path (NewLink).
Generates patterns at the smallest scope that does the job — so a broad \\Server\Finance rule does not produce thousands of redundant sub-folder patterns.
Deduplicates and optimises automatically — identical patterns from different links are consolidated into a single entry.
Flags conflicts where the same SearchString maps to two different ReplaceStrings. These are marked as Conflict and must be resolved by a human before they can be applied.

Why relative links cannot be repaired by hand

A workbook at \\ServerABC\Finance\Reports\Q2.xlsx contains the link ..\Sub1\file.xlsx. The same text appears in hundreds of other documents and points somewhere different in each one, because a relative link has meaning only in relation to the document that contains it.

No single search and replace pair can fix that. SmartMapper works out what each occurrence actually points to, applies your rule and generates the pattern. You supply one line:

\\ServerABC\Finance → https://company.sharepoint.com/sites/financenew

Step 5 Review Generated Patterns

The pattern grid shows every auto-generated search/replace combination with its status and validation metrics. Review each pattern before any document is touched:

Pattern statuses

Generated	Created by SmartMapper, not yet reviewed
Accepted	Approved — will run against documents
Rejected	Explicitly excluded — will not run
Modified	You edited the SearchString or ReplaceString — will run with your version
Conflict	Same SearchString maps to different ReplaceStrings — must be resolved before it can be accepted

Accuracy and coverage

Each pattern shows a correct count (links this pattern would correctly repair), a incorrect count (links this pattern would damage), and an accuracy percentage. The run log labels this Confidence (fix accuracy).

A pattern with 100% accuracy and zero incorrect links is safe to accept immediately. Patterns with any incorrect entries should be inspected — they may indicate an overlapping mapping rule or an ambiguous path segment.

At run level SmartMapper reports two independent figures, and you need both:

Accuracy — of the links your accepted patterns change, what proportion they change correctly.
Coverage — of all in-scope links, the proportion that will be repaired correctly.

They measure different things and move independently. A run can be 100% accurate and still cover only 82% of in-scope links — every change it made was correct, yet nearly a fifth of the work was never touched. A single blended score hides exactly that gap, which is why the two are reported separately.

An optional composite roll-up is available for stakeholder reporting. Publish it alongside the accuracy and coverage figures, never in place of them.

Conflicts require manual resolution. A conflict means two different links resolved to the same SearchString but with different ReplaceStrings — SmartMapper cannot decide which is correct. Open the conflict group, inspect the source documents, choose the right ReplaceString and click Resolve, or reject the pattern entirely if the links should not be changed.

Step 6 Apply Accepted Patterns to Documents

Once you are satisfied with the reviewed patterns, run the replacement engine. Only patterns in Accepted or Modified status are ever applied — Generated, Rejected and unresolved Conflict patterns are skipped.

Documents are processed in parallel (configurable thread count) without being opened by Word, Excel or any other application.
If Preview mode is enabled, ReplaceMagic reports every change it would make but writes nothing to disk — use this to verify the output before committing.
Enable automatic backup to save a copy of every document before it is modified.
For SharePoint targets, enable Keep Last modified date and Modified by values (requires Site Administrator rights) to preserve metadata after changes.

See How to fix broken links for detailed replacement engine settings.

Step 7 Verify and Export Results

After the replacement run completes:

Re-scan the same storage to confirm all previously broken links are now resolved. The new scan result can be compared against the baseline to show exactly which links changed status.
Check the Additional Info tab for any documents that were skipped (size limit, timeout, SharePoint throttling). Reprocess skipped files by clicking Import Skipped Files.
Export the results to CSV, Excel, or the SmartMapper database. The export contains the original link, the new link, the applied pattern, the document path and the change timestamp — a complete audit trail for compliance or stakeholder reporting.
Export the run-level report from the SmartMapper tab to provide a sign-off document showing total links scanned, patterns applied, correct / incorrect counts, and the run's accuracy and coverage figures as two separate numbers.

See How to export results for export format options.

Special Case: SharePoint DocID Links and Tenant-to-Tenant Migrations

SharePoint ID-based links (DocID, OrganizationalViewLink, DirectLink) are the hardest link type to repair with conventional tools because the ID is only meaningful inside the original tenant. Once the source tenant is decommissioned, those IDs are permanently gone.

SmartMapper solves this by scanning while the source is still live:

Connect to the source SharePoint tenant and run a full scan while it is still live.
Define your tenant-to-tenant mapping rule (old tenant base URL → new tenant base URL).
Run pattern generation.
The generated pattern replaces the old ID-based URL with the new absolute URL — a repair that works even after the source tenant is offline.

Key point: Run the SmartMapper scan on the source tenant before migration cutover. Once the source goes offline, DocID resolution is no longer possible.

For the full tenant-to-tenant migration guide see SharePoint Online Tenant-to-Tenant Migration: Fixing Broken Links.

Working with PowerQuery, ConnectionStrings and OLE Links

Many large Excel estates contain links that are not exposed as standard hyperlinks — they are buried inside PowerQuery M code, OLEDB connection strings, or Pivot cache definitions. SmartMapper extracts these automatically:

PowerQuery: SmartMapper handles paths inside PowerQuery M commands, including File.Contents, Folder.Files, Web.Contents and SharePoint.Files. Where a migration moves local files to SharePoint, changing the path alone is not enough — the query itself must work against cloud storage, and SmartMapper handles that too.
ConnectionStrings: Paths inside Provider=, DSN=, Data Source=, OPENROWSET, OPENDATASOURCE and BULK INSERT statements are extracted, resolved and mapped using the same pipeline as regular links.
OLE Links and Link Sources: Excel workbooks that link to external data sources (another workbook, a database file) have their external reference paths updated via the Link Sources area.

Ensure the Power Queries, Connections and Link Sources areas are selected in the scan settings to include these in the SmartMapper database.

Tips and Best Practices

Use SQLite for prototyping. Run your first SmartMapper pass with a SQLite backend — no server setup, instant start. Verify the pattern quality before committing to a full SQL Server deployment for a large team project.
Use RunIDs for multi-wave migrations. Each SmartMapper run is scoped by a RunID. Assign a different RunID per migration wave so results from different waves coexist in the same database without contaminating each other.
Resolve conflicts before go-live. Unresolved Conflict patterns are excluded from the replacement run. Review the conflict group list after every generation pass and resolve or reject each one explicitly.
Target the most specific mapping rule first. If \\Server\Finance\Archive should map differently from \\Server\Finance, add the Archive rule above the Finance rule in the mapping grid.
Preview before applying. Always run in Preview mode on a representative subset of documents to validate the pattern output before running across the full document library.
For the Replacements Preparation service: if your project is too large or complex to run SmartMapper in-house, the ReplaceMagic team can prepare all mapping rules and patterns on your behalf. See Replacements Preparation Package.