AppProfileSafe - Support Portal

Performing the Actual Import

This page describes what happens during the actual import step — after preflight, mandatory dry run, and system restore point have been completed. For an overview of the full workflow, see Import Overview.


Import Flow

The import processes each selected application from the manifest in sequence. For every application, it performs two operations:

  1. Registry import — Reads the registry export XML from the backup and writes entries to the Windows registry
  2. File import — Copies files and folders from the backup to their target locations on the local system

Both operations apply mapping rules to transform paths. Before processing each item, the import checks whether it should be skipped due to item filtering. The import uses best-effort error handling: if an individual item fails, the remaining items continue.


Item Filtering

During import, each item is checked against two independent filters before it is processed. If either filter matches, the item is skipped and no data is written for it.

Filter Source Skip Status
DryRun selection GUI only. During the mandatory DryRun, items can be deselected via checkboxes. Deselected items are excluded from the import. Skipped
BlackList CLI only. A BlackList XML file (--blackListFile) defines paths to exclude from the import, with optional App and Type filters. Skipped (blacklisted)

Both filters compare against the fully resolved destination path (after environment variable expansion and mapping). Filtering is checked at the individual item level — each registry key, registry value, file, and folder is evaluated independently.

If a registry key is filtered out but a value within that key was selected, the value is also skipped because the parent key is required for writing. In this case the value reports Skipped (parent key deselected).


Registry Import

For each application with Registry Available="true" in the manifest, AppProfileSafe reads the corresponding {AppName}.xml from the Registry\ subfolder in the backup.

The import processes two types of entries:

Entry Type Behavior
KeyPathItem (recursive key export) Recursively creates registry keys and writes all values. Subkeys are traversed and created as needed.
ValueItem (single value export) Creates the target key (if it does not exist) and writes the single value.

For every registry path, the import:

  1. Normalizes the hive name (e.g. HKEY_CURRENT_USER → HKCU)
  2. Applies registry mapping rules to transform the path
  3. Checks item filtering (DryRun selection or BlackList) — skips if filtered
  4. Creates the registry key if it does not exist
  5. Writes the value with the correct type (REG_SZ, REG_DWORD, REG_BINARY, etc.)

All five Windows registry hives are supported: HKCU, HKLM, HKCR, HKU, and HKCC. Access denied errors are logged and the affected entry is skipped.


File Import

For each application, AppProfileSafe restores files and folders from the Files\ subfolder in the backup. The path transformation and processing follows this order:

  1. Expand environment variables — The OriginPath from the manifest is expanded (e.g. %APPDATA% → C:\Users\CurrentUser\AppData\Roaming)
  2. Apply file mapping rules — Find/replace rules are applied to the expanded path
  3. Check item filtering — DryRun selection or BlackList — skip if filtered
  4. Copy the file — The file is copied from the backup SafePath to the resolved target path

Target directories are created automatically if they do not exist.


ACL Import (Best-Effort)

If the manifest contains SDDL data for a file or folder, AppProfileSafe attempts to restore the original NTFS permissions. The ACL policy uses a best-effort, additive approach:

Scenario Behavior
Target file/folder already exists The backed-up ACL entries are merged additively with the existing permissions. Existing permissions are preserved; new entries from the backup are added.
Target file/folder does not exist The file/folder is created first, then the SDDL from the manifest is applied.
ACL application fails A warning is logged, but the file/folder is kept. The import continues.

The SDDL string from the manifest is used directly — ACL data from the backup file copies themselves is not applied.

Privilege-Dependent ACL Scope

The scope of ACL data that can be restored depends on the current privilege level:

Privilege Level ACL Scope Behavior
Administrator Owner + DACL + SACL Full SDDL from the manifest is applied, including audit policies if present
Standard User Owner + DACL Access permissions are restored. Audit policies (SACL) from the manifest are silently skipped because they require the SeSecurityPrivilege.

This means a backup created as administrator (with full SACL data) can be imported by a standard user — the access permissions are restored and the SACL portion is gracefully ignored. No warnings are generated for this case.


Change Tracking

During the actual import (not simulation), AppProfileSafe records every change using an ImportChangeCollector. For each registry value written and each file copied, a DiffItem is recorded with:

  • Application name, item type, and target path
  • Old value (before the import) and new value (from the backup)
  • Action: Created, Changed, Unchanged, or Skipped

After import completion, the collected changes are written to a CSV file in the Audit folder. This import change report uses the same CSV schema as the Dry Run report: App, Type, Path, OldValue, NewValue, Action. A SHA256 hash of the CSV is computed and included in the audit log entry.


Best-Effort Error Handling

Like export, the import uses a best-effort approach:

  • If a registry key cannot be written (access denied), the entry is skipped and other entries continue
  • If a file cannot be copied (locked, permission denied), the entry is skipped and other files continue
  • If an entire application directory is missing from the backup, it is logged and skipped
  • If an application is listed in --apps but not found in the manifest, a warning is logged

When errors occur, the audit log records the operation as ImportCompletedWithErrors instead of ImportCompleted.


Audit and Reporting

After the import completes, AppProfileSafe:

  • Writes an audit log entry with action ImportCompleted or ImportCompletedWithErrors, including duration, file count, data size, and registry value count
  • Saves the change report CSV to the Audit folder with a SHA256 hash for integrity verification
  • Generates a run report (JSON) saved in the Report folder
  • Dispatches events to the event pipeline (if configured)

The audit entry also includes detailed lists of all restored file paths and registry values (with mapped paths).


See Also