rez_core 4.0.167 → 4.0.171

package/src/module/workflow-schedule/README.md

@@ -0,0 +1,422 @@
+# Workflow Schedule Module
+
+A comprehensive NestJS module for scheduling and executing workflows using Bull queues and Redis.
+
+## Features
+
+- ✅ Schedule workflows with cron expressions
+- ✅ Timezone support (IANA timezone format)
+- ✅ Pause/resume schedules
+- ✅ Manual trigger execution
+- ✅ Comprehensive execution logging
+- ✅ Retry with exponential backoff
+- ✅ Batch processing (100 records per batch)
+- ✅ Multiple action types:
+  - Send Email
+  - Update Records
+  - Create Tasks
+  - Send Notifications
+
+## Installation
+
+### 1. Install Required Dependencies
+
+```bash
+npm install @nestjs/bull bull redis cron-parser
+npm install --save-dev @types/bull
+```
+
+Note: `cron-parser` includes its own TypeScript definitions, so no separate `@types` package is needed.
+
+### 2. Configure Redis
+
+Add Redis configuration to your `.env` file:
+
+```env
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+```
+
+### 3. Run Migrations
+
+The module includes three migrations:
+
+1. **AddWorkflowTypeColumn** - Adds `workflow_type` to `cr_wf_master` table
+2. **CreateScheduledWorkflowsTable** - Creates `cr_wf_scheduled_workflow` table
+3. **CreateWorkflowExecutionLogsTable** - Creates `cr_wf_execution_log` table
+
+To run migrations:
+
+```bash
+# Using TypeORM CLI
+npx typeorm migration:run -d src/config/database.config.ts
+
+# Or using npm script (if configured)
+npm run migration:run
+```
+
+### 4. Start Redis Server
+
+Make sure Redis is running:
+
+```bash
+# If using Docker
+docker run -d -p 6379:6379 redis
+
+# If installed locally
+redis-server
+```
+
+## Module Structure
+
+```
+src/module/workflow-schedule/
+├── constants/
+│   └── schedule.constants.ts          # Constants and enums
+├── interfaces/
+│   └── schedule-job-data.interface.ts # TypeScript interfaces
+├── entities/
+│   ├── scheduled-workflow.entity.ts   # ScheduledWorkflow entity
+│   └── workflow-execution-log.entity.ts # WorkflowExecutionLog entity
+├── dto/
+│   ├── create-schedule.dto.ts         # Create schedule DTO
+│   ├── update-schedule.dto.ts         # Update schedule DTO
+│   └── get-execution-logs.dto.ts      # Query execution logs DTO
+├── processors/
+│   └── schedule.processor.ts          # Bull job processor
+├── service/
+│   └── workflow-schedule.service.ts   # Business logic (9 methods)
+├── controller/
+│   └── workflow-schedule.controller.ts # REST API (9 endpoints)
+└── workflow-schedule.module.ts        # Module definition
+```
+
+## API Endpoints
+
+### 1. Create Schedule
+```http
+POST /workflow-schedule/create
+Authorization: Bearer <token>
+
+{
+  "workflow_id": 1,
+  "workflow_name": "Daily Lead Assignment",
+  "name": "Assign leads every morning",
+  "description": "Automatically assign new leads to sales team",
+  "cron_expression": "0 9 * * 1-5",
+  "timezone": "Asia/Kolkata",
+  "actions": [
+    {
+      "actionType": "UPDATE_RECORDS",
+      "targetEntityType": "LEAD",
+      "actionConfig": {
+        "updateFields": {
+          "status": "ASSIGNED"
+        }
+      }
+    }
+  ]
+}
+```
+
+### 2. Update Schedule
+```http
+PUT /workflow-schedule/update
+
+{
+  "id": 1,
+  "cron_expression": "0 10 * * 1-5"
+}
+```
+
+### 3. Get Schedule by ID
+```http
+GET /workflow-schedule/:id
+```
+
+### 4. Get All Schedules
+```http
+GET /workflow-schedule/list?page=1&size=10&schedule_status=ACTIVE
+```
+
+### 5. Pause Schedule
+```http
+POST /workflow-schedule/:id/pause
+```
+
+### 6. Resume Schedule
+```http
+POST /workflow-schedule/:id/resume
+```
+
+### 7. Delete Schedule
+```http
+DELETE /workflow-schedule/:id
+```
+
+### 8. Manual Trigger
+```http
+POST /workflow-schedule/:id/trigger
+
+{
+  "metadata": {
+    "triggered_reason": "Testing"
+  }
+}
+```
+
+### 9. Get Execution Logs
+```http
+POST /workflow-schedule/execution-logs
+
+{
+  "schedule_id": 1,
+  "execution_status": "COMPLETED",
+  "page": 1,
+  "size": 10
+}
+```
+
+### 10. Get Execution Statistics
+```http
+GET /workflow-schedule/:id/stats
+```
+
+## Service Methods
+
+The `WorkflowScheduleService` provides 9 core methods:
+
+1. **createSchedule** - Create a new scheduled workflow
+2. **updateSchedule** - Update an existing schedule
+3. **getScheduleById** - Get schedule by ID
+4. **getAllSchedules** - Get all schedules with pagination
+5. **pauseSchedule** - Pause a running schedule
+6. **resumeSchedule** - Resume a paused schedule
+7. **deleteSchedule** - Delete (soft delete) a schedule
+8. **triggerManualExecution** - Manually trigger execution
+9. **getExecutionLogs** - Query execution logs with filters
+
+## Cron Expression Examples
+
+```javascript
+// Every day at 9 AM
+"0 9 * * *"
+
+// Every weekday at 9 AM
+"0 9 * * 1-5"
+
+// Every hour
+"0 * * * *"
+
+// Every 30 minutes
+"*/30 * * * *"
+
+// First day of every month at midnight
+"0 0 1 * *"
+
+// Every Monday at 8 AM
+"0 8 * * 1"
+```
+
+## Action Types
+
+### 1. Send Email
+```json
+{
+  "actionType": "SEND_EMAIL",
+  "targetEntityType": "USR",
+  "actionConfig": {
+    "subject": "Weekly Report",
+    "template": "weekly-report-template",
+    "from": "noreply@example.com"
+  },
+  "filterCriteria": {
+    "status": "ACTIVE"
+  }
+}
+```
+
+### 2. Update Records
+```json
+{
+  "actionType": "UPDATE_RECORDS",
+  "targetEntityType": "LEAD",
+  "actionConfig": {
+    "updateFields": {
+      "status": "FOLLOW_UP",
+      "last_contacted": "NOW()"
+    }
+  },
+  "filterCriteria": {
+    "status": "NEW"
+  }
+}
+```
+
+### 3. Create Task
+```json
+{
+  "actionType": "CREATE_TASK",
+  "targetEntityType": "LEAD",
+  "actionConfig": {
+    "taskName": "Follow up with lead",
+    "taskDescription": "Scheduled follow-up task"
+  },
+  "filterCriteria": {
+    "status": "QUALIFIED"
+  }
+}
+```
+
+### 4. Send Notification
+```json
+{
+  "actionType": "SEND_NOTIFICATION",
+  "targetEntityType": "USR",
+  "actionConfig": {
+    "eventType": "WORKFLOW_SCHEDULED",
+    "message": "Your weekly report is ready"
+  }
+}
+```
+
+## Retry Configuration
+
+```json
+{
+  "retry_config": {
+    "maxRetries": 3,
+    "retryDelay": 5000,
+    "backoffMultiplier": 2
+  }
+}
+```
+
+This will retry failed jobs:
+- 1st retry: after 5 seconds
+- 2nd retry: after 10 seconds (5 * 2)
+- 3rd retry: after 20 seconds (10 * 2)
+
+## Monitoring
+
+### Check Queue Status
+
+Bull provides a web UI for monitoring queues:
+
+```bash
+npm install bull-board
+```
+
+### View Execution Logs
+
+Use the execution logs API to monitor:
+- Success rate
+- Failed executions
+- Average execution time
+- Records processed
+
+```http
+GET /workflow-schedule/:id/stats
+```
+
+## Database Schema
+
+### cr_wf_scheduled_workflow
+- Stores schedule configuration
+- Includes cron expression, timezone, retry config
+- Tracks execution count and next execution time
+
+### cr_wf_execution_log
+- Logs every execution
+- Tracks success/failure status
+- Records processing metrics
+- Stores error details
+
+## Environment Variables
+
+```env
+# Redis Configuration
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
+# Database Configuration
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=root
+DB_PASS=password
+DB_NAME=core
+```
+
+## Testing
+
+### Manual Testing
+
+1. Create a schedule with a simple cron (e.g., every minute: `* * * * *`)
+2. Check execution logs after 1-2 minutes
+3. Test pause/resume functionality
+4. Test manual trigger
+5. Verify retry mechanism by creating failing actions
+
+### Unit Testing
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { WorkflowScheduleService } from './workflow-schedule.service';
+
+describe('WorkflowScheduleService', () => {
+  let service: WorkflowScheduleService;
+
+  beforeEach(async () => {
+    const module = await Test.createTestingModule({
+      providers: [WorkflowScheduleService],
+    }).compile();
+
+    service = module.get<WorkflowScheduleService>(WorkflowScheduleService);
+  });
+
+  it('should create a schedule', async () => {
+    // Test implementation
+  });
+});
+```
+
+## Troubleshooting
+
+### Redis Connection Issues
+- Verify Redis is running: `redis-cli ping`
+- Check Redis connection settings in `.env`
+
+### Jobs Not Processing
+- Check Bull queue status
+- Verify cron expression is valid
+- Check schedule is enabled and active
+
+### Migration Issues
+- Ensure database user has CREATE/ALTER permissions
+- Run migrations in order (1, 2, 3)
+
+## Performance Considerations
+
+- **Batch Size**: Default is 100 records. Adjust based on your use case.
+- **Retry Strategy**: Balance between retry attempts and system load.
+- **Redis Memory**: Monitor Redis memory usage for large queues.
+- **Database Indexes**: Migrations include optimized indexes.
+
+## Security
+
+- All endpoints are protected with `JwtAuthGuard`
+- Organization-level data isolation
+- Soft delete for schedules (audit trail)
+- Execution logs retention (configurable)
+
+## Support
+
+For issues or questions:
+1. Check the logs: `src/module/workflow-schedule/`
+2. Review Bull queue status
+3. Check Redis connection
+4. Verify database migrations ran successfully

package/src/module/workflow-schedule/constants/schedule.constants.ts

@@ -0,0 +1,48 @@
+/**
+ * Constants for Workflow Schedule Module
+ */
+
+// Entity Types
+export const SCHEDULED_WORKFLOW = 'WFSC';
+export const WORKFLOW_EXECUTION_LOG = 'WFEL';
+
+// Queue Names
+export const WORKFLOW_SCHEDULE_QUEUE = 'workflow-schedule';
+
+// Job Names
+export const EXECUTE_SCHEDULED_WORKFLOW_JOB = 'execute-scheduled-workflow';
+
+// Schedule Status
+export const SCHEDULE_STATUS_ACTIVE = 'ACTIVE';
+export const SCHEDULE_STATUS_PAUSED = 'PAUSED';
+export const SCHEDULE_STATUS_INACTIVE = 'INACTIVE';
+export const SCHEDULE_STATUS_EXPIRED = 'EXPIRED';
+
+// Execution Status
+export const EXECUTION_STATUS_PENDING = 'PENDING';
+export const EXECUTION_STATUS_RUNNING = 'RUNNING';
+export const EXECUTION_STATUS_COMPLETED = 'COMPLETED';
+export const EXECUTION_STATUS_FAILED = 'FAILED';
+export const EXECUTION_STATUS_PARTIAL = 'PARTIAL';
+
+// Workflow Types
+export const WORKFLOW_TYPE_AUTOMATED = 'AUTOMATED';
+export const WORKFLOW_TYPE_MANUAL = 'MANUAL';
+export const WORKFLOW_TYPE_SCHEDULED = 'SCHEDULED';
+
+// Action Types
+export const ACTION_TYPE_SEND_EMAIL = 'SEND_EMAIL';
+export const ACTION_TYPE_UPDATE_RECORDS = 'UPDATE_RECORDS';
+export const ACTION_TYPE_CREATE_TASK = 'CREATE_TASK';
+export const ACTION_TYPE_SEND_NOTIFICATION = 'SEND_NOTIFICATION';
+
+// Default Values
+export const DEFAULT_BATCH_SIZE = 100;
+export const DEFAULT_MAX_RETRIES = 3;
+export const DEFAULT_RETRY_DELAY = 5000; // 5 seconds
+export const DEFAULT_BACKOFF_MULTIPLIER = 2;
+export const DEFAULT_TIMEZONE = 'Asia/Kolkata';
+
+// Time Constants
+export const SECONDS_IN_MINUTE = 60;
+export const MILLISECONDS_IN_SECOND = 1000;

package/src/module/workflow-schedule/controller/workflow-schedule.controller.ts

@@ -0,0 +1,255 @@
+import {
+  Controller,
+  Post,
+  Get,
+  Put,
+  Delete,
+  Body,
+  Param,
+  Query,
+  Req,
+  UseGuards,
+  HttpCode,
+  HttpStatus,
+  ParseIntPipe,
+} from '@nestjs/common';
+import { Request } from 'express';
+import { JwtAuthGuard } from '../../auth/guards/jwt.guard';
+import { WorkflowScheduleService } from '../service/workflow-schedule.service';
+import { CreateScheduleDto } from '../dto/create-schedule.dto';
+import { UpdateScheduleDto } from '../dto/update-schedule.dto';
+import { GetExecutionLogsDto } from '../dto/get-execution-logs.dto';
+
+/**
+ * Workflow Schedule Controller
+ * Provides REST API endpoints for managing scheduled workflows
+ */
+@Controller('workflow-schedule')
+@UseGuards(JwtAuthGuard)
+export class WorkflowScheduleController {
+  constructor(private readonly workflowScheduleService: WorkflowScheduleService) {}
+
+  /**
+   * 1. Create a new scheduled workflow
+   * POST /workflow-schedule/create
+   */
+  @Post('/create')
+  @HttpCode(HttpStatus.CREATED)
+  async createSchedule(
+    @Body() createScheduleDto: CreateScheduleDto,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    const schedule = await this.workflowScheduleService.createSchedule(
+      createScheduleDto,
+      loggedInUser,
+    );
+
+    return {
+      success: true,
+      message: 'Scheduled workflow created successfully',
+      data: schedule,
+    };
+  }
+
+  /**
+   * 2. Update an existing scheduled workflow
+   * PUT /workflow-schedule/update
+   */
+  @Put('/update')
+  @HttpCode(HttpStatus.OK)
+  async updateSchedule(
+    @Body() updateScheduleDto: UpdateScheduleDto,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    const schedule = await this.workflowScheduleService.updateSchedule(
+      updateScheduleDto,
+      loggedInUser,
+    );
+
+    return {
+      success: true,
+      message: 'Scheduled workflow updated successfully',
+      data: schedule,
+    };
+  }
+
+  /**
+   * 3. Get a scheduled workflow by ID
+   * GET /workflow-schedule/:id
+   */
+  @Get('/:id')
+  @HttpCode(HttpStatus.OK)
+  async getScheduleById(
+    @Param('id', ParseIntPipe) id: number,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    const schedule = await this.workflowScheduleService.getScheduleById(id, loggedInUser);
+
+    return {
+      success: true,
+      data: schedule,
+    };
+  }
+
+  /**
+   * 4. Get all scheduled workflows with pagination and filters
+   * GET /workflow-schedule/list
+   */
+  @Get('/list')
+  @HttpCode(HttpStatus.OK)
+  async getAllSchedules(
+    @Query('workflow_id') workflow_id: string | undefined,
+    @Query('schedule_status') schedule_status: string | undefined,
+    @Query('is_enabled') is_enabled: string | undefined,
+    @Query('page') page: string | undefined,
+    @Query('size') size: string | undefined,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+
+    const filters: Record<string, any> = {};
+    if (workflow_id) filters.workflow_id = Number.parseInt(workflow_id, 10);
+    if (schedule_status) filters.schedule_status = schedule_status;
+    if (is_enabled !== undefined) filters.is_enabled = is_enabled === 'true';
+
+    const result = await this.workflowScheduleService.getAllSchedules(
+      page ? Number.parseInt(page, 10) : 1,
+      size ? Number.parseInt(size, 10) : 10,
+      filters,
+      loggedInUser,
+    );
+
+    return {
+      success: true,
+      ...result,
+    };
+  }
+
+  /**
+   * 5. Pause a scheduled workflow
+   * POST /workflow-schedule/:id/pause
+   */
+  @Post('/:id/pause')
+  @HttpCode(HttpStatus.OK)
+  async pauseSchedule(
+    @Param('id', ParseIntPipe) id: number,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    const schedule = await this.workflowScheduleService.pauseSchedule(id, loggedInUser);
+
+    return {
+      success: true,
+      message: 'Scheduled workflow paused successfully',
+      data: schedule,
+    };
+  }
+
+  /**
+   * 6. Resume a paused scheduled workflow
+   * POST /workflow-schedule/:id/resume
+   */
+  @Post('/:id/resume')
+  @HttpCode(HttpStatus.OK)
+  async resumeSchedule(
+    @Param('id', ParseIntPipe) id: number,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    const schedule = await this.workflowScheduleService.resumeSchedule(id, loggedInUser);
+
+    return {
+      success: true,
+      message: 'Scheduled workflow resumed successfully',
+      data: schedule,
+    };
+  }
+
+  /**
+   * 7. Delete a scheduled workflow
+   * DELETE /workflow-schedule/:id
+   */
+  @Delete('/:id')
+  @HttpCode(HttpStatus.OK)
+  async deleteSchedule(
+    @Param('id', ParseIntPipe) id: number,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    await this.workflowScheduleService.deleteSchedule(id, loggedInUser);
+
+    return {
+      success: true,
+      message: 'Scheduled workflow deleted successfully',
+    };
+  }
+
+  /**
+   * 8. Manually trigger a scheduled workflow execution
+   * POST /workflow-schedule/:id/trigger
+   */
+  @Post('/:id/trigger')
+  @HttpCode(HttpStatus.OK)
+  async triggerManualExecution(
+    @Param('id', ParseIntPipe) id: number,
+    @Body('metadata') metadata: Record<string, any>,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    const result = await this.workflowScheduleService.triggerManualExecution(
+      id,
+      loggedInUser,
+      metadata,
+    );
+
+    return {
+      success: true,
+      message: 'Workflow execution triggered successfully',
+      data: result,
+    };
+  }
+
+  /**
+   * 9. Get execution logs with filters and pagination
+   * POST /workflow-schedule/execution-logs
+   */
+  @Post('/execution-logs')
+  @HttpCode(HttpStatus.OK)
+  async getExecutionLogs(
+    @Body() getExecutionLogsDto: GetExecutionLogsDto,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    const result = await this.workflowScheduleService.getExecutionLogs(
+      getExecutionLogsDto,
+      loggedInUser,
+    );
+
+    return {
+      success: true,
+      ...result,
+    };
+  }
+
+  /**
+   * BONUS: Get execution statistics for a schedule
+   * GET /workflow-schedule/:id/stats
+   */
+  @Get('/:id/stats')
+  @HttpCode(HttpStatus.OK)
+  async getExecutionStats(
+    @Param('id', ParseIntPipe) id: number,
+    @Req() req: Request & { user: any },
+  ) {
+    const loggedInUser = req.user.userData;
+    const stats = await this.workflowScheduleService.getExecutionStats(id, loggedInUser);
+
+    return {
+      success: true,
+      data: stats,
+    };
+  }
+}