> ## 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.

# Execution Steps

> Run modules and automated processing as EXECUTION steps in Activity Plans, covering extraction, classification, conversion, enrichment, and validation.

`EXECUTION` steps run automated processing work. Use them for extraction, classification, conversion, enrichment, validation, or any module-backed processing that should be tracked as part of an Activity.

An execution step is the platform showing up in the business process: it does configured work, records status, captures outputs, and gives downstream steps a reliable dependency point.

## When to Use EXECUTION

Use `EXECUTION` when the Activity should run a module or pipeline component:

* Extract fields from a document
* Classify a document family
* Convert or normalize document content
* Run a reusable validation module
* Enrich a document with structured outputs
* Apply a processing module across many document families

Use `SCRIPT` for inline business logic. Use `BRIDGE_CALL` for external API calls. Use `EXECUTION` for module-backed processing.

## Basic Shape

```json theme={null}
{
  "slug": "extract-invoice",
  "kind": "EXECUTION",
  "dependsOn": ["intake"],
  "config": {
    "moduleRef": "kodexa/invoice-extractor",
    "moduleOptions": {
      "schema": "invoice"
    },
    "perDocument": true,
    "maxParallel": 4
  }
}
```

| Config key      | Description                                                         |
| --------------- | ------------------------------------------------------------------- |
| `moduleRef`     | Module reference to execute                                         |
| `moduleOptions` | Module-specific options passed into the execution                   |
| `perDocument`   | Run once per document family instead of once for the Activity       |
| `maxParallel`   | Limit parallel launches when `perDocument` is enabled               |
| `bypass`        | Skip the step while keeping downstream dependency behavior explicit |

The runtime requires `moduleRef` for an `EXECUTION` step.

## Single Execution

Use a single execution when the module should process the Activity context as one unit.

```json theme={null}
{
  "slug": "classify-packet",
  "kind": "EXECUTION",
  "config": {
    "moduleRef": "kodexa/loan-packet-classifier",
    "moduleOptions": {
      "packetType": "{{inputs.packetType}}"
    }
  }
}
```

Kodexa creates an execution pipeline for the module, attaches the Activity and project context, and marks the step running until the execution completes.

## Per-Document Execution

Use `perDocument` when each document family should be processed independently.

```json theme={null}
{
  "slug": "extract-each-document",
  "kind": "EXECUTION",
  "config": {
    "moduleRef": "kodexa/generic-extractor",
    "perDocument": true,
    "maxParallel": 5
  }
}
```

This gives the Activity document-level progress. It also lets downstream review steps focus on only the document families that failed or produced exceptions.

```mermaid theme={null}
flowchart TB
    Step["EXECUTION step"] --> D1["Document family A"]
    Step --> D2["Document family B"]
    Step --> D3["Document family C"]
    D1 --> Join["Step result"]
    D2 --> Join
    D3 --> Join
```

## Parallelism

`maxParallel` controls how many per-document executions can be launched at once. Keep it high enough for throughput and low enough for downstream systems, model limits, or module resource needs.

Typical starting points:

| Work type                        | Starting `maxParallel` |
| -------------------------------- | ---------------------: |
| Lightweight classification       |                   5-10 |
| Extraction with model calls      |                    2-5 |
| External-system-heavy enrichment |                    1-3 |
| Resource-intensive conversion    |                    1-2 |

Tune parallelism from runtime evidence: queue depth, module duration, downstream throttling, and error rates.

## Knowledge Assessment

Execution steps can run after document knowledge has been assessed and enriched. This matters when a module depends on document family classification, feature assignment, or project knowledge sets.

Practical pattern:

1. Intake creates document families.
2. Knowledge assessment identifies document type or relevant features.
3. `EXECUTION` runs the right extractor or classifier.
4. `SCRIPT` or `LLM` routes the outcome.
5. `CREATE_TASK` handles exceptions.

## Downstream Dependencies

Downstream steps should depend on the execution step once its automated work is complete.

```json theme={null}
[
  {
    "slug": "extract",
    "kind": "EXECUTION",
    "config": {
      "moduleRef": "kodexa/invoice-extractor",
      "perDocument": true
    }
  },
  {
    "slug": "route",
    "kind": "SCRIPT",
    "dependsOn": ["extract"],
    "config": {
      "scriptBody": "return { action: inputs.exceptionCount > 0 ? 'review' : 'post' };"
    }
  }
]
```

Use action-qualified dependencies only when the upstream step emits explicit actions. An `EXECUTION` step usually completes or fails; a following `SCRIPT` step is often where branching belongs.

## Error Handling

Design for failure paths. Extraction and classification modules can fail because of document quality, unsupported layouts, missing configuration, or model/provider errors.

Good Activity Plans make those outcomes explicit:

* Let the execution step fail when the module cannot produce a trustworthy result.
* Use a downstream exception task for recoverable data issues.
* Use logging and step results for operational troubleshooting.
* Keep business routing in `SCRIPT` or `LLM` steps rather than hiding it inside a module when the decision should be visible to workflow owners.

## Checklist

* `moduleRef` points to a module available to the project.
* `moduleOptions` are explicit and stable.
* `perDocument` is enabled only when document-level tracking is useful.
* `maxParallel` is tuned for the real module and downstream systems.
* The next step knows how to route success, failure, or partial results.
* Human review is modeled as `CREATE_TASK`, not hidden inside the module.

<CardGroup cols={2}>
  <Card title="Script Steps" icon="code" href="/guides/activity-plans/script-steps">
    Route execution results with inline JavaScript.
  </Card>

  <Card title="Create Task Steps" icon="list-check" href="/guides/activity-plans/create-task-steps">
    Add human review after automated processing.
  </Card>
</CardGroup>