# Notification Triggers Documentation

This document lists all notification triggers in the Royal Enfield Workflow Management System.

---

## Overview

The system sends push notifications to users based on various workflow events. Notifications are sent via the `notificationService.sendToUsers()` method and support web push notifications.

---

## 1. Workflow Service Notifications

**File:** `src/services/workflow.service.ts`

| # | Trigger Event | Recipient | Title | Body | Priority |
|---|---------------|-----------|-------|------|----------|
| 1 | New approver added to request | New Approver | "New Request Assignment" | "You have been added as an approver to request {requestNumber}: {title}" | DEFAULT |
| 2 | Approver skipped → Next approver notified | Next Approver | "Request Escalated" | "Previous approver was skipped. Request {requestNumber} is now awaiting your approval." | DEFAULT |
| 3 | New approver added at specific level | New Approver | "New Request Assignment" | "You have been added as Level {X} approver to request {requestNumber}: {title}" | DEFAULT |
| 4 | Spectator added to request | Spectator | "Added to Request" | "You have been added as a spectator to request {requestNumber}: {title}" | DEFAULT |
| 5 | Request submitted by initiator | Initiator | "Request Submitted Successfully" | "Your request '{title}' has been submitted and is now with the first approver." | MEDIUM |
| 6 | Request submitted → First approver assigned | First Approver | "New Request Assigned" | "{title}" | HIGH |

---

## 2. Approval Service Notifications

**File:** `src/services/approval.service.ts`

| # | Trigger Event | Recipient | Title | Body | Priority |
|---|---------------|-----------|-------|------|----------|
| 7 | Final approval complete (closure pending) | Initiator | "Request Approved - Closure Pending" | "Your request '{title}' has been fully approved. Please review and finalize the conclusion remark to close the request." | HIGH |
| 8 | Final approval complete (info only) | All Participants | "Request Approved" | "Request '{title}' has been fully approved. The initiator will finalize the conclusion remark to close the request." | MEDIUM |
| 9 | Level approved → Next level activated | Next Approver | "Action required: {requestNumber}" | "{title}" | DEFAULT |
| 10 | Request fully approved (auto-close) | Initiator | "Approved: {requestNumber}" | "{title}" | DEFAULT |
| 11 | Request rejected | Initiator + All Participants | "Rejected: {requestNumber}" | "{title}" | DEFAULT |

---

## 3. Pause Service Notifications

**File:** `src/services/pause.service.ts`

| # | Trigger Event | Recipient | Title | Body | Priority |
|---|---------------|-----------|-------|------|----------|
| 12 | Workflow paused by approver | Initiator | "Workflow Paused" | "Your request '{title}' has been paused by {userName}. Reason: {reason}. Will resume on {date}." | HIGH |
| 13 | Workflow paused (confirmation) | Approver (self) | "Workflow Paused Successfully" | "You have paused request '{title}'. It will automatically resume on {date}." | MEDIUM |
| 14 | Workflow resumed | Initiator | "Workflow Resumed" | "Your request '{title}' has been resumed {by user/automatically}." | HIGH |
| 15 | Workflow resumed | Approver | "Workflow Resumed" | "Request '{title}' has been resumed. Please continue with your review." | HIGH |
| 16 | Initiator requests pause cancellation | Approver who paused | "Pause Retrigger Request" | "{initiatorName} is requesting you to cancel the pause and resume work on request '{title}'." | HIGH |

---

## 4. TAT (Turnaround Time) Notifications

**File:** `src/queues/tatProcessor.ts`

| # | Trigger Event | Recipient | Title | Body | Priority |
|---|---------------|-----------|-------|------|----------|
| 17 | TAT 50% threshold reached | Approver | "TAT Reminder" | "50% TAT Alert: {message}" | MEDIUM |
| 18 | TAT 75% threshold reached | Approver | "TAT Reminder" | "75% TAT Alert: {message}" | HIGH |
| 19 | TAT 100% breach | Approver | "TAT Breach Alert" | "TAT Breached: {message}" | URGENT |
| 20 | TAT breach (initiator notification) | Initiator | "TAT Breach - Request Delayed" | "Your request {requestNumber}: '{title}' has exceeded its TAT. The approver has been notified." | HIGH |

---

## 5. Work Note Notifications

**File:** `src/services/worknote.service.ts`

| # | Trigger Event | Recipient | Title | Body | Priority |
|---|---------------|-----------|-------|------|----------|
| 21 | User mentioned in work note | Mentioned Users | "💬 Mentioned in Work Note" | "{userName} mentioned you in {requestNumber}: '{message preview}'" | DEFAULT |

---

## Summary by Recipient

### Initiator Receives:
- ✅ Request submitted confirmation
- ✅ Approval pending closure (action required)
- ✅ Request approved
- ✅ Request rejected
- ✅ Workflow paused
- ✅ Workflow resumed
- ✅ TAT breach notification

### Approver Receives:
- ✅ New request assignment
- ✅ Request escalation (previous approver skipped)
- ✅ Action required (next level activated)
- ✅ Workflow paused confirmation
- ✅ Workflow resumed
- ✅ Pause retrigger request from initiator
- ✅ TAT 50% reminder
- ✅ TAT 75% reminder
- ✅ TAT 100% breach alert

### Spectator/Participant Receives:
- ✅ Added to request
- ✅ Request approved (info only)
- ✅ Request rejected

### Mentioned Users Receive:
- ✅ Work note mention notification

---

## Notification Payload Structure

```typescript
interface NotificationPayload {
  title: string;           // Notification title
  body: string;            // Notification message
  requestId?: string;      // UUID of the request
  requestNumber?: string;  // Human-readable request number (e.g., REQ-2025-11-0001)
  url?: string;            // Deep link URL (e.g., /request/REQ-2025-11-0001)
  type?: string;           // Notification type for categorization
  priority?: 'LOW' | 'MEDIUM' | 'HIGH' | 'URGENT';
  actionRequired?: boolean; // Whether user action is required
}
```

---

## Priority Levels

| Priority | Use Case |
|----------|----------|
| **URGENT** | TAT breach alerts |
| **HIGH** | Action required notifications, assignments, resumptions |
| **MEDIUM** | Informational updates, confirmations |
| **LOW/DEFAULT** | General updates, spectator notifications |

---

## Configuration

Notifications can be enabled/disabled via environment variables:

```env
ENABLE_EMAIL_NOTIFICATIONS=true
ENABLE_PUSH_NOTIFICATIONS=true
```

Web push requires VAPID keys:

```env
VAPID_PUBLIC_KEY=your_public_key
VAPID_PRIVATE_KEY=your_private_key
VAPID_SUBJECT=mailto:admin@example.com
```

---

*Last Updated: November 2025*