--- id: CAP-CRM-REG-003 title: Configure automatic placement and its address sources feature: FEAT-CRM-REG-02 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-CRM-CFG-016 source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: - >- services-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), Since: 2026-10-14, Andrew: assignment may be on with no rules - >- services-crm:docs/migrations/crm-regions/README.md#2026-10-11 second pass (Andrew, 2026-10-11: rules are managed one at a time; an organization has a preferred address) - >- services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner) - 'services-crm:docs/milestones/CRM-M1-contacts-and-organizations.md#D-05' purpose: >- Administrators choose whether automatic placement applies and identify the address that determines it for each record kind. outcomes: - Automatic assignment can be configured before adding coverage. - Each record kind has an explicit address source. - Invalid settings leave the saved policy intact. concepts: - CON-CRM-REG-002 actors: - ACT-CRM-003 - ACT-CRM-002 surfaces: - console - api preconditions: [] postconditions: [] permissions: - key: crm.regions.read where_checked: api scope: tenant - key: crm.regions.update where_checked: api scope: tenant rules: - id: BR-CAP-CRM-REG-003-01 proved_by: [ATS-CRM-REG-003-01, TST-CRM-REG-047, TST-CRM-REG-050, TST-CRM-REG-051] statement: >- Without saved settings, automatic assignment is off, contacts use their preferred address, organizations use the seeded Main address type, both kinds are selected and the policy has no rules. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js#the capability › answers assignment off, the legacy defaults and no rules for a tenant that saved none origin: none - id: BR-CAP-CRM-REG-003-02 proved_by: [ATS-CRM-REG-003-02, TST-CRM-REG-047, TST-CRM-REG-050, TST-CRM-REG-057] statement: 'Automatic assignment can be enabled with an empty policy, whose matching result is no region.' kind: policy enforced_at: - service must_prove: true provenance: observed source: >- services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#switches assignment on with an empty rule list, and reads back on with no rules; services-crm:modules/regions/services/persistence/region-assignment-settings.ts:assignsAutomatically origin: >- services-crm:docs/migrations/crm-regions/README.md#2026-10-12 — Final acceptance (second pass), Since: 2026-10-14, Andrew: assignment may be on with no rules - id: BR-CAP-CRM-REG-003-03 proved_by: [ATS-CRM-REG-003-03, TST-CRM-REG-057, TST-CRM-REG-058, TST-CRM-REG-063] statement: >- The settings select contacts, organizations or both, and automatic placement skips a record kind outside that selection. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js#assignment switched off › gives a contact created while only organizations are assigned no region origin: none - id: BR-CAP-CRM-REG-003-04 proved_by: [ATS-CRM-REG-003-04, ATS-CRM-REG-003-08, ATS-CRM-REG-008-15, TST-CRM-REG-048, TST-CRM-REG-050] statement: >- Each record kind uses either its preferred address or a specified address type; the type choice requires a type identifier, and the preferred choice discards one supplied with it. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js#the capability › refuses the type setting with no contact address type id origin: none - id: BR-CAP-CRM-REG-003-05 proved_by: [ATS-CRM-REG-003-05, TST-CRM-REG-048, TST-CRM-REG-050] statement: >- A deciding address type must exist in the workspace regardless of its applicability label, and cannot be deleted while the settings reference it. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js#the capability › refuses a contact address type id the tenant has no address type for origin: none - id: BR-CAP-CRM-REG-003-06 proved_by: [] statement: >- Organizations can use a preferred address; omission of their address-source choice means a named type, defaulting to Main if the type is also omitted. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js#an organization decided by its preferred address › decides by the address the organization marked preferred, not by its main address origin: >- services-crm:docs/migrations/crm-regions/README.md#2026-10-11 second pass (Andrew, 2026-10-11: rules are managed one at a time; an organization has a preferred address) - id: BR-CAP-CRM-REG-003-07 proved_by: [ATS-CRM-REG-003-09] statement: >- A settings replacement supplies the automatic-assignment switch and address choices as a whole, with defaults applied to omitted fields. kind: policy enforced_at: - api must_prove: false provenance: test source: >- services-crm:modules/regions/tests/e2e/regions.e2e.spec.js#saves the settings, defaulting what the body left out origin: none - id: BR-CAP-CRM-REG-003-08 proved_by: [ATS-CRM-REG-003-06, TST-CRM-REG-050] statement: Settings replacement rejects a supplied stale version but accepts a request that omits the version. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js#the capability › refuses a save from a stale read origin: none - id: BR-CAP-CRM-REG-003-09 proved_by: [ATS-CRM-REG-003-07, TST-CRM-REG-050] statement: >- Settings validation reports its collected problems together and commits no changes when validation fails. kind: validation enforced_at: - service must_prove: true provenance: observed source: >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js#the capability › leaves the saved rules as they were when a save is refused; services-crm:modules/regions/services/persistence/region-assignment-settings.ts:assertRegionAssignmentSettingsValid origin: none - id: BR-CAP-CRM-REG-003-10 proved_by: [] statement: >- The console asks for an address source only for selected record kinds, filters types by their applicability and retains an already selected type. kind: policy enforced_at: - console must_prove: false provenance: test source: >- react-console:components/regions/__tests__/assignment-rules-editor.test.tsx#the settings on the editor › ask for an address only for a kind that is assigned origin: none - id: BR-CAP-CRM-REG-003-11 proved_by: [] statement: >- The Assignment Rules tab presents saved settings without editing controls; a separate editor and save bar handle changes, and disabled assignment leaves only the summary visible. kind: policy enforced_at: - console must_prove: false provenance: test source: >- react-console:components/regions/__tests__/assignment-rules-view.test.tsx#the Assignment Rules view › is read-only: no switch, no choices, no rule controls and no save bar origin: >- services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner) - id: BR-CAP-CRM-REG-003-12 proved_by: [] statement: >- The editor stages and counts changes, Cancel discards the draft and navigation requests confirmation before losing unsaved work. kind: policy enforced_at: - console must_prove: false provenance: test source: >- react-console:components/regions/__tests__/assignment-draft.test.ts#the count of unsaved changes › counts the switch and each setting once origin: none - id: BR-CAP-CRM-REG-003-13 proved_by: [] statement: >- The Regions page preserves its two-tab selection in the URL; without an explicit tab it opens Assignment Rules when assignment is enabled and Regions otherwise. kind: policy enforced_at: - console must_prove: false provenance: test source: >- react-console:components/regions/__tests__/tabs.test.ts#the tab chosen when the URL names none › opens the rules when automatic assignment is on, because the rules then decide where records go origin: >- services-crm:docs/migrations/crm-regions/README.md#2026-10-15 — Final acceptance (console follow-ups) (Andrew approved 2026-10-15: two tabs, Test an Address dialog, drawers, a read-only Assignment Rules tab with its own editor screen and the banner) scenarios: - id: SC-CAP-CRM-REG-003-01 given: Member placement uses a preferred address and company placement uses the main office. when: An administrator enables both kinds with those address sources. then: Reads return the saved settings while current placements remain unchanged. provenance: test source: 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0357.spec.ts#CRM-ACC-0357' - id: SC-CAP-CRM-REG-003-02 given: Contact placement is configured by a named address type. when: An administrator saves without identifying that type. then: Validation reports the missing type and commits nothing. provenance: test source: >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js#the capability › refuses the type setting with no contact address type id edge_cases: - id: SC-CAP-CRM-REG-003-03 given: Billing is labelled for organizations but selected as the contact source. when: A client saves the configuration. then: The service accepts the workspace type even though the console filters it from new contact choices. provenance: test source: >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js#the capability › takes a contact address type marked for organizations, applies_to being a guide and not a rule constraints: [] depends_on: [] related: - CAP-CRM-REG-004 - CAP-CRM-REG-008 - CAP-CRM-REG-010 journeys: - JNY-CRM-REG-001 open_questions: [] evidence: - >- services-crm: Examined the pinned regional implementation, its declared constraints and the supporting records. - 'react-console: Examined the pinned regional configuration surfaces and their available test evidence.' - 'services-crm:docs/migrations/crm-regions/README.md' - 'services-crm:docs/milestones/CRM-M1-contacts-and-organizations.md' - >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js - 'services-crm:modules/regions/tests/e2e/regions.e2e.spec.js' - 'services-crm:modules/regions/services/persistence/region-assignment-settings.ts' - >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment.integration.spec.js - >- services-crm:modules/regions/tests/integration/services/region-assignment/region-assignment-rules.integration.spec.js - 'react-console:components/regions/__tests__/assignment-rules-editor.test.tsx' - 'react-console:components/regions/__tests__/assignment-rules-view.test.tsx' - 'react-console:components/regions/__tests__/assignment-draft.test.ts' - 'react-console:components/regions/__tests__/tabs.test.ts' - 'react-console:acceptance/crm/playwright/journeys/configuration/CRM-ACC-0357.spec.ts' controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-DAT-001, TC-DAT-003, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-003, TC-TEN-001, TC-TEN-002, TC-TEN-003] exercised_by: [FAS-CRM-REG-02-01, FAS-CRM-REG-02-03, FAS-CRM-REG-02-04] suites: [TST-CRM-REG-047, TST-CRM-REG-048, TST-CRM-REG-050, TST-CRM-REG-051, TST-CRM-REG-057, TST-CRM-REG-058, TST-CRM-REG-063] --- # Configure automatic placement and its address sources ## Purpose Administrators choose whether automatic placement applies and identify the address that determines it for each record kind. ## How It Works An administrator opens the separate Assignment Rules editor to configure placement. They select which record kinds participate and choose a preferred or typed address source for each. The organization’s omitted source retains the Main-type default. The editor stages these choices with the policy and shows the amount of unsaved work. Cancel abandons the draft; leaving a changed draft requires confirmation. Saved settings appear on the read-only tab. API replacement can omit the version, while a supplied stale version conflicts. Validation retains the previous configuration when it rejects a replacement. The console filters new address-type choices more narrowly than the service. ## Relationships - Build the geographic assignment policy maintains the geographic policy that other regional workflows evaluate. - Keep placements aligned with address changes coordinates placement after committed address changes. - Identify placements that need recalculation identifies policy generations still needing application.