@elqnt/workflow

Complete workflow engine for the Eloquent platform. Build visual workflows with triggers, conditions, actions, human-in-the-loop approvals, AI agents, entity operations, and scheduling.

Installation

npm install @elqnt/workflow

Entry Points

React Hooks

useWorkflows

Hook for workflow definition CRUD operations.

import { useWorkflows } from "@elqnt/workflow/hooks";

const {
  loading,
  error,
  listWorkflows,
  getWorkflow,
  createWorkflow,
  updateWorkflow,
  deleteWorkflow,
} = useWorkflows({
  baseUrl: apiGatewayUrl,
  orgId: selectedOrgId,
});

// List all workflow definitions
const workflows = await listWorkflows();

// Get workflow by ID
const workflow = await getWorkflow("workflow-uuid");

// Create workflow
const newWorkflow = await createWorkflow({
  name: "customer-onboarding",
  title: "Customer Onboarding",
  description: "Automated customer onboarding process",
  type: "entity",
  nodes: {
    "node-1": {
      id: "node-1",
      name: "start",
      title: "Start",
      type: "trigger",
      subType: "triggerStart",
      isStart: true,
      config: { schema: {}, values: {} },
      settings: {},
      input: { schema: {} },
      output: { schema: {} },
    },
  },
  edges: [],
  entryPoints: ["node-1"],
  variables: { schema: {}, scope: {}, defaultValues: {}, computed: {} },
  permissions: { roles: {}, accessLevel: "private", editableBy: [], viewableBy: [] },
  metadata: { createdBy: userId, createdAt: new Date().toISOString(), isActive: true, version: 1 },
});

// Update workflow
const updated = await updateWorkflow("workflow-uuid", {
  description: "Updated description",
});

// Delete workflow
const success = await deleteWorkflow("workflow-uuid");

Methods:

useWorkflowInstances

Hook for workflow instance operations including execution and human-in-the-loop.

import { useWorkflowInstances } from "@elqnt/workflow/hooks";

const {
  loading,
  error,
  listInstances,
  getInstance,
  createInstance,
  updateStatus,
  executeNode,
  resumeNode,
  retryNode,
} = useWorkflowInstances({
  baseUrl: apiGatewayUrl,
  orgId: selectedOrgId,
});

// List instances for a workflow
const instances = await listInstances("definition-uuid", {
  status: "RUNNING",
  userId: currentUserId,
});

// Get instance by ID
const instance = await getInstance("instance-uuid");

// Create new instance and start execution
const newInstance = await createInstance("definition-uuid", {
  variables: { customerId: "cust-123", action: "onboard" },
  autoExecute: true,
});

// Execute a specific node
const output = await executeNode("instance-uuid", "node-id", {
  inputField: "value",
});

// Resume a waiting node (human-in-the-loop approval)
const resumed = await resumeNode("instance-uuid", "approval-node-id", {
  approved: true,
  comment: "Looks good, approved!",
});

// Retry a failed node
const retried = await retryNode("instance-uuid", "failed-node-id");

// Update instance status
const updated = await updateStatus("instance-uuid", "PAUSED");

Methods:

useWorkflowTemplates

Hook for workflow templates - pre-built workflow patterns.

import { useWorkflowTemplates } from "@elqnt/workflow/hooks";

const {
  loading,
  error,
  listTemplates,
  getTemplate,
  instantiateTemplate,
} = useWorkflowTemplates({
  baseUrl: apiGatewayUrl,
  orgId: selectedOrgId,
});

// List templates by category
const templates = await listTemplates("customer-service");

// Get template details
const template = await getTemplate("template-uuid");

// Instantiate template as new workflow
const workflow = await instantiateTemplate("template-uuid", {
  title: "My Customer Onboarding",
  variables: {
    welcomeMessage: "Welcome to our platform!",
    assigneeId: "user-123",
  },
});

Methods:

Models

WorkflowDefinition

import type { WorkflowDefinition, WorkflowMetadata } from "@elqnt/workflow/models";

interface WorkflowDefinition {
  id?: string;
  name: string;           // Normalized: lowercase, dashes (auto-generated from title)
  title: string;
  description: string;
  type: WorkflowType;     // "entity" | "document" | "chat" | "agent" | "productivity"

  // Graph Structure
  nodes: Record<string, WorkflowNode>;
  edges: WorkflowEdge[];
  entryPoints: string[];  // Start node IDs

  // Data Management
  variables: WorkflowVariables;
  constants?: Record<string, any>;

  // Runtime Configuration
  persistence?: PersistenceType;

  // Validation and Constraints
  rules?: WorkflowRule[];
  permissions: WorkflowPermissions;

  // Metadata
  metadata: WorkflowMetadata;
}

interface WorkflowVariables {
  schema: JSONSchema;
  scope: Record<string, string>;        // Variable visibility
  defaultValues: Record<string, any>;
  computed: Record<string, string>;     // Expressions
}

WorkflowNode

import type { WorkflowNode, NodeConfig, NodeSettings } from "@elqnt/workflow/models";

interface WorkflowNode {
  id: string;
  title: string;
  name: string;             // Normalized function name: "find_products"
  label?: string;
  description?: string;
  type: NodeType;
  subType?: NodeSubType;
  config: NodeConfig;
  settings: NodeSettings;
  input: NodeInput;
  output: NodeOutput;
  isStart: boolean;
}

interface NodeConfig {
  schema: JSONSchema;                   // Config schema for validation
  values: Record<string, any>;          // Actual config values
  promoteToVariables?: string[];        // Output fields to promote to workflow variables
}

interface NodeSettings {
  execution?: ExecutionConfig;
  retry?: RetryConfig;
}

WorkflowEdge

import type { WorkflowEdge, ExpressionConfig } from "@elqnt/workflow/models";

interface WorkflowEdge {
  id: string;
  fromNodeId: string;
  toNodeId: string;
  type: EdgeType;
  label?: string;
  expression?: ExpressionConfig;        // Conditional logic
  priority: number;
  retry?: RetryConfig;
  timeout?: TimeoutConfig;
  properties?: Record<string, string>;
}

interface ExpressionConfig {
  type: ExpressionType;                 // "filter" | "javascript" | "template" | "dsl" | "rules"
  expression: string;
  variables?: string[];
  timeout?: number;
  cache?: CacheConfig;
}

WorkflowInstance

import type { WorkflowInstance, InstanceState, ExecutionContext } from "@elqnt/workflow/models";

interface WorkflowInstance {
  id?: string;
  orgId?: string;
  definitionId: string;
  definitionName?: string;
  title?: string;
  description?: string;
  type?: WorkflowType;
  definitionVersion: number;
  status: InstanceStatus;
  state: InstanceState;
  context: ExecutionContext;
  persistence?: PersistenceType;
  metadata: WorkflowMetadata;
}

interface InstanceState {
  variables: Record<string, any>;
  constants: Record<string, any>;
  nodeStates: Record<string, NodeState>;
  edgeStates: Record<string, EdgeState>;
}

interface NodeState {
  status: NodeStatus;
  input?: Record<string, any>;
  output?: Record<string, any>;
  error?: string;
  startTime?: string;
  endTime?: string;
  retryCount: number;
  nextRetryAt?: string;
}

Node Types

import {
  // Primary node types
  NodeTypeTrigger,           // "trigger"
  NodeTypeHumanAction,       // "humanAction"
  NodeTypeAgent,             // "agent"
  NodeTypeAction,            // "action"
  NodeTypeLogic,             // "logic"
  NodeTypeLoop,              // "loop"
  NodeTypeParallel,          // "parallel"
  NodeTypeDelay,             // "delay"
  NodeTypeData,              // "data"
  NodeTypeIntegration,       // "integration"
  NodeTypeTimer,             // "timer"
  NodeTypeSubflow,           // "subflow"
  NodeTypeCustom,            // "custom"
} from "@elqnt/workflow/models";

Node Subtypes

import {
  // Trigger subtypes
  NodeSubTypeTriggerStart,               // "triggerStart"
  NodeSubTypeTriggerEntityRecordCreated, // "triggerEntityRecordCreated"
  NodeSubTypeTriggerEntityRecordUpdated, // "triggerEntityRecordUpdated"
  NodeSubTypeTriggerEntityRecordDeleted, // "triggerEntityRecordDeleted"
  NodeSubTypeTriggerWebhookReceived,     // "triggerWebhookReceived"
  NodeSubTypeTriggerSLAWarning,          // "triggerSLAWarning"
  NodeSubTypeTriggerSLABreach,           // "triggerSLABreach"

  // Human action subtypes
  NodeSubTypeHumanActionReview,          // "humanActionReview"
  NodeSubTypeHumanActionApproval,        // "humanActionApproval"
  NodeSubTypeHumanActionDataEntry,       // "humanActionDataEntry"
  NodeSubTypeHumanActionAssignment,      // "humanActionAssignment"

  // Agent subtypes
  NodeSubTypeAgentChat,                  // "agentChat"
  NodeSubTypeAgentIntentDetector,        // "agentIntentDetector"
  NodeSubTypeAgentKnowledgeGraph,        // "agentKnowledgeGraph"
  NodeSubTypeAgentStructuredOutput,      // "agentStructuredOutput"
  NodeSubTypeAgentTransferToHuman,       // "agentTransferToHuman"

  // Action subtypes
  NodeSubTypeActionApiCall,              // "actionApiCall"
  NodeSubTypeActionSendEmail,            // "actionSendEmail"
  NodeSubTypeActionSendSMS,              // "actionSendSMS"
  NodeSubTypeActionGenerateDocument,     // "actionGenerateDocument"
  NodeSubTypeActionCreateEntityRecord,   // "actionCreateEntityRecord"
  NodeSubTypeActionUpdateEntityRecord,   // "actionUpdateEntityRecord"
  NodeSubTypeActionDeleteEntityRecord,   // "actionDeleteEntityRecord"
  NodeSubTypeActionQueryEntityRecords,   // "actionQueryEntityRecords"
  NodeSubTypeActionSetVariables,         // "actionSetVariables"
  NodeSubTypeActionNatsRequest,          // "actionNatsRequest"

  // Logic subtypes
  NodeSubTypeLogicIf,                    // "logicIf"
  NodeSubTypeLogicSwitch,                // "logicSwitch"
  NodeSubTypeLogicFor,                   // "logicFor"
  NodeSubTypeLogicParallel,              // "logicParallel"

  // Timer subtypes
  NodeSubTypeTimerDelay,                 // "timerDelay"
  NodeSubTypeTimerSchedule,              // "timerSchedule"
  NodeSubTypeTimerBusinessHours,         // "timerBusinessHours"

  // Data subtypes
  NodeSubTypeDataFilter,                 // "dataFilter"
  NodeSubTypeDataMap,                    // "dataMap"
  NodeSubTypeDataCalculate,              // "dataCalculate"
  NodeSubTypeDataValidate,               // "dataValidate"
} from "@elqnt/workflow/models";

Edge Types

import {
  EdgeTypeNormal,        // "normal" - Standard flow
  EdgeTypeLoopBack,      // "loopBack" - Loop to previous node
  EdgeTypeError,         // "error" - Error handling path
  EdgeTypeDefault,       // "default" - Fallback path
  EdgeTypeParallel,      // "parallel" - Parallel branch
  EdgeTypeConditional,   // "conditional" - Conditional branch
  EdgeTypeMerge,         // "merge" - Merge parallel branches
  EdgeTypeCompensation,  // "compensation" - Rollback path
  EdgeTypeTimeout,       // "timeout" - Timeout handling
} from "@elqnt/workflow/models";

Status Types

import {
  // Instance status
  InstanceStatusNew,         // "NEW"
  InstanceStatusRunning,     // "RUNNING"
  InstanceStatusWaiting,     // "WAITING" (human-in-the-loop)
  InstanceStatusPaused,      // "PAUSED"
  InstanceStatusCompleted,   // "COMPLETED"
  InstanceStatusFailed,      // "FAILED"

  // Node status
  NodeStatusPending,         // "PENDING"
  NodeStatusRunning,         // "RUNNING"
  NodeStatusCompleted,       // "COMPLETED"
  NodeStatusFailed,          // "FAILED"
  NodeStatusWaiting,         // "WAITING"
  NodeStatusSkipped,         // "SKIPPED"

  // Edge status
  EdgeStatusPending,         // "PENDING"
  EdgeStatusCompleted,       // "COMPLETED"
  EdgeStatusSkipped,         // "SKIPPED"
} from "@elqnt/workflow/models";

Workflow Types

import {
  WorkflowTypeEntity,        // "entity" - Entity lifecycle workflows
  WorkflowTypeDocument,      // "document" - Document processing
  WorkflowTypeChat,          // "chat" - Chat/conversation flows
  WorkflowTypeAgent,         // "agent" - AI agent workflows
  WorkflowTypeProductivity,  // "productivity" - Automation/scheduling
} from "@elqnt/workflow/models";

Redux Store

Redux Toolkit slices for workflow state management.

Workflow Definition Slice

import { workflowDefinitionReducer } from "@elqnt/workflow";
import type { WorkflowDefinitionState } from "@elqnt/workflow";

// State shape
interface WorkflowDefinitionState {
  definitions: Record<string, WorkflowDefinition>;
  selectedDefinition?: WorkflowDefinition;
  isLoading: boolean;
  error?: string;
  loadingStates: Record<string, boolean>;
}

Actions:

Workflow Instance Slice

import { workflowInstanceReducer } from "@elqnt/workflow";
import type { WorkflowInstanceState } from "@elqnt/workflow";

// State shape
interface WorkflowInstanceState {
  instances: Record<string, WorkflowInstance>;
  selectedInstance?: WorkflowInstance;
  isLoading: boolean;
  error?: string;
  loadingStates: Record<string, boolean>;
}

NATS Subjects

For backend service communication:

import {
  // Definition CRUD
  WorkflowDefinitionCreate,     // "workflow.definition.create"
  WorkflowDefinitionCreated,    // "workflow.definition.created"
  WorkflowDefinitionUpdate,     // "workflow.definition.update"
  WorkflowDefinitionUpdated,    // "workflow.definition.updated"
  WorkflowDefinitionGet,        // "workflow.definition.get"
  WorkflowDefinitionGetByTitle, // "workflow.definition.get.by.title"
  WorkflowDefinitionList,       // "workflow.definition.list"
  WorkflowDefinitionDelete,     // "workflow.definition.delete"
  WorkflowDefinitionDeleted,    // "workflow.definition.deleted"

  // Instance operations
  WorkflowInstanceCreate,           // "workflow.instance.create"
  WorkflowInstanceGet,              // "workflow.instance.get"
  WorkflowInstanceGetByStateVariable, // "workflow.instance.get.by.state.variable"
  WorkflowInstanceList,             // "workflow.instance.list"
  WorkflowInstanceUpdate,           // "workflow.instance.update"
  WorkflowInstanceUpdated,          // "workflow.instance.updated"
  WorkflowInstanceExecuteNode,      // "workflow.instance.execute.node"
  WorkflowInstanceResumeNode,       // "workflow.instance.resume.node"
  WorkflowInstanceUpdateNodeMetadata, // "workflow.instance.update.node.metadata"

  // Templates
  WorkflowTemplateList,         // "workflow.template.list"
  WorkflowTemplateGet,          // "workflow.template.get"
  WorkflowTemplateInstantiate,  // "workflow.template.instantiate"

  // Scheduling
  WorkflowScheduleCreate,       // "workflow.schedule.create"
  WorkflowScheduleUpdate,       // "workflow.schedule.update"
  WorkflowScheduleDelete,       // "workflow.schedule.delete"
  WorkflowScheduleList,         // "workflow.schedule.list"
  WorkflowSchedulePause,        // "workflow.schedule.pause"
  WorkflowScheduleResume,       // "workflow.schedule.resume"

  // Triggers
  WorkflowTriggerRegister,      // "workflow.trigger.register"
  WorkflowTriggerPause,         // "workflow.trigger.pause"
  WorkflowTriggerResume,        // "workflow.trigger.resume"
  WorkflowTriggerStatus,        // "workflow.trigger.status"
  WorkflowTriggerFired,         // "workflow.trigger.fired"

  // Execution events
  WorkflowExecutionStarted,     // "workflow.execution.started"
  WorkflowExecutionCompleted,   // "workflow.execution.completed"
  WorkflowExecutionFailed,      // "workflow.execution.failed"
} from "@elqnt/workflow/models";

API Gateway Routes

Type Generation

Workflow types are generated from Go using tygo:

cd backend && tygo generate

See Also

• Workflow Engine - Architecture guide
• @elqnt/entity - Entity triggers in workflows
• @elqnt/agents - AI agent nodes in workflows