Notification Rules

Overview

The Notification Rules module allows you to automate notification handling by creating custom rules that trigger specific actions based on conditions. Rules can automatically mark notifications as read, dismiss them, escalate their priority, forward them to email addresses, or trigger webhooks. This powerful automation system helps reduce notification fatigue, ensure critical alerts reach the right people, and streamline notification management workflows.

Accessing Notification Rules

Navigation path: Dashboard > Communication > Notifications > Rules

Required permission: notifications.view

Quick Access: Click on "Notification Rules" in the Communication sidebar menu

Key Features

• Multiple Trigger Types: Create rules based on notification type, level, keywords, or time conditions
• Multiple Action Types: Auto-read, auto-dismiss, escalate, forward email, or call webhooks
• Priority-Based Execution: Control rule execution order with priority levels (0-100)
• Active/Inactive Toggle: Enable or disable rules without deleting them
• Flexible Conditions: Use JSON configuration for complex trigger conditions
• Audit Trail: Track rule execution in system logs
• Real-Time Application: Rules apply immediately to new notifications
• Rule Management: Create, edit, delete, and toggle rules easily

Main Interface

Rules List View

The main page displays all notification rules in a card-based layout. Each rule card shows:

• Rule Name: Descriptive name for the rule
• Status Badge: Active (green) or Inactive (gray)
• Priority Badge: Priority level (0-100)
• Description: Optional explanation of what the rule does
• Trigger Type: What condition triggers the rule
• Action Type: What action the rule performs
• Created Date: When the rule was created (relative time)
• Action Buttons: Toggle, Edit, and Delete

Empty State

When no rules exist, you'll see:

• Large icon indicating no rules
• Message: "No notification rules yet"
• "Create Your First Rule" button

Trigger Types

1. Notification Type

Triggers when a notification matches specific types.

Use Cases:

• Auto-dismiss all system update notifications
• Forward backup failure notifications to operations team
• Auto-read user action notifications

Trigger Conditions Format:

{
  "types": ["backup_failed", "security_alert", "system_update", "user_action", "custom"]
}

Example:

{
  "types": ["system_update"]
}

2. Notification Level

Triggers when a notification matches specific priority levels.

Use Cases:

• Auto-dismiss all info-level notifications after hours
• Escalate warning notifications to error level
• Forward all critical notifications to security team

Trigger Conditions Format:

{
  "levels": ["info", "warning", "error", "critical"]
}

Example:

{
  "levels": ["info", "warning"]
}

3. Keyword Match

Triggers when notification title or message contains specific keywords.

Use Cases:

• Forward notifications containing "database" to database admin
• Auto-dismiss notifications containing "test" in development
• Escalate notifications containing "urgent" or "emergency"

Trigger Conditions Format:

{
  "keywords": ["keyword1", "keyword2", "keyword3"]
}

Example:

{
  "keywords": ["database", "connection", "timeout"]
}

Note: Keyword matching is case-insensitive and searches both title and message.

4. Time Based

Triggers based on time conditions (business hours, after hours, or always).

Use Cases:

• Auto-dismiss low-priority notifications after business hours
• Forward critical notifications to on-call team after hours
• Apply different rules during business hours vs. after hours

Trigger Conditions Format:

{
  "time_condition": "always|business_hours|after_hours"
}

Time Definitions:

• always: Rule applies 24/7
• business_hours: 9:00 AM - 5:00 PM (server timezone)
• after_hours: Before 9:00 AM or after 5:00 PM

Example:

{
  "time_condition": "after_hours"
}

Action Types

1. Auto Mark as Read

Automatically marks matching notifications as read.

Use Cases:

• Mark informational notifications as read automatically
• Auto-read notifications you've already seen via email
• Reduce unread notification count for routine alerts

Action Configuration Format:

{
  "delay_seconds": 0
}

Example:

{
  "delay_seconds": 300
}

Note: delay_seconds is optional and currently not implemented. Notifications are marked as read immediately.

2. Auto Dismiss

Automatically deletes matching notifications (only if dismissible).

Use Cases:

• Remove low-priority notifications automatically
• Clean up routine system update notifications
• Dismiss test notifications in development

Action Configuration Format:

{}

Example:

{}

Important: Only dismissible notifications can be auto-dismissed. Critical system notifications may not be dismissible.

3. Escalate Priority

Changes the notification level to a higher priority.

Use Cases:

• Escalate repeated backup failures to critical
• Upgrade warning notifications to error level
• Increase priority of notifications containing specific keywords

Action Configuration Format:

{
  "escalate_to": "info|warning|error|critical"
}

Example:

{
  "escalate_to": "critical"
}

4. Forward to Email

Sends matching notifications to specified email addresses.

Use Cases:

• Forward security alerts to security team
• Send backup failures to operations team
• Notify specific admins about critical issues

Action Configuration Format:

{
  "email_addresses": ["email1@example.com", "email2@example.com"]
}

Example:

{
  "email_addresses": ["security@example.com", "admin@example.com"]
}

Email Format:

• Subject: [{level}] {title}
• Body: Plain text with title and message

5. Trigger Webhook

Calls an external webhook URL with notification data.

Use Cases:

• Integrate with external monitoring systems
• Trigger automated responses in other systems
• Send notifications to Slack, Discord, or other services

Action Configuration Format:

{
  "webhook_url": "https://example.com/webhook"
}

Example:

{
  "webhook_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
}

Webhook Payload:

{
  "notification_id": 123,
  "type": "backup_failed",
  "level": "error",
  "title": "Backup Failed",
  "message": "Database backup failed to complete",
  "data": {},
  "created_at": "2024-01-15T10:30:00Z"
}

Common Tasks

Task 1: Creating a Notification Rule

1. Navigate to Dashboard > Communication > Notifications > Rules
2. Click Create Rule button in the top right
3. Fill in the rule details:
   • Rule Name: Descriptive name (e.g., "Auto-dismiss info notifications")
   • Description: Optional explanation of the rule's purpose
4. Configure the trigger:
   • Trigger Type: Select from dropdown
   • Trigger Conditions: Enter JSON configuration
5. Configure the action:
   • Action Type: Select from dropdown
   • Action Configuration: Enter JSON configuration
6. Set priority and status:
   • Priority: 0-100 (higher executes first)
   • Active: Toggle on to enable immediately
7. Click Create Rule

Expected result: Rule is created and appears in the rules list. It will apply to new notifications immediately if active.

Task 2: Auto-Dismissing Low-Priority Notifications

Scenario: Automatically dismiss info-level notifications after business hours.

1. Navigate to Dashboard > Communication > Notifications > Rules
2. Click Create Rule
3. Enter rule details:
   • Name: "Auto-dismiss info notifications after hours"
   • Description: "Automatically dismiss informational notifications outside business hours"
4. Configure trigger:
   • Trigger Type: "Time Based"
   • Trigger Conditions:

     {
       "time_condition": "after_hours"
     }
     

5. Configure action:
   • Action Type: "Auto Dismiss"
   • Action Configuration: {}
6. Set Priority: 50
7. Ensure Active is checked
8. Click Create Rule

Result: Info notifications created after 5 PM or before 9 AM will be automatically dismissed.

Task 3: Forwarding Critical Alerts to Team

Scenario: Forward all critical security alerts to the security team.

1. Navigate to Dashboard > Communication > Notifications > Rules
2. Click Create Rule
3. Enter rule details:
   • Name: "Forward critical security alerts"
   • Description: "Send critical security notifications to security team"
4. Configure trigger:
   • Trigger Type: "Notification Type"
   • Trigger Conditions:

     {
       "types": ["security_alert"]
     }
     

5. Configure action:
   • Action Type: "Forward to Email"
   • Action Configuration:

     {
       "email_addresses": ["security@example.com", "admin@example.com"]
     }
     

6. Set Priority: 90 (high priority)
7. Ensure Active is checked
8. Click Create Rule

Result: All security alert notifications will be forwarded to the specified email addresses.

Task 4: Escalating Repeated Failures

Scenario: Escalate backup failure notifications to critical level.

1. Navigate to Dashboard > Communication > Notifications > Rules
2. Click Create Rule
3. Enter rule details:
   • Name: "Escalate backup failures"
   • Description: "Upgrade backup failure notifications to critical priority"
4. Configure trigger:
   • Trigger Type: "Notification Type"
   • Trigger Conditions:

     {
       "types": ["backup_failed"]
     }
     

5. Configure action:
   • Action Type: "Escalate Priority"
   • Action Configuration:

     {
       "escalate_to": "critical"
     }
     

6. Set Priority: 80
7. Ensure Active is checked
8. Click Create Rule

Result: Backup failure notifications will be escalated to critical level.

Task 5: Keyword-Based Webhook Trigger

Scenario: Trigger a webhook when notifications contain "database" keyword.

1. Navigate to Dashboard > Communication > Notifications > Rules
2. Click Create Rule
3. Enter rule details:
   • Name: "Database alert webhook"
   • Description: "Trigger webhook for database-related notifications"
4. Configure trigger:
   • Trigger Type: "Keyword Match"
   • Trigger Conditions:

     {
       "keywords": ["database", "db", "connection"]
     }
     

5. Configure action:
   • Action Type: "Trigger Webhook"
   • Action Configuration:

     {
       "webhook_url": "https://your-monitoring-system.com/webhook"
     }
     

6. Set Priority: 70
7. Ensure Active is checked
8. Click Create Rule

Result: Notifications containing database-related keywords will trigger the webhook.

Task 6: Editing a Rule

1. Navigate to Dashboard > Communication > Notifications > Rules
2. Locate the rule you want to edit
3. Click the Edit icon (pencil) on the right side
4. Modify any fields as needed
5. Click Update Rule

Expected result: Rule is updated and changes apply to new notifications immediately.

Task 7: Toggling Rule Status

1. Navigate to Dashboard > Communication > Notifications > Rules
2. Locate the rule you want to enable/disable
3. Click the Power icon on the right side
4. The page refreshes with updated status

Expected result:

• Active rules show green "Active" badge and apply to notifications
• Inactive rules show gray "Inactive" badge and don't apply to notifications

Task 8: Deleting a Rule

1. Navigate to Dashboard > Communication > Notifications > Rules
2. Locate the rule you want to delete
3. Click the Trash icon on the right side
4. Confirm deletion in the popup dialog
5. The page refreshes with the rule removed

Expected result: Rule is permanently deleted and no longer applies to notifications.

Warning: This action cannot be undone.

Rule Priority and Execution

Priority Levels

• Range: 0-100
• Default: 0
• Execution Order: Higher priority rules execute first
• Use Cases:
  • High priority (80-100): Critical rules that must execute first
  • Medium priority (40-79): Standard automation rules
  • Low priority (0-39): Cleanup and maintenance rules

Execution Behavior

1. When a notification is created, all active rules are evaluated
2. Rules are sorted by priority (highest first)
3. Each rule checks if its trigger conditions match the notification
4. If a rule matches, its action is executed
5. Multiple rules can match and execute for the same notification
6. Rule execution is logged for audit purposes

Example Priority Strategy

Priority 100: Forward critical security alerts to team
Priority 90:  Escalate backup failures to critical
Priority 80:  Trigger webhooks for database issues
Priority 50:  Auto-read routine notifications
Priority 10:  Auto-dismiss info notifications after hours

Settings and Options

Rule Properties

Name (Required)

• Type: Text (max 255 characters)
• Description: Descriptive name for the rule
• Example: "Auto-dismiss info notifications"

Description (Optional)

• Type: Text (multiline)
• Description: Detailed explanation of the rule's purpose
• Example: "Automatically dismiss informational notifications outside business hours to reduce clutter"

Trigger Type (Required)

• Type: Select dropdown
• Options: notification_type, notification_level, keyword, time_based
• Description: What condition triggers the rule

Trigger Conditions (Required)

• Type: JSON object
• Description: Configuration for the trigger type
• Validation: Must be valid JSON

Action Type (Required)

• Type: Select dropdown
• Options: auto_read, auto_dismiss, escalate, forward_email, webhook
• Description: What action to perform when triggered

Action Configuration (Required)

• Type: JSON object
• Description: Configuration for the action type
• Validation: Must be valid JSON

Priority (Optional)

• Type: Number (0-100)
• Default: 0
• Description: Execution order (higher executes first)

Active (Optional)

• Type: Boolean toggle
• Default: true
• Description: Whether the rule is currently active

Permissions

The following permissions control access to Notification Rules:

• notifications.view: Required to access the rules page and view rules
• notifications.create: Required to create new rules (typically granted with view permission)
• notifications.update: Required to edit rules and toggle status
• notifications.delete: Required to delete rules

Note: Rule management is typically restricted to administrators with full notification permissions.

Tips and Best Practices

• Start simple: Begin with basic rules and add complexity as needed
• Use descriptive names: Make rule names clear and self-explanatory
• Document your rules: Use the description field to explain why the rule exists
• Test thoroughly: Create test notifications to verify rules work as expected
• Set appropriate priorities: Ensure critical rules execute before cleanup rules
• Monitor rule execution: Check logs to verify rules are working correctly
• Don't over-automate: Keep some manual control for important notifications
• Use time-based rules carefully: Consider timezone implications
• Combine trigger types: Use multiple rules for complex scenarios
• Review regularly: Periodically review and update rules as needs change
• Disable instead of delete: Toggle rules inactive rather than deleting them
• Coordinate with team: Ensure team members know about automated rules
• Test webhooks: Verify webhook URLs are correct and accessible
• Validate JSON: Use a JSON validator to check configuration syntax
• Consider email volume: Be cautious with forward_email actions to avoid spam

Troubleshooting

Problem: Rule not triggering

Solution:

• Verify the rule is Active (green badge)
• Check trigger conditions match the notification
• Ensure JSON syntax is valid in trigger conditions
• Review notification type, level, and content
• Check if higher priority rules are preventing execution
• Verify the notification was created after the rule
• Review system logs for rule execution errors
• Test with a simple rule to isolate the issue

Problem: JSON syntax errors

Solution:

• Use a JSON validator (jsonlint.com) to check syntax
• Ensure all quotes are double quotes (")
• Check for missing commas or brackets
• Remove trailing commas
• Verify array and object syntax
• Copy examples from documentation
• Use a JSON formatter for readability

Problem: Webhook not being called

Solution:

• Verify webhook URL is correct and accessible
• Check if the webhook endpoint is online
• Review webhook configuration JSON syntax
• Ensure the rule is active and matching notifications
• Check system logs for webhook errors
• Test webhook URL with curl or Postman
• Verify firewall isn't blocking outbound requests
• Check if webhook requires authentication

Problem: Email forwarding not working

Solution:

• Verify email addresses are correct in action configuration
• Check mail configuration is working (test with custom notification)
• Ensure email addresses are in an array format
• Review system logs for email delivery errors
• Check spam folders for forwarded emails
• Verify mail queue is processing
• Ensure SMTP settings are correct
• Test with a single email address first

Problem: Multiple rules conflicting

Solution:

• Review rule priorities and execution order
• Check if rules have overlapping trigger conditions
• Adjust priorities to control execution order
• Disable conflicting rules temporarily
• Combine rules if they serve similar purposes
• Use more specific trigger conditions
• Review system logs to see which rules executed
• Test rules individually to identify conflicts

Problem: Rule executing too frequently

Solution:

• Review trigger conditions to make them more specific
• Add additional conditions to narrow matching
• Use keyword triggers instead of type triggers
• Combine with time-based conditions
• Increase priority to execute before other rules
• Consider if multiple notifications are being created
• Review notification creation logic
• Add rate limiting (future enhancement)

Problem: Cannot create or edit rules

Solution:

• Verify you have notifications.create or notifications.update permission
• Check JSON syntax in trigger and action configurations
• Ensure all required fields are filled
• Try refreshing the page
• Clear browser cache
• Check browser console for JavaScript errors
• Verify CSRF token is valid
• Contact an administrator if permissions are missing

Problem: Auto-dismiss not working

Solution:

• Verify the notification is dismissible (check is_dismissible property)
• Ensure action type is set to "auto_dismiss"
• Check action configuration is valid JSON (can be empty {})
• Verify rule is active and matching the notification
• Review system logs for errors
• Test with a dismissible notification
• Check if notification was already dismissed by another rule

Related Modules

• Notifications: View and manage all notifications
• Notification Preferences: Configure personal notification preferences
• Custom Notifications: Create and send custom notifications
• Audit Logs: Track rule execution and changes
• Mail Configuration: Configure email delivery for forward_email actions