# Entity: Migration job

Batch import job for onboarding org data from Excel/CSV — departments, packages, members, overrides, dependants, verification IDs.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

## Fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `id` | `string` | ✓ | `mig_*` |
| `org_id` | `string` | ✓ | |
| `created_by` | `string` | ✓ | User id |
| `dataset_type` | `MigrationDatasetType` | ✓ | |
| `status` | `MigrationJobStatus` | ✓ | |
| `file_name` | `string` | ✓ | Original upload |
| `file_storage_key` | `string` | | Server-side blob ref |
| `column_mapping` | `ColumnMapping` | | Source → canonical |
| `mapping_profile_id` | `string` | | Saved profile for reuse |
| `validation` | `ValidationReport` | | After parse |
| `preview` | `PreviewSummary` | | Before commit |
| `commit_result` | `CommitResult` | | After commit |
| `error_report_url` | `string` | | Downloadable CSV of failures |
| `rollback_until` | `Timestamp` | | Soft rollback window |
| `started_at` | `Timestamp` | | |
| `completed_at` | `Timestamp` | | |
| `created_at` | `Timestamp` | ✓ | |
| `updated_at` | `Timestamp` | ✓ | |

### MigrationDatasetType

```
departments | packages | members | overrides | dependants | verification_ids | full_onboarding_pack
```

### MigrationJobStatus

```
uploaded | mapping | validating | validated | preview_ready | committing | completed | failed | rolled_back
```

### ColumnMapping

```typescript
Record<string, string> // sourceColumn → canonicalField
// e.g. { "Dept Name": "department_name", "Emp ID": "employee_id" }
```

### ValidationReport

| Field | Type |
|-------|------|
| `total_rows` | `integer` |
| `error_count` | `integer` |
| `warning_count` | `integer` |
| `rows` | `ValidationRow[]` |

### ValidationRow

| Field | Type |
|-------|------|
| `row_number` | `integer` |
| `severity` | `error` \| `warning` |
| `code` | `string` |
| `message` | `string` |
| `field` | `string` |

Common validation codes: `MISSING_REQUIRED`, `DUPLICATE_IN_FILE`, `DUPLICATE_MEMBER`, `INVALID_PHONE`, `UNKNOWN_PACKAGE_CODE`, `UNKNOWN_DEPARTMENT`.

### PreviewSummary

| Field | Type |
|-------|------|
| `create_count` | `integer` |
| `update_count` | `integer` |
| `skip_count` | `integer` |
| `sample_creates` | `object[]` | First N rows |
| `sample_updates` | `object[]` | |

### CommitResult

| Field | Type |
|-------|------|
| `created` | `integer` |
| `updated` | `integer` |
| `skipped` | `integer` |
| `failed` | `integer` |
| `created_member_ids` | `string[]` | For rollback scope |

## Validation rules (job lifecycle)

| Transition | Rule | Error code |
|------------|------|------------|
| → `committing` | Org must be `active` | `ORG_PENDING` |
| → `committing` | No unresolved errors | `VALIDATION_FAILED` |
| → `committing` | Status must be `preview_ready` | `MIGRATION_JOB_LOCKED` |
| Rollback | Before `rollback_until` | `ROLLBACK_EXPIRED` |

## Clinical withhold

Migration datasets exclude clinical/Rx history. No withhold concerns on entity itself.

## Out of scope

- Clinical/Rx history
- Retail orders
- Admin credit/price lists

## Sample payload (completed)

```json
{
  "id": "mig_01HJOB001",
  "org_id": "org_01HQXYZ",
  "created_by": "usr_01HSUPER",
  "dataset_type": "members",
  "status": "completed",
  "file_name": "employees_march_2026.xlsx",
  "column_mapping": {
    "Full Name": "full_name",
    "Mobile": "phone",
    "Emp ID": "employee_id",
    "Dept": "department_code",
    "Plan": "package_code"
  },
  "validation": {
    "total_rows": 500,
    "error_count": 3,
    "warning_count": 12,
    "rows": []
  },
  "preview": {
    "create_count": 487,
    "update_count": 10,
    "skip_count": 3
  },
  "commit_result": {
    "created": 487,
    "updated": 10,
    "skipped": 3,
    "failed": 0,
    "created_member_ids": ["mbr_...", "..."]
  },
  "rollback_until": "2026-03-12T10:00:00Z",
  "started_at": "2026-03-11T09:00:00Z",
  "completed_at": "2026-03-11T09:45:00Z",
  "created_at": "2026-03-11T08:30:00Z",
  "updated_at": "2026-03-11T09:45:00Z"
}
```

## Events

| Event | When |
|-------|------|
| `migration.job_started` | Commit begins |
| `migration.job_completed` | Success |
| `migration.job_failed` | Fatal error |

## Related endpoints

- [`../endpoints/migration.md`](../endpoints/migration.md)

## Relation to `/members/import`

Quick member import shares the same validation engine; creates a simplified `MigrationJob` with `dataset_type=members` or a lightweight `ImportJob` alias.