> ## Documentation Index > Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Activity Plans > Activity Plans define reusable automated workflows in Kodexa, with each Activity representing one run of the plan inside a project for document processing. 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](/guides/triggers/index). * **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. ```mermaid theme={null} flowchart LR Trigger["Trigger or manual start"] --> Plan["Activity Plan"] Plan --> Activity["Activity run"] Activity --> S1["EXECUTION step"] S1 --> S2["SCRIPT step"] S2 -->|needs review| T1["CREATE_TASK step"] S2 -->|clean| B1["BRIDGE_CALL step"] T1 --> B1 B1 --> Done["Completed Activity"] ``` ## 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. ```json theme={null} { "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: ```json theme={null} { "dependsOn": ["extract"] } ``` They can also reference a specific action emitted by a branching step: ```json theme={null} { "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 "" 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 "" depends on unknown 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 1. Start with the business process: what outcome does the organization need? 2. Define the documents and data model: what document families and data definitions are involved? 3. Identify the automation: extraction, classification, validation, enrichment, posting, and notifications. 4. Identify the human work: which decisions need a Task? 5. Identify external systems: which Service Bridges are needed? 6. Convert that model into an Activity Plan step graph. 7. Bind the Activity Plan and all referenced resources to the project that will run it. Automatically generate contextual titles and descriptions using AI. Learn each Activity Plan step kind and when to use it. Create human review, correction, and exception work from an Activity. Run module-backed extraction, classification, and processing work. Add JavaScript routing and business logic to an Activity Plan. Call external systems as first-class Activity Plan steps. Run bounded prompts and map model output into the workflow. Delegate bounded work to agent runtimes. Model authorization gates and approval outcomes.