NotificationManager

NotificationManager

Overview

The NotificationManager class is responsible for managing notification templates and delivering multi-channel notifications (email, in-app, SMS) across the platform. It combines template management with notification delivery capabilities in a single Rio class.

General Purpose:

Manage notification templates with multi-channel configurations
Send notifications via email, in-app, and SMS channels
Support templated content with dynamic parameter substitution
Integrate with workflow and approval systems for template changes
Provide centralized notification orchestration for the platform

Architecture Pattern:

Instance-based class where each instance represents a notification template
instanceId = templateId (e.g., OTP_PROGRAM_MANAGEMENT_INVITE)
Templates are stored in both Rio state and MongoDB for efficient querying

Data Structure

State Schema

interface NotificationManagerState {
    private: {
        template: NotificationTemplateData
    }
    public: {}
}

interface NotificationTemplateData {
    templateId: string
    title: string
    description: string
    status: NotificationTemplateStatus
    channels: Record<NotificationChannel, NotificationChannelContent>
}

Enums and Types

enum NotificationChannel {
    EMAIL = 'email',
    IN_APP = 'in_app',
    SMS = 'sms'
}

enum NotificationTemplateStatus {
    ACTIVE = 'active',
    INACTIVE = 'inactive'
}

enum NotificationTemplateEvents {
    TEMPLATE_UPDATE = 'template_update',
    CHANNEL_UPDATE = 'channel_update',
    STATUS_UPDATE = 'status_update'
}

Channel Content Structures

Each notification channel has its own content structure:

Email Channel:

{
    channel: NotificationChannel.EMAIL,
    enabled: boolean,
    to: string[],           // Default recipient emails
    subject: string,        // Email subject template
    json: string,          // JSON email template
    html: string           // HTML email template
}

In-App Channel:

{
    channel: NotificationChannel.IN_APP,
    enabled: boolean,
    subject: string,        // Notification title
    content: string,        // Notification content template
    metadata?: Record<string, any>  // Optional metadata
}

SMS Channel:

{
    channel: NotificationChannel.SMS,
    enabled: boolean,
    content: string,        // SMS message template
    to?: string[]          // Optional default phone numbers
}

Core Functionality

Template Management

Template Creation: Initialize notification templates with default configurations
Template Updates: Modify template title, description, and metadata
Channel Configuration: Update individual channel settings (email, in-app, SMS)
Status Management: Activate or deactivate templates
MongoDB Sync: Templates are automatically synced to MongoDB for efficient querying

Multi-Channel Notification Delivery

The sendNotification method orchestrates notification delivery across configured channels:

Template Retrieval: Gets template from instance state (instanceId = templateId)
Status Check: Only sends if template status is ACTIVE
Channel Processing:
- Email: Renders HTML/JSON templates and sends via AWS SES
- In-App: Creates tasks to add notifications to UserNotification instances
- SMS: (Future implementation)
Template Rendering: Supports dynamic parameter substitution using {{parameter}} syntax

Workflow Integration

NotificationManager extends WorkflowCompatibleStateManager and integrates with the approval system:

Events: TEMPLATE_UPDATE, CHANNEL_UPDATE, STATUS_UPDATE
Approval Integration: Template changes can require approval based on workflow rules
Status Transitions: Workflow rules control status changes (active ↔ inactive)

API Methods

Notification Delivery

sendNotification (READ) - Send notification via configured channels
- Permission: All ClassIdentities (internal service method)
- instanceId: Template ID (e.g., OTP_PROGRAM_MANAGEMENT_INVITE)
- Input: { to: string[], parameters: Record<string, any> }
- Returns: 204 No Content on success

Template Management Methods

updateNotificationTemplate (WRITE) - Update template title and description
- Permission: program_management_user
- Input: { title?: string, description?: string }
- Workflow: Triggers TEMPLATE_UPDATE event
updateNotificationChannel (WRITE) - Update channel configuration
- Permission: program_management_user
- Input: { channel: NotificationChannel, content: NotificationChannelContent }
- Workflow: Triggers CHANNEL_UPDATE event
updateNotificationTemplateStatus (WRITE) - Change template status
- Permission: program_management_user
- Input: { status: NotificationTemplateStatus }
- Workflow: Triggers STATUS_UPDATE event
approve (WRITE) - Approve template changes (internal)
- Permission: ApprovalManager
- Input: CommonApprovalInput with optional JSON patch

Template Retrieval

getNotificationTemplate (READ) - Get template details
- Permission: program_management_user, NotificationManager (for internal calls)
- Returns: Template object
listNotificationTemplates (STATIC) - List all templates with pagination
- Permission: program_management_user
- Input: { page?: number, limit?: number, status?: NotificationTemplateStatus, search?: string }
- Returns: Paginated list of templates from MongoDB

Key Features

Multi-Channel Support
- Email delivery via AWS SES
- In-app notifications via UserNotification class
- SMS support (placeholder for future implementation)
Template Rendering
- Dynamic parameter substitution using {{parameter}} syntax
- Separate templates for each channel
- Fallback to template title for missing subjects
Flexible Recipient Management
- Runtime recipients (passed in to parameter)
- Default recipients (configured in channel settings)
- Automatic merging of both recipient lists
Approval & Workflow
- All template changes can be routed through approval workflow
- JSON patch support for granular approvals
- Event-driven architecture for status transitions
MongoDB Integration
- Templates automatically streamed to MongoDB
- Efficient querying and search capabilities
- Pagination support for large template lists

Integration Guide

Sending Notifications from Other Classes

Use the createNotificationTask utility function:

import { createNotificationTask } from '../NotificationManager/util/notification.task'
import { NotificationTemplateIds } from 'common/common.models'

// In your method handler (async function)
await createNotificationTask(
    NotificationTemplateIds.Values.OTP_PROGRAM_MANAGEMENT_INVITE,
    {
        to: ['user@example.com'],
        parameters: {
            otp: '123456',
            userName: 'John Doe',
        },
    },
)

Auto-Initialization:
The utility automatically initializes notification templates on first use. If the template instance doesn't exist, it will:

Create the template with default settings
Retry sending the notification
Subsequent calls will send immediately

Important Notes:

The function is async - always use await
No need to pass data.tasks - uses direct RDK method calls
Template is auto-created if missing (404 error handling)
All parameters must be strings (for template rendering)

Template Parameter Examples

Templates use {{parameterName}} syntax for substitution:

Email Template:

<h1>Welcome {{userName}}!</h1>
<p>Your OTP code is: <strong>{{otp}}</strong></p>

Parameters:

{
    userName: 'John Doe',
    otp: '123456'
}

Rendered Output:

<h1>Welcome John Doe!</h1>
<p>Your OTP code is: <strong>123456</strong></p>

Template Defaults

Template defaults are defined in constants/template.defaults.ts:

OTP_PROGRAM_MANAGEMENT_INVITE
OTP_PROGRAM_MANAGEMENT_LOGIN
OTP_PROGRAM_MANAGEMENT_PASSWORD_RESET
SSO_USER_INTIVATION_PROGRAM_MANAGEMENT

Each template must be initialized with a title and description before use.

Keyboard shortcuts

Platinum