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

# Ticketing in the Console

> Use the project Ticketing board, workflows, and forms in the Golain web Console.

The **Console** ticketing module lives under **Operations → Ticketing** in the project sidebar. You manage workflows and forms, then run day-to-day work on the **Board** kanban. Ticketing is always available in the nav for project members; the API still enforces permissions (see [Permissions](#permissions)).

> **[Board](#board)**
>
> Kanban by workflow state, create tickets, drag to transition.

> **[Workflows](#workflows)**
>
> YAML editor, graph preview, validate, save versions, activate.

> **[Forms](#forms)**
>
> Catalog of form definitions with YAML and live schema preview.

> **[API & automation](/ticketing/api-reference)**
>
> Same resources over HTTP when you outgrow the UI.

## Navigation

| Sidebar item | Route (under your project) | Purpose |
| - | - | - |
| **Board** | `ticketing/board` | Kanban for one **active** workflow at a time |
| **Workflows** | `ticketing/workflows` | List and edit workflow definitions |
| **Forms** | `ticketing/forms` | List and edit ticket forms |

Opening **Ticketing** without a child path redirects to **Board**. The board URL can include `?wf={workflow_def_id}` to select which active workflow to show.

## Permissions

The Console does not hide ticketing pages by role. Failed actions return API errors instead.

| Action | Typical project permission |
| - | - |
| View board, tickets, workflows, forms | Project read / membership |
| Create or move tickets, add tags, transition | Project membership |
| Validate a workflow | Project membership |
| Create, patch, activate workflows; create or patch forms | **Manage workflows** |
| Instantiate a workflow from a template (API) | **Manage assets** |

Saving workflows and forms and activating workflows require **manage workflows**. If **Save** or **Activate** fails with forbidden, ask a project admin to grant that permission.

> [!NOTE]
>
> Assignment in the UI uses **user** tags at create time (see the **Assign users** step under [Step-by-step workflows](#step-by-step-workflows)). The separate assign/unassign HTTP routes are documented on [Assignment and notifications](/ticketing/assignment-notifications) and are not wired into the ticket detail view today.

***

## Board

The board shows tickets for the **active version** of the workflow selected in the header (or the first active workflow if none is selected). Columns match workflow **label keys** in graph order; each column header shows the formatted label name and ticket count.

### Header and workflow scope

| Control | Behavior |
| - | - |
| **Workflows** | Opens **Active workflows** — switch board context or jump to **Edit** / **New workflow** |
| Workflow title | Active workflow name |
| Subtitle | `Active · v{n} · {count} tickets` |
| **New ticket** | Opens **Create ticket** for this workflow |

There is no separate assignee or tag filter on the board. Scoping is by **active workflow** only (`?wf=` query parameter).

### Empty board

If no workflow is active, you see **No active workflow yet.** with **Create workflow** and **Open workflows**.

### Ticket cards

Click a card to open **Ticket detail**. Each card shows:

* State icon and formatted state label
* Title (two lines max)
* Up to five tag badges (with `+N` if more)
* **Classification** badge when due-date rules apply
* Due date (urgency coloring) or created date

The avatar on the card reflects `created_by` (tooltip **Unassigned** when empty), not formal API assignment.

### Move a ticket on the board

Drag a card to another column when a transition exists from the current label to the target label key.

* Reordering within the same column updates the view only (not persisted).
* Invalid moves show a toast: `No transition {from} → {to}`.
* If the workflow requires a form **before** that transition, a **Form required to move** dialog appears with the form name/version, fields, **Cancel**, and **Move**.

Tickets whose state does not match any column appear under **Unknown**.

***

## Create ticket

Click **New ticket** on the board (or **Add sub-ticket** from ticket detail).

| Field / section | Label in UI | Notes |
| - | - | - |
| Title | **Title** | Required; placeholder `Short summary` |
| Body | **Description** | Optional; placeholder `Optional details` |
| Due date | **Due date** | Optional date input; helper **Optional — shown on the board and tracked live**. Stored in ticket `metadata.due_at` (end of local day, ISO). This is not the API `due_at` field, so it does not start [due policy](/ticketing/automation#due-dates-and-due-policy) timers |
| Required tag kinds | Per-kind headings (e.g. **Severity**, **Device**) | From `validation.on_create.require_tag_kinds`. **Severity** uses **Select severity**; entity kinds use **Search {kind}…** |
| Users | **Assign users** | Multi-select org members; adds `user` tags to `initial_tags` |
| Optional tags | **Initial tags** | **EntityTagPicker**: **Search entities for initial tags**, **Manual fallback**, **Add static tag** |
| On-create form | Banner: **This workflow requires {name} v{version}** | JSON Schema form when `require_form` is set |
| Actions | **Cancel**, **Create** | **Creating...** while in flight |

**Create** stays disabled until title is set, required tag kinds are satisfied, and any required form validates.

Sub-tickets use the same fields in a **Create sub-ticket** dialog; the parent link is stored in `metadata.parent_ticket_id`.

> [!NOTE]
>
> The server's rule that blocks closing a parent with open sub-tickets checks `subticket` tags on the parent, not `metadata.parent_ticket_id`. Sub-tickets linked only through the Console do not block the parent from closing. To enforce the rule, add a `subticket` tag (value = child ticket ID) to the parent through the [API](/ticketing/api-reference).

***

## Ticket detail

The full-screen **Ticket detail** modal (header **Ticket notebook** / **Ticket detail**) opens from a board card.

### Edit title and description

Click the large title or description; edit inline. Changes save on blur via patch.

### Read-only properties

| Label | Shows |
| - | - |
| **Assign** | Creator (`created_by` or **Unattributed**) — read-only |
| **Day** | Current workflow state label |
| **Due** | Formatted due date or **Empty** |
| **Classification** | Due / terminal classification badge |
| **Status** | `system_class` (`open`, `in_progress`, `terminal_success`, `terminal_failed`, `cancelled`) |
| **Properties** | Existing tags (`kind` + label); remove with **×**. Placeholder **Add a property** is not interactive |

**Metadata** renders below when present (internal keys such as images and parent id are handled in dedicated sections).

### Transitions

In the right column, **Transitions** lists outgoing states. Each row shows the target label and **Go**. If a **before\_transition** form is required, **Transition form** opens (**Target:** …, **Cancel**, **Apply transition**).

You can also transition by dragging on the board.

### Comments and tags

**Comments** includes **Type @ to tag**. In the composer (**Add a comment…**), type `@` to open **Tagging for @{query}** with groups **Devices**, **Fleets**, **Users**, **Labels**, **Gateways**, **Custom text**. Choosing an entry adds a tag and inserts `@[title]` in the text. Mention chips can be removed; persisted tags also appear under **Properties**.

> [!NOTE]
>
> Only the tags are saved. The comment text itself is not stored on the ticket.

### Images and sub-tickets

| Section | Purpose |
| - | - |
| **Images** | **Attach** JPEG/PNG/GIF/WebP up to 2 MB each, max 10. Stored in ticket metadata. **No images yet — click to attach** when empty |
| **Sub-tickets** | **Add sub-ticket**, list linked children, **Unlink from parent**. Child tickets cannot add further sub-tickets |

**Parent ticket:** link at top when viewing a sub-ticket.

### Delete

**Delete ticket** asks **Delete this ticket permanently?** then removes the ticket.

***

## Workflows

### List (**Workflows** page)

* **New workflow** → editor for a new definition
* Each row: name, version (`v{n}`), **Active** or **Draft** badge
* **Board** shortcut when a definition has an active version
* Pagination: **Page {n} of {m} ({total} workflows)**

### Create and edit

Open **New workflow** or a row to edit. Breadcrumb: **Workflows → {name}**.

| UI element | Behavior |
| - | - |
| Status line | **Active · v{n}**, **Not active yet**, or hint **Saving creates a draft. Activate it to use on the board.** |
| **Version** | **SearchableSelect** when multiple versions exist (`v{n} · Active` on the active row) |
| Inactive version note | `v{n} is not active. Open tickets stay on their version.` |

Editor toolbar:

| Tab / button | Action |
| - | - |
| **Graph** | DAG of states and transitions (colors by `system_class`) |
| **YAML** | Monaco YAML editor |
| **Validate** | Server validation; success toast **YAML OK** |
| **Save** | POST new workflow or PATCH new version from current YAML |
| **Activate** | Only on saved, non-active versions; confirm: *New tickets will use this version. Tickets already opened on other versions stay there and will not show on this board.* |

Parse errors show inline under the toolbar. **Activate** without saving first shows **Save first, then activate this version.**

> [!WARNING]
>
> The Console does not expose **Delete** for workflow definitions. Use the [API](/ticketing/api-reference) if you need to remove a workflow.

See [Workflows](/ticketing/workflows) for YAML structure and [Forms](/ticketing/forms) for linking `require_form` entries.

***

## Forms

**Forms** splits the page into a catalog and editor.

### Catalog (**Catalog forms**)

* Lists each form **name** and **v{version}**
* Click a row to load it in the editor
* **New form** clears selection for a blank definition

### Editor

| Control | Behavior |
| - | - |
| **Create form** / **Save new version** | POST new form or PATCH (creates a new version) |
| YAML pane | Monaco editor; must include `name` and `schema` |
| **Schema preview** | Read-only JSON Schema form preview |

Invalid YAML shows errors such as **YAML must define name + schema**.

***

## Step-by-step workflows

**1. Create a workflow**

1. Go to **Ticketing → Workflows** and click **New workflow**.
2. Edit YAML on the **YAML** tab (or inspect **Graph**).
3. Click **Validate** until you see **YAML OK**.
4. Click **Save**. You are redirected to the new workflow definition.

**2. Activate a workflow**

1. Open the workflow you saved (status **Not active yet** or **Draft** on the list).
2. Confirm the version in **Version** if you have more than one.
3. Click **Activate** and confirm the dialog.
4. Open **Board** from the list or sidebar; the board uses active workflows only.

**3. Create a ticket**

1. On **Board**, pick the workflow via **Workflows** if needed.
2. Click **New ticket**.
3. Fill **Title**, optional **Description** and **Due date**, required tag kinds, optional **Assign users** and **Initial tags**, and any required form.
4. Click **Create**.

**4. Move a ticket**

1. Drag the card to a column that matches an allowed transition, **or** open **Ticket detail** and use **Transitions** → **Go**.
2. Complete **Form required to move** or **Transition form** if prompted.
3. Confirm the card appears in the new column.

**5. Assign users**

1. When creating a ticket, expand **Assign users** and select one or more members (checkbox list, **(Me)** on your row).
2. Click **Create**. Users are stored as `user` tags on the ticket.
3. To add more people later, use **Comments** `@` user tagging or entity search (adds tags via the API).

**6. Add a sub-ticket**

1. Open the parent **Ticket detail**.
2. Under **Sub-tickets**, click **Add sub-ticket**.
3. Complete **Create sub-ticket** and click **Create**.
4. Open sub-tickets from the list; use **Unlink from parent** to detach.

**7. Create a form**

1. Go to **Ticketing → Forms** and click **New form**.
2. Edit YAML (`name`, `schema`, optional `bindings`).
3. Check **Schema preview**.
4. Click **Create form**.
5. Reference the form name (and version if needed) in workflow `validation` — see [Forms](/ticketing/forms).

***

## Related topics

* [Ticketing overview](/ticketing/overview) — concepts and vocabulary
* [First ticket](/ticketing/first-ticket) — minimal end-to-end path
* [Workflows](/ticketing/workflows) — YAML reference for operators
* [Automation](/ticketing/automation) — transitions that call HTTP or device RPC
* [Alarms](/alarms/overview) — separate operations board (not tickets)
* [Troubleshooting](/ticketing/troubleshooting) — common API and UI errors


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.