InstallHub
Merge Strategy
Merge applies a JSON diff between the existing artifact and the package version — only changed fields are updated. Fields not present in the package are left unchanged. Supported only for config-type artifacts.
Merge Eligibility
| Artifact Type | Merge Supported | Reason |
|---|---|---|
| RuleSet | Yes | Array of rules — add new rules, update existing by ruleId |
| EntitySchema | Yes | Additive field additions; existing fields preserved |
| AppDefinition | Yes | Configuration key-value pairs can be merged |
| ProcessDefinition | No | Graph structure makes automated merge ambiguous and unsafe |
| ThreadDefinition | No | Same as ProcessDefinition |
| AtlasForm | No | Field ordering and action references make merge unreliable |
How Merge Works (RuleSet Example)
// Existing RuleSet in target tenant (rule-6612):
{
"rules": [
{ "ruleId": "r1", "name": "AutoApproveUnder500", "condition": "amount < 500", "action": "APPROVE" },
{ "ruleId": "r2", "name": "RequireApproval", "condition": "amount >= 500", "action": "REQUIRE_APPROVAL" }
]
}
// Package RuleSet (after remap):
{
"rules": [
{ "ruleId": "r1", "name": "AutoApproveUnder500", "condition": "amount < 1000", "action": "APPROVE" },
{ "ruleId": "r3", "name": "HighValueAlert", "condition": "amount >= 5000", "action": "ALERT" }
]
}
// Merge result:
{
"rules": [
{ "ruleId": "r1", "name": "AutoApproveUnder500", "condition": "amount < 1000", "action": "APPROVE" }, // UPDATED
{ "ruleId": "r2", "name": "RequireApproval", "condition": "amount >= 500", "action": "REQUIRE_APPROVAL" }, // UNCHANGED
{ "ruleId": "r3", "name": "HighValueAlert", "condition": "amount >= 5000", "action": "ALERT" } // ADDED
]
}Merge Conflict within a Merge
When the same field is changed in both the existing artifact and the package artifact relative to their common ancestor (three-way merge), the automated merge fails and falls through to manual resolution:
{
"warning": "MergeConflict",
"message": "Automated merge failed for 'ApprovalRules' — field 'rules[0].condition' was changed in both the existing artifact and the package.",
"field": "rules[0].condition",
"existing": "amount < 750",
"package": "amount < 1000",
"action": "Manual resolution required — see POST /api/installhub/.../resolve"
}Merge Diff in ConflictReport
{
"artifactType": "RuleSet",
"artifactName": "ApprovalRules",
"mergeSupported": true,
"mergeDiff": {
"added": ["rules[2]"],
"changed": ["rules[0].condition"],
"removed": [],
"unchanged": ["rules[1]"]
}
}
Use Merge for Additive Updates
Merge is ideal when the package adds new rules or entity fields without removing existing ones. If the package removes items that exist locally, those removals are NOT applied — use Replace if you want the package version to be definitive.