Ticketing overview

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 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 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.
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 and 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`).

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 and API reference.

Example lifecycle

A simple maintenance-request workflow might use label keys new, in_progress, resolved, and 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

Define forms (optional) — JSON Schema and bindings for intake or completion steps. See Forms.
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.
Open tickets — manually (Console or POST …/tickets with workflow_def_id), from a template, or automatically via trigger intake when matching events arrive.
Operate — assign users or groups, add tags, patch title/body/due date/metadata, and transition with to_label when permitted transitions exist. See Console and Assignment and notifications.
Integrate — call the HTTP API from your apps; use Automation for transition side effects. When something fails, start with Troubleshooting.

For a guided first ticket end-to-end, see First ticket.

Next steps

First ticket

Walk through creating a workflow and opening your first ticket.

Console

Day-to-day ticket operations in the Golain Console.

Workflows

Labels, transitions, permits, guards, validation, and activation.

Forms

JSON Schema forms, versions, and bindings to tags and metadata.

Assignment and notifications

Assignees, groups, and who gets notified when work is assigned.

Automation

HTTP and Device RPC actions on transition enter and exit.

API reference

Routes, request bodies, permissions, and response envelopes.

Troubleshooting

Common errors when creating, transitioning, or validating tickets.

Getting started

Dataspaces

Console

Dashboards

Alarms

Ticketing

Ticketing overview

What ticketing is

Core concepts

Example lifecycle

How it fits together

Next steps

First ticket

Console

Workflows

Forms

Assignment and notifications

Automation

API reference

Troubleshooting

​What ticketing is

​Core concepts

​Example lifecycle

​How it fits together

​Next steps

First ticket

Console

Workflows

Forms

Assignment and notifications

Automation

API reference

Troubleshooting

What ticketing is

Core concepts

Example lifecycle

How it fits together

Next steps