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.

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: 
{
  "slug": "route-invoice",
  "kind": "SCRIPT",
  "dependsOn": ["extract"],
  "conditionExpr": "inputs.sourceSystem != 'manual'",
  "config": {}
}
FieldDescription
slugUnique identifier for the step inside the Activity Plan
kindThe step type, such as SCRIPT or BRIDGE_CALL
dependsOnSteps or step actions that must complete before this step can run
conditionExprOptional predicate that can skip the step
configKind-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: 
{
  "slug": "extract",
  "kind": "EXECUTION"
},
{
  "slug": "route",
  "kind": "SCRIPT",
  "dependsOn": ["extract"]
}
Run only after a specific action: 
{
  "slug": "analyst-review",
  "kind": "CREATE_TASK",
  "dependsOn": ["route:review"]
}
Join multiple paths: 
{
  "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. 
{
  "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 keyDescription
taskTemplateRefTask Template used to create the Task
taskStatusSlugInitial Task status
waitForCompletionWhether the Activity should pause until the Task reaches a terminal status
taskDataData 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 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
{
  "slug": "route",
  "kind": "SCRIPT",
  "dependsOn": ["extract"],
  "config": {
    "scriptActions": [
      { "name": "review" },
      { "name": "post" },
      { "name": "reject" }
    ],
    "scriptBody": "return { action: inputs.needsReview ? 'review' : 'post' };"
  }
}
See 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
{
  "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 for the full bridge-step guide.

​
EXECUTION

Use EXECUTION to run a module or automated processing component. 
{
  "slug": "extract",
  "kind": "EXECUTION",
  "config": {
    "moduleRef": "kodexa/invoice-extractor",
    "options": {
      "documentFamilyId": "{{inputs.documentFamilyId}}"
    },
    "perDocument": true,
    "maxParallel": 4
  }
}
Config keyDescription
moduleRefModule to run
optionsModule-specific options
perDocumentWhether to run once per document family
maxParallelParallelism limit when running per document
See 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. 
{
  "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 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 for the full agent-step guide.

​
APPROVAL

Use APPROVAL when a workflow must explicitly pause for authorization before continuing. 
{
  "slug": "manager-approval",
  "kind": "APPROVAL",
  "dependsOn": ["analyst-review:approved"],
  "config": {
    "approverRole": "finance-manager",
    "approvalCriteria": {
      "amountGreaterThan": 10000
    }
  }
}
See Approval Steps for approval-gate modeling.

​
Choosing Between SCRIPT and BRIDGE_CALL

NeedPrefer
One configured external API call with clear input and outputBRIDGE_CALL
Multiple calls, custom branching, or document mutationSCRIPT using serviceBridge.call()
Pure routing or validation logic inside KodexaSCRIPT
External system update that should be visible as its own workflow stepBRIDGE_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.