The import wizard, end to end

The import wizard

Bulk imports live under Admin → Imports. The flow is four steps:

1. Pick the entity — what kind of record you’re importing (Tickets, Assets, Sites, etc.). Entities marked Preview-only can be mapped and dry-run but not committed yet.
2. Pick a preset (optional) — a saved column-name mapping from a known source system (FreshService, Civica, ServiceNow…). The preset auto-maps headers; you can still tweak the mapping on the next step.
3. Upload the CSV — UTF-8 encoded, headers in row 1, up to 50 MB.
4. Map the columns — match each source-system column to a Keystone field. Required fields are marked with an asterisk; the natural key (asset tag, email, etc.) is what de-duplicates on re-import.

After mapping you have two choices:

• Dry-run — validates every row against the mapping rules, marks each as would create, would update, would skip, or failed. No data is written. Use this to find shape problems before committing.
• Commit — writes the validated rows. Idempotent on the natural key — re-running the same CSV won’t duplicate existing records, it’ll update them.

Preview-only entities

Some entities (Assets, Contractors, People, Risks, Sites) currently let you map and dry-run but disable the Commit button. The wizard tells you on the entity picker and again on the run page when this is the case. The preview-only state means the import shape is correct, but the entity-side commit logic isn’t wired yet — you can use the dry-run to verify your CSV without affecting any production data.

When you select a preview-only entity, the wizard shows a yellow banner:

Preview-only import — Foo imports are still being wired into the data layer. You can upload, map columns and run a dry-run to verify your CSV — but the final commit step is disabled.

When rows fail

A failed row in dry-run usually means:

• A required field was empty after mapping (often because the source-system column name didn’t match — check your mapping).
• A unique constraint clashed (two rows with the same natural key, or a row clashes with an existing record under a non-matching name).
• A value couldn’t be parsed (a date in an unexpected format, a malformed email).

The Show page lists every failed row with its row number and the error message. Fix your CSV (or the mapping) and re-run — failures are non-destructive, so iterating is safe.

What if I commit and the job dies halfway?

Imports are idempotent — re-running the same CSV picks up where the previous run left off. Rows that already exist (matched on the natural key) are updated rather than duplicated. The Show page shows running totals for created / updated / skipped / failed.