> ## 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 Plan Steps

> Reference for all step kinds in a Kodexa Activity Plan, including how steps materialize at runtime and how status, timing, results, and logs are tracked.

An Activity Plan is a graph of steps. Each step is materialized when an Activity starts, then tracked independently with status, timing, result, logs, and error details.

## Step Anatomy

Every step has the same top-level shape:

```json theme={null}
{
  "slug": "route-invoice",
  "kind": "SCRIPT",
  "dependsOn": ["extract"],
  "conditionExpr": "inputs.sourceSystem != 'manual'",
  "config": {}
}
```

| Field           | Description                                                       |
| --------------- | ----------------------------------------------------------------- |
| `slug`          | Unique identifier for the step inside the Activity Plan           |
| `kind`          | The step type, such as `SCRIPT` or `BRIDGE_CALL`                  |
| `dependsOn`     | Steps or step actions that must complete before this step can run |
| `conditionExpr` | Optional predicate that can skip the step                         |
| `config`        | Kind-specific settings                                            |

When an Activity starts, Kodexa copies the plan's step graph into Activity-owned step rows. After that, the running Activity uses the materialized steps. Editing the Activity Plan affects future Activities, not Activities already in flight.

## Dependency Patterns

Run after another step completes:

```json theme={null}
{
  "slug": "extract",
  "kind": "EXECUTION"
},
{
  "slug": "route",
  "kind": "SCRIPT",
  "dependsOn": ["extract"]
}
```

Run only after a specific action:

```json theme={null}
{
  "slug": "analyst-review",
  "kind": "CREATE_TASK",
  "dependsOn": ["route:review"]
}
```

Join multiple paths:

```json theme={null}
{
  "slug": "finalize",
  "kind": "BRIDGE_CALL",
  "dependsOn": ["auto-approve", "analyst-review:approved"]
}
```

Use action-qualified dependencies when a step can produce more than one outcome. This keeps the graph explicit: the routing decision lives on the upstream step, and the downstream step declares which outcome it depends on.

## CREATE\_TASK

Use `CREATE_TASK` when the workflow needs human judgment, correction, exception handling, or approval.

```json theme={null}
{
  "slug": "analyst-review",
  "kind": "CREATE_TASK",
  "dependsOn": ["route:review"],
  "config": {
    "taskTemplateRef": "invoice-review",
    "taskStatusSlug": "open",
    "waitForCompletion": true,
    "taskData": {
      "priority": "{{inputs.priority}}",
      "documentFamilyId": "{{inputs.documentFamilyId}}"
    }
  }
}
```

| Config key          | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `taskTemplateRef`   | Task Template used to create the Task                                      |
| `taskStatusSlug`    | Initial Task status                                                        |
| `waitForCompletion` | Whether the Activity should pause until the Task reaches a terminal status |
| `taskData`          | Data copied onto the created Task                                          |

If `waitForCompletion` is true, the Activity waits for the reviewer to complete the Task. The Task's status or action can then drive the next step.

See [Create Task Steps](/guides/activity-plans/create-task-steps) for the full human-work guide.

## SCRIPT

Use `SCRIPT` when the workflow needs custom JavaScript logic.

Good uses:

* Route based on document content or metadata
* Normalize values before review
* Assign knowledge features
* Call several Service Bridges and make a decision
* Prepare inputs for another step

```json theme={null}
{
  "slug": "route",
  "kind": "SCRIPT",
  "dependsOn": ["extract"],
  "config": {
    "scriptActions": [
      { "name": "review" },
      { "name": "post" },
      { "name": "reject" }
    ],
    "scriptBody": "return { action: inputs.needsReview ? 'review' : 'post' };"
  }
}
```

See [Script Steps](/guides/activity-plans/script-steps) for the full scripting guide.

## BRIDGE\_CALL

Use `BRIDGE_CALL` when the workflow should call an external system as a first-class step.

Good uses:

* Validate extracted data against a system of record
* Post approved data to an ERP, CRM, claims, or lending system
* Fetch enrichment data needed by the next step
* Notify a downstream system when a workflow completes

```json theme={null}
{
  "slug": "post-to-erp",
  "kind": "BRIDGE_CALL",
  "dependsOn": ["analyst-review:approved"],
  "config": {
    "serviceBridgeRef": "finance-erp",
    "endpointName": "post-invoice",
    "requestBody": {
      "documentFamilyId": "{{inputs.documentFamilyId}}"
    },
    "treatAsError": "$.status != 'accepted'",
    "timeoutSeconds": 30
  }
}
```

See [Service Bridge Steps](/guides/activity-plans/service-bridge-steps) for the full bridge-step guide.

## EXECUTION

Use `EXECUTION` to run a module or automated processing component.

```json theme={null}
{
  "slug": "extract",
  "kind": "EXECUTION",
  "config": {
    "moduleRef": "kodexa/invoice-extractor",
    "options": {
      "documentFamilyId": "{{inputs.documentFamilyId}}"
    },
    "perDocument": true,
    "maxParallel": 4
  }
}
```

| Config key    | Description                                 |
| ------------- | ------------------------------------------- |
| `moduleRef`   | Module to run                               |
| `options`     | Module-specific options                     |
| `perDocument` | Whether to run once per document family     |
| `maxParallel` | Parallelism limit when running per document |

See [Execution Steps](/guides/activity-plans/execution-steps) for the full module execution guide.

## LLM

Use `LLM` for bounded prompt execution where the Activity Plan owns the prompt, inputs, and result mapping.

```json theme={null}
{
  "slug": "summarize-exception",
  "kind": "LLM",
  "dependsOn": ["route:review"],
  "config": {
    "promptTemplateRef": "invoice-exception-summary",
    "promptVariables": {
      "documentFamilyId": "{{inputs.documentFamilyId}}"
    },
    "includeDocument": true
  }
}
```

Prefer an `LLM` step for direct prompt execution. Prefer an `AGENT` step when the work requires tool use or multi-step reasoning.

See [LLM Steps](/guides/activity-plans/llm-steps) for the full prompt-step guide.

## AGENT

Use `AGENT` when a bounded part of the Activity should be delegated to an agent runtime.

Typical uses:

* Draft a routine Activity Plan or Data Form
* Investigate a document exception and propose next steps
* Assemble test cases or validation checks
* Use tools to inspect project resources before producing a result

Keep agent steps constrained. The Activity Plan should still define the process boundary, inputs, expected output, and downstream routing.

See [Agent Steps](/guides/activity-plans/agent-steps) for the full agent-step guide.

## APPROVAL

Use `APPROVAL` when a workflow must explicitly pause for authorization before continuing.

```json theme={null}
{
  "slug": "manager-approval",
  "kind": "APPROVAL",
  "dependsOn": ["analyst-review:approved"],
  "config": {
    "approverRole": "finance-manager",
    "approvalCriteria": {
      "amountGreaterThan": 10000
    }
  }
}
```

See [Approval Steps](/guides/activity-plans/approval-steps) for approval-gate modeling.

## Choosing Between SCRIPT and BRIDGE\_CALL

| Need                                                                   | Prefer                                |
| ---------------------------------------------------------------------- | ------------------------------------- |
| One configured external API call with clear input and output           | `BRIDGE_CALL`                         |
| Multiple calls, custom branching, or document mutation                 | `SCRIPT` using `serviceBridge.call()` |
| Pure routing or validation logic inside Kodexa                         | `SCRIPT`                              |
| External system update that should be visible as its own workflow step | `BRIDGE_CALL`                         |

Make the graph explain the business process. Use first-class steps for work operators should monitor directly. Use scripts for logic that is naturally internal to a decision.