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

• Group-Based Assignment

  • Tasks assigned to users based on assignee groups (roles/departments/teams/etc)
  • Fully customizable group 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 { UserGroupProvider } from "./user-group.provider";

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

User group provider

The workflow engine does not manage users directly. Instead, it relies on a user group provider to fetch users eligible for a task group.

You must implement the IUserGroupProvider interface.

import { IUserGroupProvider } from "nest-workflow-engine";

export class UserGroupProvider implements IUserGroupProvider {
  async findUsersByGroupNames(groupsCsv: 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

WorkflowTaskGroupEntity

WorkflowTaskGateEntity

WorkflowTransitionEntity

WorkflowCaseEntity

WorkflowCaseHistoryEntity

WorkflowUserDelegationEntity

WorkflowParticipatedCaseViewEntity

Testing

Run unit tests using:

npm run test

License

MIT