--- id: CON-CRM-REG-002 name: Assignment Policy feature: FEAT-CRM-REG-02 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: observed source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- An assignment policy combines the workspace’s automatic-placement choices with ordered geographic coverage that associates addresses with regions. owned_by: MOD-CRM-REG synonyms: - regional assignment configuration - geographic policy not_to_be_confused_with: - Regional catalogue entries - Manual record placement - Search and eligibility criteria facets: - name: Assignment switch meaning: The workspace chooses whether records participate in automatic regional placement. used_for: Enabling or pausing the assignment behavior. - name: Participating records meaning: 'The selection covers contacts, organizations or both kinds.' used_for: Keeping an unselected record kind under manual control. - name: Address source meaning: Each kind selects its preferred address or an address with a specified type. used_for: Choosing the deciding input for placement. - name: Geographic coverage meaning: 'A rule links postal intervals, states, countries or a fallback to a region.' used_for: Expressing the customer’s regional boundaries. - name: Evaluation order meaning: 'The saved sequence resolves overlapping geographic coverage, with fallback deferred.' used_for: Giving narrow coverage precedence over broader coverage. - name: Rule availability and explanation meaning: An enabled setting controls participation and a note records staff’s explanation. used_for: Temporarily excluding a rule without removing its context. - name: Policy generation meaning: An internal count and a displayed change time identify policy changes. used_for: Comparing current settings with completed recalculation work. - name: Saved-address preview meaning: A preview explains the result of evaluating an address against saved coverage. used_for: Reviewing regional results before applying policy widely. relationships: - to: CON-CRM-REG-001 statement: Policy rules target definitions from the same workspace. provenance: test source: >- services-crm:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js#the capability › refuses a rule naming a region the tenant does not have, naming it - to: CON-CRM-REG-003 statement: Eligible placements use the policy’s deciding inputs. provenance: observed source: 'services-crm:modules/regions/services/region-assignment/region-assignment.ts:reconcileRegionAssignments' - to: CON-CRM-REG-004 statement: Recalculation evaluates saved policy for eligible records. provenance: observed source: 'services-crm:modules/regions/services/region-assignment/region-recalculation.ts:recalculateBatch' lifecycle: - state: never saved meaning: Default configuration disables assignment and contains no rules. how_it_changes: An administrator saves configuration or a client creates its first rule. - state: 'off' meaning: Saved coverage can remain while assignment is paused. how_it_changes: An administrator enables the switch. - state: 'on' meaning: Eligible record kinds participate in address-based placement. how_it_changes: An administrator disables the switch. acted_on_by: - CAP-CRM-REG-003 - CAP-CRM-REG-004 - CAP-CRM-REG-005 - CAP-CRM-REG-006 - CAP-CRM-REG-007 - CAP-CRM-REG-010 - CAP-CRM-REG-015 visible_to: - ACT-CRM-002 - ACT-CRM-003 - ACT-CRM-004 - ACT-CRM-005 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:modules/regions/tests/integration/services/persistence/region-assignment-settings.integration.spec.js - 'services-crm:modules/regions/services/region-assignment/region-assignment.ts' - 'services-crm:modules/regions/services/region-assignment/region-recalculation.ts' supersedes: [] --- # Assignment Policy ## What It Is An assignment policy expresses the customer’s answer to where an address belongs. It combines a workspace switch, a selection of participating record kinds, an address source for each kind and an ordered collection of geographic rules. Staff can use a narrow postal area, a set of states, a set of countries or a fallback to describe the regional map they need. The policy is shared rather than copied onto every person. A contact or organization supplies its deciding address when processing needs a placement. Saved rules then determine the target region. This separation lets administrators alter coverage without editing every record immediately. It also makes the point at which existing records adopt new coverage an explicit operational choice. ## What It Is Not The policy is separate from the catalogue of regional names and from the region currently stored on a record. A saved change can therefore coexist with older placements. It is also separate from a record’s automatic-assignment override, which preserves an individual exception. Geographic coverage here determines placement rather than query eligibility or membership entitlement. ## How It Is Used Administrators inspect saved settings on the Assignment Rules tab and open the separate editor to change them. The editor stages settings, rule edits and ordering together. Staff review validation issues and coverage warnings before saving the draft. Readers can inspect the saved configuration and use address preview without changing the policy. Preview evaluates saved rules, so checking an edited policy means saving it and returning to the view. Integrations can maintain a single rule through the API, although the current console saves the complete policy. These two write paths share settings-version coordination, but whole-list replacement resets individual rule versions and leaves a known concurrency gap. After changing policy, staff use recalculation to update existing eligible placements. ## Its Facets **Assignment switch.** The workspace can pause placement while retaining rules. It may also enable placement before coverage exists. **Participating records.** Contacts, organizations or both can participate. An excluded record kind remains outside automatic regional assignment. **Address source.** Each kind uses its preferred address or an address of one named type. The console’s new-choice filters are narrower than the service’s existence checks. **Geographic coverage.** Each rule holds the criteria appropriate to its kind and names a workspace region. Postal coverage can additionally be restricted to a country. **Evaluation order.** Earlier geographic matches win. Fallback coverage is reserved until other criteria miss, with the final enabled fallback supplying the result. **Rule availability and explanation.** Staff can disable a rule without deleting it and retain a note about its purpose. Notes do not affect matching. **Policy generation.** Writes count policy changes and record a display time. Successful recalculations record the generation under which they began. **Saved-address preview.** Staff receive the region, winning rule and explanation for one address without changing records. ## How It Relates Regional definitions supply the targets, while placements retain the selected region on each record. Recalculation applies the shared policy to existing eligible records. Contact and organization address types provide the named address sources; their ownership remains with record configuration. ## What It Could Become The product should resolve inactive-target matching and whether reversed postal intervals should be refused at save. It should preserve meaningful individual-rule versions across whole-policy replacement before relying on both editing paths concurrently. A future draft-preview experience would need to distinguish unsaved coverage from the currently saved policy.