Notification Templates & Configuration
GrantFlow's notification system keeps stakeholders informed about critical access events — role activations, approval requests, account checkouts, and administrative changes. Configure which events trigger notifications, choose delivery channels, and customize message templates.
Overview
The notification system consists of three parts:
- Event Types — What triggers a notification (e.g., activation requested, approval needed)
- Channels — How notifications are delivered (email, in-app, Teams)
- Templates — What the notification message contains
Event Types
GrantFlow supports 19 notification event types grouped into four categories. Events marked System are routed to system recipients instead of deriving recipients from the event context.
Approval & Activation Events
| Event | Description | Recipients |
|---|---|---|
Approval.Requested | A user requested role activation requiring approval | Assigned approvers |
Activation.Succeeded | A role activation completed successfully | Requester |
Activation.Failed | A role activation failed | Requester |
Activation.Expired | A role activation reached its time limit | Requester |
Activation.Revoked | A role activation was manually revoked | Requester |
Role Lifecycle Events
| Event | Description | Recipients |
|---|---|---|
Role.Enabled | A role was enabled | Requester |
Role.Disabled | A role was disabled | Requester |
Role.RequestApproved | A role request was approved | Requester |
Role.RequestDenied | A role request was denied | Requester |
Role.NeedsApproval | A role request needs approval | Assigned approvers |
Account Events
| Event | Description | Recipients |
|---|---|---|
Account.Enabled | An account was enabled (checked out for use) | Requester |
Account.Disabled | An account was disabled (checked back in after use) | Requester |
Account.PasswordRollover | An account password was rotated | System recipients System |
System Events
System events alert administrators about infrastructure health and do not have a per-user recipient. They are delivered to the addresses listed in system recipients.
| Event | Description | Recipients |
|---|---|---|
Agent.Online | An on-premises agent connected | System recipients System |
Agent.Offline | An on-premises agent went offline | System recipients System |
Agent.CertExpiring | An agent certificate is approaching expiry | System recipients System |
Agent.RequiresUpdate | An agent is running an outdated version | System recipients System |
DirSync.Completed | A directory synchronization completed successfully | System recipients System |
DirSync.Failed | A directory synchronization failed | System recipients System |
System.Notification | Generic system notification (maintenance, announcements) | System recipients System |
System Recipients
System events (agent alerts, directory sync results, password rollovers, and generic system notifications) do not have a natural per-user recipient. Instead, they are delivered to the system recipients list you configure in the email channel settings.
Configuration:
- Navigate to Admin > Notification Configuration
- In the Email channel settings, find the System Recipients field
- Enter one or more email addresses — these addresses receive all system event notifications
- Save the configuration
If no system recipients are configured, system events are still logged in the Delivery Log but no email is sent.
Smart Event Debouncing
Short-lived connectivity interruptions — such as network blips, rolling updates, or brief host restarts — can produce rapid pairs of Agent.Offline and Agent.Online events. Without filtering, each pair would trigger two separate emails within seconds of each other.
GrantFlow automatically holds Agent.Offline notifications for a short window before sending. If the same agent reconnects within that window, both the offline and online notifications are silently suppressed. The result: you only receive an alert when an agent is genuinely unreachable, not when it bounces for a few seconds.
This behavior applies automatically — there is no configuration required. If the agent does not come back online within the hold window, the offline notification is delivered normally.
INFO
Debouncing only affects Agent.Offline / Agent.Online pairs. Agent.RequiresUpdate has its own throttling (see below). All other event types are delivered immediately.
Agent Update Notifications
When an on-premises agent connects with a version older than the latest published release, GrantFlow sends an Agent.RequiresUpdate notification to system recipients. This helps you keep agents current and ensures compatibility with new features and security patches.
Update notifications are throttled to once per 24 hours per agent — even if an agent reconnects multiple times during the day, administrators receive at most one reminder. The throttle resets automatically after 24 hours.
TIP
If you don't want update notifications, leave the agent releases URL unconfigured in your deployment. The feature is opt-in via the AGENT_RELEASES_URL environment variable on the control plane.
Channels
Email
Email is the primary notification channel. GrantFlow uses Microsoft Graph API to send emails from your tenant's configured sender mailbox.
Configuration:
- Navigate to Admin > Notification Configuration
- Select the Email channel
- Configure the sender mailbox and display name
- Add system recipients for agent, sync, and other system alerts
- Test the configuration with a test email
Teams (Coming Soon)
Microsoft Teams channel notifications via webhook connectors will be available in a future release.
In-App Notifications
In-app notifications appear in the GrantFlow notification bell. These are always enabled for the requesting user and cannot be disabled.
Templates
Template Editor
Each event type has a customizable email template. Navigate to Admin > Notification Templates to view and edit templates.
Templates support:
- Subject line — The email subject
- Body — HTML email body with placeholder support
- Rich text formatting — Bold, italic, links, lists
Placeholder Syntax
Use double curly braces to insert dynamic values:
| Placeholder | Description | Example Value |
|---|---|---|
{{.UserDisplayName}} | Name of the affected user | Jane Smith |
{{.UserEmail}} | Email of the affected user | jane@contoso.com |
{{.RoleName}} | Name of the role | Global Administrator |
{{.ConnectorName}} | Name of the connector | Contoso Entra ID |
{{.AccountName}} | Name of the account | admin-svc |
{{.Justification}} | Reason provided by requester | Monthly audit review |
{{.ActivationStart}} | Activation start time | 2025-01-15 09:00 UTC |
{{.ActivationEnd}} | Activation end time | 2025-01-15 17:00 UTC |
{{.Duration}} | Activation duration | 8 hours |
{{.ApproverName}} | Name of the approver | John Admin |
{{.TenantName}} | Your tenant display name | Contoso Corp |
{{.PortalUrl}} | Link to GrantFlow portal | https://app.grantflow.cloud |
{{.RequestId}} | Unique request identifier | req-abc123 |
{{.Timestamp}} | Event timestamp | 2025-01-15T09:00:00Z |
Agent Event Placeholders
These placeholders are available in Agent.Online, Agent.Offline, Agent.CertExpiring, and Agent.RequiresUpdate templates.
| Placeholder | Description | Example Value |
|---|---|---|
{{.AgentName}} | Agent identifier | agent-dc01 |
{{.DisplayName}} | Human-readable agent name | DC01 Domain Controller |
{{.ComputerName}} | Host machine name | DC01.contoso.local |
{{.ConnectorName}} | Associated connector | Contoso AD |
{{.PeerIP}} | Agent's IP address | 10.0.1.50 |
{{.ConnectedAt}} | Connection timestamp (online) | 2025-03-15T09:00:00Z |
{{.LastSeen}} | Last heartbeat timestamp (offline) | 2025-03-15T08:55:00Z |
{{.CurrentVersion}} | Agent's current version (update events) | v1.2.0 |
{{.LatestVersion}} | Latest available version (update events) | v1.3.1 |
Account Event Placeholders
These placeholders are available in Account.Enabled, Account.Disabled, and Account.PasswordRollover templates.
| Placeholder | Description | Example Value |
|---|---|---|
{{.AccountName}} | Account name | admin-svc |
{{.AccountUPN}} | Account User Principal Name | admin-svc@contoso.com |
{{.ConnectorName}} | Connector the account belongs to | Contoso AD |
{{.UserDisplayName}} | User who performed the action | Jane Smith |
{{.UserEmail}} | Email of the acting user | jane@contoso.com |
{{.EnabledBy}} | Who enabled the account (checkout) | Jane Smith |
{{.DisabledBy}} | Who disabled the account (check-in) | System |
{{.EnabledAt}} | Checkout timestamp | 2025-03-15T09:00:00Z |
{{.DisabledAt}} | Check-in timestamp | 2025-03-15T17:00:00Z |
{{.ExpiresAt}} | Checkout expiry (enabled events) | 2025-03-15T17:00:00Z |
{{.RotatedAt}} | Password rotation timestamp | 2025-03-15T17:01:00Z |
{{.Reason}} | Reason for disable/check-in | checkout expired |
Directory Sync Placeholders
These placeholders are available in DirSync.Completed and DirSync.Failed templates.
| Placeholder | Description | Example Value |
|---|---|---|
{{.ConnectorName}} | The connector that ran the sync | Contoso AD |
{{.SyncType}} | Sync mode | full or partial |
{{.UsersProcessed}} | Number of users synced | 142 |
{{.GroupsProcessed}} | Number of groups synced | 38 |
{{.Reason}} | Error reason (failed syncs only) | LDAP connection timeout |
Example Template
Subject: Role Activation Approved - {{.RoleName}}
Hi {{.UserDisplayName}},
Your request to activate **{{.RoleName}}** on **{{.ConnectorName}}**
has been approved by {{.ApproverName}}.
**Details:**
- Start: {{.ActivationStart}}
- End: {{.ActivationEnd}}
- Duration: {{.Duration}}
- Justification: {{.Justification}}
View in GrantFlow: {{.PortalUrl}}Reset to Default
If you have customized a template and want to revert, click Reset to Default on the template editor. This restores the original GrantFlow template for that event type.
Timezone Settings
Notification timestamps use the tenant's configured timezone by default. Users see times formatted according to their browser locale when viewing in-app notifications.
To configure the tenant timezone:
- Navigate to Admin > Tenant Settings
- Set the Display Timezone for email notifications
- All email timestamps will use this timezone
Best Practices
- Start with defaults — GrantFlow ships with sensible default templates. Only customize when you have specific branding or compliance requirements.
- Test after changes — Use the Send Test button after editing a template to verify formatting and placeholder resolution.
- Keep subjects concise — Email subjects should be scannable. Include the event type and key identifier (role name, account name).
- Include portal links — Always include the portal URL placeholder so recipients can take action directly.
- Review delivery logs — Monitor the Notification Delivery Log to verify notifications are being delivered.
Security Considerations
- Notification templates are tenant-scoped — changes only affect your tenant
- Email sending requires a configured Microsoft Graph mail permission
- Template placeholders are sanitized before rendering to prevent injection
- Delivery logs retain records for audit compliance
Troubleshooting
| Issue | Solution |
|---|---|
| Emails not sending | Verify email channel configuration and Graph API permissions |
| Placeholders showing raw text | Check placeholder syntax uses the correct double curly brace format |
| Wrong timezone in emails | Update tenant timezone in Admin > Tenant Settings |
| Missing notifications | Check event type is enabled in Notification Configuration |
| System events not delivered | Verify system recipients are configured in email channel settings |
| Template changes not applied | Templates are cached briefly — wait 1-2 minutes and retry |
See Also
- Notification Delivery Log — Monitor delivery status
- Audit Events — All auditable events reference
- Tenant Entra Setup — Configure Microsoft Graph permissions