Reference

Technical reference

On this page

Reference documentation for Conclude’s app model — the YAML definition that shapes a channel’s activities, automations, integrations, and AI agents.

Contents

DocCovers
App YAMLTop-level YAML structure, every field on the App type
AttributesAttribute types, options, visibility, ACLs
Statuses and statesActivity states, built-in/custom statuses, Zendesk + Jira mapping
TriggersonCreate / onComment / onEdit / onConclude, conditions, actions
Scripting (Starlark)Starlark API, scheduled re-entry, conclude.editComment / conclude.schedule
Agents in YAMLAI agent configuration and trigger wiring
ConnectorsEmail, web, Jira, Zendesk, lookup endpoints
Macros and rolesRole expressions, install-time and runtime macros

What an app is

An app is a YAML document that turns a channel into a structured workspace for a specific kind of work — support tickets, incidents, approvals, decisions. Installing an app on a channel binds the channel to that definition; everything the channel does after that — activity creation, attribute prompts, automations, AI agents, integrations — is shaped by the YAML.

The smallest valid app declares a name, a label, and at least one attribute (which must include title):

name: simple
label: Simple
attributes:
  - name: title
    type: string
    label: Subject
    mandatory: true

Conceptual model

   Channel ── installs ──> App (YAML)
                            │
                            ├── Settings        — operational config
                            ├── Roles           — who can do what
                            ├── Texts           — UI text overrides
                            │
                            ├── Attributes[]    — fields on each activity
                            │       └── Options, Triggers
                            │
                            ├── Triggers[]      — onCreate/onComment/onEdit/onConclude
                            │       └── Actions: setAttribute, message, email,
                            │           conclude, agent, script
                            │
                            ├── Scripts[]       — named Starlark
                            ├── agent actions   — organization agents named in triggers
                            │
                            ├── EmailConnector  — inbound email
                            ├── WebConnector    — inbound web form
                            ├── Jira / Zendesk  — external sync
                            └── Lookup          — HTTP enrichment endpoint

An activity is one instance of work tracked under the app — one ticket, one incident, one approval request. Each activity has the attributes the app declares. Triggers fire as the activity moves through its lifecycle.

Lifecycle

[user posts in channel]
        │
        ▼
   onCreate ──► attributes filled / triggers fire / agents engaged
        │
        ▼
   activity open
        │
        ├── onComment   (user replies)
        ├── onEdit      (attribute changed)
        └── onConclude  (activity closed)

Scripts and agents only fire on user-originated events (loop protection via the call stack — see Scripting (Starlark)).

Where to start reading

Bundled apps (canonical examples)

FileDemonstrates
support.yamlMinimal support ticket
incident.yamlStatus states, severity, postmortem
approval.yamlSuperusers role, option-driven close
contact-form.yamlWeb connector, attribute mapping
bug.yamlStatus + severity, conclusion templates
jira.yamlJira integration, display macros

In this section

App YAMLTop-level structure of an app YAML. AttributesAttributes 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. Statuses and statesEvery activity has two related notions of "where it is in its lifecycle": TriggersTriggers are reactions to events on an activity. Each trigger has an **event** (when it fires), optional **conditions** (whether it fires), and one or more **actions** (what it does). Scripting (Starlark)Scripts are inline Starlark code that runs in response to triggers. They can read/write attributes, post and edit comments, and schedule themselves to fire again later. Agents in YAMLAgents are LLM-backed participants in a channel's activities. They read the ticket context and conversation history, then respond with a comment. ConnectorsConnectors bring data into a Conclude app from outside the chat platform — email, web forms, ticketing systems — or push enrichment data into an agent's context. Macros and rolesRoles control *who* can do things; macros let YAML reference *who* and *what* dynamically. They share a syntax — a role is essentially a macro that resolves to one or more users or channels. HTTP endpointsThe public HTTP endpoints Conclude exposes for web forms and inbound email, with request and response shapes from the code. Example appsAnnotated walkthroughs of the bundled support, incident, approval and contact-form app definitions, block by block, for builders reading YAML.