Workflows (YAML)
A workflow models a process: a task that moves through a series of states, from creation to closure. Workflows are the most powerful — and the most structured — resource in Cotalker. You rarely write one from scratch: cotctl workflows scaffold generates a correct skeleton, and this page explains what that skeleton contains so you can customize it with confidence.
This is the map. It covers the hierarchy, the real root fields, and the commands; the subpages cover the parts subtle enough to bite you — merge semantics, immutability, COTLang expressions.
The hierarchy
A single workflow YAML document manages a nested structure:
Workflow (the process: name, permissions, settings)
└── stateMachines[] (one or more independent flows)
└── states[] (the steps a task moves through)
└── next[] (the allowed transitions between states)
The workflow level
The top of the file describes the workflow itself:
kind: Workflow
nameCode: purchase_orders # immutable after creation
nameDisplay: Purchase Orders
isActive: true
hideClosedAfterDays: 30
readPermissions:
- purchase_orders:view # literal permission codes (see below)
writePermissions:
- purchase_orders:start-form
stateMachines:
- # ...
Root fields
The schema defines these top-level fields:
| Field | Required | Notes |
|---|---|---|
kind | Yes | Always Workflow |
nameCode | Yes | Unique per company. Immutable after creation. Min 3 chars, ^[a-z][_a-z0-9]*$ |
nameDisplay | No | Display name. If omitted, apply runs in "SM-only mode" (see below) |
nameTranslations | No | es / en / pt / fr |
color, icon | No | Display appearance |
weight | No | Display order (default 0) |
isActive | No | Defaults to true on create; an update that omits it keeps the stored value |
hideClosedAfterDays | No | Days before closed tasks are hidden (0–1825). Defaults to 7 on create, which is often too short — consider 30 |
readPermissions | No | Permission codes — who can read tasks |
writePermissions | No | Permission codes — who can create tasks |
taskImportPermissions | No | Permission codes — who can import tasks |
taskFollowerPermissions | No | Permission codes — who can be added as followers |
taskEditorPermissions | No | Permission codes — who can edit tasks |
availableViews, defaultView | No | Which UI views (e.g. kanban, list) are available |
taskPaginationLimit | No | Tasks per page in the task list, an integer from 10 to 100 (0.16.0+). Takes precedence over the Company's limit. Omit it to keep the stored value; null clears it, back to the Company's limit |
defaultSortBy | No | Order of the task list's default view: modifiedAt or createdAt (0.16.0+). See below |
stateMachines | No | The list of state machines |
Task list paging and order
New in 0.16.0. Two root fields configure the workflow's task list:
taskPaginationLimit: 50 # 10–100, or null for the Company's limit
defaultSortBy: createdAt # modifiedAt | createdAt
taskPaginationLimit — how many Tasks the task list loads per page. validate and every apply refuse a value outside 10–100, a fraction or a string. Omitting the key keeps the stored value, and a workflow that never set one uses the Company's limit; taskPaginationLimit: null — or the key written with no value, which YAML reads as null — clears it, back to the Company's limit. workflows get prints it as Tasks per page when the workflow has its own limit.
defaultSortBy — which date orders the default view. Tasks are always listed newest first; modifiedAt (the default of a workflow that never set it) sorts by last modification, createdAt by creation. Any other value is refused before a request is sent, null included — and so is the key written with no value: to go back to the default, write modifiedAt.
For both, --dry-run shows the change in the workflow's diff, and workflows export writes the key only when the workflow stores a value.
Both fields need a backend that stores them. An older backend accepts the request and drops the key, so the apply reports success and the next --dry-run lists the same change again.
Since 0.14.0 a key the root doesn't declare is refused, by validate and every apply (exit 1), instead of dropped without a word. The usual cause is a state-machine field written one level too high — cardLabels at the root — and the message says where it goes (stateMachines[].cardLabels); a root code or name is pointed at nameCode or nameDisplay.
Permission fields are literal permission codes — not AccessRole names. The five permission arrays (readPermissions, writePermissions, taskImportPermissions, taskFollowerPermissions, taskEditorPermissions) hold permission code strings like web-admin-write or purchase_orders:view, and cotctl sends them to the server verbatim — it does not resolve them to AccessRole IDs. This is different from surveys, whose permissions field does take AccessRole names. Put the permission code itself here, exactly as it appears on the role that grants it. (Older workflows may still carry raw ObjectIds in these fields from a previous cotctl version; export surfaces those with a legacy marker so you can replace them.)
A StartForm's and a transition's permissions take permission codes too. Since 0.14.0, workflows apply, apply -f and apply --dir warn about a code that no active AccessRole grants — a typo, an AccessRole id written where a code belongs, or a code only an inactive role grants. No user holds such a code, so a list made only of them keeps the StartForm or the transition from everyone. The warning doesn't stop the apply.
State machines, states, and transitions
Each stateMachines[] entry is an independent flow. It declares which data drives it and where it starts:
stateMachines:
- code: sm_po_main
name: PO Main Flow
propertyType: pt_po_states # immutable after creation
asset:
type: unique # "unique" or "generic" — immutable
propertyType: pt_po_assets
initialState: po_draft
states:
- property: po_draft # a Property code that must already exist
type: new # "new" | "in-progress" | "closed" — immutable
next:
- target: po_approved
canChange: manual
- target: po_rejected
canChange: survey
requiredSurvey: survey_rejection_reason
The asset. asset.type is unique or generic. A generic asset must name its Property in asset.property — one Property code, written as a one-entry list as workflows export writes it:
asset:
type: generic
propertyType: pt_po_assets
property: [po_asset_main]
Since 0.14.0 a generic asset without asset.property, or with property: [], is refused by validate and every apply (exit 1) — the server refuses to save it, and before, that surfaced mid-apply as a server error. asset.property takes one code on any asset; a list of two or more is refused too. On a unique asset it stays optional, and property: [] clears it.
Each state corresponds to a Property. Its type is one of new, in-progress, closed. A transition's canChange controls how it fires:
canChange | Meaning |
|---|---|
manual (default for a new transition) | A user triggers it from the task UI |
survey | The user must complete a survey first — set requiredSurvey to its code |
none | Only automation/system can trigger it (e.g. auto-closure) |
State machines also support a requiredSurvey (a StartForm that gates task creation), and states support subtask and surveyTriggers slots — all of which can carry automation bots. Those slots have preserve/replace/delete rules you must understand before editing a live workflow; the Merge semantics page covers them — including partial: true (0.14.0+), which edits one state, transition or bot stage without restating the rest.
Card labels, task extensions and the default tab
New in 0.12.0. Three settings that could only be configured from the webclient are now declarable from YAML. Before this release cotctl could not see any of them — and worse, every workflows apply silently erased the first two, so an apply meant to rename a transition also wiped configuration somebody had set in the UI. Both halves are fixed: they are preserved when your YAML omits them, and declarable when it does not.
stateMachines:
- code: sm_po_main
cardLabels:
status1: pt_po_priority
status3: pt_po_supplier
allowedExtensions:
- pt_po_photo
- pt_po_signature
defaultSelectedTaskTab: task # a root field, not a state-machine one
cardLabels — which PropertyType values a task card shows. The map takes a slot (status1 through status5) to a PropertyType code, so declaring a slot is what activates it. Slots may be sparse, and the card renders them in ascending slot order, which the YAML cannot change. An unknown slot key such as status6 is a validation error, not a key that gets quietly dropped.
allowedExtensions — the PropertyTypes a task may carry as an extension, by code. The list is replaced wholesale rather than merged, so an entry you leave out stops being an accepted extension.
defaultSelectedTaskTab — the tab a task opens on, set at the workflow root. One of notes, channel, task, documents, or null to clear it. There is no detail tab; it has been reported as one, and that value is rejected rather than sent.
Omitting a key is not the same as emptying it
This is the distinction to get right, and it is the same one Merge semantics draws for the rest of the document:
| You write | What happens |
|---|---|
| The key is absent | The server's value is preserved. Nothing changes |
cardLabels: {} | Every label slot is deactivated |
A cardLabels map with some slots | The slots you name are activated; every slot you omit is deactivated |
allowedExtensions: [] | Every accepted extension is removed |
defaultSelectedTaskTab: null | The setting is cleared |
A --dry-run reports the destructive half of this: which labels the card stops showing, and how many extensions the apply would lose — from workflows apply and, since 0.14.0, from the unified apply as well. Since 0.15.0 it also lists a declared cardLabels equal to the stored one as preserved, so the diff alone shows that the labels survive the apply; the entry counts in the headline's preserved and reaches --json as a diff[] entry with field: "dynamicPropertyTypes" and kind: "preserved", while the state machine still reads no-op.
The text output names the labels cardLabels, the key the YAML uses (0.16.0+): ~ cardLabels: … when they change, = cardLabels (preserved) when they don't. Earlier versions printed the API's name, dynamicPropertyTypes; --json keeps that name in its diff[] entry. And since 0.16.0, --diff verbose lists a state machine's preserved entries even when it changes nothing else — under its No changes or [NO-OP] line — where before they reached only --json.
What validate --dir checks, and what export warns about
Every cardLabels slot and every allowedExtensions entry is resolved against the PropertyTypes declared in the directory (check X3), so a typo is caught offline rather than becoming a backend error.
A code that resolves to nothing aborts the whole workflow apply with PropertyType "<code>" not found. Since 0.16.0 the dry run reports the same error and exits 1 — for a workflow the server has and for one it doesn't have yet — where it used to show the code as a planned change with exit 0. The same holds for the state machine's propertyType, its asset's propertyType, a generic asset's property (Property "<code>" not found) and a state's property. Under apply --dir --dry-run, a PropertyType or Property the same directory declares counts as present, since the apply creates it first. When the dry run cannot read the Properties a state machine references, it says so in a warning naming the state machine and leaves the verdict to the apply. On the way out, workflows export warns on stderr when it cannot resolve a stored id back to a code and emits the raw id — re-applying that YAML would abort, naming a PropertyType nobody wrote. The usual cause is a slot left pointing at a PropertyType that was deleted, deactivated, or is invisible to the profile doing the export.
workflows export output changed shape in 0.12.0. cardLabels and allowedExtensions are now emitted when they are configured. A workflow that uses neither exports exactly as before, but if you keep exports under version control, expect the two keys to appear in your next diff.
SM-only mode
If your YAML declares none of the workflow's root fields — no Group field (nameDisplay, color, …) and no TaskGroup field (the permission lists, hideClosedAfterDays, …) — apply runs in SM-only mode: it touches only the state machines and states, leaving the workflow's display settings and permissions untouched, and the workflow must already exist. This is exactly what you want when adding a second state machine to a workflow that already exists, without resetting anything.
Since 0.14.0 the two root levels are also applied separately: a YAML that declares only TaskGroup fields (say, readPermissions) patches the TaskGroup and leaves the Group alone, and the reverse. And because an omitted field keeps its stored value on every level, the defaults in the table above apply only when the workflow is created.
What the subpages cover
- Merge semantics — the GET-merge-PUT contract (0.7.0+): why an omitted field is preserved but an explicit
[]deletes, which fields it applies to, and the silent errors it prevents. Read this before editing a live workflow. - COTLang — the expression language for bot
data, and the reserved characters that break it. - Immutability & versioning — what can't change after creation, why states are permanent, and the bot-version rules
cotctlenforces. - Complete example — a full purchase-order workflow, annotated.
Managing workflows with cotctl
| Command | What it does |
|---|---|
cotctl workflows list | List workflows (active by default; --all includes inactive) |
cotctl workflows get <nameCode> | Show one workflow with its state machines and states |
cotctl workflows export <nameCode> | Export a workflow as YAML |
cotctl workflows apply -f <file> | Create or update a workflow from YAML |
cotctl workflows scaffold | Generate a correct workflow skeleton |
cotctl workflows deactivate <nameCode> | Deactivate the workflow (its state machines stay active) |
Applying safely
# Preview against the server, showing a verbose diff
cotctl workflows apply -f workflow.yaml -c acme --dry-run --diff verbose
# In CI: fail on any destructive change the dry-run detects
cotctl workflows apply -f workflow.yaml -c acme --dry-run --fail-on-destructive
--dry-runvalidates and shows what would happen without applying.--diff <off|compact|verbose>sets the before/after verbosity (defaultcompact).verbosealso lists what a state machine with nothing to change keeps —= cardLabels (preserved), say — under itsNo changesline.--fail-on-destructiveexits with code2when the dry-run finds a danger-severity change (requires--dry-run).--rollbackdeactivates anything created during a partial apply if it fails partway.--yesskips confirmations;--jsonemits one result object per line.
A dependency note
A transition's requiredSurvey — like a StartForm's requiredSurvey.surveyCode and a state's surveyTriggers[].survey — references a survey by code. Since 0.14.0 a workflow that names a survey the server doesn't have is refused before its first write, --dry-run included, with exit 1 and the reference named in the error. Before, the apply stopped halfway — after creating the Group, the TaskGroup, the state machine and its states — while the dry run passed.
Under apply --dir this is handled for you: surveys are applied before workflows, so a survey the same directory applies counts as present (and validate --dir checks it offline, as X7). It matters when you run the two commands separately — then the order is yours to get right:
cotctl surveys apply -f surveys.yaml -c acme
cotctl workflows apply -f workflow.yaml -c acme
Since 0.16.0 validate --remote reaches the same verdict on those Surveys. validate --dir --remote and validate -f --remote look each one up as the dry run does (not for a partial: true document) and fail with exit 1 on one the server doesn't have, naming where the workflow names it (--dir --json lists it under remoteResults with the id R3). With --dir, a Survey the directory declares counts as present, wherever its file sorts; with -f, only the server counts — so validate a workflow whose Surveys sit in sibling files with --dir, next to them. Codes match whatever their case, and --remote needs a credential: -c <profile>, or COTCTL_TOKEN and COTCTL_API_URL. The dry run still checks more — a Survey's permissions, and a bot stage missing the data its type requires, which validate --remote only warns about — so it stays the last check before an apply.
See also
- Scaffolding — generate the workflow skeleton
- Properties and Roles — the resources a workflow references
- validate — the production-readiness checklist for live workflows
- Data models — Task and TaskGroup, the entities a workflow produces