# Custom fields

A team can give its cards fields of its own, next to the built-in ones: Area, Customer, Severity, Spec link. Fields
belong to a team, and its sub-teams' cards have them too. Use them to sort and filter the board, and to hand a run
extra facts about a card.

## Add a field to a team

1. Open Settings and search for **Fields**. Pick the team. (A card's fields also link to this section.)
2. Type its name in **Add a field**, pick its kind, and for a select give its options, separated by commas.
3. Click **Add**.
4. Optional: tick **Required**, or **On the card face** to show the value as a small chip on the card.

Owners and admins manage fields. Each field's arrows reorder it; the bin deletes it. Deleting a field takes its values
off the team's cards and its sub-teams'.

A field has a name, which you can change, and a key made from the name when it is added, which never changes. Its kind
never changes either. Templates and views use the key.

### Kinds

| Kind | A value is |
| --- | --- |
| Text | up to 2,000 characters |
| Number | any number |
| Date | a day |
| Select | one of its options |
| Multi-select | some of its options |
| Person | someone in the org |
| URL | an `http` or `https` link |
| Checkbox | ticked or not |

### Fields and sub-teams

A sub-team's cards have their own team's fields and every parent team's. A sub-team's field with the same key
replaces its parent's, for example to offer a different set of options. The **Fields** section lists what comes from
above.

## Fill in a field

Open the card. Its fields are in the details, below the built-in properties, and on the rail's **Fields** tab after the
recipe's inputs. Click a value to edit it.

- A required field can be changed but not cleared once it has a value. Imports, quick add and agents can still make a card without it.
- If a value no longer fits (the card moved to a team without the field, its option was removed, or the field
  was deleted), Andon drops the value and the change goes through.

### Set a field on many cards

1. Pick the cards (see [bulk edit](https://andon-docs.pages.dev/guide/templates-and-bulk-edit.md#change-many-cards-at-once)).
2. On the selection bar, open **Set**, then **Field**, and pick the field.
3. Enter the value, or leave it empty to clear it.

Cards that aren't yours, or whose team doesn't have the field, are left as they are, and the toast says how many and
why. Undo puts the rest back.

## Filter by a field

The filter bar's `field:` key matches a field by its key or its name, each card against its own team's fields:

| Query | Matches |
| --- | --- |
| `field:severity` | cards with any severity |
| `field:severity=high` | that option (case doesn't matter) |
| `field:"t-shirt size=M"` | by name; quote a name or option with a space in it |
| `field:effort>=3`, `field:target<2030-04-01` | numbers as numbers, dates as dates |
| `field:areas=api` | a multi-select that includes it |
| `field:reviewer=me`, `field:reviewer=sam` | a person, by you or by name |
| `field:flag=yes`, `field:severity=none` | ticked; no value |
| `-field:severity=low` | not that |

The List layout sorts by any field; empty values sort last. See [Views](https://andon-docs.pages.dev/guide/views.md).

## Fields in a run

A run sees a card's fields only when its recipe's template asks for them, with `{{fields}}` or `{{fields.<key>}}`.
See [Writing a recipe](https://andon-docs.pages.dev/guide/writing-a-recipe.md).

## Fields from another tracker

A Jira import brings the issue's custom fields along. A Jira field whose name matches one of the team's fields
(ignoring case) fills that field. The rest, and any value the field can't take, go into the card's notes under
**Fields from Jira**. Only new cards get them.

Moving a whole team from another tracker works the same way: fields you map fill the team's fields, and the rest go
into the notes under **Fields from** and the tracker's name. See [Moving a team from another
tracker](https://andon-docs.pages.dev/guide/import-from-a-tracker.md).
