SendNotificationToGroupCommand

Category: Communication Commands
Permission: bnk_send_group_notification
Resilient: ✅ Yes (Offline users receive it on next connection)

Send a real-time SignalR notification to a group of back-office users resolved by role IDs, permission codes, or both — with an optional branch filter.

---

Overview

SendNotificationToGroupCommand resolves recipients from the user management database and dispatches a SendNotificationCommand with target="users". Online users receive the notification instantly via SignalR; offline users receive it when they next connect.

Recipient Resolution Order

1. If roleIds provided → include all users in those roles
2. If permissionCodes provided → resolve roles that carry any of those permissions, include their users
3. Union both sets (duplicates removed)
4. If branchIds provided → keep only users in those branches

At least one of roleIds or permissionCodes must be supplied.

---

When to Use

✅ Use For:	❌ Don't Use For:
Real-time alerts to approvers	Bulk announcements that need delivery guarantees (use SendMailToGroupCommand)
Live process status updates to a team	Customer-facing notifications
Dashboard nudges to branch staff	Long-term archival messages

---

Parameters

Recipient Selection (at least one required)

Parameter	Type	Description
permissionCodes	string[]	Users whose role includes ANY of these permission codes
roleIds	long[]	Users directly assigned to any of these role IDs

Optional Filters

Parameter	Type	Description
branchIds	long[]	When provided, restricts recipients to users in those branches

Notification Content

Parameter	Type	Default	Description
title	string	required	Notification heading
message	string	required	Notification body
notificationType	string	"info"	"info" | "success" | "warning" | "error"
priority	string	"normal"	"high" | "normal" | "low"
action	string	—	Client-side route / action identifier
data	object	—	Arbitrary payload passed to the client
expirationMinutes	int	1440	How long the notification lives (default: 24 hours)

Response

{
  "isSuccessful": true,
  "statusCode": "00",
  "message": "Notification sent to 5 recipient(s).",
  "data": {
    "recipientCount": 5,
    "recipientUserIds": ["12", "15", "23", "31", "44"]
  }
}

---

Examples

By Permission Code (all branches)

doCmd('SendNotificationToGroupCommand', {
  Data: {
    permissionCodes: ['bnk_approve_loan'],
    title: 'New Loan Pending Approval',
    message: 'A loan application requires your review.',
    notificationType: 'info',
    priority: 'high',
    action: '/loans/pending'
  }
});

By Role ID

doCmd('SendNotificationToGroupCommand', {
  Data: {
    roleIds: [5, 7],
    title: 'System Alert',
    message: 'Scheduled maintenance starts in 30 minutes.',
    notificationType: 'warning'
  }
});

Combined — Roles + Permissions + Branch Filter

doCmd('SendNotificationToGroupCommand', {
  Data: {
    permissionCodes: ['bnk_approve_loan'],
    roleIds: [12],
    branchIds: [3, 8],
    title: 'Urgent: Approval Required',
    message: 'Loan #' + context.loanReference + ' is pending your action.',
    priority: 'high',
    action: '/loans/' + context.loanId,
    data: {
      loanId: context.loanId,
      applicant: context.applicantName
    }
  }
});

With Custom Data Payload

doCmd('SendNotificationToGroupCommand', {
  Data: {
    permissionCodes: ['bnk_manage_fraud_alerts'],
    title: 'Fraud Alert',
    message: 'Suspicious activity detected on account ' + context.accountNumber,
    notificationType: 'error',
    priority: 'high',
    action: '/fraud/alerts',
    data: {
      accountNumber: context.accountNumber,
      alertId: context.alertId,
      riskScore: context.riskScore
    },
    expirationMinutes: 120
  }
});

---

Comparison with SendMailToGroupCommand

	SendMailToGroupCommand	SendNotificationToGroupCommand
Delivery channel	Email	SignalR (in-app)
Offline delivery	Yes (email always arrives)	Yes (queued, delivered on reconnect)
Immediate for online users	No	Yes (sub-second)
Supports templates	Yes (templateId)	No
Permission	bnk_send_group_mail	bnk_send_group_notification

Tip: Use both together for critical workflows — send a notification for immediate visibility and an email as a persistent record.

---

Notes

• If no users are found matching the criteria, the command returns isSuccessful: true with recipientCount: 0 — it is not treated as an error.
• Both the legacy RolePermission table and the newer DirectPermissions system are checked when resolving permission codes.
• Notification delivery and offline queuing are handled by the underlying SendNotificationCommand.