Workflow Instance

A workflow instance represents a single execution of a workflow definition.

Structure

class WorkflowInstance {
  final String id;                        // Unique identifier
  final String workflowId;                // Reference to definition
  final int workflowVersion;              // Version of the workflow definition
  final WorkflowStatus status;            // Current status
  final Map<String, dynamic> input;       // Original input (immutable)
  final Map<String, dynamic> output;      // Accumulated state
  final List<WorkflowToken> tokens;       // Current execution positions
  final int runNumber;                    // Current run number (for retries)
  final String? parentInstanceId;         // Parent workflow (for subprocesses)
  final String? parentNodeId;             // Parent node that spawned this
  final WorkflowError? error;             // Error info if failed
  final DateTime createdAt;
  final DateTime updatedAt;
  final DateTime? startedAt;
  final DateTime? finishedAt;
  final String? correlationId;            // For tracking related workflows
  final Map<String, dynamic> metadata;    // Additional metadata
}

Status Values

Status	Description
pending	Created but not started
running	Actively executing
paused	Workflow is paused
waitingForUser	Paused, waiting for user input (user task)
waitingForSignal	Paused, waiting for external signal
completed	Finished successfully
failed	Finished with error
cancelled	Manually cancelled

Lifecycle

Creating Instances

final instance = await engine.startWorkflow(
  workflowId: 'approval-workflow',
  input: {
    'entityId': 'REQ-001',
    'submittedBy': 'alice@example.com',
    'priority': 'high',
  },
);

print('Instance ID: ${instance.id}');
print('Status: ${instance.status}');

Input vs Output

Input

• Provided when starting the workflow
• Immutable after workflow starts
• Copied to output at start

Output

• Accumulated workflow state
• Grows as workflow executes
• Each node can add/update values
• Used for gateway routing decisions

// Starting input
input: { 'entityId': '123' }

// After start: copied to output
output: { 'entityId': '123' }

// After validateTask
output: { 'entityId': '123', 'validated': true }

// After approvalTask
output: { 'entityId': '123', 'validated': true, 'decision': 'approved' }

Querying Instances

// Get by ID
final instance = await storage.instances.getById(instanceId);

// Find by status
final waiting = await storage.instances.findByStatus(
  WorkflowStatus.waitingForSignal,
);

// Find by workflow ID
final approvals = await storage.instances.listByDefinition(
  'approval-workflow',
);

Resuming Instances

After a server restart, resume waiting workflows:

await engine.resumeWorkflow(instanceId);

The engine:

1. Loads the instance from storage
2. Finds active tokens
3. Re-executes from current node positions

Cancelling Instances

await engine.cancelWorkflow(instanceId, reason: 'User requested cancellation');

Next Steps

• Tokens - Understanding execution tracking
• Data Flow - How data moves through workflows
• Signals - External triggers