Skip to content

FlowDrop StateGraph

Stateful graph execution orchestrator with checkpointing, reducers, loops, and human-in-the-loop support.

Overview

The flowdrop_stategraph module provides an alternative orchestrator that maintains execution state across steps — enabling features like loop iteration, conditional edge evaluation, approval gates, and checkpoint-based resumption.

Unlike the standard runtime orchestrators that process nodes in a single pass, the StateGraph orchestrator maintains a mutable state object that nodes can read and write to. This makes it suitable for complex workflows involving iterative processing, human-in-the-loop approvals, and long-running multi-step operations.

The module includes state management with reducer support, pluggable checkpointers (in-memory for development, entity-based for production), and specialized node processors for loops and approval gates.

Dependencies

Configuration

Admin Pages

Path Description
/admin/flowdrop/stategraph/test Test StateGraph execution form
/admin/flowdrop/stategraph/checkpoints List state checkpoints
/admin/flowdrop/stategraph/checkpoint/{id} View checkpoint details

Permissions

Permission Description
administer flowdrop_stategraph Full access to StateGraph configuration. Restricted.
view state_checkpoint View state checkpoints
create state_checkpoint Create state checkpoints
edit state_checkpoint Edit state checkpoints
delete state_checkpoint Delete state checkpoints
manage approval gates Approve or reject approval gate requests

Tips and Tricks

When to Use StateGraph vs Standard Orchestrators

Use Case Recommended Orchestrator
Simple linear workflows Synchronous (flowdrop_runtime:synchronous)
Background processing Asynchronous (flowdrop_runtime:asynchronous)
Workflows with loops/iteration StateGraph
Workflows with approval gates StateGraph
Stateful multi-step processing StateGraph
Chat-based interactive workflows StateGraph (used by playground)

Checkpointer Selection

  • Memory checkpointer — Fast, no persistence. Use for development and testing.
  • Entity checkpointer — Persists checkpoints as Drupal content entities. Use in production for resumable workflows.

Loop Nodes

The module provides specialized nodes for iteration:

  • ForEachNode — Iterates over an array, executing downstream nodes for each item
  • IteratorStartNode — Initializes an iterator
  • IteratorNextNode — Advances to the next item
  • IteratorCollectNode — Collects all iterator results into an array
  • LoopControlNode — Controls loop behavior (break, continue)

Approval Gates (deprecated)

The ApprovalGateNode pauses workflow execution at designated points, waiting for human approval before continuing. It is deprecated in 1.6.0 and removed in 2.0.0 — use the confirmation node (simple approve/reject) or form_input node (approval with notes) from flowdrop_interrupt instead. During the deprecation window the node pauses through the interrupt system, so pending approvals are resolvable via the interrupt API and playground UI. See the change record.

Developer API

Services

Service ID Class Description
flowdrop_stategraph.orchestrator StateGraphOrchestrator Main orchestrator service
flowdrop_stategraph.state_manager StateManager State lifecycle, reducer application, serialization
flowdrop_stategraph.checkpointer_factory CheckpointerFactory Creates the appropriate checkpointer
flowdrop_stategraph.memory_checkpointer MemoryCheckpointer In-memory checkpointing
flowdrop_stategraph.entity_checkpointer EntityCheckpointer Entity-based persistent checkpointing
flowdrop_stategraph.conditional_edge_evaluator ConditionalEdgeEvaluator Evaluates state conditions for routing
flowdrop_stategraph.array_iterator_helper ArrayIteratorHelper Array iteration with state management
flowdrop_stategraph.approval_gate_handler ApprovalGateHandler Deprecated in 1.6.0 — use the flowdrop_interrupt system

Entities

FlowDropStateCheckpoint (Content Entity)

Stores serialized state checkpoints for resumable execution.

Node Processors

Plugin Description
ApprovalGateNode Pauses execution for human approval (deprecated in 1.6.0)
LoopControlNode Controls loop behavior (break, continue)
ForEachNode Iterates over arrays
IteratorStartNode Initializes an iterator
IteratorNextNode Advances to next item
IteratorCollectNode Collects iterator results
StateStorageNode Reads/writes to the state store

StateAwareProcessorInterface

Node processors that need access to the execution state can implement StateAwareProcessorInterface to receive the current state and participate in state management.

References