# Attributes

> Attributes are the fields on each activity — the title, the body, the category, the deadline. The attributes: list shapes the activity form and the activity itself.

Canonical HTML page: https://conclude.io/doc/reference/attributes/
Last updated: 2026-11-02

---

Attributes are the fields on each activity — the title, the body, the
category, the deadline. The `attributes:` list shapes the activity form
and the activity itself.

## Anatomy

```yaml
attributes:
  - name: title                # required, unique identifier
    type: string               # required, attribute type
    label: Subject             # required, display label
    description: Short summary # optional, help text
    placeholder: e.g. ...      # optional, input placeholder
    hint: tip for the user     # optional, secondary hint
    defaultValue: ""           # optional, initial value (supports macros)
    visible: always            # optional, when to show
    mandatory: true            # optional, must be non-empty
    important: false           # optional, highlight in UI
    readonly: false            # optional, hide from edit forms
    postmortem: false          # optional, only visible after concluding
    multiSelect: false         # for select/tag only
    style: ""                  # for button only
    viewers: ""                # optional, role expression
    editors: ""                # optional, role expression (defaults to viewers)
    display: ""                # optional, render template
    options: []                # for select/tag/button only
    trigger: {...}             # optional, runs when this attribute changes
```

## Types

| Type | Use for | Notes |
|---|---|---|
| `string` | Short single-line text | Required for `title` |
| `text` | Long multi-line text | Required for `conclusion` |
| `markdown` | Multi-line markdown | Rendered as Slack mrkdwn / Teams |
| `markdownLine` | Single-line markdown | |
| `html` | Pre-rendered HTML | For imported content |
| `select` | Dropdown / multi-select | Requires `options`; supports `multiSelect` |
| `user` | Member picker | |
| `link` | URL | |
| `button` | Clickable button | Combine with a `trigger`; supports `style: primary` or `danger` |
| `tag` | Tag picker | Requires `options` |

## Reserved attribute names

These names have built-in meaning. You can declare them to customize their
label, defaults, visibility, or to add a trigger; you cannot rename them.

| Name | Built-in type | Purpose |
|---|---|---|
| `title` | `string` | Activity headline. **Required.** |
| `body` | `text` or `markdown` | Long description |
| `conclusion` | `text` | Filled when the activity is closed |
| `deadline` | (built-in) | Due date; hide via `settings.disableDeadline: true` |
| `severity` | (built-in) | Severity scale |
| `status` | `select` | Activity status; selected option's `state:` can drive auto-close (see [Statuses and states](https://conclude.io/doc/reference/statuses/)) |

## Visibility

`visible:` controls when the attribute appears on the form. Values combine
with commas:

| Value | Effect |
|---|---|
| `always` (default) | Visible on create, edit, and conclude |
| `never` | Hidden from all forms |
| `create` | Only on the create form |
| `edit` | Only when editing an existing activity |
| `conclude` | Only on the close form |
| `nonempty` | Combine with the above to hide when value is empty |

Examples:

```yaml
- name: notes
  type: text
  label: Notes
  visible: edit               # only show after creation

- name: triage
  type: select
  visible: edit,conclude      # not on create

- name: assignedTo
  type: user
  visible: always,nonempty    # hide until set
```

## Mandatory, readonly, important, postmortem

- `mandatory: true` — must be set before the activity can be saved.
- `readonly: true` — visible but not editable from forms; scripts or
  triggers can still write to it via `activity.set` / `setAttribute`.
- `important: true` — highlighted in the activity banner / list.
- `postmortem: true` — hidden until the activity is concluded.

## Default values

`defaultValue:` is the initial value when an activity is created. It supports
[macros](https://conclude.io/doc/reference/macros-and-roles/), so you can pre-fill from the initiator,
channel, or another attribute.

```yaml
- name: assignedTo
  type: user
  defaultValue: ${initiator}

- name: pageUrl
  type: link
  defaultValue: https://wiki.example/${title}
```

## ACLs: viewers and editors

`viewers` and `editors` accept [role expressions](https://conclude.io/doc/reference/macros-and-roles/#role-expressions).
`editors` defaults to `viewers` if unset.

```yaml
- name: budget
  type: string
  viewers: team           # all team members can see
  editors: ${owner}       # only the owner can change
```

Both fields support the special tokens `team`, `external`, and direct user
or channel references.

## Display templates

`display:` overrides how the attribute renders in summaries. Supports macros
and Markdown.

```yaml
- name: jira.id
  type: string
  label: Jira issue
  display: "[${jira.id}](https://acme.atlassian.net/browse/${jira.id})"
```

## Options (select, tag, button)

For `select` and `tag` attributes, declare each choice under `options:`.

```yaml
- name: status
  type: select
  label: Status
  options:
    - name: open
      label: Open
      state: open               # ActivityState binding
    - name: in_progress
      label: In progress
    - name: resolved
      label: Resolved
      state: closed             # selecting this concludes the activity
      trigger:
        setAttribute:
          name: conclusion
          value: "Resolved by ${owner}"
```

**Option fields:**

| YAML key | Type | Purpose |
|---|---|---|
| `name` | string | Unique identifier (required) |
| `label` | string | Display text (required) |
| `state` | `open` \| `closed` \| `pending` | Override the activity's lifecycle state when this option is selected |
| `external` | string | Mapping to an external system value (Jira/Zendesk) |
| `filter` | string | Conditional visibility: `attr==value` or `attr in [v1,v2]` |
| `trigger` | object | Runs when this option is selected (same shape as a normal trigger; see [Triggers](https://conclude.io/doc/reference/triggers/)) |

### Conditional options with `filter`

Hide an option until another attribute has a specific value:

```yaml
- name: severity
  type: select
  options:
    - name: low
      label: Low
    - name: high
      label: High
- name: pager
  type: select
  options:
    - name: yes
      label: Page on-call
      filter: severity == high     # only available when severity is "high"
```

### `multiSelect`

For `select`, set `multiSelect: true` to allow multiple choices. The
attribute value is then a comma-separated list of option names.

## Per-attribute triggers

Set `trigger:` on an attribute to react when *that* attribute changes
(equivalent to an `onEdit` trigger filtered by attribute name).

```yaml
- name: status
  type: select
  trigger:
    setAttribute:
      name: conclusion
      value: "Status set to ${status}"
  options: [...]
```

See [Triggers](https://conclude.io/doc/reference/triggers/) for the full trigger action vocabulary.

## Button attributes

A `button` attribute renders a button instead of an input. The button's
trigger fires when clicked.

```yaml
- name: page
  type: button
  label: Page on-call
  style: danger
  trigger:
    alert: "#oncall"
    script: page
```