Combine organizations and their connections safely

Purpose

Administrators can combine organizations while preserving a valid hierarchy and the people linked to it.

How It Works

The organization preview compares names, domains, types and contact details. It excludes participants and their descendants from possible survivor parents. Existing parent links between participants disappear with a warning rather than creating a cycle. Children move to the survivor. The plan retains one primary domain and combines distinct alternatives. Different organization types create a choice and a caution about whether the records describe the same organization. Affiliations move with their roles, combining equivalent stays where needed. Linked employee contact details follow retained organization details or become copies if no source of that type remains. The plan enforces size limits and warns when people may wait for edits. Compliance and automatic region assignment are recalculated after execution. Approval includes the affiliations that move, not merely their count.

Relationships

Decision review governs organization choices. Related-record policies cover child and affiliation references. Atomic execution applies the same safety boundary as contact merging.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes: People from both organizations retain affiliations to the survivor.Parent and child movements preserve an acyclic hierarchy.Size refusals and warnings make unusually large work visible.
Surfaces: consoleapi
Constraints: Near the affiliation ceiling, execution can take several minutes within the durable job limit.
Intent sources: services-crm:docs/merging/decisions.md#D7 (decided 2026-10-12), D9 and D10 (decided 2026-10-14)services-crm:docs/merging/conflict-resolution.md#4. Collection rules (organization merge re-points links, Andrew 2026-10-13)services-crm:docs/merging/experience/functional-requirements.md#ORG-2 to ORG-8 (package approved by Andrew 2026-10-13)

Controls

29 controls apply, from the corpus control catalogue.

TC-AVL-004 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-MON-001 TC-MON-002 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-PRV-001 TC-PRV-002 TC-PRV-003 TC-TEN-001 TC-TEN-002 TC-TEN-003

Permissions

Key	Checked at	Scope
`crm.organizations.merge`	api	tenant
`crm.organizations.read`	api	tenant

Business Rules

10 rules, 9 to be proved before approval. A rule's product intent is derived from its origin: 10 confirmed by a product decision, the rest inheriting this capability's confirmed.

Id	Rule	Kind	Enforced at	Provenance
`01`must prove Confirmed	The survivor's parent can only be outside participants and their descendants; internal parent links are removed with a cycle warning and children of absorbed organizations re-parent to the survivor. origin: services-crm:docs/merging/experience/functional-requirements.md#ORG-2 no proof recorded yet	validation	service, database	test services-crm:modules/merges/tests/unit/services/planning/organization-hierarchy.spec.js#says the link it removed would have made a cycle
`02`must prove Confirmed	One primary domain remains, defaulting to the survivor's, distinct remaining domains become alternates and boolean flags combine automatically. origin: services-crm:docs/merging/experience/functional-requirements.md#ORG-5 no proof recorded yet	calculation	service	test services-crm:modules/merges/tests/unit/services/planning/organization-fields.spec.js#unions every other distinct domain into the alternate domain names
`03`must prove Confirmed	Different organization types create a type question and a warning about separate branches without blocking execution. origin: services-crm:docs/merging/experience/functional-requirements.md#ORG-7 no proof recorded yet	policy	service	test services-crm:modules/merges/tests/unit/services/planning/organization-decisions.spec.js#asks which type the survivor keeps and warns that they may not be duplicates at all
`04`must prove Confirmed	Affiliations and roles move to the survivor, equivalent stays combine into its affiliation with primary status if either held it and discarded details are listed. origin: services-crm:docs/merging/experience/functional-requirements.md#ORG-6 no proof recorded yet	lifecycle	service	test services-crm:modules/merges/tests/integration/services/merges/organization-merge-execution.integration.spec.js#combines the two stays of somebody who worked at both into the survivor’s own affiliation
`05`must prove Confirmed	Organization merges above 100,000 affiliation writes, including combined-away rows, are rejected; large plans explain affected people, duration and editing waits. origin: services-crm:docs/merging/decisions.md#D7 (decided 2026-10-12: a ceiling of 100,000 employees) no proof recorded yet	validation	service	test services-crm:modules/merges/tests/unit/services/planning/organization-decisions.spec.js#refuses a merge of 100,001 affiliations
`06`must prove Confirmed	Linked employee details retain kept source records, redirect discarded slots to the retained same-type detail or copy their last value when no detail of that type remains, with each changed link recorded. origin: services-crm:docs/merging/conflict-resolution.md#4. Collection rules (organization merge re-points links, Andrew 2026-10-13) no proof recorded yet	lifecycle	service	test services-crm:modules/merges/tests/integration/services/merges/organization-merge-execution.integration.spec.js#re-points a link to a record that lost its slot to the record of its type the merge kept
`07`must prove Confirmed	The result keeps one address and phone per type, lists discarded items and retains exactly one preferred address selected by the plan. no proof recorded yet	calculation	service, database	test services-crm:modules/merges/tests/integration/services/merges/organization-merge-preferred-address.integration.spec.js#carries the merge out, rather than failing on the preferred-address index
`08`must prove Confirmed	Organization role compliance and region assignment are recomputed after merging rather than offered as choices. origin: services-crm:docs/merging/experience/functional-requirements.md#ORG-8 no proof recorded yet	calculation	service	test services-crm:modules/merges/tests/unit/services/planning/organization-fields.spec.js#never offers the contact role compliance status and recomputes it after the merge
`09`must prove Confirmed	Adding, removing or editing an affiliation that the merge moves invalidates the approved preview, even without an affiliation combination. origin: services-crm:docs/milestones/CRM-M4-duplicates-and-merge.md#D-31 no proof recorded yet	policy	service	observed services-crm:modules/merges/services/planning/merge-engine.ts:materialPlanHash
`10` Confirmed	An organization locked against changes cannot participate in a merge.	validation	service	test services-crm:modules/merges/tests/unit/services/planning/organization-decisions.spec.js#blocks a merge of a locked organization

Scenarios

Id	Given	When	Then	Provenance
`01`	Two organizations have children, employees, domains and a person affiliated to both.	An administrator combines them.	The absorbed domain becomes an alternate, children and people move and the overlapping stay combines.	test react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0270.spec.ts#CRM-ACC-0270
`02`	Employees link work addresses from the absorbed organization.	The plan retains the survivor's address of that type.	Employee links redirect to that address and each change is recorded.	test react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0282.spec.ts#CRM-ACC-0282

Edge Cases

Id	Given	When	Then	Provenance
`03`	An organization and its descendant participate together.	The administrator opens their preview.	Neither an excluded descendant nor the internal link can become the survivor's parent, and the removed link is explained.	test react-console:acceptance/crm/playwright/journeys/merging/CRM-ACC-0271.spec.ts#CRM-ACC-0271

Planning

Combine organizations and their connections safely ​

Purpose ​

How It Works ​

Relationships ​