Task Template

Kodexa Task Template Authoring

A task template is the organization-scoped definition of a human task's shape: the buttons a reviewer sees, the data forms that open, the documents that attach, how the task is titled, which panels are visible. One YAML file per template.

Projects do not own templates — they bind to them (the binding lives in kdxa_project_resources). The same template is reused by many projects.

Automation is not here. Step graphs are a separate activity-plan resource. planned: and planTemplate: are gone — the fields and their kdxa_task_templates columns were both removed, and the decoder discards them silently, so authoring them looks fine and does nothing.

The file that works

type: taskTemplate                # required by `kdx apply` (or pass --type)
orgSlug: acme-corp                # required (or pass --org-slug)
slug: invoice-review              # required — unique in the org, 3–100 chars
name: "Invoice Review"            # canonical display name
title: "Invoice Review"           # legacy column, still read at runtime — set BOTH (see below)
description: "Manual review of extracted invoice data"
template: false                   # true only for starter/library templates
deprecated: false                 # badge only; nothing is gated on it
metadata:
  teamSlug: finance-reviewers
  priority: 2                     # 1 Highest … 5 Lowest
  properties:
    hideDefaultCancelButton: true
  actions:
    - slug: approve               # slug is the action's IDENTITY
      label: "Approve"
      properties:
        statusSlug: approved      # the key that actually transitions the task

kdx apply -f task-templates/invoice-review.yaml

Without type: kdx apply errors with "resource file must contain a 'type' field"; without orgSlug: it errors with "cannot determine the target organization"; without slug: it refuses to push. Accepted type: spellings: taskTemplate, task-template, task-templates, taskTemplates, tasktemplate. Do not put organizationId: in the file — the CLI strips it before the push, so it is inert noise.

Six things that silently break

1 — slug is an action's identity; never let uuid disagree with it. An action's slug is what an activity plan's dependsOn: "<stepSlug>:<actionSlug>" edge points at, and what is recorded as the step's completion token when the task finishes. uuid is the deprecated legacy spelling; readers alias it when slug is absent. But if one action carries both and they differ, the platform refuses: every activity start (and plan validation) whose dependsOn names an action on a CREATE_TASK step using this template fails with "conflicting identities (uuid … vs slug …) — uuid is the legacy spelling of slug; keep the slug". One bad action poisons all of them. To rename a button, change label and keep the slug.

2 — the status transition key is properties.statusSlug. targetStatus appears nowhere in the platform. An action with only targetStatus is a no-op button: it saves the task, never transitions it, so no completion token is written and the downstream activity branch never fires. (properties.statusId is read only when statusSlug is absent.)

properties:
  statusSlug: approved      # ✅ works
  # targetStatus: approved  # ❌ read by nothing

3 — attribute writes use properties.attributes, an array. setAttributes is read by nothing. The real key writes taxon-path values onto the task's extracted data attributes (stamped with the reviewer's user:// owner), not onto task fields. See references/actions.md.

4 — set title: as well as name:. name is the canonical column; title is a separate legacy column still read directly in two places: the {templateName} placeholder in AI naming, on both the activity CREATE_TASK path and the intake path; and the CREATE_TASK "no title supplied" fallback. A template authored with only name: renders {templateName} as an empty string and gives activity-created tasks a blank title. Only the create-task API reads name first and falls back to title.

5 — the org placeholder is ${org}, not ${orgSlug}. In a kdx sync tree the CLI substitutes ${org}/ across the whole payload and hard-fails the push if any ${org} survives. ${orgSlug} is a server-side placeholder expanded only inside metadata.forms[].dataFormRef. Anywhere else — companion.moduleRefs, anything — ${orgSlug} is stored and used as a literal string that will never resolve.

6 — deleting a key usually does not delete it. metadata.properties is the one region where the local file is the desired state: remove a key from it and kdx sync push pushes the removal — but only while the file still has a properties: node. Delete the whole block and the region stops counting as authored, so the push keeps every server-side key; spell a full clear as properties: {}. Everywhere else in the file an absent key is indistinguishable from a key you never mentioned — push silently no-ops on the removal, --force included — so clear those by setting an explicit empty value instead.

There is also no server-side task-template validation: the rule set is empty and the handler defaults to disabled. Nothing will catch any of the above for you.

Declared but inert

Persisted, round-tripped, visible in existing YAML and sometimes editable in Studio — and read by nothing at runtime. Do not delete them from files that already have them; do not add them to new ones.

What changed from older YAML

Common mistakes

References

• references/fields.md — every live metadata key: the properties switchboard, forms[], documentFamilyGroups[], aiNaming and chatPrompt placeholder tables, agentShortcuts[], teamSlug/priority, companion, panel ids, plus how tasks get created, assignment/take-next and locking.
• references/actions.md — the action model end to end: identity, the activity-plan contract, and the full properties vocabulary.
• references/examples.md — three complete files with their kdx invocations.

Related skills: activity-plan (CREATE_TASK steps and dependsOn edges), task-status (what statusSlug points at, plus the locked / lockDocumentFamily defaults an action overrides), data-form (what dataFormRef points at), project-resource and project-template (where the project→template binding is authored), kdx-cli (kdx apply, kdx sync push).