---
id: WF-CRM-REG-005
title: Import regions from a file
trigger: A client submits a regional import file with both regional bulk and update authority.
product_area: crm
module: regions
revision: 2
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  services-crm: a8d1364f1dd44b723bb5f9acba12f983e9ec8d69
implements:
  - CAP-CRM-REG-014
  - CAP-CRM-REG-001
moves:
  - STATE-CRM-REG-001
crosses:
  - SVC-CRM-REG-regions
  - SVC-PFM-DJE-crm-data-jobs
  - SVC-PFM-DJE-engine
idempotency: >-
  The engine handles submission keys and source-revision deduplication. Regional adapters distinguish insert,
  upsert and update: existing targets reject insert, upsert can create or replace, and update requires a
  target. Reusing an identifier alone does not make every row an update.
concurrency: >-
  Regional replacement locks and compares a version. Shared adapters support reject and overwrite conflict
  policies and can read a current version when none is supplied. The engine owns job scheduling and keyed-item
  coordination; this regional examination does not prove those internals.
hops:
  - 'n': 1
    actor_or_service: Regions API (submitRegionsDataJob)
    action: >-
      The hosted submission checks bulk and update keys, resolves the uploaded source and delegates job
      acceptance and execution startup to the bulk engine.
    anchor: 'services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts:configurationDataJobRoutes'
    seam: sync
    on_failure: >-
      Invalid submission is refused; any execution-start failure after acceptance belongs to the delegated
      engine’s recovery contract.
    left_inconsistent: The regional route alone does not establish whether a failed startup left an accepted job.
    observer: Clients inspect accepted-job responses and job status.
    provenance: observed
    source: 'services-crm:modules/regions/aws/regions.module.ts'
  - 'n': 2
    actor_or_service: Data Job Engine bulk execution
    action: The shared import adapter validates regional row values and reports row rejections before application.
    anchor: 'services-crm:modules/data-jobs/services/operations/configuration-imports.ts:regionImports'
    seam: state_machine
    on_failure: Classified item validation failures become rejections; other failures propagate for engine handling.
    left_inconsistent: Rejected rows are not applied by this validation step.
    observer: 'Results, rejections and job status expose engine-reported outcomes.'
    provenance: observed
    source: >-
      services-crm:modules/data-jobs/services/operations/configuration-imports.ts:regionImports;
      services-crm:modules/data-jobs/services/operations/configuration-import.ts:configurationImportOperation
  - 'n': 3
    actor_or_service: Regions API (applyRegionsDataJob) and the engine's workers
    action: >-
      Application delegates validated items to regional create or versioned replacement. Mapping rejects a
      conflicting workspace and retains accepted lock and integration values; the engine controls worker
      dispatch.
    anchor: 'services-crm:modules/regions/services/persistence/regions.ts:createRegion, updateRegion'
    seam: queue
    on_failure: >-
      The engine reports item or batch failures according to its classification; previously committed rows
      remain applied.
    left_inconsistent: >-
      Partial application can leave a partly changed catalogue. Regional imports provide no compensating
      operation.
    observer: 'The hosted result, rejection and status reads expose application outcomes.'
    provenance: documented
    source: >-
      services-crm:modules/data-jobs/aws/api/bulk-data-jobs.routes.ts (header: no rollback for configuration
      imports)
branches:
  - Imported retirement of an enabled target records the same policy-change stamp as a direct regional save.
  - 'The regional file-import declarations omit assignment rules, which remain policy-owned configuration.'
waits:
  - Application requires the client’s explicit apply request after validation.
evidence:
  - >-
    services-crm at a8d1364f: modules/data-jobs/aws/api/bulk-data-jobs.routes.ts (regionDataJobsRoutes);
    modules/data-jobs/services/operations/configuration-imports.ts (regionImports);
    modules/regions/aws/regions.module.ts; docs/data-jobs.md.
  - >-
    services-crm:modules/data-jobs/services/operations/configuration-import.ts:configurationImportOperations,
    configurationWriteOf, expectedVersionOf
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-DAT-004, TC-IAM-001, TC-IAM-005, TC-IAM-006, 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]
---

# Import regions from a file

## What It Does

Regional file imports populate or change the customer’s catalogue through the shared Data Job Engine. Regions hosts submission, review and control routes, while its adapter validates row values and calls the normal regional persistence functions. Assignment policy is configured separately.

## The Flow

```mermaid
sequenceDiagram
  participant C as Import client
  participant A as Regional hosted routes
  participant J as Data Job Engine
  participant R as Regional persistence
  C->>A: Submit uploaded source
  A->>J: Accept and start bulk work
  J->>J: Validate regional row values
  C->>A: Review results and apply
  A->>J: Authorize application
  loop Accepted items
    J->>R: Insert or versioned replacement
  end
  C->>A: Read outcomes and control job
```

## When Something Fails

Rejected rows and application failures remain inspectable through engine results. Already committed regional changes are not reversed, because these imports declare no compensating operation. Conflict handling depends on reject or overwrite policy and the supplied or resolved version; a changed record is not universally guaranteed to be skipped. Engine startup recovery, retry scheduling and source-key deduplication require the engine’s own proof.

## Open Design Questions

Imports currently accept ordinary writable lock values, inheriting the unresolved audited-lock requirement. Delegated startup recovery and conflict behavior should be linked to the engine’s contract before implementation preparation relies on stronger guarantees. The scoped regional screens expose no file-import control.