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

``bash
npm install @venturialstd/workflow
`

Entities

$3


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

$3

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)

$3

Represents connections between nodes:
- edgeId: ReactFlow edge identifier
- source: Source node ID
- target: Target node ID
- sourceHandle / targetHandle: Handle identifiers

$3

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

$3

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

$3

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.

$3


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

$3

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

$3

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

$3

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

$3

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

$3

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

Usage

$3

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

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

$3

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

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

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

Constants

$3


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

$3

- NODE_TYPE.CHATBOT
- NODE_TYPE.AI
- NODE_TYPE.CONDITIONAL
- NODE_TYPE.TWILIO

$3

- NODE_CATEGORY.TRIGGER
- NODE_CATEGORY.ACTION

$3

- WORKFLOW_STATUS.ACTIVE
- WORKFLOW_STATUS.INACTIVE
- WORKFLOW_STATUS.DRAFT

$3

- 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:

$3

Modules can define credentialFields in their module definition:

`typescript
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,
},
]
`

$3

`typescript
// 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.