AppProfileSafe - Support Portal

Mapping

Mapping rules transform registry and file system paths during import. They allow you to restore application profiles to a different machine, user account, or folder structure without manually editing the backup data.


Why Mapping Is Needed

When restoring a backup to a different machine, paths often change. For example:

  • Username changes: C:\Users\OldUser\... → C:\Users\NewUser\...
  • Registry user SID changes: HKEY_USERS\S-1-5-21-old-sid\... → HKEY_USERS\S-1-5-21-new-sid\...
  • Application paths change: D:\Programs\... → C:\Program Files\...

Mapping rules define find/replace transformations that are applied automatically to every path during the import.


Two Types of Mappings

Mapping rules are separated into two categories, each applied independently:

Category Applied To
Registry Mappings Registry key paths and value paths before writing to the Windows registry
File Mappings File and folder target paths (after environment variable expansion) before copying


Rule Structure

Each mapping rule consists of:

Property Description
Enabled Whether the rule is active (default: true). Disabled rules are stored but ignored during import.
Type String (literal find/replace, default) or Regex (regular expression pattern)
Pattern The text to search for. For String type, the pattern is automatically escaped. For Regex type, a full regular expression is used.
Replacement The replacement text. May contain environment variables (e.g. %USERNAME%, %APPDATA%) which are expanded at runtime.

Rules are applied sequentially from top to bottom. The output of one rule becomes the input for the next. Order matters.


Mapping File Format

Mapping rules are stored in an XML file with namespace urn:appprofilesafe:mappings:v1:

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<Mappings xmlns="urn:appprofilesafe:mappings:v1" SchemaVersion="1.0">
  <RegistryMappings>
    <Rule Enabled="true" Type="String">
      <Pattern>OldUser</Pattern>
      <Replacement>NewUser</Replacement>
    </Rule>
  </RegistryMappings>
  <FileMappings>
    <Rule Enabled="true" Type="String">
      <Pattern>C:\Users\OldUser</Pattern>
      <Replacement>C:\Users\%USERNAME%</Replacement>
    </Rule>
  </FileMappings>
</Mappings>

The file is validated against AppProfileSafe.Mappings-v1.0.0.xsd when loaded and when saved.


Mapping Editor (GUI)

The mapping editor is accessible from the Import window via the Mapping Rules button. The window title is "Import Mapping Rules" and contains:

  • Mapping File selection — Browse for an existing file, Create New, or Unload the current file
  • Two tabs: Registry Mappings and File Mappings, each with a DataGrid showing Enabled (checkbox), Pattern, and Replacement columns
  • Rule management buttons: Add Rule, Remove, Move Up, Move Down, Select All, Deselect All
  • Save button — Highlighted with bold text when unsaved changes exist

Rules are applied sequentially from top to bottom — use Move Up / Move Down to control priority.


Environment Variables in Replacements

Replacement strings can contain Windows environment variables in %VAR% format. These are expanded at runtime during the import. Common variables:

  • %USERNAME% — Current user name
  • %USERPROFILE% — Current user profile path (e.g. C:\Users\CurrentUser)
  • %APPDATA% — Roaming application data folder
  • %LOCALAPPDATA% — Local application data folder

This makes mapping files portable — the same mapping file works on different machines because the variables resolve to the correct local paths.


Topics in This Section