rez_core 4.0.184 → 4.0.187

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

@@ -0,0 +1,244 @@
+# Workflow Schedule Module - Installation Guide
+
+## Quick Start
+
+### Step 1: Install 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 `@types` package is needed.
+
+### Step 2: Setup Redis
+
+#### Option A: Using Docker (Recommended)
+```bash
+docker run -d \
+  --name redis-workflow \
+  -p 6379:6379 \
+  redis:latest
+```
+
+#### Option B: Local Installation
+**macOS:**
+```bash
+brew install redis
+brew services start redis
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get install redis-server
+sudo systemctl start redis-server
+```
+
+**Windows:**
+Download from: https://redis.io/download
+
+### Step 3: Configure Environment Variables
+
+Add to your `.env` file:
+
+```env
+# Redis Configuration
+REDIS_HOST=localhost
+REDIS_PORT=6379
+REDIS_PASSWORD=
+REDIS_DB=0
+
+# Existing Database Configuration (verify these)
+DB_HOST=13.234.25.234
+DB_PORT=3306
+DB_USER=root
+DB_PASS=Rezolut@123
+DB_NAME=core
+```
+
+### Step 4: Verify Redis Connection
+
+```bash
+# Test Redis connection
+redis-cli ping
+# Should respond: PONG
+```
+
+### Step 5: Run Database Migrations
+
+The module requires three migrations to be run:
+
+```bash
+# Using TypeORM CLI (recommended)
+npx ts-node -r tsconfig-paths/register ./node_modules/typeorm/cli.js migration:run -d src/config/database.config.ts
+
+# Or create a migration script in package.json:
+# "migration:run": "typeorm migration:run -d src/config/database.config.ts"
+# Then run:
+npm run migration:run
+```
+
+**Migrations will create:**
+1. ✅ `workflow_type` column in `cr_wf_master` table
+2. ✅ `cr_wf_scheduled_workflow` table with indexes
+3. ✅ `cr_wf_execution_log` table with indexes
+
+### Step 6: Start Your Application
+
+```bash
+npm run start:dev
+```
+
+### Step 7: Verify Installation
+
+Check the console logs for:
+```
+[Nest] INFO [BullModule] Bull queues registered
+[Nest] INFO [WorkflowScheduleModule] Workflow Schedule Module initialized
+```
+
+## Quick Test
+
+### Create Your First Schedule
+
+```bash
+curl -X POST http://localhost:3000/workflow-schedule/create \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
+  -d '{
+    "workflow_id": 1,
+    "name": "Test Schedule",
+    "cron_expression": "*/5 * * * *",
+    "timezone": "Asia/Kolkata",
+    "actions": []
+  }'
+```
+
+### List All Schedules
+
+```bash
+curl -X GET http://localhost:3000/workflow-schedule/list \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+## Troubleshooting
+
+### Issue: Cannot connect to Redis
+
+**Solution:**
+```bash
+# Check if Redis is running
+redis-cli ping
+
+# If not running, start Redis
+docker start redis-workflow
+# or
+brew services start redis
+```
+
+### Issue: Migration fails with "Table already exists"
+
+**Solution:**
+Migrations check if tables exist before creating them. If you see this message, the tables are already present. You can safely ignore it.
+
+### Issue: Jobs are not processing
+
+**Checklist:**
+- [ ] Redis is running and accessible
+- [ ] Schedule status is `ACTIVE`
+- [ ] Schedule `is_enabled` is `true`
+- [ ] Cron expression is valid
+- [ ] Application has restarted after creating the schedule
+
+**Verify:**
+```bash
+# Check Redis keys
+redis-cli KEYS "bull:workflow-schedule:*"
+
+# Should show keys if jobs are queued
+```
+
+### Issue: TypeScript errors after installation
+
+**Solution:**
+```bash
+# Clear node_modules and reinstall
+rm -rf node_modules package-lock.json
+npm install
+
+# Restart your IDE/editor
+```
+
+## Verify Bull Queue Dashboard (Optional)
+
+Install Bull Board for visual queue monitoring:
+
+```bash
+npm install @bull-board/express @bull-board/api
+```
+
+Add to your `main.ts`:
+```typescript
+import { createBullBoard } from '@bull-board/api';
+import { BullAdapter } from '@bull-board/api/bullAdapter';
+import { ExpressAdapter } from '@bull-board/express';
+
+// Get queue from your app
+const schedulerQueue = app.get('BullQueue_workflow-schedule');
+
+const serverAdapter = new ExpressAdapter();
+createBullBoard({
+  queues: [new BullAdapter(schedulerQueue)],
+  serverAdapter,
+});
+
+serverAdapter.setBasePath('/admin/queues');
+app.use('/admin/queues', serverAdapter.getRouter());
+```
+
+Then access: `http://localhost:3000/admin/queues`
+
+## Package Versions
+
+Tested with:
+```json
+{
+  "@nestjs/bull": "^10.0.0",
+  "@nestjs/common": "^11.0.0",
+  "@nestjs/core": "^11.0.0",
+  "bull": "^4.12.0",
+  "redis": "^4.6.0",
+  "cron-parser": "^4.9.0"
+}
+```
+
+## Production Checklist
+
+Before deploying to production:
+
+- [ ] Configure Redis with persistence
+- [ ] Set up Redis password authentication
+- [ ] Configure appropriate retry strategies
+- [ ] Set up monitoring and alerting
+- [ ] Configure log retention policies
+- [ ] Test failover scenarios
+- [ ] Set up backup for scheduled workflow configurations
+- [ ] Document schedule ownership and purpose
+- [ ] Configure rate limiting if needed
+- [ ] Set up Redis clustering for high availability
+
+## Next Steps
+
+1. Read the full [README.md](./README.md) for API documentation
+2. Test the 9 API endpoints
+3. Create your first scheduled workflow
+4. Monitor execution logs
+5. Set up Bull Board for visual monitoring
+
+## Support
+
+If you encounter issues:
+1. Check application logs
+2. Verify Redis connectivity
+3. Ensure migrations ran successfully
+4. Review the [README.md](./README.md) troubleshooting section

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

@@ -0,0 +1,196 @@
+# Multi-Project Configuration Guide
+
+## Overview
+This `workflow-schedule` module is designed to be used as a **shared package** across multiple NestJS projects. You can control whether the cron processor runs in each project independently.
+
+## Problem Scenario
+You have multiple servers importing this module:
+- **Server 1 (Scheduler Server)** - Should run the cron processor ✅
+- **Server 2 (API Server)** - Should NOT run cron, but can create/manage schedules ❌
+- **Server 3 (Worker Server)** - Should NOT run cron, but can create/manage schedules ❌
+
+## Solution
+
+### Server 1: Enable Cron Processor (Scheduler Server)
+
+```typescript
+// app.module.ts
+import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
+
+@Module({
+  imports: [
+    BullModule.forRootAsync(bullConfigFactory),
+    // ✅ Enable processor - this server will execute scheduled workflows
+    WorkflowScheduleModule.forRoot({ enableProcessor: true }),
+    WorkflowAutomationModule,
+    // ... other modules
+  ],
+})
+export class AppModule {}
+```
+
+### Server 2 & 3: Disable Cron Processor (API/Worker Servers)
+
+```typescript
+// app.module.ts
+import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
+
+@Module({
+  imports: [
+    BullModule.forRootAsync(bullConfigFactory),
+    // ❌ Disable processor - this server will NOT execute cron jobs
+    WorkflowScheduleModule.forRoot({ enableProcessor: false }),
+    WorkflowAutomationModule,
+    // ... other modules
+  ],
+})
+export class AppModule {}
+```
+
+## What Each Configuration Does
+
+### With `enableProcessor: true`
+- ✅ `WorkflowScheduleService` is available (create/manage schedules)
+- ✅ `ScheduleProcessor` is registered (listens to Bull queue)
+- ✅ **Cron jobs WILL execute** on this server
+- ✅ REST API endpoints are available
+- ✅ Can trigger manual executions
+
+### With `enableProcessor: false`
+- ✅ `WorkflowScheduleService` is available (create/manage schedules)
+- ❌ `ScheduleProcessor` is NOT registered
+- ❌ **Cron jobs will NOT execute** on this server
+- ✅ REST API endpoints are available
+- ✅ Can trigger manual executions
+- ⚠️ Scheduled workflows will be executed by the server with `enableProcessor: true`
+
+## Environment-Based Configuration
+
+For better control, use environment variables:
+
+```typescript
+// app.module.ts
+import { WorkflowScheduleModule } from './module/workflow-schedule/workflow-schedule.module';
+
+@Module({
+  imports: [
+    BullModule.forRootAsync(bullConfigFactory),
+    WorkflowScheduleModule.forRoot({
+      enableProcessor: process.env.ENABLE_WORKFLOW_SCHEDULER === 'true',
+    }),
+    WorkflowAutomationModule,
+  ],
+})
+export class AppModule {}
+```
+
+Then in each project's `.env` file:
+
+**Server 1 (Scheduler Server):**
+```env
+ENABLE_WORKFLOW_SCHEDULER=true
+```
+
+**Server 2 & 3:**
+```env
+ENABLE_WORKFLOW_SCHEDULER=false
+```
+
+## Default Behavior
+
+If you call `WorkflowScheduleModule.forRoot()` without options, the processor is **ENABLED by default**:
+
+```typescript
+// This is equivalent to { enableProcessor: true }
+WorkflowScheduleModule.forRoot()
+```
+
+## Architecture Considerations
+
+### Recommended Setup for High Availability
+
+1. **Dedicated Scheduler Server** (Server 1)
+   - `enableProcessor: true`
+   - Runs cron processor
+   - Handles scheduled workflow executions
+   - Monitor with PM2/Forever for auto-restart
+
+2. **API Servers** (Server 2, 3, ...)
+   - `enableProcessor: false`
+   - Handle HTTP requests
+   - Create/update/delete schedules
+   - Schedules are executed by Server 1
+
+### Redis Requirement
+
+All servers must connect to the **same Redis instance**:
+- Server 1 adds jobs to the queue
+- Servers 2 & 3 can also add jobs (manual triggers)
+- Only Server 1 (with processor enabled) will consume/execute jobs
+
+```typescript
+// bull.config.ts (same across all servers)
+export const bullConfigFactory = {
+  useFactory: () => ({
+    redis: {
+      host: process.env.REDIS_HOST || 'localhost',
+      port: parseInt(process.env.REDIS_PORT) || 6379,
+      password: process.env.REDIS_PASSWORD,
+    },
+  }),
+};
+```
+
+## Testing
+
+### Test Processor is Disabled
+
+Start your server with `enableProcessor: false` and check logs. You should NOT see:
+```
+[ScheduleProcessor] Processing job {jobId}
+```
+
+### Test Processor is Enabled
+
+Start your server with `enableProcessor: true` and:
+1. Create a schedule with `is_enabled: true`
+2. Check logs for processor activity
+3. Verify jobs execute on schedule
+
+## Migration from Old Setup
+
+If you previously imported the module directly:
+
+**Before:**
+```typescript
+imports: [
+  WorkflowScheduleModule, // ❌ Old way
+]
+```
+
+**After:**
+```typescript
+imports: [
+  WorkflowScheduleModule.forRoot({ enableProcessor: true }), // ✅ New way
+]
+```
+
+## Troubleshooting
+
+### Issue: Cron runs on multiple servers
+
+**Cause:** Multiple servers have `enableProcessor: true`
+
+**Solution:** Set `enableProcessor: false` on all servers except one
+
+### Issue: Cron doesn't run on any server
+
+**Cause:** All servers have `enableProcessor: false`
+
+**Solution:** Set `enableProcessor: true` on at least one server
+
+### Issue: "Cannot find module WorkflowScheduleModule"
+
+**Cause:** Wrong import after refactor
+
+**Solution:** Ensure you're importing from the correct path and using `.forRoot()`