Skip to main content

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​

FieldRequiredDescription
kindYesAlways Survey
codeYesUnique per company. Must match ^[a-z][a-z0-9_]*$. Immutable after creation
idNoThe 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
nameYesDisplay name
isActiveNoDefaults to true on create; an update that omits it keeps the stored value
nameTranslationsNoes / en / pt / fr display-name translations
permissionsNoAccessRole names, resolved to IDs on apply — who can respond
boundsNoMaps answers to task fields. cotctl cannot set it — the server's survey update doesn't store it, and apply warns (see Logic & validation)
srcNoScoring 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:

FieldRequiredDescription
typeYesThe question type — one of 13 (see below)
identifierYesCompany-wide unique ID. Must match ^[a-zA-Z][a-zA-Z0-9_]*$
labelYesThe visible label
helpNoSecondary help text
requiredNoDefaults to false
isReadOnlyNoDefaults to false
twoColumnsNoTwo-column layout
translationsNoPer-language label and help
conditionalDisplayNoShow/hide based on another answer
execNoAutomation 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 (options for lists, filters for properties, source for 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 validation cotctl runs 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.

CommandWhat it does
cotctl surveys listList 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-run validates and prints exactly what would be sent, without applying.
  • --diff <off|compact|verbose> sets how much of the before/after the dry-run prints (default compact). 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), and verbose lists every entry. A chat bubble added or removed whole is one entry per item, its title included; the same questions in another order are one changed entry on the chat list. 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 --json the entries are in diff[], the notes are not, and a stored value the update removes — such as required: false — or a removed question is a kind: "deleted" entry: to stop a pipeline only on a real loss, check the entry's field, or rely on destructiveChanges and --fail-on-destructive.
  • --fail-on-destructive exits with code 2 when the dry-run finds any danger-severity change — an emptied permissions list 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 exit 2: 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 as text/system, which since 0.16.0 --format raw skips too, with a warning), and a title whose own condition the apply drops.
  • --yes skips the confirmation prompts; --json emits one result object per line for scripting (the prompt and Apply 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