Skip to main content

Notifications System

TestPlanIt includes a comprehensive notification system that keeps users informed about important events and activities. This document covers how notifications work, user preferences, and email templates.

Overview​

The notification system consists of:

  1. In-app notifications - Displayed within the TestPlanIt interface
  2. Email notifications - Sent to users based on their preferences
  3. Notification preferences - User-configurable settings
  4. Background processing - Asynchronous job queue for reliable delivery

Notification Types​

TestPlanIt currently supports the following notification types:

  • Work Assigned - When a test case or exploratory testing session is assigned to you
  • Comment Mentions - When someone mentions you in a comment (@username)
  • System Announcements - Important system-wide announcements and updates
  • Milestone Due Reminder - When a milestone's due date is approaching or overdue

Notification Center UI​

Accessing Notifications​

The notification center is accessible from the bell icon in the top navigation bar:

  1. Bell Icon: Located in the header, next to your user menu
  2. Badge Counter: Shows unread notification count (displays "9+" for more than 9 unread)
  3. Visual Indicator: Red badge appears when you have unread notifications
  4. Click to Open: Click the bell icon to open the notification dropdown panel

Notification Panel​

The notification panel displays when you click the bell icon:

Panel Features:

  • Width: Fixed at 400px for comfortable reading
  • Height: Scrollable area showing up to 20 most recent notifications
  • Live updates: New notifications appear within ~1 second via a server-pushed event stream — no polling
  • Focus refresh: Automatically refreshes when you return to the browser tab

Panel Header:

  • Title: "Notifications" with bell icon
  • Mark All Read Button: Quickly mark all notifications as read
    • Disabled when no unread notifications
    • Click to mark all as read at once
  • Delete All Button: Remove all notifications at once
    • Disabled when no notifications exist
    • Displays a confirmation dialog before deleting
    • Soft-deletes all notifications (they will no longer appear in the panel)

Notification Items​

Each notification in the list displays:

Visual Indicators:

  • Unread: Light blue/primary background color
  • System Announcements: Special blue background color
  • Read: Standard background (muted)
  • Hover effect: Background changes on mouse hover

Notification Content:

  • Title/Summary: Bold heading describing the notification
  • Details: Description with links to relevant items
  • Timestamp: When the notification was created (formatted per your preferences)
  • Actionable Links: Click on project, test case, or user names to navigate

Interaction Behavior:

  • Auto-mark as Read: Hover over an unread notification for 1 second to mark it as read automatically
  • Click through: Click on any link within the notification to navigate to that item
  • Context Menu: Three-dot menu for additional actions

Notification Actions​

Each notification has a context menu (three-dot icon) with the following actions:

Mark as Read/Unread:

  • Toggle read status manually
  • Option changes based on current state
  • Useful for re-reading important notifications

Delete Notification:

  • Permanently remove the notification
  • Cannot be undone
  • Keeps your notification list clean

Empty State​

When you have no notifications, the panel displays:

  • Empty message: "No notifications"
  • Centered text: Muted, centered in the scrollable area
  • Clean appearance: Encourages checking back later

Real-time Features​

Automatic Updates:

  • Server-pushed updates: When you sign in, the bell opens a long-lived Server-Sent Events (SSE) connection to TestPlanIt. New notifications arrive within ~1 second of being created — no polling, no refresh required.
  • Auto-reconnect: If the connection drops (network blip, server restart, deploy), the browser automatically reconnects and re-syncs missed notifications.
  • Window focus: When you return to the tab, the panel refreshes immediately as a safety net for anything that might have been missed during a long sleep/suspend.
  • URL parameter: Can open notifications automatically with ?openNotifications=true.

Badge Counter:

  • Updates in real-time as notifications arrive
  • Shows unread count accurately
  • Caps display at "9+" for readability
Operator note

For SSE to work behind a load balancer, the ingress / reverse proxy must allow long-lived streamed responses (no buffering, idle timeouts ≥ 1 hour). See SSE Notifications and Live Updates for nginx-ingress, Traefik, AWS LBC, and plain nginx configuration recipes plus the tuning environment variables. The same ingress recipe also covers the project-scoped issue-update stream that powers live updates from inbound webhooks.

Notification Details by Type​

Work Assigned Notifications​

Single Assignment:

  • Shows who assigned the work
  • Links to the specific test case
  • Displays the test run name
  • Shows project context
  • Direct link with ?selectedCase= parameter for easy access

Bulk Assignment:

  • Indicates multiple test cases assigned
  • Shows count of assigned items
  • Groups by test run
  • Lists each test run with case count
  • Provides links to each test run

Comment Mention Notifications​

When someone mentions you with @username:

  • Shows who mentioned you
  • Displays the comment preview
  • Links to the commented item (test case, run, or session)
  • Includes project context
  • Direct navigation to the comment

If you are mentioned in a project you do not have access to, the notification is redacted: the message names the project and who mentioned you, but does not name the specific item or include a clickable link. This protects the project's contents while still letting you know that someone tried to loop you in.

System Announcement Notifications​

Special Formatting:

  • Distinctive blue background color
  • Megaphone icon indicator
  • System-wide importance
  • Usually from administrators
  • May include rich formatting

Content Types:

  • Maintenance notices
  • Feature announcements
  • System updates
  • Policy changes
  • Important deadlines

Milestone Due Reminder Notifications​

When a milestone's due date is approaching or has passed, notifications are automatically sent to all users who have participated in the milestone's work.

Recipients Include:

  • Milestone creator
  • Test run creators for runs in the milestone
  • Users assigned to test cases
  • Users who have executed test results
  • Session creators for sessions in the milestone
  • Users assigned to sessions

Notification Variants:

  • Due Soon: Sent when the milestone is within the configured notification window (e.g., 5 days before due date)
  • Overdue: Sent when the milestone's due date has passed

Features:

  • Each user receives only one notification per milestone per day (deduplicated)
  • Notifications link directly to the milestone details page
  • Processing occurs daily at 6:00 AM server time
  • Overdue notifications continue until the milestone is marked complete

Enabling Milestone Notifications:

  1. Navigate to the milestone details page
  2. Set a due date for the milestone
  3. Enable the "Notify days before due date" toggle
  4. Configure how many days before the due date to start notifications

For more details, see Milestone Details - Due Date Notifications.

User Preferences​

Notification Modes​

Users can configure their notification preferences with these modes:

  1. In-App Only (IN_APP) - Notifications appear only in the application
  2. In-App + Immediate Email (IN_APP_EMAIL_IMMEDIATE) - Get both in-app and immediate email notifications
  3. In-App + Daily Digest (IN_APP_EMAIL_DAILY) - In-app notifications plus a daily email summary at 8 AM
  4. None (NONE) - No notifications (not recommended)
  5. Use Global Settings (USE_GLOBAL) - Follow system-wide default settings

Configuring Preferences​

Users can manage their notification preferences in their profile:

  1. Navigate to your user profile
  2. Click on "Notification Preferences"
  3. Select your preferred notification mode
  4. Save changes

Email Templates​

TestPlanIt uses Handlebars templates for all email notifications, providing consistent, professional formatting.

Template Structure​

lib/email/
├── template-service.ts      # Template rendering engine
├── notificationTemplates.ts # Email sending functions
├── templates/
│   ├── layouts/
│   │   └── main.hbs        # Base email layout
│   ├── partials/           # Reusable components
│   ├── notification.hbs    # Single notification
│   └── daily-digest.hbs    # Daily summary

Available Templates​

Single Notification Email​

Sent immediately when events occur (if user has immediate email mode):

  • Clean, focused design
  • Direct link to the relevant item
  • Unsubscribe/preference links

Daily Digest Email​

Sent at 8 AM daily containing all unread notifications:

  • Summary of all notifications from the past 24 hours
  • Grouped by type and priority
  • Single email reduces inbox clutter

Email Configuration​

Configure email settings in your .env file:

EMAIL_SERVER_HOST=smtp.example.com
EMAIL_SERVER_PORT=587
[email protected]
EMAIL_SERVER_PASSWORD=your-password
[email protected]

Architecture​

Components​

  1. Notification Worker (workers/notificationWorker.ts)

    • Processes notification creation jobs
    • Determines user preferences
    • Queues email jobs when needed
    • After creating each Notification row, publishes a small {id, event} wake-up payload to a tenant-scoped Valkey channel so live SSE subscribers refetch immediately

  2. SSE Stream Route (app/api/notifications/stream/route.ts)

    • Serves the long-lived text/event-stream connection that the bell consumes
    • Subscribes per-connection to the user's Valkey channel and the tenant broadcast channel
    • Treats wake-up payloads as opaque "something changed" signals; the bell re-fetches through the policy-enforced ZenStack hook so multi-tenant isolation and access control are re-applied on every read
    • Enforces per-user (4) and per-tenant (1000, default) connection caps and a 25-second heartbeat for proxy-friendly liveness

  3. Email Worker (workers/emailWorker.ts)

    • Sends actual emails
    • Handles retries and failures
    • Processes both immediate and digest emails

  4. Scheduler (scheduler.ts)

    • Sets up cron jobs for daily digests
    • Runs at 8 AM daily

  5. Queue System (BullMQ + Valkey)

    • Ensures reliable delivery
    • Handles retries automatically
    • Prevents duplicate notifications
    • The same Valkey is reused for the SSE pub/sub fan-out — channels are namespaced by tenant prefix, no separate Valkey deployment needed

Flow Diagram​

Event Occurs → Create Notification Job → Notification Worker
                                              ↓
                                    Check User Preferences
                                              ↓
                        ┌─────────────────────┼─────────────────────┐
                        ↓                     ↓                     ↓
                   IN_APP Only         EMAIL_IMMEDIATE         EMAIL_DAILY
                        ↓                     ↓                     ↓
                 Store in DB          Queue Email Job      Store for Digest
                        ↓                     ↓
              Publish to Valkey         Email Worker
                  (wake-up)                   ↓
                        ↓               Send Email
              SSE Route relays
                        ↓
              Bell refetches → Badge updates

For ingress / proxy configuration required to run SSE reliably behind a load balancer, see SSE Notifications and Live Updates. The same page covers the project-scoped issue-update stream used by inbound webhooks.

Global Settings​

Administrators can configure system-wide defaults:

  1. Navigate to Admin → Notification Settings
  2. Set the default notification mode
  3. Configure email sending limits
  4. Manage notification types

Best Practices​

For Users​

  • Choose a notification mode that matches your workflow
  • Daily digest is recommended for most users
  • Check in-app notifications regularly
  • Keep your email address up to date

For Administrators​

  • Set reasonable global defaults
  • Monitor email sending rates
  • Ensure Valkey has sufficient memory
  • Configure SMTP settings properly
  • Test email delivery regularly

Troubleshooting​

Notifications Not Appearing​

  1. Check your notification preferences
  2. Ensure you haven't selected "None"
  3. Verify your email address is correct
  4. Check spam/junk folders

Bell does not update in real time​

If new notifications only appear after a manual page refresh, the SSE event stream is not reaching the browser. This is almost always an ingress / reverse-proxy configuration issue, not an application bug.

  1. In the browser DevTools Network tab, filter for stream. There should be one long-lived /api/notifications/stream request with status 200 and Content-Type: text/event-stream.
  2. If the request returns 401, the user is not signed in (expected on the sign-in page).
  3. If the request closes after a few seconds, the proxy is buffering the response or applying a short idle timeout. See SSE Notifications for nginx-ingress, Traefik, AWS LBC, and plain nginx fixes.
  4. Server logs include a sse.connections.active JSON line every 30 seconds per tenant — if that line is missing, no connections are reaching the route.

Emails Not Sending​

  1. Verify SMTP configuration in .env
  2. Check email worker logs: docker logs testplanit-workers
  3. Ensure Valkey is running
  4. Verify network connectivity to SMTP server

Daily Digest Issues​

  1. Check scheduler is running: docker exec testplanit-workers pm2 list
  2. Verify cron job is scheduled
  3. Check timezone settings
  4. Review worker logs for errors

Development​

Adding New Notification Types​

  1. Add the type to the notification enum in schema
  2. Create handler in the appropriate service
  3. Queue notification job when event occurs
  4. Update email templates if needed

Creating New Email Templates​

  1. Create template file in lib/email/templates/
  2. Use Handlebars syntax
  3. Include common variables (userName, appUrl, etc.)
  4. Test with different email clients

Example template:

<h2>{{title}}</h2>
<p>Hi {{userName}},</p>
<p>{{message}}</p>
<a href='{{actionUrl}}' class='button'>{{actionText}}</a>

Testing Notifications​

  1. Use development environment with MailHog
  2. Configure test SMTP settings
  3. Trigger events to generate notifications
  4. Verify email rendering and delivery

Security Considerations​

  • Never include sensitive data in notifications
  • Use secure SMTP connections (TLS/SSL)
  • Implement rate limiting for email sending
  • Validate email addresses before sending
  • Include unsubscribe links in all emails
  • Log notification activity for audit purposes