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

# Overview

> Use CSV imports to bulk-create or update records in ION.

ION's import feature lets you upload a CSV file to create or update records in bulk. Instead of entering data one row at a time through the UI, you can prepare a spreadsheet offline and import it all at once.

## How imports work

To start an import, navigate to **Imports** in the sidebar, then pick an import type from the **New Import** tab. The importer cards are grouped by category (**Production**, **Supply Chain**, **Quality**, and **OS**) to match where each record type lives in ION. Imports are processed **asynchronously**, so you can navigate away and continue working while the import runs. You receive a notification when the import completes or fails.

Clicking **Start Import** on any card opens the import wizard, which walks you through **Upload**, **Match**, and **Review** steps.

On the **Upload** step you can download the CSV template, toggle the importer's options (the option set varies by importer), or choose **Enter data manually** to type rows into the grid instead of uploading a file.

The **Match** step maps your file's columns to ION fields. ION auto-maps each column to the field whose name it matches, and you can adjust any mapping in that column's **Maps To** dropdown: pick a different field, keep the column as a custom attribute, or skip the column so it isn't imported. Required fields must stay mapped. When you enter data manually instead of uploading, this step becomes a column picker where you choose which fields to include.

On the **Review** step, ION shows your rows in an editable grid. Edit any cell inline, then use the validate control to check the data. ION flags each failing cell with its error and highlights the affected rows, so you can fix them and revalidate before importing. The control reads **Validate** before the first check and **Revalidate** after, and editing a validated file prompts you to revalidate before you can import.

<Frame caption="The Review step flags each failing cell so you can fix it before importing.">
  <img src="https://mintcdn.com/firstresonance/Sz_vZtaxyNMzjHVb/images/administration/ion-importers/import-wizard-review-errors.png?fit=max&auto=format&n=Sz_vZtaxyNMzjHVb&q=85&s=0cf30dec7b264636261be02c14b53646" alt="Import wizard Review step showing an editable grid with three rows flagged Name is required and a banner reading 3 issues in rows 1, 2, 3" width="1824" height="552" data-path="images/administration/ion-importers/import-wizard-review-errors.png" />
</Frame>

Imports are **all-or-nothing**. If any row fails validation, no rows are written and you receive an error report. You never end up with a partially imported file.

You can track the status of all imports from the **Import History** tab. Expand any failed job to see its per-row error messages, or click **Download** to pull the full error CSV.

## Video walkthrough

The end-to-end import flow is the same for every importer: pick a type, download the template, upload your CSV, run validation, then commit. The walkthrough below uses the mBOM importer as an example.

<iframe src="https://www.loom.com/embed/34129c65cde941189007b971c80382d0" frameBorder="0" allowFullScreen style={{ width: "100%", aspectRatio: "16 / 9", borderRadius: "8px" }} />

## Required and optional columns

Each import type has its own set of columns. Some columns are required and must be present in every row, while others are optional. Optional columns that you omit from your CSV are skipped entirely, so ION does not touch those fields on the imported records. Only when an optional column is included in the CSV but left blank for a given row does ION apply a default value based on the field type (see below). If a required column is missing or empty, the import fails with a validation error.

## How empty CSV cells are handled

When an optional column is present in your CSV but a row leaves it blank, the cell defaults to a falsy or zero-equivalent value (not null). This only applies to columns that are actually in the file. Omitting the column entirely leaves the field untouched.

### Lookup and control columns are exempt

A handful of columns are exempt from the falsy-default rule, either because they're used to look up an existing record or control importer behavior, or because `0` isn't a falsy value for that field's type. For these, an empty cell means "not provided":

| Column                                | Importer                                                                                                                                                                       | Empty cell means                                     |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- |
| `id`                                  | [Part Inventory](/administration/ion-importers/part-inventory), [Tool Inventory](/administration/ion-importers/tool-inventory), [Issues](/administration/ion-importers/issues) | Create a new record (no update lookup)               |
| `original_name`                       | [Locations](/administration/ion-importers/location-imports)                                                                                                                    | No rename                                            |
| `original_po_number`                  | [Purchase Orders](/administration/ion-importers/purchase-orders)                                                                                                               | No rename                                            |
| `latitude`, `longitude`               | [Locations](/administration/ion-importers/location-imports)                                                                                                                    | Unset. `0` is not a falsy value for a coordinate     |
| `last_maintained_date`, `uri`         | [Tool Inventory](/administration/ion-importers/tool-inventory)                                                                                                                 | Unset. No date is written and no URI is stored       |
| `due_date`, `quantity`, `assigned_to` | [Runs](/administration/ion-importers/runs)                                                                                                                                     | Unset. No due date, quantity, or assignee is written |

Each importer's column table calls out which fields behave this way.

| Field Type | Empty Cell Value | Examples                                    |
| ---------- | ---------------- | ------------------------------------------- |
| Text       | `""`             | `description`, `address`                    |
| Numeric    | `0`              | `quantity`                                  |
| Boolean    | `false`          | `made_on_assembly`, `available`, `archived` |

<Info>
  If you leave a boolean column blank, ION treats it as **false** (unchecked). To set a field to true, you must explicitly write a truthy value.
</Info>

### Accepted boolean values

Boolean fields accept any of the following (case-insensitive):

| Truthy | Falsy   |
| ------ | ------- |
| `true` | `false` |
| `yes`  | `no`    |
| `1`    | `0`     |

## Errors

When validation fails, ION reports up to **100 errors** with the specific row number and a description of the problem. Row numbers correspond to the CSV file where row 1 is the header and row 2 is the first data row.

<Info>
  If your file contains more than 100 errors, fix the first batch and re-upload. ION caps error reporting at 100 to keep the output manageable.
</Info>

<Tip>
  Review your column headers and values before uploading, and pay special attention to boolean columns: blank cells default to `false`, so any field you intend to be `true` must be set explicitly. Because imports are all-or-nothing, resolve every error the **Review** step flags and revalidate until the file passes before you re-upload. Run your import in a staging environment and verify the results before importing into production.
</Tip>
