Conflict Resolution Overview — Conflict Resolution

What is a Conflict?

A conflict arises when:

The package contains an artifact of type AtlasForm named EmployeeForm
AND the target tenant already has an AtlasForm named EmployeeForm

The import engine detects this during the ID remapping phase. The existing artifact in the target tenant has a known ID; the package artifact has been remapped to a new ID. A conflict exists — the engine must decide whether to overwrite, merge, or leave the existing artifact.

Three Conflict Strategies

Replace Destructive

The existing artifact is overwritten by the package version. The existing artifact's data is permanently replaced. Previous versions are not automatically preserved (though they may exist in export history if previously exported).

Best for: Environment promotion (dev → staging → prod) where you always want the latest version from the source.

Merge Selective

The engine computes a JSON diff between the existing artifact and the package version, and applies only the changed fields. Fields not present in the package version are left unchanged in the existing artifact.

Supported for: RuleSet, EntitySchema, AppDefinition (pure JSON config). Not supported for ProcessDefinition, ThreadDefinition, or AtlasForm (complex nested structures where automated merge is unreliable).

Best for: Additive updates where local customizations should be preserved.

Skip Safe

The existing artifact is left completely unchanged. The package artifact is not installed for this artifact — the conflict is silently skipped. The import continues with other non-conflicting artifacts.

Best for: Installing a package that may contain artifacts the target tenant has already customized — protect local modifications.

Strategy Selection

Strategies can be applied at two levels:

Default strategy: Set in ImportOptions.defaultConflictStrategy — applied to all conflicts that don't have a per-artifact override.
Per-artifact override: For manual resolution, the administrator can choose a different strategy for each conflicting artifact individually.

ConflictReport

Before the installation stage begins, the engine generates a ConflictReport listing all detected conflicts:

{
  "conflictsFound": 2,
  "conflicts": [
    {
      "artifactType":      "AtlasForm",
      "artifactName":      "EmployeeForm",
      "packageVersion":    "1.3.0",
      "existingVersion":   "1.0.0",
      "proposedStrategy":  "Replace",
      "mergeSupported":    false
    },
    {
      "artifactType":      "RuleSet",
      "artifactName":      "ApprovalRules",
      "packageVersion":    "1.2.0",
      "existingVersion":   "1.1.0",
      "proposedStrategy":  "Merge",
      "mergeSupported":    true,
      "mergeDiff": {
        "added":   ["rules[2]"],
        "changed": ["rules[0].priority"],
        "removed": []
      }
    }
  ]
}

Conflict Resolution in Unattended Imports

For CI/CD pipeline imports, set defaultConflictStrategy in ImportOptions to run without human interaction. The engine applies the strategy to all conflicts automatically:

{
  "defaultConflictStrategy": "Replace",
  "dryRun":                  false
}

Replace is Irreversible The Replace strategy overwrites the existing artifact permanently. If you need to preserve the previous version, export it before running the import, or enable the "backup before replace" option in ImportOptions.

Next: Conflict Detection →