Surveys (YAML)
A survey is a form — the way Cotalker captures structured data from people. Surveys are usually the first resource partners learn to manage with cotctl, because they're self-contained and immediately useful. A survey is a code, a name, and a list of questions, and everything else — who can respond, conditional visibility, scoring, automation hooks — is layered on top of that spine.
This page is the map. It covers the minimal structure you'll write every day and the four commands you'll use to manage surveys; the subpages go deep on the parts that reward it.
The shape of a survey
At its simplest, a survey is three things:
kind: Survey
code: registro_empleado # unique per company, immutable after creation
name: "Employee Registration"
questions:
- type: textinput
identifier: re_nombre # company-wide unique, immutable after creation
label: "Name"
- type: listquestion
identifier: re_cargo
label: "Role"
options:
- label: "Analyst"
value: "analista"
Root fields
| Field | Required | Description |
|---|---|---|
kind | Yes | Always Survey |
code | Yes | Unique per company. Must match ^[a-z][a-z0-9_]*$. Immutable after creation |
id | No | The survey's _id, as surveys export writes it. It must be a 24-character hex ObjectId: validate and every apply, dry runs included, refuse any other value — id: "" too — and a malformed id no longer falls back to the code. With it, the survey is looked up by _id, and a code other than the stored one is refused |
name | Yes | Display name |
isActive | No | Defaults to true on create; an update that omits it keeps the stored value |
nameTranslations | No | es / en / pt / fr display-name translations |
permissions | No | AccessRole names, resolved to IDs on apply — who can respond |
bounds | No | Maps answers to task fields. cotctl cannot set it — the server's survey update doesn't store it, and apply warns (see Logic & validation) |
src | No | Scoring script (see Logic & validation) |
code is immutable, and so is every question identifier. Once a survey is created these can't change — choose them carefully. To "rename" either, you create a new resource. This is why a clear naming convention from the start pays off.
Beyond these, surveys carry optional fields for channel visibility and post-submission editing; export a real survey to see them all. Five keys the platform knows are out of cotctl's reach: the server's survey update stores none of onlyChannelCreation, responders, representation, bounds and reassignable, so a create gets their defaults whatever the YAML sets, and an update that is sent erases a value another client stored. Since 0.14.0 apply warns about both cases.
Questions
questions is an array. Every question, regardless of type, shares a common set of fields:
| Field | Required | Description |
|---|---|---|
type | Yes | The question type — one of 13 (see below) |
identifier | Yes | Company-wide unique ID. Must match ^[a-zA-Z][a-zA-Z0-9_]*$ |
label | Yes | The visible label |
help | No | Secondary help text |
required | No | Defaults to false |
isReadOnly | No | Defaults to false |
twoColumns | No | Two-column layout |
translations | No | Per-language label and help |
conditionalDisplay | No | Show/hide based on another answer |
exec | No | Automation hooks |
Identifiers: the one rule to internalize
A question's identifier must be unique across the entire company, not just within this survey. The convention that keeps you out of trouble is to prefix every identifier with the survey code:
# GOOD — prefixed, won't collide
identifier: re_nombre
# BAD — generic, will collide with other surveys
identifier: nombre
A few words are reserved and can't be used as identifiers: survey, user, channel, _id, UUID, target, properties.
What the subpages cover
The survey model has four areas deep enough to deserve their own page:
- Question types — the catalog of 13 types, with the minimal YAML and the type-specific fields each one needs (
optionsfor lists,filtersfor properties,sourcefor API-backed selectors, and so on). - Exec scripting — the six lifecycle hooks that run JavaScript inside a survey, the contexts your script can read, the commands it returns, and how to make authenticated network requests.
- Logic & validation — conditional display, scoring, binding answers to task fields (
bounds), and the three-layer validationcotctlruns before anything reaches the server. - Complete example — a full, annotated survey you can read end to end.
Managing surveys with cotctl
Surveys have their own entity-scoped command group. Every command takes a profile via the global -c <profile> flag.
| Command | What it does |
|---|---|
cotctl surveys list | List surveys (active by default; --all includes inactive; --code <code> looks up an exact code, paginating as needed and including inactive surveys; -s, --search <text> matches the name, not the code) |
cotctl surveys get <code> | Show one survey; --populate includes the full question list (and switches the default output to YAML) |
cotctl surveys export <code> | Export a survey as YAML (--format simplified or raw) |
cotctl surveys apply -f <file> | Create or update a survey from a YAML file |
cotctl surveys deactivate <code> | Soft-delete a survey (it's never hard-deleted) |
Applying safely
apply matches questions by identifier rather than position, so you can add, edit, remove, and reorder questions freely — IDs are preserved. Removing a question deactivates it rather than hard-deleting it. An interactive apply asks first; -y skips the question and apply --dir never asks it, and a dry run flags it as ⚠ DANGER. If you apply a survey YAML without its questions section, the existing questions are left untouched.
At the survey level, a key you omit keeps its stored value, and nameTranslations, editable, hidden and post are completed from the stored ones. A question you declare is the exception: it is written whole. It keeps its ID, but a field it omits takes its default (required: false, …), not its stored value — so declare every field a question should keep. The one field kept is display, which the simplified format has no key for: a question or table column that keeps its identifier and its type keeps its stored display — a placeholder, a datetime's input labels — instead of its type's default. A text question's label, a listquestion's option labels, and the label of a gps, image, file or signature question still replace the parts of display they stand for; a new question, a changed type, or a dateMode that adds or drops the time input gets the default. The dry run lists each display the update changes and counts as preserved each stored one it keeps. (Since 0.15.0 — before, every update sent the default. To put a display back to its default, edit it in the raw format or in the webclient.) A survey is sent whole or not at all: since 0.14.0 a YAML that changes nothing sends nothing and reads unchanged. (The first re-apply of an unmodified export of a survey built in the web app is the one exception: it is sent, and rewrites the survey in cotctl's shape. Since 0.16.0 its dry run names what that update changes, one entry per question and field.)
Two flags make apply safe to run in anger:
# Preview without touching the server. --diff controls verbosity.
cotctl surveys apply -f survey.yaml -c acme --dry-run --diff verbose
# In CI: fail the build if the dry-run detects a destructive change.
cotctl surveys apply -f survey.yaml -c acme --dry-run --fail-on-destructive
--dry-runvalidates and prints exactly what would be sent, without applying.--diff <off|compact|verbose>sets how much of the before/after the dry-run prints (defaultcompact). Since 0.16.0 the diff of a survey update names each question and field it changes (questions[identifier="…"].isReadOnly), and each question it adds or removes (questions[identifier="…"]); the compact diff counts a change several questions share on one line (+ questions[].isReadOnly ×7,+ questions[] ×3), andverboselists every entry. A chat bubble added or removed whole is one entry per item, its title included; the same questions in another order are onechangedentry on thechatlist. A note under the diff counts the stored keys at their default value that the update leaves out and that read back the same. In--jsonthe entries are indiff[], the notes are not, and a stored value the update removes — such asrequired: false— or a removed question is akind: "deleted"entry: to stop a pipeline only on a real loss, check the entry'sfield, or rely ondestructiveChangesand--fail-on-destructive.--fail-on-destructiveexits with code2when the dry-run finds any danger-severity change — an emptiedpermissionslist or, since 0.14.0, questions the update would deactivate — useful in a pipeline. (Requires--dry-run.) Two dry-run findings are only warnings and never exit2: a chat bubble the apply deactivates because the YAML cannot write it (one whose questions were all deactivated, or a bubble the export leaves out — a text bubble in the simplified format, or a bubble of a type the survey update does not accept back, such astext/system, which since 0.16.0--format rawskips too, with a warning), and a title whose own condition the apply drops.--yesskips the confirmation prompts;--jsonemits one result object per line for scripting (the prompt andApply cancelled.go to stderr).
A practical tip
The fastest way to learn the full structure is to export a real survey and read it:
cotctl surveys export <some_survey> -c acme -o example.yaml
Add --extract-scripts <dir> to pull inline exec scripts out into separate .js files referenced with file:// — much nicer to edit and diff.
See also
- apply — the shared apply pipeline and its ordering rules
- Export & import — export formats and
--extract-scripts - Workflows — surveys are referenced by workflow transitions and StartForms
- Data models — the entities a survey reads and writes