Custom Notifications

Overview

The Custom Notifications module allows administrators to create and send custom notifications to users. Unlike system-generated notifications that are triggered automatically by events, custom notifications give you full control over the content, timing, and audience. This powerful feature is ideal for announcements, maintenance alerts, feature updates, policy changes, and emergency communications. You can target all users, specific users, or role-based groups, and schedule notifications for future delivery.

Accessing Custom Notifications

Navigation path: Dashboard > Communication > Notifications > Custom

Required permission: notifications.view, notifications.create

Quick Access: Click on "Custom Notifications" in the Communication sidebar menu

Key Features

• Rich Content Creation: Create notifications with custom titles, messages, and priority levels
• Flexible Targeting: Send to all users, specific users, or role-based groups
• Scheduled Delivery: Schedule notifications for future delivery or save as drafts
• Draft System: Prepare notifications in advance without sending them immediately
• Status Tracking: Monitor notification status (draft, scheduled, sent)
• Duplicate Functionality: Quickly create similar notifications by duplicating existing ones
• Expiration Dates: Set automatic expiration times for time-sensitive notifications
• Dismissible Control: Choose whether users can dismiss the notification
• Send Now Option: Override scheduled time and send immediately
• Internal Organization: Use internal names and descriptions for team reference

Main Interface

Custom Notifications List

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

• Internal Name: Descriptive name for internal reference
• Status Badge: Draft (gray), Scheduled (blue), or Sent (green)
• Level Badge: Info (blue), Warning (yellow), Error (red), or Critical (purple)
• Description: Optional explanation of the notification's purpose
• Content Preview: Title and truncated message in a preview box
• Target Information: Who will receive the notification (all users, specific users, or role-based)
• Scheduling Info: Scheduled send time (if applicable)
• Sent Info: When the notification was sent (if applicable)
• Action Buttons: Send Now, Duplicate, Edit, and Delete

Empty State

When no custom notifications exist, you'll see:

• Large bullhorn icon
• Message: "No custom notifications yet"
• "Create Your First Notification" button

Notification Levels

Info (Blue)

• Use for: General information, updates, tips, feature announcements
• Visual: Blue badge and blue background in emails
• Priority: Low
• Example: "New feature available: Dark mode is now enabled"

Warning (Yellow)

• Use for: Important notices requiring attention, upcoming changes
• Visual: Yellow badge and yellow background in emails
• Priority: Medium
• Example: "Scheduled maintenance in 24 hours"

Error (Red)

• Use for: Issues that need to be addressed, service disruptions
• Visual: Red badge and red background in emails
• Priority: High
• Example: "Service temporarily unavailable"

Critical (Purple)

• Use for: Urgent issues requiring immediate action, security alerts
• Visual: Purple badge and dark red background in emails
• Priority: Highest
• Example: "Security update required immediately"

Target Types

All Users

Sends the notification to every user in the system.

Target Configuration:

{}

Use Cases:

• System-wide announcements
• Maintenance notifications
• Feature launches
• Policy updates

Example: "The system will be down for maintenance on Saturday from 2-4 AM"

Specific Users

Sends the notification to selected users by their user IDs.

Target Configuration:

{
  "user_ids": [1, 2, 3, 15, 42]
}

Use Cases:

• Personal messages to specific administrators
• Beta feature access notifications
• Account-specific alerts
• VIP user communications

Example: "You've been granted access to the new analytics dashboard"

Role Based

Sends the notification to all users with specific roles.

Target Configuration:

{
  "roles": ["admin", "moderator", "editor"]
}

Use Cases:

• Role-specific training announcements
• Permission changes affecting specific roles
• Feature access by role
• Team-specific communications

Example: "New moderation tools available for moderators and admins"

Notification Status

Draft

• Notification is saved but not sent
• Can be edited and modified
• Not visible to users
• Can be sent immediately or scheduled

Scheduled

• Notification is scheduled for future delivery
• Will be sent automatically at the scheduled time
• Can be sent immediately by clicking "Send Now"
• Can be edited before scheduled time

Sent

• Notification has been delivered to target users
• Cannot be edited or resent
• Can be duplicated to create a similar notification
• Shows sent timestamp and recipient count

Common Tasks

Task 1: Creating a Custom Notification

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Click Create Notification button in the top right
3. Fill in the basic information:
   • Internal Name: Descriptive name for your reference (e.g., "System Maintenance Alert")
   • Description: Optional explanation of the notification's purpose
4. Configure the notification content:
   • Level: Select info, warning, error, or critical
   • Title: The title users will see (e.g., "Scheduled Maintenance")
   • Message: The full message users will see
5. Configure the target audience:
   • Target Type: Select all users, specific users, or role based
   • Target Configuration: Enter JSON configuration based on target type
6. Set additional options:
   • Scheduled Send Time: Leave empty for draft, or set future date/time
   • Expiration Time: Optional auto-dismiss time
   • Allow users to dismiss: Toggle on/off (default: on)
7. Click Create Notification

Expected result: Notification is created with draft or scheduled status and appears in the list.

Task 2: Sending a System-Wide Announcement

Scenario: Announce a new feature to all users.

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Click Create Notification
3. Enter basic information:
   • Internal Name: "Dark Mode Feature Launch"
   • Description: "Announce new dark mode feature to all users"
4. Configure content:
   • Level: Info
   • Title: "New Feature: Dark Mode"
   • Message: "We're excited to announce that dark mode is now available! You can toggle it in your profile settings. Enjoy a more comfortable viewing experience in low-light environments."
5. Configure target:
   • Target Type: All Users
   • Target Configuration: {}
6. Leave Scheduled Send Time empty (will save as draft)
7. Ensure Allow users to dismiss is checked
8. Click Create Notification
9. Back on the list page, click Send Now (paper plane icon)
10. Confirm sending

Result: All users receive the notification immediately.

Task 3: Scheduling a Maintenance Alert

Scenario: Notify users about upcoming maintenance 24 hours in advance.

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Click Create Notification
3. Enter basic information:
   • Internal Name: "Weekend Maintenance Alert"
   • Description: "Notify users 24 hours before scheduled maintenance"
4. Configure content:
   • Level: Warning
   • Title: "Scheduled Maintenance"
   • Message: "The system will be unavailable on Saturday, January 20th from 2:00 AM to 4:00 AM EST for scheduled maintenance. Please save your work and plan accordingly. We apologize for any inconvenience."
5. Configure target:
   • Target Type: All Users
   • Target Configuration: {}
6. Set Scheduled Send Time: January 19th at 2:00 AM (24 hours before maintenance)
7. Set Expiration Time: January 20th at 4:00 AM (when maintenance ends)
8. Ensure Allow users to dismiss is checked
9. Click Create Notification

Result: Notification is scheduled and will be sent automatically at the specified time.

Task 4: Sending Role-Specific Notifications

Scenario: Notify administrators about new admin features.

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Click Create Notification
3. Enter basic information:
   • Internal Name: "New Admin Tools"
   • Description: "Announce new admin dashboard features"
4. Configure content:
   • Level: Info
   • Title: "New Admin Dashboard Features"
   • Message: "We've added new analytics and reporting tools to the admin dashboard. Check out the new 'Analytics' section in the sidebar to explore enhanced data visualization and export capabilities."
5. Configure target:
   • Target Type: Role Based
   • Target Configuration: {"roles": ["admin", "super-admin"]}
6. Leave Scheduled Send Time empty
7. Click Create Notification
8. Click Send Now to deliver immediately

Result: Only users with admin or super-admin roles receive the notification.

Task 5: Creating an Emergency Alert

Scenario: Send a critical security alert immediately.

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Click Create Notification
3. Enter basic information:
   • Internal Name: "Security Update Required"
   • Description: "Critical security patch notification"
4. Configure content:
   • Level: Critical
   • Title: "🔴 Security Update Required"
   • Message: "A critical security update is available. Please log out and log back in within the next hour to apply the update. This is required for all users to maintain system security."
5. Configure target:
   • Target Type: All Users
   • Target Configuration: {}
6. Leave Scheduled Send Time empty
7. Set Expiration Time: 2 hours from now
8. Uncheck "Allow users to dismiss" (force visibility)
9. Click Create Notification
10. Click Send Now immediately

Result: All users receive a critical notification that cannot be dismissed until expiration.

Task 6: Duplicating a Notification

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Locate the notification you want to duplicate
3. Click the Copy icon (duplicate button)
4. The page refreshes with a new notification created
5. The duplicate has "(Copy)" appended to the name
6. The duplicate is saved as a draft
7. Click Edit to modify the duplicated notification
8. Make your changes and save

Use case: Quickly create similar notifications for recurring announcements or different user groups.

Task 7: Editing a Draft or Scheduled Notification

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Locate the notification with "Draft" or "Scheduled" status
3. Click the Edit icon (pencil button)
4. Modify any fields as needed
5. Click Update Notification

Expected result: Changes are saved and the notification remains in its current status.

Note: Sent notifications cannot be edited. Duplicate them instead if you need to send a similar notification.

Task 8: Sending a Scheduled Notification Immediately

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Locate the scheduled notification
3. Click the Send Now icon (paper plane button)
4. Confirm sending in the popup dialog
5. Wait for confirmation message showing recipient count

Expected result: Notification is sent immediately regardless of scheduled time, and status changes to "Sent".

Task 9: Deleting a Notification

1. Navigate to Dashboard > Communication > Notifications > Custom
2. Locate the notification you want to delete
3. Click the Trash icon (delete button)
4. Confirm deletion in the popup dialog
5. The page refreshes with the notification removed

Warning: This action cannot be undone. Deleting a sent notification removes the custom notification record but does not remove notifications already delivered to users.

Settings and Options

Internal Name (Required)

• Type: Text (max 255 characters)
• Description: Name for internal reference only, not visible to users
• Example: "Monthly Newsletter - January 2024"
• Best Practice: Use descriptive names that indicate purpose and timing

Description (Optional)

• Type: Multiline text
• Description: Detailed explanation for team reference
• Example: "Monthly newsletter sent to all active users on the first Monday of each month"
• Best Practice: Document the purpose, audience, and any special considerations

Level (Required)

• Type: Select dropdown
• Options: info, warning, error, critical
• Description: Priority level affecting visual appearance and user attention
• Default: info
• Best Practice: Use critical sparingly to maintain its impact

Title (Required)

• Type: Text (max 255 characters)
• Description: Notification title visible to users
• Example: "New Feature Available"
• Best Practice: Keep concise and action-oriented

Message (Required)

• Type: Multiline text
• Description: Full notification message visible to users
• Example: "We've added a new dark mode feature. Toggle it in your profile settings."
• Best Practice: Be clear, concise, and include any necessary actions

Target Type (Required)

• Type: Select dropdown
• Options: all_users, specific_users, role_based
• Description: Determines who receives the notification
• Default: all_users

Target Configuration (Required)

• Type: JSON object
• Description: Configuration for the selected target type
• Validation: Must be valid JSON
• Examples:
  • All users: {}
  • Specific users: {"user_ids": [1, 2, 3]}
  • Role based: {"roles": ["admin", "moderator"]}

Scheduled Send Time (Optional)

• Type: Datetime picker
• Description: When to automatically send the notification
• Format: YYYY-MM-DD HH:MM
• Behavior: If empty, notification is saved as draft
• Best Practice: Schedule during low-traffic hours for system announcements

Expiration Time (Optional)

• Type: Datetime picker
• Description: When the notification should automatically expire and be dismissed
• Format: YYYY-MM-DD HH:MM
• Use Cases: Time-sensitive alerts, event reminders, temporary notices

Allow Users to Dismiss (Optional)

• Type: Boolean toggle
• Default: true (checked)
• Description: Whether users can manually dismiss the notification
• Best Practice: Disable only for critical notifications that require acknowledgment

Permissions

The following permissions control access to Custom Notifications:

• notifications.view: Required to access the custom notifications page and view notifications
• notifications.create: Required to create new custom notifications
• notifications.update: Required to edit draft and scheduled notifications
• notifications.delete: Required to delete custom notifications

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

Tips and Best Practices

• Plan ahead: Use the draft system to prepare notifications in advance
• Test with yourself: Create a specific_users notification targeting only your account to test content
• Use descriptive internal names: Make it easy for team members to understand notification purpose
• Schedule wisely: Send non-urgent notifications during business hours
• Consider timezones: Remember that scheduled times use server timezone
• Keep messages concise: Users are more likely to read shorter notifications
• Use appropriate levels: Don't overuse critical level or it loses impact
• Include actions: Tell users what they should do in response to the notification
• Set expiration dates: Remove time-sensitive notifications automatically
• Duplicate for efficiency: Reuse successful notification templates
• Document in description: Explain why the notification was created for future reference
• Coordinate with team: Ensure multiple admins aren't sending conflicting notifications
• Monitor delivery: Check that scheduled notifications are sent successfully
• Archive old notifications: Delete sent notifications that are no longer relevant
• Use role-based targeting: Segment communications for better relevance

Troubleshooting

Problem: Cannot create custom notification

Solution:

• Verify you have notifications.create permission
• Check that all required fields are filled
• Validate JSON syntax in target configuration
• Ensure target_config matches the selected target_type
• Try refreshing the page and attempting again
• Check browser console for JavaScript errors
• Clear browser cache and cookies
• Contact an administrator if permissions are missing

Problem: JSON syntax error in target configuration

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
• Copy examples from documentation
• For all users, use empty object: {}
• For specific users: {"user_ids": [1, 2, 3]}
• For role based: {"roles": ["admin"]}

Problem: Scheduled notification not sending

Solution:

• Verify the scheduled time is in the future when creating
• Check that the notification status is "Scheduled" not "Draft"
• Ensure the scheduled task/cron job is running
• Review system logs for errors
• Verify server timezone matches your expectations
• Check if the notification was manually sent before scheduled time
• Contact system administrator to verify task scheduler is working

Problem: Notification sent to wrong users

Solution:

• Review target_type and target_config before sending
• Verify user IDs are correct in specific_users configuration
• Check that role names match exactly in role_based configuration
• Test with a small group first (specific_users with your account)
• Duplicate and modify if you need to resend to correct audience
• Document target configuration in description field for future reference

Problem: Cannot edit notification

Solution:

• Check notification status - only draft and scheduled can be edited
• Sent notifications cannot be edited (duplicate instead)
• Verify you have notifications.update permission
• Try refreshing the page
• Check if another admin is editing the same notification
• Contact an administrator if you need to modify a sent notification

Problem: Users not receiving notifications

Solution:

• Verify notification was actually sent (check status is "Sent")
• Check that target users exist and are active
• Ensure users have notifications.view permission
• Verify notification preferences aren't blocking custom notifications
• Check if notification rules are auto-dismissing the notifications
• Review system logs for delivery errors
• Ask users to refresh their page or check the Notifications page
• Verify the notification hasn't expired

Problem: Cannot delete notification

Solution:

• Verify you have notifications.delete permission
• Confirm deletion in the popup dialog
• Try refreshing the page
• Check browser console for errors
• Ensure you're not trying to delete while another admin is editing
• Contact an administrator if permissions are missing

Problem: Duplicate button not working

Solution:

• Refresh the page and try again
• Check browser console for JavaScript errors
• Verify you have notifications.create permission
• Clear browser cache
• Try a different browser
• Check if you've reached any notification limits

Problem: Expiration not working

Solution:

• Verify expiration time is in the future when creating
• Check that the expiration task/cron job is running
• Ensure server timezone is configured correctly
• Review system logs for errors
• Verify the notification was actually delivered to users
• Contact system administrator to verify task scheduler

Related Modules

• Notifications: View all notifications including custom ones
• Notification Preferences: Configure how users receive custom notifications
• Notification Rules: Set up automatic actions for custom notifications
• Audit Logs: Track who created and sent custom notifications
• Users: Manage users who receive notifications
• Roles: Manage roles for role-based targeting