ReplaceMagicHelp

A mapping rule is a pair: Source (where content is now) → Target (where it will be). Rules are stored per RunID.

How rules are matched

• A rule matches when its Source is the beginning of a link, ending on a folder boundary. A rule never matches in the middle of a folder or file name.
• When several rules match, the longest Source wins. You can define a broad rule for a whole server and narrower rules for individual libraries – the most specific one is used.
• Matching ignores upper and lower case.
• Encoded and plain characters are equivalent: a rule written Shared Documents matches a link written Shared%20Documents, and vice versa. The same applies to accented characters and other encoded punctuation.

Practical guidance

• Write folder names exactly as they really are. Shared Documents (with the space) is a different name from SharedDocuments, and the latter will never match.
• Cover the locations where your documents live, not only the locations they link to. This matters if you intend to repair documents after moving them. SmartMapper reports any document whose own location no rule describes.
• Start from the suggestions. The Suggest rules action inspects the unmapped links of a run and proposes rule drafts for the locations that appear most often. The Coverage gaps action lists the locations that are still unmapped, ordered by how many links they affect. Together they turn rule authoring into a short, prioritised checklist.

SmartMapper checks your rules

Before the keys are created, SmartMapper checks the mapping rules against the scan and writes a Mapping rules check section to the log. Findings are marked [ERROR], [WARNING] or [CHECK].

• Where each scanned folder ends up. A rule for a parent of the scanned folder keeps the folder's own name in the target. With the rule Z: → .../Shared Documents and a scan of Z:\Finance, every document is expected under .../Shared Documents/Finance/.... That is right if the folder was migrated as a folder. If only its contents were migrated into the library, add the rule Z:\Finance → .../Shared Documents; otherwise no key will find its document after the migration.
• Rules that are not used by any document or link of the run.
• Rules that send links outside the scanned folders, which SmartMapper cannot verify, and links to local paths such as C:\Users\... or C:\Program Files\.... Mapping those to SharePoint breaks links that work on the users' computers, so narrow or remove such a rule.
• Other drives or shares that point to the same folders as the scanned one, for example G:\Finance when Z:\Finance was scanned. SmartMapper recognises them because the same files exist in the scan, and maps them the same way.

Verifying the rules against the migrated location. If the database also contains a scan of the migrated location, SmartMapper finds it automatically and checks every rule against it. When the documents are not where a rule sends them, it proposes the correct rule. It also finds folders the migration tool renamed, for example ~Rec Logs → _Rec Logs or Account # 1 → Account _ 1, and adds one rule per renamed folder. To get this check, scan the migrated location with ReplaceMagic before you create the keys. The Ultra fast scan option is sufficient, because only the list of files is needed. A scan of only a part of the migrated location is enough to correct a wrong rule, but renamed folders are found only where the scan covers them.

Warning about special characters. When keys point to folder names with characters that migrations usually replace (~ # % & ; : * ? " < > | { } – the list of SharePoint illegal characters in the Configuration) and the scan of the migrated location does not contain those folders, or there is no such scan, SmartMapper shows a warning after the keys are created, with the number of keys and files and the most frequent folder names (for example ~Rec Logs 13,133). ReplaceMagic cannot know the new names of such folders, so if the migration replaced these characters, those links will not work after the replacement. Scan the migrated location (Ultra fast scan is enough) into the same database and create the keys again – renamed folders are then detected automatically and the warning disappears. File names are not checked: a renamed file is not detected even with a scan of the migrated location.

Did the migration replace special characters? On the Create keys page SmartMapper asks "Did the migration replace special characters in folder names (~ # % & ...)?". The answer is kept for the next time.

• I don't know (default) – the warning above.
• Yes – ReplaceMagic replaces these characters itself during the replacement, as set in Configuration → SharePoint 2 (Replace SharePoint illegal characters?, and Use optional illegal characters? for # % & { } ~). The wizard does not change the Configuration; a note under the question says what is still missing there. After the keys are created you get an information message instead of the warning, and a warning for folders that the scan of the migrated location shows unchanged (the migration kept their name, so replacing their characters would make those links wrong – for example a folder Finance & Ops that still has its &).
• No – no warning. If the Configuration still replaces illegal characters, the note asks you to turn that off, because it would change names the migration kept.

The note under the question always reflects the current Configuration → SharePoint 2 settings, so change them there and come back to the page to see the result. When you click Create keys, the answer, the full note and the characters (those that are checked, and those that ReplaceMagic replaces itself) are written at the top of the log, so they are also part of Export processing data. In the log, the result appears as [WARNING] ... point to folder names with characters that migrations usually replace (answer I don't know) or [INFO] ... ReplaceMagic replaces during the replacement (answer Yes).

ReplaceMagic replaces illegal characters only in folder and file names: the address of the server (https://..., \\server\share, Z:), encoded characters such as %20 in Shared%20Documents, and the part of a link after ? are never changed.

Suggested rules are added automatically when they are backed by evidence in the scans. Your own rules are never changed or deleted, and the rules as they were before are listed in the log. Every rule shows its origin in the rules list: User (added by you), Suggested (added by SmartMapper) or Accepted (a suggestion you confirmed). After the keys are created you can review the suggestions on the page Suggested mapping rules.