Re_Backend/QUICK_START_SKIP_ADD_APPROVER.md

Quick Start: Skip & Add Approver Features

🚀 Setup (One-Time)

Step 1: Run Database Migration

# Connect to database
psql -U postgres -d re_workflow

# Run migration
\i Re_Backend/src/migrations/add_is_skipped_to_approval_levels.sql

# Verify columns added
\d approval_levels
# Should show: is_skipped, skipped_at, skipped_by, skip_reason

Step 2: Restart Backend

cd Re_Backend
npm run dev

---

📖 User Guide

How to Skip an Approver (Initiator/Approver)

1. Go to Request Detail → Workflow tab
2. Find the approver who is pending/in-review
3. Click "Skip This Approver" button
4. Enter reason (e.g., "On vacation")
5. Click OK

Result:

• ✅ Approver marked as SKIPPED
• ✅ Next approver becomes active
• ✅ Notification sent to next approver
• ✅ Activity logged

---

How to Add New Approver (Initiator/Approver)

1. Go to Request Detail → Quick Actions
2. Click "Add Approver"
3. Review Current Levels (shows all existing approvers with status)
4. Select Approval Level (where to insert new approver)
5. Enter TAT Hours (e.g., 48)
6. Enter Email (use @ to search: @john)
7. Click "Add at Level X"

Result:

• ✅ New approver inserted at chosen level
• ✅ Existing approvers shifted automatically
• ✅ TAT jobs scheduled if level is active
• ✅ Notification sent to new approver
• ✅ Activity logged

---

🎯 Examples

Example 1: Skip Non-Responding Approver

Scenario: Mike (Level 2) hasn't responded for 3 days, deadline approaching

Steps:

1. Open request REQ-2025-001
2. Go to Workflow tab
3. Find Mike's card (Level 2 - In Review)
4. Click "Skip This Approver"
5. Reason: "Approver on extended leave - deadline critical"
6. Confirm

Result:

Before:                    After:
Level 1: Sarah ✅          Level 1: Sarah ✅
Level 2: Mike ⏳    →      Level 2: Mike ⏭️ (SKIPPED)
Level 3: Lisa ⏸️           Level 3: Lisa ⏳ (ACTIVE!)

---

Example 2: Add Finance Review

Scenario: Need Finance Manager approval between existing levels

Steps:

1. Click "Add Approver" in Quick Actions
2. See current levels:
   • Level 1: Sarah (Approved)
   • Level 2: Mike (In Review)
   • Level 3: Lisa (Waiting)
3. Select Level: 3 (to insert before Lisa)
4. TAT Hours: 48
5. Email: @john → Select "John Doe (john@finance.com)"
6. Click "Add at Level 3"

Result:

Before:                          After:
Level 1: Sarah ✅                Level 1: Sarah ✅
Level 2: Mike ⏳                 Level 2: Mike ⏳
Level 3: Lisa ⏸️         →       Level 3: John ⏸️ (NEW!)
                                  Level 4: Lisa ⏸️ (shifted)

---

⚙️ API Reference

Skip Approver

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

Headers:
  Authorization: Bearer <token>

Body:
{
  "reason": "Approver on vacation"
}

Response:
{
  "success": true,
  "message": "Approver skipped successfully"
}

---

Add Approver at Level

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

Headers:
  Authorization: Bearer <token>

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
  }
}

---

🛡️ Permissions

Action	Who Can Do It
Skip Approver	✅ INITIATOR, ✅ APPROVER
Add Approver	✅ INITIATOR, ✅ APPROVER
View Skip Reason	✅ All participants

---

⚠️ Limitations

Limitation	Reason
Cannot skip approved levels	Data integrity
Cannot skip rejected levels	Already closed
Cannot skip already skipped levels	Already handled
Cannot skip future levels	Not yet active
Cannot add before completed levels	Would break workflow state
Must provide valid TAT (1-720h)	Business rules

---

📊 Dashboard Impact

Skipped Approvers in Reports:

-- Count skipped approvers
SELECT COUNT(*) 
FROM approval_levels 
WHERE is_skipped = TRUE;

-- Find requests with skipped levels
SELECT r.request_number, al.level_number, al.approver_name, al.skip_reason
FROM workflow_requests r
JOIN approval_levels al ON r.request_id = al.request_id
WHERE al.is_skipped = TRUE;

KPIs Affected:

• Avg Approval Time - Skipped levels excluded from calculation
• Approver Response Rate - Skipped marked separately
• Workflow Bottlenecks - Identify frequently skipped approvers

---

🔍 Troubleshooting

"Cannot skip approver - level is already APPROVED"

• The level has already been approved
• You cannot skip completed levels

"Cannot skip future approval levels"

• You're trying to skip a level that hasn't been reached yet
• Only current level can be skipped

"Cannot add approver at level X. Minimum allowed level is Y"

• You're trying to add before a completed level
• Must add after all approved/rejected/skipped levels

"User is already a participant in this request"

• The user is already an approver, initiator, or spectator
• Cannot add same user twice

---

✅ Testing Checklist

• Run database migration
• Restart backend server
• Create test workflow with 3 approvers
• Approve Level 1
• Skip Level 2 (test skip functionality)
• Verify Level 3 becomes active
• Add new approver at Level 3 (test add functionality)
• Verify levels shifted correctly
• Check activity log shows both actions
• Verify notifications sent correctly

---

Ready to use! 🎉