Backup & Restore

Overview

The Backup feature allows admins to export a complete snapshot of their organization's data as a JSON file and restore it later. This is useful for data backup, migration between environments, and disaster recovery.

Key Concepts

Export Format

Backups are exported as structured JSON files containing:

• Metadata -- Export timestamp, tenant ID, tenant name, version, and export options
• Schema -- Enum definitions and data structure version for forward compatibility
• Master Data -- Referenced OEMs, equipment models, machine families, component catalog, machine positions, and work activities (only records used by the tenant)
• Tenant Data -- All tenant-scoped records including sites, profiles, vehicles, components, events, maintenance logs, meter readings, forecasts, work orders, parts, financial records, notifications, attachments, downtime events, fuel transactions, TCO scenarios, and settings
• Statistics -- Record counts per table for quick verification

Import Modes

Tenant Validation

Backups are validated against the current tenant:

• The backup's tenant ID must match the current tenant. You cannot import a backup from a different organization.
• Replace mode enforces the same-tenant requirement to prevent accidental data loss.

How to Use

Viewing Backup Statistics

Before exporting, you can view record counts for your tenant:

1. Navigate to Admin > Backup.
2. The stats panel shows counts for sites, profiles, vehicles, components, events, maintenance logs, meter readings, forecasts, work orders, parts, financial records, and audit logs.

Exporting Data

1. Navigate to Admin > Backup.
2. Configure export options:
   • Include Audit Logs -- Include the full audit trail (can significantly increase file size)
   • Include Deleted Records -- Include soft-deleted records (profiles, vehicles, work orders, parts)
3. Click Export JSON.
4. Save the downloaded file.

The export operation is audited, recording the export options and record counts.

Importing Data

1. Navigate to Admin > Backup.
2. Click Import.
3. Select your backup JSON file.
4. Choose the import mode (Merge or Replace).
5. Review the import preview.
6. Confirm the import.

Currently supported for import:

• Sites, profiles, vehicles
• Profile components and profile events
• Meter readings, parts

Exported but not currently imported:

• Maintenance logs, forecast events, work orders, financial records
• Notifications, attachments, downtime events, fuel transactions
• TCO scenarios

Master Data Requirements

Master data (OEMs, equipment models) is exported for reference but not imported automatically. Before importing a backup, ensure all referenced master data already exists in the target database. The import will fail with a descriptive error if profiles or vehicles reference non-existent OEM or model records.

To resolve foreign key errors:

1. Check the error message for the missing OEM/model name.
2. Create the missing master data records in Admin > Master Data.
3. Retry the import.

Common Questions

Is there a size limit on exports?

The recommended maximum is approximately 50 MB. Very large tenants (over 100,000 records) may experience timeouts or memory issues. For production PostgreSQL backups, use pg_dump directly.

Can I import a backup from a different tenant?

No. The backup's tenant ID must match the current tenant. This prevents accidental cross-tenant data contamination.

What happens if the import fails?

Imports run inside a database transaction. If any step fails, the entire import is rolled back and no data is changed. The transaction has a 10-minute timeout for large imports.

Is SQL export supported?

No. The SQL export endpoint exists for backward compatibility but returns a "not supported" error. Use JSON export for all backup needs, or pg_dump for raw database dumps.

Are backups encrypted?

No. Backup JSON files are plain text. Handle them according to your organization's data security policies.