# Import data

**Flow key:** `import-data`

## Outcome

An authorized user previews, maps, validates, commits, and reconciles an import without silent loss, duplicate side effects, or cross-tenant writes.

## Actors

- User/admin
- Import service
- Record store
- Background worker

## Preconditions and entry points

- Synthetic files cover valid, partially invalid, duplicate, Unicode, and boundary row counts.
- Schema, mapping, atomicity, and rollback policy are known.

## Required test data

Use synthetic, isolated, resettable data. Never use real credentials, payment instruments, private customer records, or production notifications.

| Data | Canonical valid seed | Critical variations |
|---|---|---|
| Source | `carbon-import-valid.csv` with 10 rows | empty, header-only, malformed, old schema, Unicode/emoji, mixed line endings |
| Rows | stable external IDs `CARBON-IMP-001..010` | duplicate, missing required, wrong type, unauthorized relation |
| Mapping | name/status/owner mapping | unmapped required, unknown column, transformed value |
| Mode | create new | upsert, update-only, dry-run, partial acceptance |
| Scale | 10 rows | 1, boundary batch, supported maximum |

## Canonical steps

Treat this as the ordinary successful path inferred from common product behavior. Adapt it to observed labels, business rules, APIs, and implementation evidence; do not invent a requirement.

| Step | User or system action | Expected evidence |
|---:|---|---|
| 1 | Open import and upload/select the source. | Format, encoding, row count, and detected schema are accurate. |
| 2 | Map fields and choose import mode. | Required, ignored, transformed, related, and unknown fields are explicit. |
| 3 | Run preview/validation. | Row-level errors, duplicates, permissions, and proposed effects are inspectable without mutation. |
| 4 | Commit once. | One versioned job starts with stable source hash and idempotency. |
| 5 | Monitor completion. | Counts for created/updated/skipped/failed reconcile to source and transaction policy. |
| 6 | Inspect records, error export, audit, and retry. | Persisted values are exact and retry cannot duplicate successful rows. |

## Alternate paths

- Create-only
- Upsert
- Partial import
- All-or-nothing import
- Scheduled/background import

## Failure and recovery paths

- Worker crashes mid-batch
- Schema changes after preview
- Duplicate job submission
- Permission changes mid-import
- Rollback or error export fails

## Completion oracle

- The stated outcome is true in visible UI and authoritative persisted state.
- Exactly one intended business result and no unintended side effect occurred.
- Identity, tenant, authorization, money/data, lifecycle, notifications, integrations, analytics, and audit agree where applicable.
- Refresh, retry, back/forward, and a second authorized read do not reveal a contradictory result.
- Any partial, delayed, canceled, failed, or unknown outcome is labeled truthfully and has a safe recovery path.

## Evidence to capture

- Entry context, actor, tenant, role, feature flags, locale, time zone, and initial identifiers/state.
- Step-level screenshots or DOM state plus request/response, correlation, job, event, and stable business IDs where available.
- Before/after authoritative records, versions, totals, permissions, lifecycle states, and downstream side effects.
- Notifications, audit events, integration deliveries, retries, deduplication, latency, and recovery evidence.
- Untested branches, unsafe-to-run cases, product decisions, and evidence tier.

## Product decisions to resolve

- Exact eligibility, required data, authorization, and validation rules.
- Which steps are synchronous, asynchronous, optional, skippable, reversible, or irreversible.
- Idempotency, concurrency, timeout, retry, cancellation, and compensation semantics.
- Retention, privacy, notification, audit, performance, accessibility, and localization commitments.

## Related CARBON items

- [import](../../items/content/import.md)
- [upload and file input](../../items/content/upload-and-file-input.md)
- [json and structured payload](../../items/organization/json-and-structured-payload.md)
- [concurrency and idempotency](../../items/quality/concurrency-and-idempotency.md)

[Back to Productivity and collaboration flows](index.md)
