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

> Project-scoped tickets, workflow definitions, and lifecycle concepts for maintenance, work orders, and incident follow-up.

**Ticketing** gives each **Project** a structured way to track work items that move through states you define. You might use it for maintenance requests, CMMS work orders, or incident follow-up after an [alarm](/alarms/overview) fires. Every ticket belongs to one workflow **definition** and stays on the workflow **version** that was active when the ticket was created.

## What ticketing is

You author a **workflow** (states, transitions, validation, optional automation) and optional **forms** (JSON Schema with bindings to tags and metadata). Operators and integrators then **create tickets**, **assign** them, attach **tags**, and **transition** them along allowed edges. The platform enforces permissions, guards, required forms, and due-date policy from that workflow spec.

Tickets are always scoped to a **Project** in your **Organization**. The HTTP API lives under `https://api.ilyama.golain.io/core/api/v1/projects/{project_id}/…` — see [API reference](/ticketing/api-reference) for routes and examples.

## Core concepts

| Concept | What it means |
| - | - |
| **Ticket** | A single work item: `title`, optional `body`, `metadata`, tags, assignment, optional `due_at`, and a current **state label**. API responses include `id`, `workflow_version_id`, `state_label_id`, `system_class`, and a readable `number`. |
| **Workflow definition** | Stable identity for a workflow (`workflow_def_id`). You create it once; each edit adds a new **version** rather than mutating history. |
| **Workflow version** | Immutable snapshot of the spec (`version`, `spec`, `validation_report`). Exactly one version per definition is **active** (`is_active: true`) for new tickets. Existing tickets keep their pinned `workflow_version_id` when you activate a newer version — they are not migrated. |
| **State label** | A named step in the graph (`key`, e.g. `new`, `in_progress`). Each label has a **class** stored as `system_class`: `open`, `in_progress`, `terminal_success`, `terminal_failed`, or `cancelled`, plus optional `color` and `terminal`. Transitions target a label **key** (`to_label` in the API). |
| **Transition** | Allowed edge `from` → `to` in the workflow spec. Each edge lists **permit** actors (who may fire it), optional **guards** (CEL booleans), and optional **on\_enter** / **on\_exit** actions. |
| **Permit** | Who can take a transition. Built-in targets include `system` (automated actors), `ticket.assignee`, `ticket.tagged_user` (user tags on the ticket), `ticket.assignee_group_member`, and `ticket.creator`. You can also use `{entity}.{permission}` (for example `project.member`, `project.admin`, or `device.can_invoke_rpc`). `project` checks the ticket's Project; other entities such as `device` are resolved from tags on the ticket. See [Workflows](/ticketing/workflows). |
| **Form** | Project-scoped JSON Schema (`name`, `schema`, `bindings`). Bindings map form fields to **tags** (`writes_to.kind: tag`) or **metadata** (`writes_to.kind: metadata`). Patching a form appends a **new version**; `require_form` without `version` resolves to the latest. |
| **Tags and tag kinds** | Typed links on a ticket (`kind`, `value`, optional `label`). Platform kinds include `user`, `device`, `fleet`, `project`, `subticket`, `ticket`, `object`, `ota_release`, `datapoint`, `user_context`, `asset`, `alarm_instance`, `maintenance_plan`, `severity`, `priority`, `wo_type`, `eta`, and `custom`. Workflows can require certain kinds at create or before specific transitions. |
| **Assignment** | At most one assignee: either `assigned_user_id` / response field `assigned_to`, or `assigned_group_id` — not both. Unassign with `target`: `user` or `group`. |
| **Sub-tickets** | Child work items linked to a parent. The platform treats a child as linked when the **parent** has a tag `kind: subticket` and `value` set to the child ticket UUID (each child may appear on only one parent). The Console also stores `parent_ticket_id` on the child’s `metadata` for navigation. A parent **cannot** move to a terminal state while any linked child still has `system_class` `open` or `in_progress`. |
| **Ticket number** | Integer field `number` on each ticket — a human-friendly counter **per workflow definition**, continuing across definition versions (not reset when you activate a new spec version). Numbers only increase; gaps are allowed if a create rolls back. |
| **Due date and due policy** | Optional `due_at` (RFC3339) on the ticket. Workflow `due_policy` can set `lead_time` (warning before due) and `on_breach.to` (label key). Breach moves the ticket only if you declared a transition from the current state to that label with `system` in `permit`. |
| **Trigger intake** | Workflow `trigger_intake` entries listen for domain **events** (routing keys), optionally filter with CEL, and create tickets with templated title, tags, and metadata. Supports dedupe (`dedupe_key`, `cooldown`) and optional grouping. Alarms can also open work-order tickets; you configure that on the alarm definition — see [Alarms](/alarms/overview) and [Automation](/ticketing/automation). |
| **Workflow templates** | Platform catalog entries you instantiate into a Project (requires **manage assets** permission). Example template key: `cmms.work_order` (CMMS work-order blueprint with `kind: work_order`). |

> [!NOTE]
>
> Workflow **actions** on transitions include `ticket.http` (outbound HTTP with optional response bindings) and `ticket.rpc` (Device RPC to a device service method). Details and field lists are on [Automation](/ticketing/automation) and [API reference](/ticketing/api-reference).

## Example lifecycle

A simple **maintenance-request** workflow might use label keys `new`, `in_progress`, `resolved`, and `cancelled`:

```mermaid theme={null}
stateDiagram-v2
  [*] --> new
  new --> in_progress: Start work
  in_progress --> resolved: Complete
  new --> cancelled: Cancel
  in_progress --> cancelled: Cancel
  resolved --> [*]
  cancelled --> [*]
```

Label classes would typically map `new` → `open`, `in_progress` → `in_progress`, `resolved` → `terminal_success`, and `cancelled` → `cancelled` (with `terminal: true` on the two end states).

## How it fits together

1. **Define forms** (optional) — JSON Schema and bindings for intake or completion steps. See [Forms](/ticketing/forms).
2. **Author and validate a workflow** — labels, transitions, validation rules, trigger intake, due policy, and actions. POST to `…/ticket-workflows/validate`, then create and **activate** a version. See [Workflows](/ticketing/workflows).
3. **Open tickets** — manually (Console or `POST …/tickets` with `workflow_def_id`), from a **template**, or automatically via **trigger intake** when matching events arrive.
4. **Operate** — assign users or groups, add tags, patch title/body/due date/metadata, and transition with `to_label` when permitted transitions exist. See [Console](/ticketing/console) and [Assignment and notifications](/ticketing/assignment-notifications).
5. **Integrate** — call the HTTP API from your apps; use [Automation](/ticketing/automation) for transition side effects. When something fails, start with [Troubleshooting](/ticketing/troubleshooting).

For a guided first ticket end-to-end, see [First ticket](/ticketing/first-ticket).

## Next steps

> **[First ticket](/ticketing/first-ticket)**
>
> Walk through creating a workflow and opening your first ticket.

> **[Console](/ticketing/console)**
>
> Day-to-day ticket operations in the Golain Console.

> **[Workflows](/ticketing/workflows)**
>
> Labels, transitions, permits, guards, validation, and activation.

> **[Forms](/ticketing/forms)**
>
> JSON Schema forms, versions, and bindings to tags and metadata.

> **[Assignment and notifications](/ticketing/assignment-notifications)**
>
> Assignees, groups, and who gets notified when work is assigned.

> **[Automation](/ticketing/automation)**
>
> HTTP and Device RPC actions on transition enter and exit.

> **[API reference](/ticketing/api-reference)**
>
> Routes, request bodies, permissions, and response envelopes.

> **[Troubleshooting](/ticketing/troubleshooting)**
>
> Common errors when creating, transitioning, or validating tickets.


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