Replace Strategy

When to Use Replace

• Promoting a workflow from dev to staging — staging should always match dev exactly
• Deploying a new version of a workflow to all customer tenants — every tenant must run the same version
• Restoring an artifact from a backup package
• Automated CI/CD pipelines where the source is always authoritative

How Replace Works

When the Replace strategy is applied to a conflicting artifact:

1. The import engine identifies the existing artifact's ID in the target tenant
2. The package artifact's definition (with remapped IDs) is used to UPDATE the existing artifact record — not INSERT a new one
3. The existing artifact retains its original ID in the target tenant (the package ID is discarded in favor of the existing one)
4. The artifact version field is updated to the package version
5. All other properties are replaced with the package values

// Before import:
Existing: { id: "form-9104", name: "EmployeeForm", version: "1.0.0", fields: [3 fields] }

// After Replace:
Updated:  { id: "form-9104", name: "EmployeeForm", version: "1.3.0", fields: [6 fields] }
// Same ID, new content

Backup Before Replace Option

Enable the backupBeforeReplace option in ImportOptions to automatically export the existing artifact before replacing it. The backup is stored as a single-artifact package in the export history:

{
  "defaultConflictStrategy": "Replace",
  "backupBeforeReplace":     true  // default: false
}

This allows you to re-import the backup package to restore the previous version if needed.

Version Downgrade Warning

If the package version is lower than the existing artifact version (downgrade), the engine displays a warning and requires explicit confirmation unless allowVersionDowngrade: true is set:

{
  "warning": "VersionDowngrade",
  "message": "Replacing 'EmployeeForm' v1.5.0 (existing) with v1.3.0 (package). This is a version downgrade.",
  "existingVersion": "1.5.0",
  "packageVersion":  "1.3.0"
}

Audit Log Entry

{
  "action":           "Replace",
  "artifactType":     "AtlasForm",
  "artifactName":     "EmployeeForm",
  "artifactId":       "form-9104",
  "previousVersion":  "1.0.0",
  "replacedWith":     "1.3.0",
  "importId":         "imp-f9a2c1e8-...",
  "resolvedBy":       "engineer@company.com",
  "resolvedAt":       "2026-05-25T10:30:00Z"
}