Activity Plan

Kodexa ActivityPlan authoring

An ActivityPlan is an org-scoped directed graph of typed steps; starting one creates a project-scoped Activity plus a runtime step row per step. Plans live in kdxa_activity_plans, resolve as activity-plan://acme-corp/invoice-intake (unversioned), sync from an activity-plans/ directory, and must be bound to a project to run.

Resource shape

slug: invoice-intake                  # required, unique in the org
orgSlug: acme-corp                    # `kdx apply -f` needs it (or --org-slug); ${org} also resolves
name: Invoice Intake
type: activity-plan                   # routes the file — `kdx apply -f` refuses one without it
inputOptions:                         # the ONLY server-enforced input contract
  - { name: vendorId, label: Vendor, type: string, required: true }
  - { name: priority, label: Priority, type: selection, required: false }
inputsSchema: { type: object, required: [vendorId], properties: { vendorId: { type: string } } }
defaultTitleTemplate: "Invoice — {{ filename .documentPath }}"   # Go text/template; the start
defaultDescriptionTemplate: "{{ .documentCount }} document(s)"   # returns 400 if it fails to render
steps: [...]

A required inputOptions entry missing (or empty) in inputs fails the start: missing required inputs: <names>. inputsSchema only renders the Studio start form — never validated server-side — so declare every input in both.

The step envelope is FLAT and keyed by type

steps:
  - slug: extract                     # required; unique in plan; ^[a-z0-9][a-z0-9_-]*$
    type: EXECUTION                   # required — the discriminator is `type`, never `kind`
    moduleRef: "kodexa/fast-pdf-model"          # kind fields sit at the TOP LEVEL
    conditionExpr: "inputs.priority = 'high'"   # JSONata; false ⇒ step NOT_TAKEN
    setDocumentStatus: extracted      # any type; stamps a project document status on completion
    bypass: false                     # any type; true ⇒ step settles SKIPPED with no work

• kind: is not an alias — a step without type fails the start: step missing required slug or type.
• There is no config: {} wrapper: it is silently flattened into the step on save (so a later pull looks like a rewrite), and the save-time validator runs before that flattening, over the flat keys — so wherever that validator is enabled it reports your wrapped fields as missing.
• bypass: true settles the step SKIPPED, never COMPLETED — and SKIPPED is pass-through for every dep form, action-qualified ones included, so bypassing a router releases its branches, never strands them.

Step types

Only these seven are safe. TASK, BRIDGE and AI_PLANNER sit outside the accepted type set and materialize with none of their type-specific fields (AI_PLANNER settles SKIPPED); AI_PROMPT is accepted but loses its prompt fields at start; APPROVAL is not implemented — the orchestrator settles it SKIPPED at once, so it never reaches an approver and can never emit an action (use CREATE_TASK with a review template); and AGENT ignores assistantRef/agentInputs, then fails the step with planned agent <id> has no agent_runtime_id.

Reference formats differ per field

${orgSlug} is expanded when the plan is saved, inside steps, metadata, inputOptions, inputsSchema, documentFamilyGroups and the two templates — so moduleRef: "${orgSlug}/helpers" works while promptTemplateRef: "${orgSlug}/…" does not. ${org}/ is a different placeholder, expanded by kdx at push.

Dependency and action edges

Only SCRIPT, LLM, BRIDGE_CALL and CREATE_TASK can emit actions — an action edge off an EXECUTION, AGENT or APPROVAL step is an error at start (action-edge-upstream-cannot-emit). Actions are declared {name, slug} (uuid is the legacy spelling of slug; both, differing, is rejected). The live source is scriptActions / promptActions / bridgeActions — and for CREATE_TASK, the referenced TaskTemplate's own actions plus the org's DONE-typed task-status slugs; the step's inline actions: array is a mirror only, and an edge matching only it fails the start.

Every SCRIPT step must declare scriptActions and return one of them. The runtime needs a returned object with a non-empty action matching one by slug (exact) or name (case-insensitive); return {}, or returning an action with nothing declared, fails the step. There is no action() function and no ctx/context global — the globals are inputs, families, task, org, documents, tasks, knowledge, loadDocument, serviceBridge, llm, log. Worked SCRIPT steps: references/examples.md.

Per-document processing, routing and document status

perDocument: true fans a step out over the activity's document families. Valid only on EXECUTION (default true), LLM, SCRIPT, BRIDGE_CALL (default false); anywhere else is an error (per-document-unsupported). maxParallel is EXECUTION-only (default 5) — on LLM/SCRIPT/BRIDGE_CALL it is an error, because those per-document paths run sequentially.

Routing is auto-detected, never a flag: it turns on when a perDocument step declaring actions is the target of an action-qualified dep. Branch with dependsOn: ["classify:receipt"] / ["classify:invoice"], then re-join on a perDocument step with joinPolicy: ANY_BRANCH whose branch deps are await-only (["receipt-extract?", "invoice-extract?"]) — plain branch deps AND-combine per document and converge nothing. joinPolicy is ALL_SETTLED (default), ALL_COMPLETED, ANY_COMPLETED or ANY_BRANCH; a document whose action matches no edge is NOT_TAKEN on every branch and counted unrouted.

setDocumentStatus: <slug> works on any step type, resolving against the project's document statuses (kdxa_project_document_status, not task statuses): a perDocument step stamps the families that COMPLETED there, any other step stamps every family in the activity. Best-effort — an unknown slug is logged, never fatal. Under routing, conditionExpr is evaluated per document and gains a document object (.status slug-or-null, .statusLabel, .locked, .labels, .path), so a root step can gate with "$not(document.status in ['reviewed', 'completed'])"; elsewhere document.* is inert.

Template languages — four, in one file

JSONata roots: conditionExpr and BRIDGE_CALL maps see {orgId, projectId, inputs, documentFamilyId, extractedData, steps}, where upstream output is steps.<slug>.<key>; LLM promptVariables see {context: {orgId, projectId, inputs}, enrichment, steps}, so an enrichment result is at enrichment.<outputKey>, never context.<outputKey>. Backtick hyphenated slugs: steps.`a-b`.action. steps holds COMPLETED steps only, and in a BRIDGE_CALL request* map a path that matches nothing fails the step (eval: no results found) — guard the full path: "$exists(steps.review.completedActionUuid) ? steps.review.completedActionUuid : ''".

Validate, bind, start

• POST /api/activity-plans/validate with {steps, organizationId} returns {valid, issues:[{stepSlug, code, severity, message}]}, always 200 — the same checks the start enforces, but all of them; every severity: "error" means start returns 400. The separate save-time rule set is off unless a deployment enables it, so a clean save proves nothing.
• The plan must be bound to the project — a kdxa_project_resources binding of type activity-plan — else POST /api/activities returns 400: activity-plan "<slug>" is not bound to project <id>; create a project-resource binding first.
• Start body: projectId + activityPlanRef required, plus optional title, inputs, triggerKind (default MANUAL), documentFamilyIds, documentFamilyFilter; success is 201. Also launchable from a Trigger, an intake script returning { activityPlan: 'invoice-intake', … }, or a SCRIPT nextActivity.

What the run runs over is chosen at start, not by the plan — and selecting nothing is silent. documentFamilyIds / documentFamilyFilter resolve once at start, then intersect with the document stores bound to the project; a family in an unbound store is dropped there with no error either side. An empty result is not a failure: every perDocument step fans out over zero documents, settles COMPLETED, and the activity finishes green — so "the plan ran and nothing came out" is more often an empty document set than a broken step. Assert the document count before debugging a step. Only a documentFamilyGroups entry with required: true fails loudly instead, with a 400 naming the group.

Declared but inert

Persisted, round-tripped, present in existing YAML — and read by nothing.

Common mistakes

See references/step-types.md (per-type fields, runtime contexts, limits, plan-level keys), references/validation.md (every issue code) and references/examples.md (complete plans). Related skills: task-template, task-status, trigger, service-bridge, prompt-template, module.