nest-workflow-engine

A flexible workflow engine for NestJS that enables building configurable approval flows, task routing systems, and case management pipelines.

This package provides a structured way to model processes, tasks, transitions, and workflow cases while integrating seamlessly with NestJS and TypeORM.

Typical use cases include:

• Approval systems
• Procurement workflows
• Document review pipelines
• Ticket escalation systems
• Business process management (BPM)

Features

• Process Management

  • Define workflow processes
  • Configure tasks and transitions

• Task Routing

  • Tasks connected with gates
  • Action-based transitions

• Case Management

  • Start workflow cases
  • Move cases through workflow steps
  • Maintain complete workflow history

• Role-Based Assignment

  • Tasks assigned to users based on roles
  • Fully customizable user provider

• Workflow Canvas

  • Save workflow diagrams and structures

• Highly Extensible

  • Plug in your own user system
  • Works with existing NestJS applications

Installation

npm install nest-workflow-engine

npm install @nestjs/common @nestjs/core @nestjs/typeorm typeorm reflect-metadata

Quick Start

Import the module into your NestJS application.

import { Module } from '@nestjs/common';
import { WorkflowEngineModule } from 'nest-workflow-engine';
import { RoleProvider } from './role.provider';

@Module({
  imports: [
   WorkflowEngineModule.forRootAsync({
      imports: [RoleModule],
      inject: [RoleService],
      useFactory: (roleService: RoleService) => ({
        roleProvider: roleService,
      }),
    }),
  ],
})
export class AppModule {}

Role Provider

The workflow engine does not manage users directly. Instead, it relies on a Role Provider to fetch users assigned to roles.

You must implement the IRoleProvider interface.

import { IRoleProvider } from 'nest-workflow-engine';

export class RoleProvider implements IRoleProvider {
  async findRoleUsersByRoleNames(roles: string) {
    return [
      {
        id: 1,
        name: 'John Doe',
        email: '[email protected]',
      },
    ];
  }
}

Then pass it when registering the module:

Database Setup

The workflow engine provides a list of entities you can register with TypeORM.

import { WORKFLOW_ENTITIES } from 'nest-workflow-engine';

TypeOrmModule.forRoot({
  type: 'postgres',
  host: 'localhost',
  port: 5432,
  username: 'postgres',
  password: 'password',
  database: 'workflow',
  entities: [...WORKFLOW_ENTITIES],
  synchronize: true,
});

Exported Services

The module exports three main services:

WorkflowProcessService

WorkflowTaskService

WorkflowCaseService

Entities

The workflow engine includes the following entities:

WorkflowProcessEntity

WorkflowTaskEntity

WorkflowTaskRoleEntity

WorkflowTaskGateEntity

WorkflowTransitionEntity

WorkflowCaseEntity

WorkflowCaseHistoryEntity

WorkflowUserDelegationEntity

WorkflowParticipatedCaseViewEntity

Testing

Run unit tests using:

npm run test

License

MIT