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.
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
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.
| Field | Description |
|---|
moduleRef | Resource URI of the module to execute (e.g., module://kodexa/pdf-parser) |
options | Key-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.
| Field | Description |
|---|
taskTemplateRef | Slug of the sub-task template to use |
taskStatusSlug | Initial status to assign to the created sub-task |
taskData | Override title, description, priority, forms, actions, and document groups |
hideLock | Hide the lock button on the sub-task |
subTaskOnly: true so they do not appear in the main task creation dialog.
SCRIPT
Runs inline JavaScript (Goja) to make routing decisions. Scripts evaluate conditions and return an action name that determines which downstream dependency edge to follow.
| Field | Description |
|---|
script | JavaScript source code to execute |
scriptActions | Array of {uuid, name} objects defining the possible action outcomes |
// Example: route based on document page count
if (task.documents[0].pageCount > 50) {
return "large-document";
} else {
return "standard";
}
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.
| Field | Description |
|---|
agentRuntimeId | ID of the agent runtime to invoke |
agentModuleRefs | Module references available as tools for the agent |
prompt | Instruction prompt guiding the agent’s behavior |
AI_PLANNER
Uses an LLM to dynamically insert additional plan steps based on the current task context.
| Field | Description |
|---|
plannerContext | Context information provided to the LLM for planning decisions |
maxStepsToInsert | Maximum 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
- 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"
stepUUID:actionName. If no action qualifier is provided, the step runs regardless of which action was taken.
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
Create a Task Template
Navigate to Task Templates and create or edit a template. Enable the Planned Activity tab.
Define Plan Steps
Add planned items (EXECUTION, TASK, SCRIPT, AGENT) and configure their settings.
Set Dependencies
Connect steps by adding dependency references. Use action-qualified dependencies for conditional branching.
Test the Workflow
Create a task from the template. 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.
