Skip to main content
Planning Mode provides a structured approach to designing automated multi-step workflows for tasks. A plan template defines the sequence of steps — executions, sub-tasks, scripts, and agents — that run when a task is created from a task template. Planning Mode interface showing workflow design view

​
Overview

Planning Mode allows you to:
  • Design multi-step processing workflows as a directed acyclic graph (DAG)
  • Chain together module executions, human review tasks, JavaScript routing scripts, and AI agents
  • Define dependencies between steps, including action-qualified edges (e.g., proceed only if “Approve” was clicked)
  • Visualize the workflow as an interactive flow diagram
  • Monitor execution progress with automatic deadlock detection

​
The Flow Editor

The visual flow editor provides a drag-and-drop interface for designing workflows:
  • Left panel — Node palette with available step types. Drag nodes onto the canvas to add them.
  • Center — Interactive canvas showing nodes and edges. Draw connections between nodes to set dependencies.
  • Right panel — Properties panel for the selected node. Configure step-specific settings here.
Nodes are color-coded by type:
TypeColorDescription
EXECUTIONBlueModule execution
TASKGreenHuman review sub-task
SCRIPTVioletJavaScript routing/processing
AGENTAmberAI agent processing
AI_PLANNERPurpleDynamic AI planning
Double-click a node to zoom and center it. Use the mini-map in the corner for navigation in large workflows.

​
Plan Node Types

Each step in a plan is a planned item with a specific type. The platform supports the following node types:

​
EXECUTION

Runs a module (such as a parser, extractor, or classifier) on the task’s documents.
FieldDescription
moduleRefResource URI of the module to execute (e.g., module://kodexa/pdf-parser)
optionsKey-value options passed to the module at runtime

​
TASK

Creates a sub-task assigned to a human reviewer. The plan pauses at this step until the reviewer completes the task by clicking an action button.
FieldDescription
taskTemplateRefSlug of the sub-task template to use
taskStatusSlugInitial status to assign to the created sub-task
taskDataOverride title, description, priority, forms, actions, and document groups
hideLockHide the lock button on the sub-task
Sub-task templates used in plans are typically marked with subTaskOnly: true so they do not appear in the main task creation dialog.

​
SCRIPT

Runs inline JavaScript to make routing decisions, inspect documents, modify content, or assign knowledge features. Scripts return an action name that determines which downstream dependency edge to follow, enabling conditional branching.
FieldDescription
scriptJavaScript source code to execute
scriptActionsArray of {uuid, name} objects defining the possible action outcomes
The script has access to the task context, document families, knowledge features, and can load and modify KDDB documents. Downstream steps can depend on a specific action outcome. 
// Example: route based on document content
var doc = loadDocument(families[0].id);
var content = doc.getRootNode().getAllContent(" ", true);

var hasFinancialData = content.indexOf("Revenue") !== -1;
doc.close();

return {
  action: hasFinancialData ? "financial" : "general"
};

Script Steps Guide

See the full Script Steps guide for the complete API reference, document modification examples, knowledge feature assignment, and ready-to-use code snippets.

​
AGENT

Spawns an AI agent to process the task’s documents autonomously. The agent uses configured modules as tools and follows a prompt to decide how to process the documents.
FieldDescription
agentRuntimeIdID of the agent runtime to invoke
agentModuleRefsModule references available as tools for the agent
promptInstruction prompt guiding the agent’s behavior

​
AI_PLANNER

Uses an LLM to dynamically insert additional plan steps based on the current task context.
FieldDescription
plannerContextContext information provided to the LLM for planning decisions
maxStepsToInsertMaximum number of steps the planner can add

​
Dependencies

Each plan step can declare dependencies on other steps using the dependsOn array. Dependencies control execution order — a step will not start until all its dependencies have completed.

​
Simple Dependencies

In the flow editor, draw an edge from one node to another to create a dependency. In YAML: 
- uuid: "step-2"
  type: EXECUTION
  dependsOn:
    - "step-1"

​
Action-Qualified Dependencies

When a dependency is on a TASK or SCRIPT step, you can qualify the dependency with a specific action. The downstream step only executes if the upstream step completed with that particular action. This enables conditional branching — for example, routing to different processing steps based on whether a reviewer clicked “Approve” or “Reject”: 
# This step only runs if the reviewer clicked "Approve" on step-2
- uuid: "step-3-approved"
  type: EXECUTION
  dependsOn:
    - "step-2:approve"

# This step only runs if the reviewer clicked "Reject" on step-2
- uuid: "step-3-rejected"
  type: TASK
  dependsOn:
    - "step-2:reject"
The format is stepUUID:actionUUID. In the flow editor, when you connect from a TASK or SCRIPT node that has multiple actions, each action appears as a separate connection handle at the bottom of the node. Draw edges from the specific action handle to create action-qualified dependencies.

​
Example Workflows

​
Simple Extraction Pipeline

A linear workflow that parses a document, extracts data, then creates a review task: 
items:
  - uuid: "parse"
    type: EXECUTION
    name: "Parse Document"
    moduleRef: "module://kodexa/pdf-parser"

  - uuid: "extract"
    type: EXECUTION
    name: "Extract Data"
    moduleRef: "module://acme/invoice-extractor"
    dependsOn: ["parse"]

  - uuid: "review"
    type: TASK
    name: "Human Review"
    taskTemplateRef: "invoice-review"
    taskStatusSlug: "in-review"
    dependsOn: ["extract"]

​
Conditional Branching with Scripts

A workflow that classifies documents and routes them to different processing paths: 
items:
  - uuid: "parse"
    type: EXECUTION
    name: "Parse Document"
    moduleRef: "module://kodexa/pdf-parser"

  - uuid: "classify"
    type: SCRIPT
    name: "Classify Document"
    script: |
      var doc = loadDocument(families[0].id);
      var content = doc.getRootNode().getAllContent(" ", true);
      var isInvoice = content.indexOf("INVOICE") !== -1;
      doc.close();
      return { action: isInvoice ? "invoice" : "other" };
    scriptActions:
      - uuid: "act-invoice"
        name: "invoice"
      - uuid: "act-other"
        name: "other"
    dependsOn: ["parse"]

  - uuid: "extract-invoice"
    type: EXECUTION
    name: "Extract Invoice Data"
    moduleRef: "module://acme/invoice-extractor"
    dependsOn: ["classify:act-invoice"]

  - uuid: "general-review"
    type: TASK
    name: "Manual Classification"
    taskTemplateRef: "manual-review"
    dependsOn: ["classify:act-other"]

​
Approval Workflow

A workflow with a human approval gate that branches based on the reviewer’s decision: 
items:
  - uuid: "extract"
    type: EXECUTION
    name: "Extract Data"
    moduleRef: "module://acme/data-extractor"

  - uuid: "review"
    type: TASK
    name: "Review & Approve"
    taskTemplateRef: "approval-review"
    taskStatusSlug: "pending-approval"
    dependsOn: ["extract"]

  - uuid: "finalize"
    type: EXECUTION
    name: "Finalize Export"
    moduleRef: "module://acme/data-exporter"
    dependsOn: ["review:approve"]

  - uuid: "re-extract"
    type: EXECUTION
    name: "Re-Extract with Corrections"
    moduleRef: "module://acme/data-extractor"
    options:
      useCorrections: true
    dependsOn: ["review:reject"]

​
DAG Flow Visualization

Plans are displayed as an interactive top-to-bottom flow diagram in the plan monitoring panel. Each node represents a planned item, and edges show dependencies (with action labels on qualified edges). Node colors indicate status:
  • Pending — Waiting for dependencies
  • Running — Currently executing
  • Completed — Finished successfully
  • Failed — Encountered an error
  • Deadlocked — Blocked by a failed dependency (see below)

​
Deadlock Detection

The platform automatically detects deadlocked plans. A deadlock occurs when:
  • A plan step fails, and
  • Other pending steps depend on the failed step (directly or transitively)
When a deadlock is detected, the affected pending steps are marked as deadlocked and the plan is flagged for attention. This prevents plans from hanging indefinitely when a step fails.

​
Getting Started

1

Create a Task Template

Navigate to Task Templates and create or edit a template. On the Details tab, check Enable Planned Sub-Tasks.
2

Open the Flow Editor

Switch to the Planned tab. The visual flow editor appears with a node palette on the left.
3

Add Plan Steps

Drag nodes from the palette onto the canvas. Configure each node using the properties panel on the right.
4

Connect Dependencies

Draw edges between nodes to set execution order. For TASK and SCRIPT nodes with multiple actions, connect from specific action handles for conditional branching.
5

Test the Workflow

Save the template, then create a task from it. The plan executes automatically, and you can monitor progress in the plan status panel.
Use SCRIPT nodes for lightweight routing decisions (e.g., checking page counts or metadata values) and AGENT nodes when you need AI-driven processing that can adapt to document content. See the Script Steps guide for detailed examples and the full API reference.