laxmanhalaki cd6a71b804 configuration screen added added

2025-11-05 15:38:08 +05:30

19 KiB

Raw Blame History

Skip Approver & Dynamic Approver Addition

Overview

This feature allows initiators and approvers to manage approval workflows dynamically when approvers are unavailable or additional approval is needed.

Key Features:

Skip Approver - Skip non-responding approvers and move to next level
Add Approver at Specific Level - Insert new approver at any position
Automatic Level Shifting - Existing approvers are automatically renumbered
Smart Validation - Cannot modify completed levels (approved/rejected/skipped)
TAT Management - New approvers get their own TAT, jobs scheduled automatically

Use Cases

Use Case 1: Approver on Leave

Scenario:

Level 1: Sarah (Approved) ✅
Level 2: Mike (Pending) ⏳  ← On vacation, not responding
Level 3: Lisa (Waiting) ⏸️

Solution:

Initiator clicks "Skip This Approver" on Level 2
→ Mike is marked as SKIPPED
→ Level 3 (Lisa) becomes active
→ Lisa receives notification
→ TAT jobs cancelled for Mike, scheduled for Lisa

Result:

Level 1: Sarah (Approved) ✅
Level 2: Mike (Skipped) ⏭️  ← Skipped
Level 3: Lisa (In Review) ⏳  ← Now active

Use Case 2: Add Additional Reviewer

Scenario:

Level 1: Sarah (Approved) ✅
Level 2: Mike (In Review) ⏳
Level 3: Lisa (Waiting) ⏸️

Need: Add Finance Manager (John) between Mike and Lisa

Solution:

Click "Add Approver"
→ Email: john@example.com
→ TAT: 48 hours
→ Level: 3 (between Mike and Lisa)
→ Submit

Result:

Level 1: Sarah (Approved) ✅
Level 2: Mike (In Review) ⏳  ← Still at level 2
Level 3: John (Waiting) ⏸️  ← NEW! Inserted here
Level 4: Lisa (Waiting) ⏸️  ← Shifted from 3 to 4

Use Case 3: Replace Skipped Approver

Scenario:

Level 1: Sarah (Approved) ✅
Level 2: Mike (Skipped) ⏭️
Level 3: Lisa (In Review) ⏳

Need: Add replacement for Mike at level 2

Solution:

Click "Add Approver"
→ Email: john@example.com
→ TAT: 24 hours
→ Level: 2 (Mike's old position)
→ Submit

Result:

Level 1: Sarah (Approved) ✅
Level 2: John (Waiting) ⏸️  ← NEW! Inserted at level 2
Level 3: Mike (Skipped) ⏭️  ← Shifted from 2 to 3
Level 4: Lisa (In Review) ⏳  ← Shifted from 3 to 4

Database Schema

New Fields in `approval_levels` Table:

-- Migration: add_is_skipped_to_approval_levels.sql

ALTER TABLE approval_levels
ADD COLUMN is_skipped BOOLEAN DEFAULT FALSE,
ADD COLUMN skipped_at TIMESTAMP,
ADD COLUMN skipped_by UUID REFERENCES users(user_id),
ADD COLUMN skip_reason TEXT;

Status Enum Update:

Already includes SKIPPED status:

status ENUM('PENDING', 'IN_PROGRESS', 'APPROVED', 'REJECTED', 'SKIPPED')

Example Data:

-- Level 2 was skipped
SELECT 
  level_number,
  approver_name,
  status,
  is_skipped,
  skipped_at,
  skip_reason
FROM approval_levels
WHERE request_id = 'xxx';

-- Results:
-- 1 | Sarah  | APPROVED | FALSE | NULL       | NULL
-- 2 | Mike   | SKIPPED  | TRUE  | 2025-11-05 | On vacation
-- 3 | Lisa   | PENDING  | FALSE | NULL       | NULL

API Endpoints

1. Skip Approver

Endpoint:

POST /api/v1/workflows/:id/approvals/:levelId/skip

Request Body:

{
  "reason": "Approver on vacation - deadline approaching"
}

Response:

{
  "success": true,
  "message": "Approver skipped successfully",
  "data": {
    "levelId": "...",
    "levelNumber": 2,
    "status": "SKIPPED",
    "skippedAt": "2025-11-05T10:30:00Z"
  }
}

Logic:

✅ Mark level as SKIPPED
✅ Cancel TAT jobs for skipped level
✅ Activate next level (move to level+1)
✅ Schedule TAT jobs for next level
✅ Notify next approver
✅ Log activity

Validation:

❌ Cannot skip already approved/rejected/skipped levels
❌ Cannot skip future levels (only current level)
✅ Only INITIATOR or APPROVER can skip

2. Add Approver at Specific Level

Endpoint:

POST /api/v1/workflows/:id/approvers/at-level

Request Body:

{
  "email": "john@example.com",
  "tatHours": 48,
  "level": 3
}

Response:

{
  "success": true,
  "message": "Approver added successfully",
  "data": {
    "levelId": "...",
    "levelNumber": 3,
    "approverName": "John Doe",
    "tatHours": 48,
    "status": "PENDING"
  }
}

Logic:

✅ Find user by email
✅ Validate target level (must be after completed levels)
✅ Shift existing levels at and after target level (+1)
✅ Create new approval level at target position
✅ Add as participant (APPROVER type)
✅ If new level is current level, schedule TAT jobs
✅ Notify new approver
✅ Log activity

Validation:

❌ User must exist in system
❌ User cannot be existing participant
❌ Level must be after completed levels (approved/rejected/skipped)
✅ Automatic level shifting for existing approvers

Level Shifting Logic

Example: Add at Level 3

Before:

Level 1: Sarah (Approved) ✅
Level 2: Mike (In Review) ⏳
Level 3: Lisa (Waiting) ⏸️
Level 4: Tom (Waiting) ⏸️

Action:

Add John at Level 3 with 48h TAT

Backend Processing:

// Step 1: Get levels to shift (levelNumber >= 3)
levelsToShift = [Lisa (Level 3), Tom (Level 4)]

// Step 2: Shift each level
Lisa: Level 3 → Level 4
Tom: Level 4 → Level 5

// Step 3: Insert new approver
John: Create at Level 3

// Step 4: Update workflow.totalLevels
totalLevels: 4 → 5

After:

Level 1: Sarah (Approved) ✅
Level 2: Mike (In Review) ⏳
Level 3: John (Waiting) ⏸️  ← NEW!
Level 4: Lisa (Waiting) ⏸️  ← Shifted from 3
Level 5: Tom (Waiting) ⏸️  ← Shifted from 4

Frontend Implementation

AddApproverModal Enhancements:

New Props:

interface AddApproverModalProps {
  open: boolean;
  onClose: () => void;
  onConfirm: (email: string, tatHours: number, level: number) => Promise<void>;
  currentLevels?: ApprovalLevelInfo[];  // ✅ NEW!
}

interface ApprovalLevelInfo {
  levelNumber: number;
  approverName: string;
  status: string;
  tatHours: number;
}

UI Components:

Current Levels Display - Shows all existing levels with status badges
Level Selector - Dropdown with available levels (after completed)
TAT Hours Input - Number input for TAT (1-720 hours)
Email Search - Existing @ mention search

Example Modal:

┌─────────────────────────────────────────────────┐
│ Add Approver                                    │
├─────────────────────────────────────────────────┤
│ Current Approval Levels                         │
│ ┌─────────────────────────────────────────────┐ │
│ │ [1] Sarah          50h TAT    [✓] approved  │ │
│ │ [2] Mike           24h TAT    [⏳] pending  │ │
│ │ [3] Lisa           36h TAT    [⏸] waiting   │ │
│ └─────────────────────────────────────────────┘ │
│                                                   │
│ Approval Level *                                │
│ [Select: Level 2 (will shift existing Level 2)] │
│                                                   │
│ TAT (Turn Around Time) *                        │
│ [48] hours                                       │
│                                                   │
│ Email Address *                                 │
│ [@john or john@example.com]                     │
│                                                   │
│ [Cancel] [Add at Level 2]                       │
└─────────────────────────────────────────────────┘

RequestDetail Skip Button:

Added to Workflow tab for each pending/in-review level:

{/* Skip Approver Button - Only for active levels */}
{(isActive || step.status === 'pending') && !isCompleted && !isRejected && (
  <Button 
    variant="outline" 
    size="sm"
    className="w-full border-orange-300 text-orange-700 hover:bg-orange-50"
    onClick={() => {
      const reason = prompt('Provide reason for skipping:');
      if (reason !== null) {
        handleSkipApprover(step.levelId, reason);
      }
    }}
  >
    <AlertCircle className="w-4 h-4 mr-2" />
    Skip This Approver
  </Button>
)}

Validation Rules

Skip Approver Validation:

Rule	Validation	Error Message
Already completed	❌ Cannot skip APPROVED level	"Cannot skip approver - level is already APPROVED"
Already rejected	❌ Cannot skip REJECTED level	"Cannot skip approver - level is already REJECTED"
Already skipped	❌ Cannot skip SKIPPED level	"Cannot skip approver - level is already SKIPPED"
Future level	❌ Cannot skip level > currentLevel	"Cannot skip future approval levels"
Authorization	✅ Only INITIATOR or APPROVER	403 Forbidden

Add Approver Validation:

Rule	Validation	Error Message
User exists	✅ User must exist in system	"User not found with this email"
Already participant	❌ Cannot add existing participant	"User is already a participant"
Level range	❌ Level must be ≥ (completed levels + 1)	"Cannot add at level X. Minimum is Y"
TAT hours	✅ 1 ≤ hours ≤ 720	"TAT hours must be between 1 and 720"
Email format	✅ Valid email format	"Please enter a valid email"
Authorization	✅ Only INITIATOR or APPROVER	403 Forbidden

Examples

Example 1: Skip Current Approver

Initial State:

Request: REQ-2025-001
Current Level: 2

Level 1: Sarah (APPROVED) ✅
Level 2: Mike (IN_PROGRESS) ⏳  ← Taking too long
Level 3: Lisa (PENDING) ⏸️

Action:

# Initiator skips Mike
POST /api/v1/workflows/REQ-2025-001/approvals/LEVEL-ID-2/skip
Body: { "reason": "Approver on extended leave" }

Backend Processing:

1. Get Level 2 (Mike) → Status: IN_PROGRESS ✅
2. Validate: Not already completed ✅
3. Update Level 2:
   - status: 'SKIPPED'
   - is_skipped: TRUE
   - skipped_at: NOW()
   - skipped_by: initiator userId
   - skip_reason: "Approver on extended leave"
4. Cancel TAT jobs for Level 2
5. Get Level 3 (Lisa)
6. Activate Level 3:
   - status: 'IN_PROGRESS'
   - levelStartTime: NOW()
   - tatStartTime: NOW()
7. Schedule TAT jobs for Level 3
8. Update workflow.currentLevel = 3
9. Notify Lisa
10. Log activity: "Level 2 approver (Mike) was skipped"

Final State:

Request: REQ-2025-001
Current Level: 3

Level 1: Sarah (APPROVED) ✅
Level 2: Mike (SKIPPED) ⏭️  ← Skipped!
Level 3: Lisa (IN_PROGRESS) ⏳  ← Now active!

Example 2: Add Approver Between Levels

Initial State:

Request: REQ-2025-001
Current Level: 2

Level 1: Sarah (APPROVED) ✅
Level 2: Mike (IN_PROGRESS) ⏳
Level 3: Lisa (PENDING) ⏸️

Action:

# Add John at Level 3 (between Mike and Lisa)
POST /api/v1/workflows/REQ-2025-001/approvers/at-level
Body: {
  "email": "john@example.com",
  "tatHours": 48,
  "level": 3
}

Backend Processing:

1. Find user: john@example.com ✅
2. Validate: Not existing participant ✅
3. Validate: Level 3 ≥ minLevel (2) ✅
4. Get levels to shift: [Lisa (Level 3)]
5. Shift Lisa:
   - Level 3 → Level 4
   - levelName: "Level 4"
6. Create new Level 3:
   - levelNumber: 3
   - approverId: John's userId
   - approverEmail: john@example.com
   - tatHours: 48
   - status: PENDING (not current level)
7. Update workflow.totalLevels: 3 → 4
8. Add John to participants (APPROVER type)
9. Notify John
10. Log activity: "John added as approver at Level 3 with TAT of 48 hours"

Final State:

Request: REQ-2025-001
Current Level: 2

Level 1: Sarah (APPROVED) ✅
Level 2: Mike (IN_PROGRESS) ⏳  ← Still working
Level 3: John (PENDING) ⏸️  ← NEW! Will review after Mike
Level 4: Lisa (PENDING) ⏸️  ← Shifted from 3 to 4

Example 3: Complex Scenario - Skip and Add

Initial State:

Level 1: Sarah (APPROVED) ✅
Level 2: Mike (APPROVED) ✅
Level 3: David (IN_PROGRESS) ⏳  ← Taking too long
Level 4: Lisa (PENDING) ⏸️
Level 5: Tom (PENDING) ⏸️

Action 1: Skip David

Result:
Level 1: Sarah (APPROVED) ✅
Level 2: Mike (APPROVED) ✅
Level 3: David (SKIPPED) ⏭️
Level 4: Lisa (IN_PROGRESS) ⏳  ← Now active
Level 5: Tom (PENDING) ⏸️

Action 2: Add John at Level 4 (before Tom)

Result:
Level 1: Sarah (APPROVED) ✅
Level 2: Mike (APPROVED) ✅
Level 3: David (SKIPPED) ⏭️
Level 4: Lisa (IN_PROGRESS) ⏳
Level 5: John (PENDING) ⏸️  ← NEW!
Level 6: Tom (PENDING) ⏸️  ← Shifted

UI/UX

RequestDetail - Workflow Tab:

Skip Button Visibility:

✅ Shows for levels with status: pending or in-review
❌ Hidden for approved, rejected, skipped, or waiting
✅ Orange/amber styling to indicate caution
✅ Requires reason via prompt

Button Appearance:

┌───────────────────────────────────────────┐
│ Level 2: Mike (In Review)                 │
│ TAT: 24h  •  Elapsed: 15h                 │
│                                            │
│ [⚠ Skip This Approver]                    │
│ Skip if approver is unavailable...        │
└───────────────────────────────────────────┘

AddApproverModal - Enhanced UI:

Sections:

Current Levels - Scrollable list showing all existing levels with status
Level Selector - Dropdown with available levels (grayed out completed levels)
TAT Input - Hours input with validation (1-720)
Email Search - @ mention search (existing)

Features:

✅ Auto-selects first available level
✅ Shows which existing level will be shifted
✅ Visual indicators for completed vs pending levels
✅ Prevents selecting invalid levels
✅ Real-time validation

Activity Log Examples

Skip Approver Log:

Action: Approver Skipped
Details: Level 2 approver (Mike Johnson) was skipped by Sarah Smith. 
         Reason: Approver on extended leave
Timestamp: 2025-11-05 10:30:00
User: Sarah Smith (Initiator)

Add Approver Log:

Action: Added new approver
Details: John Doe (john@example.com) has been added as approver at 
         Level 3 with TAT of 48 hours by Sarah Smith
Timestamp: 2025-11-05 11:15:00
User: Sarah Smith (Initiator)

Notifications

Skip Approver Notifications:

To Next Approver:

Title: Request Escalated
Body: Previous approver was skipped. Request REQ-2025-001 is now 
      awaiting your approval.

Add Approver Notifications:

To New Approver:

Title: New Request Assignment
Body: You have been added as Level 3 approver to request REQ-2025-001: 
      New Office Location Approval

TAT Handling

Skip Approver:

// Skipped level's TAT jobs are cancelled
await tatSchedulerService.cancelTatJobs(requestId, skippedLevelId);

// Next level's TAT jobs are scheduled
await tatSchedulerService.scheduleTatJobs(
  requestId,
  nextLevelId,
  nextApproverId,
  nextLevelTatHours,
  now,
  workflowPriority
);

Add Approver:

// If new approver is at current level, schedule TAT immediately
if (newLevel === currentLevel) {
  await tatSchedulerService.scheduleTatJobs(
    requestId,
    newLevelId,
    newApproverId,
    tatHours,
    now,
    workflowPriority
  );
}
// Otherwise, jobs will be scheduled when level becomes active

Testing Scenarios

Test 1: Skip Current Approver

# 1. Create workflow with 3 approvers
# 2. Level 1 approves
# 3. Level 2 receives notification
# 4. Level 2 doesn't respond for extended time
# 5. Initiator clicks "Skip This Approver"
# 6. Provide reason: "On vacation"
# 7. Verify:
#    ✅ Level 2 status = SKIPPED
#    ✅ Level 3 status = IN_PROGRESS
#    ✅ Level 3 receives notification
#    ✅ TAT jobs scheduled for Level 3
#    ✅ Activity logged

Test 2: Add Approver at Middle Level

# 1. Workflow has 3 levels
# 2. Level 1 approved
# 3. Click "Add Approver"
# 4. Select Level 2 (between current levels)
# 5. Enter TAT: 48
# 6. Enter email: new@example.com
# 7. Submit
# 8. Verify:
#    ✅ Old Level 2 becomes Level 3
#    ✅ Old Level 3 becomes Level 4
#    ✅ New approver at Level 2
#    ✅ totalLevels increased by 1
#    ✅ New approver receives notification

Test 3: Cannot Add Before Completed Level

# 1. Workflow: Level 1 (Approved), Level 2 (Pending)
# 2. Try to add at Level 1
# 3. Modal shows: "Minimum allowed level is 2"
# 4. Level 1 is grayed out in selector
# 5. Cannot submit ✅

Files Modified

Backend:

Re_Backend/src/migrations/add_is_skipped_to_approval_levels.sql - Database migration
Re_Backend/src/services/workflow.service.ts - Skip and add approver logic
Re_Backend/src/routes/workflow.routes.ts - API endpoints

Frontend:

Re_Figma_Code/src/services/workflowApi.ts - API client methods
Re_Figma_Code/src/components/participant/AddApproverModal/AddApproverModal.tsx - Enhanced modal
Re_Figma_Code/src/pages/RequestDetail/RequestDetail.tsx - Skip button and handlers

Summary

Feature	Description	Benefit
Skip Approver	Mark approver as skipped, move to next	Handle unavailable approvers
Add at Level	Insert approver at specific position	Flexible workflow modification
Auto Shifting	Existing levels automatically renumbered	No manual level management
Smart Validation	Cannot modify completed levels	Data integrity
TAT Management	Jobs cancelled/scheduled automatically	Accurate time tracking
Activity Logging	All actions tracked in audit trail	Full transparency
Notifications	Affected users notified automatically	Keep everyone informed

Benefits

✅ Flexibility - Handle real-world workflow changes
✅ No Bottlenecks - Skip unavailable approvers
✅ Dynamic Addition - Add approvers mid-workflow
✅ Data Integrity - Cannot modify completed levels
✅ Audit Trail - Full history of all changes
✅ Automatic Notifications - All affected parties notified
✅ TAT Accuracy - Time tracking updated correctly
✅ User-Friendly - Intuitive UI with clear feedback

The approval workflow is now fully dynamic and can adapt to changing business needs! 🚀

19 KiB Raw Blame History

Skip Approver & Dynamic Approver Addition

Overview

Key Features:

Use Cases

Use Case 1: Approver on Leave

Use Case 2: Add Additional Reviewer

Use Case 3: Replace Skipped Approver

Database Schema

New Fields in approval_levels Table:

Status Enum Update:

Example Data:

API Endpoints

1. Skip Approver

2. Add Approver at Specific Level

Level Shifting Logic

Example: Add at Level 3

Frontend Implementation

AddApproverModal Enhancements:

RequestDetail Skip Button:

Validation Rules

Skip Approver Validation:

Add Approver Validation:

Examples

Example 1: Skip Current Approver

Example 2: Add Approver Between Levels

Example 3: Complex Scenario - Skip and Add

UI/UX

RequestDetail - Workflow Tab:

AddApproverModal - Enhanced UI:

Activity Log Examples

Skip Approver Log:

Add Approver Log:

Notifications

Skip Approver Notifications:

Add Approver Notifications:

TAT Handling

Skip Approver:

Add Approver:

Testing Scenarios

Test 1: Skip Current Approver

Test 2: Add Approver at Middle Level

Test 3: Cannot Add Before Completed Level

Files Modified

Backend:

Frontend:

Summary

Benefits

19 KiB

Raw Blame History

New Fields in `approval_levels` Table: