Rollback on Failure — Import System

When Rollback Occurs

Failure Stage	Rollback Triggered?	Note
Upload / Validation / Security Scan	No	No data was written — no rollback needed
Package Dependency Check	No	No data was written
ID Remapping	No	No data was written (in-memory only)
Conflict Detection	No	No data was written
Installation (any artifact fails)	Yes	Full transaction rollback
Post-Install Verification (any check fails)	Yes	Full transaction rollback

What is Rolled Back

All database writes performed during the installation stage are within a single transaction. A rollback undoes:

All INSERT statements for newly created artifacts
All UPDATE statements for artifacts that were replaced or merged
The import history record (the record is only committed on success)

The target tenant's artifact database is left exactly as it was before the import began.

What is NOT Rolled Back

The following are not part of the transaction and are not rolled back:

The import attempt log entry (failure is recorded for audit)
The security scan result
The blob storage read of the ZIP file
Any notifications sent during the import

Failure Response

HTTP 422 Unprocessable Entity
{
  "importId":   "imp-f9a2c1e8-...",
  "status":     "Failed",
  "stage":      "Installation",
  "error":      "ArtifactInstallFailed",
  "message":    "Failed to install AtlasForm 'EmployeeForm' (form-9104): field 'f3' has an invalid datasource configuration.",
  "rolledBack": true,
  "partialInstall": {
    "installedBeforeFailure": ["ent-2291", "rule-6612"],
    "failedAt": "form-9104"
  }
}

Diagnosing Failures

The failure response includes the stage and error code to help diagnose the problem. Common failure causes:

Error Code	Cause	Resolution
`ArtifactInstallFailed`	The artifact service rejected the artifact definition	Inspect the artifact JSON for invalid configuration
`BrokenReference`	A cross-reference could not be resolved after installation	Verify all referenced artifacts are in the package
`VerificationFailed`	Post-install check failed	Inspect the verification details in the response
`TransactionTimeout`	Installation took longer than the transaction timeout (120s)	Split large packages into smaller ones
`DatabaseError`	Unexpected database error during install	Check database connectivity and retry

Retrying After Failure

After a rollback, the target tenant is clean — you can safely retry the import after fixing the issue. Common retry scenarios:

Artifact configuration issue: Fix the artifact in the source tenant, re-export, and retry the import.
Missing dependency: Install the missing package dependency first, then retry the import.
Database error: Wait for the database to recover, then retry. The import engine is idempotent — a retry produces the same result.

Idempotency Import is idempotent: importing the same package twice with the same conflict strategy produces the same result. A retry after rollback is safe.

← Post-Install Verification