Notification Scenario Template
Data Entity
Description
Configurable rule templates that define which platform events trigger notifications, which delivery channels are used, message templates with variable placeholders, and which user roles receive alerts. Provides the scenario rule engine backing the Notification Scenarios feature.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Primary key | PKrequiredunique |
organization_id |
uuid |
FK to organizations — tenant scope. NULL for system-default templates shared across all orgs. | - |
scenario_key |
string |
Machine-readable event key identifying the scenario, e.g. 'assignment.received', 'expense.approved', 'certification.expiring'. Unique per organization (or globally for system defaults). | required |
name |
string |
Human-readable display name for the scenario shown in the admin UI. | required |
description |
text |
Explanation of when this scenario fires and what it communicates. | - |
trigger_event |
string |
Dot-notation platform event that activates this scenario, e.g. 'activity.created', 'assignment.dispatched', 'expense.status_changed', 'certification.expiry_approaching'. Consumed by scenario-event-evaluator. | required |
trigger_conditions |
json |
Optional filter conditions that must be satisfied for the trigger to fire, e.g. {"expense.amount_gte": 1000, "role": "coordinator"}. NULL means always fire on trigger_event. | - |
channels |
json |
Array of enabled delivery channels for this scenario, e.g. ["push", "email", "sms"]. At least one channel required when is_active is true. | required |
target_roles |
json |
Array of role strings that receive this notification, e.g. ["peer_mentor", "coordinator"]. Empty array means no recipients (effectively disabled). | required |
push_title_template |
string |
Push notification title with {{variable}} placeholders, e.g. 'New assignment from {{coordinator_name}}'. | - |
push_body_template |
text |
Push notification body with {{variable}} placeholders. | - |
email_subject_template |
string |
Email subject line with {{variable}} placeholders. | - |
email_body_template |
text |
HTML or plain-text email body template with {{variable}} placeholders. Processed by email-template-engine. | - |
sms_template |
string |
Short SMS text with {{variable}} placeholders. Max 160 chars after variable substitution recommended. | - |
available_variables |
json |
Declared list of variables available for substitution in templates, e.g. [{"key":"coordinator_name","description":"Full name of coordinator"},{"key":"activity_date","description":"ISO date of the activity"}]. Used for admin UI hints and validation. | - |
priority |
enum |
Delivery priority affecting push notification prominence and email queue position. | required |
cooldown_minutes |
integer |
Minimum minutes between repeated firings of this scenario for the same recipient. 0 means no cooldown. Prevents notification spam for high-frequency events. | required |
is_active |
boolean |
Whether this scenario is currently enabled. Inactive scenarios are evaluated by scenario-event-evaluator but produce no notifications. | required |
is_system_default |
boolean |
True for platform-shipped baseline templates that cannot be deleted by org admins. Org admins may deactivate or override templates but not remove system defaults. | required |
is_user_configurable |
boolean |
Whether users can suppress this scenario via their notification_settings. Some critical scenarios (e.g. security alerts) bypass user preferences. | required |
created_at |
datetime |
Row creation timestamp. | required |
updated_at |
datetime |
Last modification timestamp. | required |
created_by |
uuid |
FK to users — who created or last seeded this template. NULL for system-seeded defaults. | - |
Database Indexes
idx_nst_organization_id
Columns: organization_id
idx_nst_scenario_key_org
Columns: scenario_key, organization_id
idx_nst_trigger_event
Columns: trigger_event
idx_nst_is_active
Columns: is_active
idx_nst_trigger_event_active
Columns: trigger_event, is_active
Validation Rules
scenario_key_format
error
Validation failed
channels_valid_values
error
Validation failed
target_roles_valid_values
error
Validation failed
template_variables_declared
warning
Validation failed
channel_template_present
error
Validation failed
cooldown_non_negative
error
Validation failed
Business Rules
tenant_isolation
Templates with a non-null organization_id are visible only to that organization. System defaults (organization_id IS NULL) are readable by all tenants but writable only by global admins.
system_default_no_delete
Templates where is_system_default=true cannot be deleted. Org admins may deactivate them (is_active=false) or create an org-scoped override with the same scenario_key, but the system record must persist.
org_override_takes_precedence
When scenario-event-evaluator resolves a scenario_key for a tenant, an org-scoped template (organization_id = tenant) takes precedence over the system default with the same key. The system default is used only when no org override exists.
at_least_one_channel_when_active
An active template (is_active=true) must have at least one entry in the channels array. Saving an active template with an empty channels array is rejected.
cooldown_deduplication
Before dispatching, notification-event-bus checks whether a notification for this scenario_id and recipient was created within the last cooldown_minutes. If so, the notification is suppressed.
non_configurable_bypasses_user_settings
When is_user_configurable=false, notification-event-bus ignores the recipient's notification_settings preference for this scenario and delivers unconditionally (used for security and compliance alerts).