Skip to main content

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

{
  "slug": "extract-invoice",
  "kind": "EXECUTION",
  "dependsOn": ["intake"],
  "config": {
    "moduleRef": "kodexa/invoice-extractor",
    "moduleOptions": {
      "schema": "invoice"
    },
    "perDocument": true,
    "maxParallel": 4
  }
}
Config keyDescription
moduleRefModule reference to execute
moduleOptionsModule-specific options passed into the execution
perDocumentRun once per document family instead of once for the Activity
maxParallelLimit parallel launches when perDocument is enabled
bypassSkip 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. 
{
  "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. 
{
  "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.

​
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 typeStarting maxParallel
Lightweight classification5-10
Extraction with model calls2-5
External-system-heavy enrichment1-3
Resource-intensive conversion1-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. 
[
  {
    "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.

Script Steps

Route execution results with inline JavaScript.

Create Task Steps

Add human review after automated processing.