Workflow Event Plugin

Topic Namespace

workflow.started                // ProcessExecution started
workflow.nodeExecutionStarted   // A node began executing
workflow.nodeExecutionCompleted // A node finished (success)
workflow.nodeExecutionFailed    // A node threw an error
workflow.suspended              // Execution paused for HIL
workflow.resumed                // Execution continued after HIL
workflow.completed              // ProcessExecution finished successfully
workflow.failed                 // ProcessExecution terminated with error
workflow.cancelled              // Execution was cancelled

Message Formats

// workflow.started
interface WorkflowStartedEvent {
  processId: string;
  executionId: string;
  workflowName: string;
  startedBy: string;
  startedAt: string;       // ISO timestamp
  inputData?: unknown;
}

// workflow.nodeExecutionCompleted
interface NodeExecutionCompletedEvent {
  processId: string;
  executionId: string;
  nodeId: string;
  nodeName: string;
  nodeType: string;
  startedAt: string;
  completedAt: string;
  durationMs: number;
  outputData?: unknown;
}

// workflow.suspended (HIL — Human in the Loop)
interface WorkflowSuspendedEvent {
  processId: string;
  executionId: string;
  suspendedAt: string;
  reason: string;          // e.g., 'approval-required'
  hilTaskId: string;       // ID of the HIL task awaiting response
  assignedTo?: string[];   // actor IDs who can resume
}

Subscribing to Workflow Events

// Subscribe to all workflow events for a specific process execution
stream.subscribe('bas', 'workflow.*', (envelope) => {
  const event = envelope.body;
  const topic = envelope.meta.topic;

  switch (topic) {
    case 'workflow.started':
      observerPanel.initExecution(event.executionId, event.workflowName);
      break;
    case 'workflow.nodeExecutionStarted':
      observerPanel.highlightNode(event.nodeId, 'executing');
      break;
    case 'workflow.nodeExecutionCompleted':
      observerPanel.updateNode(event.nodeId, 'completed', event.durationMs);
      break;
    case 'workflow.nodeExecutionFailed':
      observerPanel.updateNode(event.nodeId, 'failed', { error: event.error });
      break;
    case 'workflow.suspended':
      observerPanel.showHilPrompt(event.hilTaskId, event.reason);
      break;
    case 'workflow.completed':
      observerPanel.markComplete(event.executionId);
      break;
  }
});

Flow Studio Observer Panel

The Observer Panel in Flow Studio subscribes to workflow.* and overlays live execution state onto the workflow diagram:

• Each node shows a color indicator: blue (executing), green (completed), red (failed), yellow (suspended)
• Duration is displayed for completed nodes
• Error details overlay on failed nodes (click to expand)
• HIL suspension triggers the approval sidebar

Filtering by Execution ID

// Only handle events for the currently viewed execution
const currentExecutionId = 'exec-abc123';

stream.subscribe('bas', 'workflow.*', (envelope) => {
  if (envelope.body.executionId !== currentExecutionId) return;
  // handle event...
});