Repair before or after the migration

Previous Top Next

A single source scan supports both approaches, because SmartMapper stores two addresses with every key: the document's current location and its calculated future location.

Option A – repair first, then migrate

Run the replacement while the documents are still in place. The links are corrected to point at the future locations, and the corrected documents are then moved. Simple and predictable; nothing extra is required.

Use Option A only before the migration. The documents are changed in place, so after the replacement the documents at the source location already link to the new locations. If the content has already been copied, users who still work at the old location would get links to the new one – use Option B instead. Turn on the Backup option before you repair at the source (file system; on SharePoint the previous versions are kept by SharePoint versioning).

Warning before documents at the source are changed. When a SmartMapper replacement is started on documents that are still at their source location, ReplaceMagic first shows Documents at the SOURCE location: how many documents of the list are at the source, an example with its new location, and, for documents in the file system, whether the Backup option is on (not for SharePoint documents: ReplaceMagic makes no backup copy there, SharePoint versioning keeps the previous versions). No (the default) cancels the replacement; Yes changes the documents in place. A command-line (silent) run does not ask: it writes a WARNING with the same numbers to the log and continues. A scan of the target location (Option B) does not show this question.

Option B – migrate first, then repair

Move the content, then run the replacement at the new location. ReplaceMagic recognises each document by its new address and applies exactly that document's keys.

Conditions for Option B:

  • Per-file mode must have been used.
  • Every document's own location must be covered by a mapping rule. SmartMapper checks this and reports it explicitly:

[target] 21 document(s) have NO MappingRule for their own location -> ... Add rules for:

    \\fileserver\Finance\Reports\budget.xlsx

    ...

Add the missing rules and regenerate. If the message says all document locations are rule-covered, Option B is safe.

  • The migration must place files where the rules say. Differences in upper/lower case or in encoded characters are handled automatically; genuine renames are not. Documents that the migration tool renamed (for example ShareGate replaces # and % with _, and .. with _.) are not found with the keys of a source scan: SmartMapper finds the keys of a document by its calculated new path, and a renamed document has another path. ReplaceMagic warns before the replacement (see below). If you know that the migration renamed documents, scan the target location instead (see Where to scan): there the documents already have their new names, and the keys and the replacement work for them like for all other documents.

Documents with keys not found. Before every SmartMapper replacement ReplaceMagic checks whether all documents with keys of the run are in the documents to process. Only the documents under the common folder of the list are checked, so documents of other sites or locations are not reported. If documents are missing, the message Documents with keys not found shows how many, an example, the possible reasons and what to do, and the replacement then continues with the other documents. The links in the missing documents are not changed. The full list is saved next to the log as ReplaceMagic.SmartMapper - run N - documents with keys not found - yyyyMMdd HHmmss.txt (expected path and source path). A command-line (silent) run writes the same information to the log as a WARNING and shows no message.

  • Keys from a scan of the source: the documents were not migrated, they were deleted or moved, or the migration tool renamed them. Check the list. Documents that were not migrated or were deleted need nothing. If the migration tool renamed documents, scan the target location and create the SmartMapper keys from that scan: there the documents have their new names. Document-ID links can only be resolved with a scan of the source (see Where to scan).
  • Keys from a scan of this location: the names were already the new ones, so the documents were deleted, moved or renamed after the scan. Check the list. Deleted documents need nothing. For documents that were moved or renamed, scan the location again and create the keys again.

Running the replacement again is safe: documents that are already correct are not changed.

If no document with keys of the run is at the selected location (the keys of the run are for another location), the message No documents with keys at this location says that no links will be changed and shows an example of the location the keys are for. No (the default) cancels the replacement; Yes continues it (nothing is changed). Check that the right SmartMapper run and the right location are selected.A command-line (silent) run writes the warning to the log and continues. While ReplaceMagic reads the keys of a big run and checks the documents, the progress bar shows what is being checked and for how many seconds.

Only for this replacement. The choice applies to the replacement that is started. The list of documents and the documents grid stay complete, so a later replacement in the same session (another run, All documents, or a replacement without SmartMapper) sees all documents again. Before 2026.2.6.1 the list stayed reduced until the next scan or import. The log shows how many documents the replacement processes.

Both options can be prepared from the same run – you do not have to decide in advance.

Process only the documents that can change

You can scan everything and create the keys for everything, and still open only the documents that will change. When you import a saved run (Saved RUN(s) → Import), choose in the row above the runs:

  • All documents (default) – every scanned document is imported.
  • Only documents with links – only documents in which the scan found links (hyperlinks, OLE links, link sources, pivot tables or Power Queries).
  • Only documents with SmartMapper keys – only the documents for which SmartMapper created Search & Replace keys, i.e. exactly the documents the replacement will change.

For example, a scan of 1.1 million documents had 71,126 documents with links and 27,067 with SmartMapper keys. The documents grid shows only the imported documents, and a message tells you how many were imported. If the run has no link counts (an Ultra fast scan) or no SmartMapper keys yet, all documents are imported and you are told so.

The same choice exists for command-line (silent) runs: Silent run params → SmartMapper options → Documents, saved in the XML file as <SMARTMAPPERDOCUMENTS>All|WithLinks|WithKeys</SMARTMAPPERDOCUMENTS>.

Use these options for link replacement only. If you also replace other text in the documents, keep All documents, because documents without links would not be opened.

At the target location (new in 2026.2.4.1). The same choice is also on the last page of the SmartMapper wizard (Documents to process). It applies to the replacement you start from the wizard, whatever documents are in the list – a scan of the source, an imported run, or a scan of the target location after the migration:

  • Only documents with SmartMapper keys – the documents whose path matches a key of the selected run, also at the target location given by the mapping rules. A scan of the target (Ultra fast scan is enough) is all that is needed; the target does not have to be saved in the database.
  • Only documents with links – the documents in which the scan being processed found links. This needs a full scan; after an Ultra fast scan the link counts of the saved run are used.

Before the replacement starts, ReplaceMagic shows how many documents will be processed (N of M documents will be processed): Yes processes only those, No all documents. If no document matches (for example a scan of another location), all documents are processed and you are told so. A command-line (silent) run never asks: it uses the setting from the XML file and writes the numbers to the log – there, too, a scan of the target with WithKeys processes only the documents with keys, and WithLinks uses the link counts of the run's own scan.

The last page of the wizard (2026.2.5.5). At the top, a green box shows the result for the run: the number of Search & Replace keys and of documents with keys (and the coverage, if you created the keys in this session). Below it, under Which documents should the replacement process?, the three choices are listed one under the other, each with a short description. Only documents with SmartMapper keys is the fastest choice and works on a scan of the source as well as on a scan of the target, because the keys contain both paths. Click Finish to start the replacement with these keys.