API Reference

Complete reference documentation for the Vyuh Workflow Engine.

Core Classes

Engine & Execution

Class	Description
WorkflowEngine	Main engine class for workflow execution
WorkflowBuilder	Fluent API for building workflow definitions
WorkflowDescriptor	Collection of executors for the engine
NodeResult	Result types returned by node executors
WorkflowEffect	Declarative side effects returned by executors
WorkflowStorage	Abstract storage interface

Data Types

Type	Description
Workflow	Complete workflow definition
WorkflowInstance	Runtime state of a workflow
WorkflowToken	Execution position marker
WorkflowNode	Individual workflow node
WorkflowEdge	Connection between nodes
ExecutionContext	Read-only context for executor access

Executors

Interface	Description
TaskExecutor	Executes automated tasks
UserTaskExecutor	Manages human tasks
ConditionExecutor	Evaluates gateway conditions
NodeExecutor	Executes specific node types

Typed Executors

Interface	Description
TypedTaskExecutor	Type-safe task executor with typed I/O
TypedUserTaskExecutor	Type-safe user task executor
TypedConditionExecutor	Type-safe condition executor
TypedNodeExecutor	Type-safe node executor with typed config

Quick Reference

WorkflowEngine

class WorkflowEngine {
  // Constructor
  WorkflowEngine({
    required WorkflowDeserializationContext context,
    required WorkflowStorage storage,
    WorkflowEngineConfig config = const WorkflowEngineConfig(),
  });

  // Initialization
  Future<void> initialize();
  Future<void> dispose();

  // Workflow lifecycle
  Future<WorkflowInstance> startWorkflow({
    required String workflowCode,
    int? version,
    Map<String, dynamic> input = const {},
    String? correlationId,
    String? parentInstanceId,
    String? parentNodeId,
  });
  Future<void> resumeWorkflow(String instanceId);
  Future<WorkflowInstance> cancelWorkflow(String instanceId, {String? reason});

  // Signals
  Future<void> sendSignal({
    required String workflowInstanceId,
    required String node,
    String? port,
    Map<String, dynamic>? payload,
  });

  // User tasks are accessed via storage.userTaskInstances repository
  // Example: engine.storage.userTaskInstances.query(...)
}

WorkflowBuilder

class WorkflowBuilder {
  // Constructor
  WorkflowBuilder(String code, String name, {String? description});

  // Workflow metadata
  WorkflowBuilder version(int v);
  WorkflowBuilder withMetadata(Map<String, dynamic> metadata);

  // Control nodes
  WorkflowBuilder start(String id, {String? name});
  WorkflowBuilder end(String id, {String? name, String? outcome});

  // Task nodes
  WorkflowBuilder task(String id, {String? name, TaskExecutor? executor, TaskExecuteFunction? execute});
  WorkflowBuilder userTask(String id, {String? name, String? signal, UserTaskExecutor? executor, ...});

  // Gateway nodes
  WorkflowBuilder oneOf(String id, List<Branch> branches, {String? name});
  WorkflowBuilder anyOf(String id, List<String> targets, {String? name});
  WorkflowBuilder allOf(String id, List<String> targets, {String? name});

  // Signal nodes
  WorkflowBuilder signalWait(String id, {required String signal, String? name, String? storeAs});

  // Flow control
  WorkflowBuilder from(String nodeId);
  WorkflowBuilder to(String targetId);
  WorkflowBuilder connect(String from, String to, {String? label});

  // Build
  Workflow build();
}

TaskResult

sealed class TaskResult {}

class TaskSuccess extends TaskResult {
  final Map<String, dynamic> output;
  final String? outputPortId;  // Optional port for routing
  final List<WorkflowEffect> effects;  // Declarative side effects
}

class TaskFailure extends TaskResult {
  final ErrorType errorType;
  final String message;
  final bool isRetryable;  // Default: true
  final Map<String, dynamic>? details;
}

NodeResult

sealed class NodeResult {}

class ContinueResult extends NodeResult {
  final List<String> targetNodeIds;
  final Map<String, dynamic> output;
  final List<WorkflowEffect> effects;  // Side effects before continuing
}

class WaitForSignalResult extends NodeResult {
  final String signalName;
  final Duration? timeout;
}

class WaitForUserTaskResult extends WaitForSignalResult {
  final UserTaskConfiguration config;
  final List<WorkflowEffect> effects;  // Effects before creating task
}

class CompleteWorkflowResult extends NodeResult {
  final Map<String, dynamic> output;
}

class FailWorkflowResult extends NodeResult {
  final ErrorType errorType;
  final String message;
  final bool isRetryable;
  final Map<String, dynamic>? details;
}

class WaitForJoinResult extends NodeResult {
  final List<String> waitingForBranches;
}

class WaitForSubflowResult extends NodeResult {
  final String workflowRef;
  final Map<String, dynamic> input;
}

class FireAndForgetSubflowResult extends NodeResult {
  final String workflowRef;
  final Map<String, dynamic> input;
}

class WaitForTimerResult extends NodeResult {
  final String timerId;
  final DateTime firesAt;
}

WorkflowEffect

Declarative side effects returned by executors:

sealed class WorkflowEffect {}

// Output Effects
class SetOutputEffect extends WorkflowEffect {
  final Map<String, dynamic> output;
  final String? path;  // Optional namespace
}

// Status Effects
class UpdateStatusEffect extends WorkflowEffect { ... }
class CompleteWorkflowEffect extends WorkflowEffect { ... }
class FailWorkflowEffect extends WorkflowEffect { ... }

// Token Effects
class CreateTokensEffect extends WorkflowEffect { ... }
class ConsumeTokenEffect extends WorkflowEffect { ... }
class DropTokenEffect extends WorkflowEffect { ... }
class WaitTokenEffect extends WorkflowEffect { ... }
class ActivateTokenEffect extends WorkflowEffect { ... }

// User Task Effects
class CreateUserTaskEffect extends WorkflowEffect { ... }
class CancelUserTasksEffect extends WorkflowEffect {
  final String? nodeId;  // Cancel all if null
}

// Event Effects
class RecordEventEffect extends WorkflowEffect {
  final WorkflowEvent event;
}
class EmitErrorEffect extends WorkflowEffect { ... }

See Workflow Effects for complete reference.

ExecutionContext

Read-only context providing access to execution state:

class ExecutionContext {
  // Core workflow state
  final Workflow workflow;
  final WorkflowInstance workflowInstance;
  final WorkflowNode currentNode;
  final WorkflowToken currentToken;

  // Data access - three levels
  final Map<String, dynamic> input;         // Previous node output
  Map<String, dynamic> get workflowInput;   // Original workflow input
  Map<String, dynamic> get accumulated;     // All accumulated output

  // Typed accessors with dot notation support
  T? get<T>(String path);           // From previous node output
  T getRequired<T>(String path);    // Throws if missing
  T? getInitial<T>(String path);    // From original workflow input
  T? getAny<T>(String path);        // From accumulated output
  T? getConfig<T>(String key);      // From node configuration

  // Navigation
  List<WorkflowEdge> get outgoingEdges;
  List<WorkflowEdge> get incomingEdges;
  WorkflowNode? getNode(String nodeId);

  // Retry info
  int get attemptNumber;  // 1-based
  bool get isRetry;       // True if attemptNumber > 1
}

Enums

WorkflowStatus

enum WorkflowStatus {
  pending,           // Created but not yet started
  running,           // Currently executing
  paused,            // Paused
  completed,         // Completed successfully
  failed,            // Failed due to error
  cancelled,         // Cancelled by user or system
  waitingForUser,    // Waiting for user task
  waitingForSignal,  // Waiting for external signal
}

NodeType

enum NodeType {
  start,       // Entry point
  end,         // Terminal point
  task,        // Automated task
  userTask,    // Human task
  signalWait,  // Wait for signal
  oneOf,       // Exclusive gateway (XOR)
  allOf,       // Parallel gateway (AND)
  anyOf,       // Race gateway (first wins)
  subflow,     // Invoke another workflow
  timerWait,   // Wait for timer
}

ErrorType

enum ErrorType {
  validation,  // Invalid input/configuration
  timeout,     // Operation timed out
  activity,    // Activity execution failed
  condition,   // Gateway condition evaluation failed
  internal,    // Internal engine error
  cancelled,   // Operation was cancelled
}

UserTaskPriority

enum UserTaskPriority {
  low,
  normal,
  high,
  urgent,
}

WorkflowDescriptor

Register executors using WorkflowDescriptor:

class WorkflowDescriptor {
  const WorkflowDescriptor({
    this.tasks = const [],           // TaskExecutor type descriptors
    this.userTasks = const [],       // UserTaskExecutor type descriptors
    this.conditions = const [],      // ConditionExecutor type descriptors
    this.nodeConfigurations = const [], // NodeConfiguration type descriptors
    this.nodeExecutors = const [],    // NodeExecutor instances
    this.title,
    this.description,
  });
}

Usage

// Create descriptor with executors
final descriptor = WorkflowDescriptor(
  title: 'My Executors',
  tasks: [SendEmailTaskExecutor.typeDescriptor],
  userTasks: [ApprovalTaskExecutor.typeDescriptor],
  conditions: [AmountConditionExecutor.typeDescriptor],
  nodeExecutors: [MyCustomGatewayHandler()],
);

// Create context with all descriptors (order matters - later overrides earlier)
final context = RegistryDeserializationContext(
  descriptors: [
    DefaultWorkflowDescriptor(),  // Built-in executors first
    descriptor,                    // Your executors
  ],
);

// Create engine with context and storage
final engine = WorkflowEngine(
  context: context,
  storage: InMemoryStorage(context: context),
);
await engine.initialize();

DefaultWorkflowDescriptor

Provides all built-in node executors:

Executor	Node Type
StartEventNodeExecutor	start
EndEventNodeExecutor	end
SignalEventNodeExecutor	signalWait
TaskNodeExecutor	task
UserTaskNodeExecutor	userTask
OneOfGatewayNodeExecutor	oneOf
AnyOfGatewayNodeExecutor	anyOf
AllOfGatewayNodeExecutor	allOf

See WorkflowDescriptor API for complete reference.

Detailed Documentation

Core

• WorkflowEngine - Engine API details
• WorkflowBuilder - Builder API details
• WorkflowDescriptor - Descriptor API details
• NodeResult - Result types
• WorkflowEffect - Effect types reference
• WorkflowStorage - Storage interface

Executors

• TaskExecutor - Automated task executors (includes TypedTaskExecutor)
• UserTaskExecutor - Human task executors (includes TypedUserTaskExecutor)
• ConditionExecutor - Gateway condition executors (includes TypedConditionExecutor)
• NodeExecutor - Node type executors (includes TypedNodeExecutor)

Reference

• Glossary - Term definitions