--- id: CAP-CRM-REG-014 title: Import a catalogue of regions feature: FEAT-CRM-REG-01 product_area: crm module: regions revision: 2 status: draft product_intent: proposed implementation_evidence: partially-observed supersedes: [] source_sha: services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f intent_sources: [] purpose: Authorized integrations load regional configuration from files through the shared data-job workflow. outcomes: - Valid file rows use regional persistence; rejected rows retain an explanation. concepts: - CON-CRM-REG-001 actors: - ACT-CRM-004 - ACT-CRM-003 surfaces: - api - job preconditions: [] postconditions: [] permissions: - key: crm.regions.bulk where_checked: api scope: tenant - key: crm.regions.update where_checked: api scope: tenant rules: - id: BR-CAP-CRM-REG-014-01 proved_by: [ATS-CRM-REG-013-07, ATS-CRM-REG-014-01, ATS-CRM-REG-014-04, TST-CRM-REG-023, TST-CRM-REG-067] statement: >- Every regional import operation requires both bulk and update authority and cannot be used with read authority alone. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-crm:tests/unit/regions-authorization.spec.ts#the data jobs of regions, which are the configuration data-job routes under /regions › requires crm.regions.bulk AND crm.regions.update of every one of them, which the read key alone does not give origin: none - id: BR-CAP-CRM-REG-014-02 proved_by: [ATS-CRM-REG-014-02, TST-CRM-REG-067] statement: >- Regional import exposes twelve operations covering submission, job listing and reading, source-key lookup, results, rejections, application, pause, resume, cancel, retry and conflict revalidation. kind: policy enforced_at: - api must_prove: true provenance: test source: >- services-crm:tests/unit/regions-authorization.spec.ts#the data jobs of regions, which are the configuration data-job routes under /regions › publishes the twelve routes a job of regions has: the submission, the list, the status, the lookup by source key, the two pages, the apply, the four control actions and the revalidation of conflicts origin: none - id: BR-CAP-CRM-REG-014-03 proved_by: [ATS-CRM-REG-001-10, ATS-CRM-REG-014-03, ATS-CRM-REG-014-04, ATS-CRM-REG-014-05] statement: >- Imported region rows use the same validation and persistence as direct creation or replacement, including identifier, name and workspace checks. kind: validation enforced_at: - service must_prove: true provenance: observed source: 'services-crm:modules/data-jobs/services/operations/configuration-imports.ts:regionImports' origin: none - id: BR-CAP-CRM-REG-014-04 proved_by: [] statement: Region imports can supply external identifiers and locks accepted by ordinary creation. kind: policy enforced_at: - service must_prove: false provenance: observed source: 'services-crm:modules/data-jobs/services/operations/configuration-imports.ts:regionImports' origin: none - id: BR-CAP-CRM-REG-014-05 proved_by: [] statement: >- The acceptance catalogue describes no regional import control in the console, leaving this workflow available through API operations. kind: policy enforced_at: - console must_prove: false provenance: documented source: 'react-console:acceptance/crm/inventory/capabilities.json#CAP-CRM-CFG-022' origin: none - id: BR-CAP-CRM-REG-014-06 proved_by: [ATS-CRM-REG-014-05] statement: >- The Data Job Engine owns job execution and controls; Regions hosts the regional routes and delegates the row writes. kind: policy enforced_at: - service must_prove: false provenance: observed source: >- services-crm:modules/regions/aws/api/regions.routes.ts:regionsModuleRoutes; services-crm:modules/regions/aws/regions.module.ts:regionsModule origin: none scenarios: - id: SC-CAP-CRM-REG-014-01 given: An integration prepares a file containing a chapter catalogue. when: It submits and applies the regional data job. then: Valid rows become regions and an identifier containing a space is rejected. provenance: inferred source: 'services-crm:modules/data-jobs/services/operations/configuration-imports.ts:regionImports' edge_cases: [] constraints: [] depends_on: - CAP-CRM-REG-001 related: - CAP-CRM-REG-001 - CAP-CRM-REG-013 journeys: [] 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:tests/unit/regions-authorization.spec.ts' - 'services-crm:modules/data-jobs/services/operations/configuration-imports.ts' - 'react-console:acceptance/crm/inventory/capabilities.json' - 'services-crm:modules/regions/aws/api/regions.routes.ts' - 'services-crm:modules/regions/aws/regions.module.ts' controls: [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-003, 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-TEN-001, TC-TEN-002, TC-TEN-003] exercised_by: [FAS-CRM-REG-01-02] suites: [TST-CRM-REG-023, TST-CRM-REG-067] --- # Import a catalogue of regions ## Purpose Authorized integrations load regional configuration from files through the shared data-job workflow. ## How It Works An integration submits a regional file through the shared data-job surface. Every regional job operation requires bulk and update authority together. The hosted routes expose submission, inspection, results and job controls. The Data Job Engine carries out processing and reports row outcomes. Regional row mapping applies the same schema and persistence used by direct regional writes. Invalid identifiers, unusable names or conflicting workspace values can reject a row. Accepted inputs can carry external identifiers and locks. The console currently provides no regional file-import action. Product can decide whether a customer-facing import flow is needed without duplicating the job engine’s responsibilities. ## Relationships - Maintain the region catalogue supplies the regional catalogue used by the surrounding work. - Restrict regional work to authorised users defines authority for the regional workflow.