> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstresonance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Imports

> Bulk-create runs from a CSV file, including procedures, part inventory, assignees, and run batches.

## 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` — not both.                                                                                               |
| `autogenerate_title`         | Conditional | When `true`, ION generates the run title. Boolean field (see [accepted values](/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 (e.g. `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](/administration/ion-importers#accepted-boolean-values)).                                                 |
| `run_batch_title`            | No          | Title of the run batch to add the run to. See [Run batches](#run-batches).                                                                                                          |

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

## 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.

## Related pages

For general import behavior, empty cell handling, and error reporting, see [Importers](/administration/ion-importers).