Workflow Module

A comprehensive workflow management module for Venturial that handles workflow creation, execution, and session management.

Features

• Workflow Management: Create, update, and manage workflows with nodes and edges
• Node Types: Support for multiple node types (Chatbot, AI, Conditional, Twilio)
• Execution Tracking: Track workflow executions with status and data
• Session Management: Persistent sessions for multi-step workflows
• Execution Modes: Support for single-run and persistent session workflows

Installation

npm install @venturialstd/workflow

Entities

Workflow

Main workflow entity containing:

• name: Workflow name
• active: Whether the workflow is active
• executionMode: single or persistent
• status: active, inactive, or draft
• Relationships to nodes, edges, executions, and sessions

WorkflowNode

Represents a node in the workflow:

• nodeId: ReactFlow node identifier
• type: Node type (chatbot, ai, conditional, twilio)
• actionType: Specific trigger or action identifier
• properties: Node-specific properties (JSONB)
• position: Node position on canvas (x, y)

WorkflowEdge

Represents connections between nodes:

• edgeId: ReactFlow edge identifier
• source: Source node ID
• target: Target node ID
• sourceHandle / targetHandle: Handle identifiers

WorkflowExecution

Tracks individual workflow runs:

• status: pending, running, completed, failed, cancelled
• sessionId: Optional session ID for persistent workflows
• currentNodeId: Current node being executed
• inputData / outputData / errorData: Execution data

WorkflowSession

Manages persistent workflow sessions:

• userId: Optional user identifier
• externalId: External identifier (phone, email, etc.)
• currentNodeId: Current node in session
• context: Session context/variables (JSONB)
• history: Array of node execution history

WorkflowModuleCredential

Stores credentials for workflow modules:

• moduleId: Module identifier (e.g., 'twilio', 'ai')
• name: User-defined name for this credential set
• credentials: Encrypted credential values (JSONB)
• organizationId: Optional organization scope
• userId: Optional user scope
• isActive: Whether the credential is active

Services

All services extend TypeOrmCrudService and provide CRUD operations via @dataui/crud.

WorkflowService

• getWorkflowsByOrganization(organizationId)
• getActiveWorkflows(organizationId?)
• activateWorkflow(workflowId)
• deactivateWorkflow(workflowId)
• getWorkflowWithNodesAndEdges(workflowId)

WorkflowNodeService

• getNodesByWorkflowId(workflowId)
• getNodeByNodeId(workflowId, nodeId)
• updateNodeProperties(id, properties)
• updateNodePosition(id, position)

WorkflowEdgeService

• getEdgesByWorkflowId(workflowId)
• getEdgeByEdgeId(workflowId, edgeId)
• getEdgesBySourceNode(workflowId, sourceNodeId)
• getEdgesByTargetNode(workflowId, targetNodeId)

WorkflowExecutionService

• getExecutionsByWorkflowId(workflowId)
• getExecutionsBySessionId(sessionId)
• getActiveExecutions(workflowId?)
• startExecution(executionId)
• completeExecution(executionId, outputData?)
• failExecution(executionId, errorMessage, errorData?)
• updateCurrentNode(executionId, currentNodeId)

WorkflowSessionService

• getSessionsByWorkflowId(workflowId)
• getActiveSessions(workflowId?)
• getSessionByExternalId(workflowId, externalId)
• getSessionByUserId(workflowId, userId)
• updateSessionContext(sessionId, context)
• addToSessionHistory(sessionId, nodeId, data?)
• deactivateSession(sessionId)

WorkflowModuleCredentialService

• getCredentialsByModule(moduleId, organizationId?, userId?)
• getCredentialByName(moduleId, name, organizationId?, userId?)
• getActiveCredentials(moduleId, organizationId?)
• updateCredential(id, credentials)
• activateCredential(id)
• deactivateCredential(id)

Usage

Import the Module

import { WorkflowModule } from '@venturialstd/workflow';

@Module({
  imports: [WorkflowModule],
})
export class AppModule {}

Use Services

import { WorkflowService } from '@venturialstd/workflow';

@Injectable()
export class MyService {
  constructor(private workflowService: WorkflowService) {}

  async createWorkflow(data: CreateWorkflowDto) {
    return this.workflowService.create(data);
  }
}

Constants

Execution Modes

• EXECUTION_MODE.SINGLE: One-time execution
• EXECUTION_MODE.PERSISTENT: Maintains session state

Node Types

• NODE_TYPE.CHATBOT
• NODE_TYPE.AI
• NODE_TYPE.CONDITIONAL
• NODE_TYPE.TWILIO

Node Categories

• NODE_CATEGORY.TRIGGER
• NODE_CATEGORY.ACTION

Workflow Status

• WORKFLOW_STATUS.ACTIVE
• WORKFLOW_STATUS.INACTIVE
• WORKFLOW_STATUS.DRAFT

Execution Status

• EXECUTION_STATUS.PENDING
• EXECUTION_STATUS.RUNNING
• EXECUTION_STATUS.COMPLETED
• EXECUTION_STATUS.FAILED
• EXECUTION_STATUS.CANCELLED

DTOs

All DTOs follow the Create*Dto pattern:

• CreateWorkflowDto
• CreateWorkflowNodeDto
• CreateWorkflowEdgeDto
• CreateWorkflowExecutionDto
• CreateWorkflowSessionDto
• CreateWorkflowModuleCredentialDto
• UpdateWorkflowModuleCredentialDto

Database Schema

The module uses PostgreSQL with JSONB columns for flexible data storage:

• Node properties stored as JSONB
• Edge data stored as JSONB
• Execution input/output/error data as JSONB
• Session context and history as JSONB
• Module credentials stored as JSONB (should be encrypted at application level)

Module Credentials

Each module can define required credential fields. Users can create multiple credential sets per module:

Defining Credential Fields in Modules

Modules can define credentialFields in their module definition:

credentialFields: [
  {
    id: 'apiKey',
    name: 'API Key',
    description: 'API key for the service',
    type: FIELD_TYPE.STRING,
    validation: { required: true },
    sensitive: true, // Will be encrypted/masked
    required: true,
  },
]

Managing Credentials

// Create credentials for a module
const credential = await credentialService.create({
  moduleId: 'twilio',
  name: 'Production Twilio',
  credentials: {
    accountSid: 'AC...',
    authToken: '...',
  },
  organizationId: 'org-123',
});

// Get all credentials for a module
const credentials = await credentialService.getCredentialsByModule(
  'twilio',
  'org-123'
);

License

Part of the Venturial Core NPM package.