## Overview

The Issues importer bulk-creates or updates issues. The distinction is row-by-row:

- Rows **without** an `id` value **create** a new issue. `title` is required, and the issue starts at status `pending` unless the row sets an explicit `status`.
- Rows **with** an `id` value **update** the matching issue.

## Columns

| Column | Required | Description |
| --- | --- | --- |
| `id` | No | Issue ID. Provide to update an existing issue; omit to create a new one. **Lookup column**: an empty cell is treated as “not provided,” not `0`. |
| `title` | Yes (for create) | Issue title. |
| `status` | No | One of `pending`, `in_progress`, `in_review`, `resolved`. Matched case-insensitively. New issues default to `pending`. |
| `cause_condition` | No | Plain-text cause description. See [Rich-text fields](https://docs.firstresonance.io/administration/ion-importers/issues#rich-text-fields). |
| `disposition` | No | Plain-text disposition description. See [Rich-text fields](https://docs.firstresonance.io/administration/ion-importers/issues#rich-text-fields). |
| `expected_condition` | No | Plain-text expected-condition description. See [Rich-text fields](https://docs.firstresonance.io/administration/ion-importers/issues#rich-text-fields). |
| `issue_disposition_type` | No | Title of a disposition type configured in your organization. Matched case-insensitively. |
| `assigned_to` | No | Email address of the user to assign. Matched case-insensitively against existing users. |

## Rich-text fields

`cause_condition`, `disposition`, and `expected_condition` are rich-text fields in the ION UI. The importer accepts plain text and converts it into a single paragraph, which you can elaborate on later in the UI. On update rows, an empty cell leaves the existing content untouched.

## Custom attributes

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