--- id: CON-CRM-REG-001 name: Region feature: FEAT-CRM-REG-01 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: inconsistent source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f definition: >- A region is a customer-defined grouping for contacts and organizations, often representing a chapter, territory or residual geographic area. owned_by: MOD-CRM-REG synonyms: - chapter grouping - regional territory not_to_be_confused_with: - Chapter organization records - Geographic criteria - Address-purpose classification facets: - name: Stable identifier meaning: >- The region’s lasting reference uses a supplied or generated identifier with the legacy character grammar. used_for: 'Connecting records, policies and external imports to the same region.' - name: Display information meaning: A required trimmed name and optional description explain the regional group. used_for: Helping staff recognize a region in lists and choices. - name: Availability meaning: The active setting distinguishes available regions from retired catalogue entries. used_for: Retaining existing references while signalling retirement. - name: Protection and integration key meaning: The record can hold a deletion or full lock and an external identifier. used_for: Restricting ordinary writes and relating imported definitions to another system. - name: Dependencies meaning: 'Contacts, organizations and policy rules can reference a region.' used_for: Preventing removal while a regional reference remains in use. - name: Metadata and export meaning: The platform registers regional references and exports the saved catalogue. used_for: Sharing the definitions with record workflows and exported data. relationships: - to: CON-CRM-REG-002 statement: Rules can share one regional target. provenance: observed source: 'services-crm:modules/regions/db/region-assignment-settings.table.ts:regionAssignmentRules' - to: CON-CRM-REG-003 statement: A record references at most one regional definition. provenance: observed source: 'services-crm:modules/regions/db/regions.table.ts' - to: CON-CRM-ENT-001 statement: Contact references prevent deletion of their regional target. provenance: test source: >- services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#references › refuses to delete a region a contact is in, naming what uses it - to: CON-CRM-ENT-002 statement: Organization references prevent deletion of their regional target. provenance: test source: >- services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js#references › refuses to delete a region an organization is in lifecycle: - state: active meaning: Available for ordinary regional selection. how_it_changes: Staff deactivate the definition. - state: inactive meaning: Retired while existing references remain intact. how_it_changes: Staff reactivate it or remove it after dependencies disappear. - state: deleted meaning: Permanently removed from the catalogue. how_it_changes: Deletion requires the absence of references and is not reversed. acted_on_by: - CAP-CRM-REG-001 - CAP-CRM-REG-002 - CAP-CRM-REG-006 - CAP-CRM-REG-013 - CAP-CRM-REG-014 - CAP-CRM-REG-015 visible_to: - ACT-CRM-001 - 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/db/region-assignment-settings.table.ts' - 'services-crm:modules/regions/db/regions.table.ts' - 'services-crm:modules/regions/tests/integration/db/regions.table.integration.spec.js' supersedes: [] --- # Region ## What It Is A region gives staff a name for a group of people and organizations they work with together. An association might use regions for its chapters, a service organization for its territories, or a customer for a broad residual area outside its usual coverage. The grouping belongs to the customer’s workspace and supplies a common reference for records and geographic policy. An administrator establishes the catalogue in CRM configuration. Each entry has a stable identifier, a name, an optional description and an active setting. The identifier allows a rule or record to continue referring to the same entry after its name changes. Integration work can supply an external identifier alongside that regional identity. The catalogue contains definitions rather than copies of the people assigned to them. ## What It Is Not A regional definition does not itself describe a geographic boundary. The assignment policy provides that coverage and can use several geographic rules for the same target. A chapter may also have an organization record, but that record and its regional grouping have separate purposes. Country, state and postal values are geographic inputs, while address types describe which part of a record supplies an address. ## How It Is Used Administrators maintain the catalogue, readers inspect it and integrations can load definitions from files. Coordinators encounter regional references while working with people and organizations. A useful catalogue uses names staff can distinguish and descriptions where the distinction needs explanation. The Regions tab shows the available definitions and permits authorized editing through a drawer. Retiring an entry preserves the references already held by records and policy. Removal is possible only after dependencies are gone. The current implementation does not make an inactive policy target stop receiving automatic placements. Staff therefore need to consider the policy as well as the catalogue when closing a regional group. The acceptance tests also record shortcomings in the display of existing inactive choices on contact screens. ## Its Facets **Stable identifier.** This reference survives ordinary edits and accepts the legacy regional character grammar. It supports both staff-created definitions and integration inputs. **Display information.** The name is required; the description provides optional context. Naming alone does not constrain which geographic rules can target the region. **Availability.** Active and inactive distinguish ordinary use from retirement. Existing references remain intact when availability changes. **Protection and integration key.** Locks restrict deletion or both editing and deletion. Their current treatment as ordinary writable fields differs from the recorded policy for audited lock actions. **Dependencies.** Regional references connect contacts, organizations and rules to the definition. A dependency prevents deletion and supplies the category named in the refusal. **Metadata and export.** Platform metadata makes the regional object available for record references, while workspace export includes the catalogue, including inactive definitions. ## How It Relates The assignment policy chooses target regions, and regional placement records the resulting choice on a person or organization. A recalculation changes eligible placements under the saved policy without recreating the catalogue. Contacts and organizations own their regional references; Regions owns the definitions those references identify. ## What It Could Become The product should settle whether an inactive target remains eligible for automatic assignment and provide a retirement experience consistent with that decision. The product should also apply the recorded audited lock policy to regional definitions. Custom fields are excluded by the recorded CRM decision, so adding them would require a new product choice.