86 lines
5.0 KiB
Markdown
86 lines
5.0 KiB
Markdown
# Component: Notification Service
|
|
|
|
## Purpose
|
|
|
|
The Notification Service provides email notification capabilities to scripts running at site clusters. It manages notification lists, handles email delivery, and integrates with the Store-and-Forward Engine for reliable delivery when the email server is unavailable.
|
|
|
|
## Location
|
|
|
|
Central cluster (definition management, stores in config DB). Site clusters (email delivery, reads definitions from local SQLite).
|
|
|
|
## Responsibilities
|
|
|
|
### Definitions (Central)
|
|
- Store notification lists in the configuration database: list name, recipients (name + email address).
|
|
- Store email server configuration (SMTP settings).
|
|
- Deploy notification lists and SMTP configuration uniformly to all sites. Deployment requires **explicit action** by a user with the Deployment role.
|
|
- Managed by users with the Design role.
|
|
|
|
### Delivery (Site)
|
|
- Resolve notification list names to recipient lists from **local SQLite** (populated by artifact deployment). Sites do not access the central config DB.
|
|
- Compose and send emails via SMTP using locally stored SMTP configuration.
|
|
- On delivery failure, submit the notification to the Store-and-Forward Engine for buffered retry.
|
|
|
|
## Notification List Definition
|
|
|
|
Each notification list includes:
|
|
- **Name**: Unique identifier (e.g., "Maintenance-Team", "Shift-Supervisors").
|
|
- **Recipients**: One or more entries, each with:
|
|
- Recipient name.
|
|
- Email address.
|
|
|
|
## Email Server Configuration
|
|
|
|
The SMTP configuration is defined centrally and deployed to all sites. It includes:
|
|
|
|
- **Server hostname**: SMTP server address (e.g., `smtp.office365.com`).
|
|
- **Port**: SMTP port (e.g., 587 for StartTLS, 465 for SSL).
|
|
- **Authentication mode**: One of:
|
|
- **Basic Auth**: Username and password. For on-prem SMTP relays or servers that support basic authentication.
|
|
- **OAuth2 Client Credentials**: Tenant ID, Client ID, and Client Secret. For Microsoft 365 and other modern SMTP providers that require OAuth2. The Notification Service handles the token lifecycle internally (fetch, cache, refresh on expiry).
|
|
- **TLS mode**: None, StartTLS, or SSL.
|
|
- **From address**: The sender email address for all notifications (e.g., `scada-notifications@company.com`).
|
|
- **Connection timeout**: Maximum time to wait for SMTP connection (default: 30 seconds).
|
|
- **Max concurrent connections**: Maximum simultaneous SMTP connections per site (default: 5).
|
|
- **Retry settings**: Max retry count, fixed time between retries (used by Store-and-Forward Engine for transient failures).
|
|
|
|
## Script API
|
|
|
|
```csharp
|
|
Notify.To("listName").Send("subject", "message")
|
|
```
|
|
|
|
- Available to instance scripts (via Script Execution Actors), alarm on-trigger scripts (via Alarm Execution Actors), and shared scripts (executing inline).
|
|
- Resolves the list name to recipients, composes the email, and attempts delivery.
|
|
- The message body is **plain text** only. No HTML content.
|
|
|
|
## Email Delivery Behavior
|
|
|
|
### Recipient Handling
|
|
- A single email is sent per `Notify.To().Send()` call, with all list recipients in **BCC**. The from address is placed in the To field.
|
|
- Recipients do not see each other's email addresses.
|
|
- No per-recipient deduplication — if the same email address appears in multiple lists and a script sends to both, they receive multiple emails.
|
|
|
|
### Error Classification
|
|
Consistent with the External System Gateway pattern:
|
|
- **Transient failures** (connection refused, timeout, SMTP 4xx temporary errors): The notification is handed to the **Store-and-Forward Engine** for buffered retry per the SMTP configuration's retry settings. The script does **not** block waiting for eventual delivery.
|
|
- **Permanent failures** (SMTP 5xx permanent errors, e.g., mailbox not found): The error is returned **synchronously** to the calling script for handling. No retry — the notification will never deliver.
|
|
- This prevents the S&F buffer from accumulating notifications that will never succeed.
|
|
|
|
### No Rate Limiting
|
|
- No application-level rate limiting. If the SMTP server enforces sending limits (e.g., Microsoft 365 throttling), those manifest as transient failures and are handled naturally by store-and-forward.
|
|
|
|
## Dependencies
|
|
|
|
- **Configuration Database (MS SQL)**: Stores notification list definitions and SMTP config (central only).
|
|
- **Local SQLite**: At sites, notification lists, recipients, and SMTP configuration are read from local SQLite (populated by artifact deployment). Sites do not access the central config DB.
|
|
- **Store-and-Forward Engine**: Handles buffering for failed email deliveries.
|
|
- **Security & Auth**: Design role manages notification lists.
|
|
- **Configuration Database (via IAuditService)**: Notification list changes are audit logged.
|
|
|
|
## Interactions
|
|
|
|
- **Site Runtime (Script/Alarm Execution Actors)**: Scripts invoke `Notify.To().Send()` through this component.
|
|
- **Store-and-Forward Engine**: Failed notifications are buffered here.
|
|
- **Deployment Manager**: Receives updated notification lists and SMTP config as part of system-wide artifact deployment (triggered explicitly by Deployment role).
|