System Backup and Restore
Overview
Section titled “Overview”The SENSE Backup & Restore (B&R) feature involves the importing and exporting of system archives, structured JSON representations of selected SENSE configuration domains. These are not a full disaster-recovery backup, but instead allow for operators and some users to more easily move their data between SENSE Orchestrator deployments.
Currently, the B&R system supports three domains: system settings, service profiles, and driver configurations. It does not support service instances, tasks, alerts, runtime or model state, metadata, or logging or audit history.
By default, this system is only for system administrators, but there is one exception: any PROFILE_MANAGER user may
import profiles under the COPY mode, allowing them to load in shared profiles from other managers or administrators.
More details on this can be found below or in the user guide.
As always, before any potentially destructive restore make sure a separately managed deployment and database recovery plan is available. A successful restore has no automated undo. Additionally, until our secure credential handling review completes, system settings and driver archives may contain secrets and credentials; these credential-bearing archive operations are restricted to system administrators but should still be treated with care. Store these archives only in secure locations and operate only on trusted machines; do not put them in version control or expose them to the public.
Export and Restore a Full System Archive
Section titled “Export and Restore a Full System Archive”- In the portal, open Admin Settings → Backup & Restore and select Download Backup.
- Review any export warnings, then save the JSON securely.
- To restore, select Restore Backup, choose the archive file or paste its JSON, and select Review.
- Evaluate the settings, drivers, and profiles in the review. Choose the import behavior where offered.
- If you change a value or import mode, select Re-Check Plan and review the updated plan.
- Type
RESTORE, then select Restore System. - Validate the resulting settings, driver configurations, profiles, and ACLs in the portal. Newly created drivers remain unplugged; inspect them before connecting them.
The SENSE Orchestrator backend operates the review and restore process, which means it is accessible via both REST API and SENSE Portal interactions. The restore validates all supplied domains before writing, then applies them in the order (SETTINGS → DRIVER → PROFILE) in one transaction. If any domain import fails, the transaction rolls back. A Bundle archive can have any or all domains present.
Import Behavior
Section titled “Import Behavior”| Domain | Modes |
|---|---|
| Settings | - MERGE (Default) applies archived keys and leaves other current keys in place.- REPLACE removes any archivable current keys not present within the archive; the review must acknowledge the proposed changes. |
| Drivers | - Only a single mode; upserting any present driver configurations by topologyUri. If an imported property is absent, the existing property is retained. Runtime and health fields are not archived. |
| Profiles | - COPY (Default) creates new UUIDs for each profile, assigns ownership to the importing principal, and imports archived READ and WRITE licenses except a regular license matching the destination owner.- RESTORE preserves UUIDs, owners, and ACLs, and overwrites matching profiles. RESTORE requires administrator privileges. |
Settings Exports
Section titled “Settings Exports”In the Admin Settings → Backup & Restore panel you can also find a specific dialog just for the System Settings
domain. Use Export Settings to create a settings JSON file or Import Settings
to review and apply one, similar to other domains. The settings archive policy currently exports understood keys in the
global.,
ipa., agent., and
system. namespaces. It classifies portable values, environment-specific values, and secrets; environment-specific
values and secrets require review before applying them elsewhere. Unknown namespaces and internal/runtime keys are
excluded.
Use MERGE unless you intentionally need removal of archivable keys not present in the archive. Review
deployment-specific values and secrets, acknowledge required changes, and re-check the plan after changing the mode or
values.
Credential Store and Provider Recovery
Section titled “Credential Store and Provider Recovery”System and settings JSON archives do not export the encrypted credential rows in sense_cred or the runtime master
keys. The settings archive policy also excludes the projectsync.* namespace, including the external provider’s URL
and token binding. Importing a configuration archive therefore does not recreate the provider/token configuration.
Other archived settings and driver properties can still contain secrets; continue to protect those archives.
Plan credential and provider recovery separately from configuration-archive import. See Configure the Credential Store, the master-key rotation procedure, and Configure an External Project Provider. These pages do not replace a deployment-specific database backup and restore procedure.
REST API
Section titled “REST API”The system archive functionality is almost entirely contained within the /archive path, which can be viewed in detail
at our OpenAPI Spec Demo.
Troubleshooting
Section titled “Troubleshooting”- Invalid or unsupported archive: Keep the original trusted archive unchanged and get a corrected archive from a trusted source.
- The review token is stale: If settings changed while reviewing, run the preview again with Re-Check Plan.
- 403 response: Contact an administrator to confirm the required access role.
- 413 response: Reduce the archive size or have an operator review the configured payload limits.
- Content is Missing: Confirm the archive contains the expected domain, and the requested content is present in the archive JSON. Content outside the archive policy is intentionally out of scope.