Activity Plans - Kodexa Developer Portal

Activity Plans describe how Kodexa should run a document-heavy business process. They are the reusable definition. An Activity is one run of that definition inside a project. Use Activity Plans when you need the platform to coordinate automated work, human review, external system calls, and audit history as one workflow.

What an Activity Plan Defines

An Activity Plan answers four questions:

What starts the work? A manual start, intake upload, task status change, another Activity completing, or a Trigger.
What inputs are required? Document family IDs, project-specific values, routing hints, external reference IDs, or metadata supplied by the Trigger.
What steps run? A graph of CREATE_TASK, SCRIPT, BRIDGE_CALL, EXECUTION, LLM, AGENT, and APPROVAL steps.
What result is produced? Completed tasks, updated documents, external system updates, extracted data, logs, and step results.

Activity Plan vs Activity

Concept	Scope	What it means
Activity Plan	Organization	The reusable workflow definition: inputs, step graph, defaults, and metadata
Activity	Project	One execution of an Activity Plan with concrete inputs, status, steps, logs, and results
Step	Activity	One materialized unit of work inside an Activity run
Task	Project	Human work created by an Activity when review, correction, or approval is needed

Activity Plans are organization-level resources so the same business process can be reused across projects. A project must bind an Activity Plan before it can start Activities from it. That binding is intentional: it says this project is allowed to run this process with its document stores, task templates, data definitions, data forms, modules, and service bridges.

Basic Shape

An Activity Plan is usually authored as resource configuration and deployed with the rest of your Kodexa project assets.

{
  "name": "Invoice Intake",
  "slug": "invoice-intake",
  "description": "Classify, extract, review, and post invoice data",
  "inputsSchema": {
    "type": "object",
    "required": ["documentFamilyId"],
    "properties": {
      "documentFamilyId": { "type": "string" },
      "sourceSystem": { "type": "string" }
    }
  },
  "defaultTitleTemplate": "Invoice intake for {{documentFamilyId}}",
  "steps": [
    {
      "slug": "extract",
      "kind": "EXECUTION",
      "config": {
        "moduleRef": "kodexa/invoice-extractor",
        "options": {
          "documentFamilyId": "{{inputs.documentFamilyId}}"
        }
      }
    },
    {
      "slug": "route",
      "kind": "SCRIPT",
      "dependsOn": ["extract"],
      "config": {
        "scriptActions": [
          { "name": "review" },
          { "name": "post" }
        ],
        "scriptBody": "return { action: inputs.needsReview ? 'review' : 'post' };"
      }
    },
    {
      "slug": "analyst-review",
      "kind": "CREATE_TASK",
      "dependsOn": ["route:review"],
      "config": {
        "taskTemplateRef": "invoice-review",
        "waitForCompletion": true
      }
    },
    {
      "slug": "post-to-erp",
      "kind": "BRIDGE_CALL",
      "dependsOn": ["route:post", "analyst-review:approved"],
      "config": {
        "serviceBridgeRef": "finance-erp",
        "endpointName": "post-invoice",
        "requestBody": {
          "documentFamilyId": "{{inputs.documentFamilyId}}"
        }
      }
    }
  ]
}

Step Graphs

Steps form a directed graph. Each step has a slug, a kind, optional dependencies, and kind-specific configuration. Dependencies can reference a step generally:

{ "dependsOn": ["extract"] }

They can also reference a specific action emitted by a branching step:

{ "dependsOn": ["route:review"] }

This is how a SCRIPT step, approval step, human task, or bridge call can decide which path the Activity follows next.

Steps and Actions Are Keyed by Slug

An Activity Plan is portable: steps and their dependencies key on slugs, so a plan means the same thing wherever it runs. When an Activity starts, Kodexa projects the plan’s steps into fresh Activity-owned step rows and mints new internal identifiers for each one — nothing in dependsOn needs to know those runtime IDs. Because slugs are the only identity dependencies resolve against, they must be unambiguous. Kodexa validates this at Activity start:

Every step needs a slug and a kind. A step missing either fails the start.
Step slugs must be unique within a plan. A duplicate slug fails the start rather than silently misrouting every dependency that names it.
Action slugs must be unique within a step. Duplicate action slugs on one step fail the start.

Author slug values you control and keep them stable — renaming a slug is a breaking change to every step that depends on it.

dependsOn Forms

dependsOn accepts four forms:

Form	Meaning
`"slug"`	Run after the named step reaches `COMPLETED` or `SKIPPED`.
`"slug?"`	Await-only dependency: also satisfied when the upstream step is `NOT_TAKEN` (its branch was not chosen). An await-only dependency requires a `conditionExpr` on the step — Kodexa fails the Activity start with `step "<slug>" has await deps (? suffix) but no conditionExpr` if one is absent (the only exception is an `ANY_BRANCH` join whose union supplies its own guard).
`"slug:action"`	Run after the named step completes with that specific action.
`"slug?:action"`	Await-only, action-qualified. The `?` may sit on either side of the colon (`"slug?:action"` and `"slug:action?"` are equivalent).

A dependency on an unknown step slug fails the Activity start with step "<step>" depends on unknown slug "<slug>".

Action-Qualified Dependencies Resolve Against the Live Action Source

The action qualifier in "slug:action" must name an action the source step can actually emit at runtime. Each step kind has a single live action source:

Step kind	Live action source
`SCRIPT`	`scriptActions`
`BRIDGE_CALL`	`bridgeActions`
`LLM`	`promptActions`
`CREATE_TASK`	the referenced Task Template’s `metadata.actions`

The qualifier can be an action’s declared slug or, for legacy plans, its uuid value. References that could never fire are rejected at Activity start with a precise message — for example, an action declared only in a CREATE_TASK step’s inline actions array (a documentation mirror; tasks render actions from the template), or an action a step kind does not execute. A qualifier that matches more than one action sharing a slug also fails as ambiguous.

In earlier releases, an unresolvable action reference was stored verbatim and produced a silently dead branch that never fired. It now fails the Activity start loudly, so a mistyped or stale action reference surfaces immediately.

Legacy `uuid` Identities

Plans authored before slug portability carried a uuid on steps and actions. Kodexa treats an authored uuid as a legacy alias of the slug — the same identity space — so older plans and their dependsOn references keep working:

A step’s authored uuid is never a database identity; every run mints fresh internal IDs. A dependsOn entry that names a step by its authored uuid still resolves to that step’s slug.
An action declaring only a uuid (no slug) adopts the uuid value as its slug.

Aliases obey the same uniqueness rules as slugs, and identity conflicts fail the Activity start:

Two steps declaring the same authored uuid, or an authored uuid that collides with another step’s slug, fail the start.
An action declaring both a uuid and a slug with different values fails the start — uuid is the legacy spelling of slug, so keep the slug. Equal values are the accepted aliased form.

New plans carry no uuid fields. When an Activity starts from a plan that still holds legacy uuid identities, Kodexa logs a warning noting how many step and action uuids remain. Resaving the plan in the plan editor rewrites those uuids as slugs and converges the plan to the portable form.

Common Step Kinds

Step kind	Use it for
`CREATE_TASK`	Create human review, exception, approval, or correction work from a Task Template
`SCRIPT`	Run inline JavaScript for routing, document inspection, data updates, enrichment, or custom logic
`BRIDGE_CALL`	Call a configured Service Bridge as a first-class workflow step
`EXECUTION`	Run a module or automated extractor/classifier
`LLM`	Run a prompt or prompt template and map the result into the Activity
`AGENT`	Delegate a bounded operation to an agent runtime
`APPROVAL`	Pause for approval before continuing

A Practical Modeling Order

Start with the business process: what outcome does the organization need?
Define the documents and data model: what document families and data definitions are involved?
Identify the automation: extraction, classification, validation, enrichment, posting, and notifications.
Identify the human work: which decisions need a Task?
Identify external systems: which Service Bridges are needed?
Convert that model into an Activity Plan step graph.
Bind the Activity Plan and all referenced resources to the project that will run it.

AI Naming

Automatically generate contextual titles and descriptions using AI.

Step Catalog

Learn each Activity Plan step kind and when to use it.

Create Task Steps

Create human review, correction, and exception work from an Activity.

Execution Steps

Run module-backed extraction, classification, and processing work.

Script Steps

Add JavaScript routing and business logic to an Activity Plan.

Service Bridge Steps

Call external systems as first-class Activity Plan steps.

LLM Steps

Run bounded prompts and map model output into the workflow.

Agent Steps

Delegate bounded work to agent runtimes.

Approval Steps

Model authorization gates and approval outcomes.

​What an Activity Plan Defines

​Activity Plan vs Activity

​Basic Shape

​Step Graphs

​Steps and Actions Are Keyed by Slug

​dependsOn Forms

​Action-Qualified Dependencies Resolve Against the Live Action Source

​Legacy uuid Identities

​Common Step Kinds

​A Practical Modeling Order

AI Naming

Step Catalog

Create Task Steps

Execution Steps

Script Steps

Service Bridge Steps

LLM Steps

Agent Steps

Approval Steps

What an Activity Plan Defines

Activity Plan vs Activity

Basic Shape

Step Graphs

Steps and Actions Are Keyed by Slug

dependsOn Forms

Action-Qualified Dependencies Resolve Against the Live Action Source

Legacy `uuid` Identities

Common Step Kinds

A Practical Modeling Order