## Overview

The Runs importer bulk-creates runs, one CSV row per run. It drives the same path as creating runs in the UI, so step copying, batching, and every downstream side effect behave identically. This importer is **create-only**: it does not update existing runs. Each run can:

- be created from a **procedure**, identified by `procedure_id` _or_ `procedure_title` + `procedure_version` (a run with no procedure is also allowed),
- be tied to **part inventory**, either linking an existing record via `part_inventory_id` or creating a new one via `part_number`,
- join a **run batch** via `run_batch_title`,
- carry an assignee, intent option, due date, and custom attributes.

## Columns

| Column | Required | Description |
| --- | --- | --- |
| `title` | Conditional | Run title. Each row needs either a `title` or `autogenerate_title = true`, but not both. |
| `autogenerate_title` | Conditional | When `true`, ION generates the run title. Boolean field (see [accepted values](https://docs.firstresonance.io/administration/ion-importers#accepted-boolean-values)). |
| `procedure_id` | No | ID of the procedure to create the run from. Cannot be combined with `procedure_title` / `procedure_version`. |
| `procedure_title` | No | Procedure title. Must be paired with `procedure_version`. |
| `procedure_version` | No | Procedure version (integer). Must be paired with `procedure_title`. |
| `description` | No | Free-text description. |
| `due_date` | No | Due date, such as `2026-06-15`. An empty cell leaves the field unset. |
| `quantity` | No | Run quantity. Must be a non-negative integer. When the row creates a new inventory via `part_number`, the quantity applies to that inventory. An empty cell leaves the field unset. |
| `part_number` | No | Part number. Creates a **new** inventory record for the run. Cannot be combined with `part_inventory_id`. |
| `revision` | No | Part revision for the new inventory. If omitted and the part has exactly one revision, that revision is used. |
| `serial_number` | No | Serial number for the new inventory. |
| `lot_number` | No | Lot number for the new inventory. |
| `autogenerate_serial_number` | No | When `true`, ION generates a serial number for the new inventory. Boolean field. |
| `autogenerate_lot_number` | No | When `true`, ION generates a lot number for the new inventory. Boolean field. |
| `part_inventory_id` | No | ID of an **existing** inventory record to link to the run. Cannot be combined with `part_number` or any of the new-inventory columns above. |
| `assigned_to` | No | Email address of the user to assign. An empty cell leaves the run unassigned. |
| `intent_option` | No | Intent option name. Must match a configured intent option. |
| `export_controlled` | No | Whether the run is export controlled. Boolean field (see [accepted values](https://docs.firstresonance.io/administration/ion-importers#accepted-boolean-values)). |
| `run_batch_title` | No | Title of the run batch to add the run to. See [Run batches](https://docs.firstresonance.io/administration/ion-importers/runs#run-batches). |

Three column groups are mutually exclusive per row:

- `title` vs. `autogenerate_title`: provide exactly one.
- `procedure_id` vs. `procedure_title` + `procedure_version`: provide at most one form.
- `part_inventory_id` vs. `part_number`: when linking an existing inventory, the new-inventory columns (`revision`, `serial_number`, `lot_number`, `autogenerate_serial_number`, `autogenerate_lot_number`) must be empty.

Procedure titles aren’t globally unique, so a `(procedure_title, procedure_version)` pair that matches more than one procedure produces an ambiguity error. Use `procedure_id` to disambiguate.

## Run batches

Rows sharing a `run_batch_title` are grouped into a single run batch. Batch titles are unique in ION, so this is a find-or-create: if a batch with that title already exists, the runs join it; otherwise ION creates the batch.

## Custom attributes

Any column not in the standard list above is treated as a custom attribute on the run. Custom attribute columns must match a configured attribute key for your organization; unknown columns cause a validation error.