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 and in-app; approvers can also receive Teams approval cards)
- 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.
To set the list, go to Admin → Notifications → Templates, click Channel Settings, and open the Email tab. With email notifications enabled, enter up to 10 comma-separated addresses in System Notification Recipients and save. These addresses receive every system event notification.
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 sends email through Microsoft Graph from a sender mailbox that is configured at the service level, not per tenant, so you don't set up a sender address or grant any mail permission in your own tenant.
Your tenant's email settings live under Admin → Notifications → Templates: click Channel Settings and open the Email tab. There you turn email notifications on or off and set:
- Timezone — the IANA time zone (for example
Europe/Vienna) used for timestamps in notification emails; empty means UTC - Recipient Override — an optional address that receives every notification instead of the event's recipients, useful for testing
- System Notification Recipients — the addresses that receive agent, sync, and other system events
To check a template's output, save it and use Send Test in the template editor, which sends the template to an address you choose with sample data.
INFO
The Email section on Admin → Notifications → Channels is a placeholder for upcoming sender settings and has no options yet. Use the Channel Settings dialog on the Templates tab instead.
Microsoft Teams
GrantFlow reaches Microsoft Teams through the GrantFlow Teams app. When an activation request needs approval, the app sends each approver a Teams approval card in a 1:1 Teams chat, where they approve or deny the request directly. The card updates as the request moves on. You turn approval cards on, and download the GrantFlow Teams app package, under Admin → Notifications → Channels. See Teams Approval Cards Setup for the full rollout.
Approval cards are the only notifications GrantFlow sends to Teams; the notifications on this page are delivered by email, and approvers still receive the approval request email alongside the card. Approval cards have a fixed layout and do not use the email templates below.
INFO
The Teams Webhook tab in the channel settings under Admin → Notifications → Templates is being retired. Teams incoming webhooks are not a supported delivery channel; use Teams approval cards instead.
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 → Notifications → 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://portal.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
Timestamps in notification emails use the Timezone set on the Email tab of Channel Settings under Admin → Notifications → Templates. Enter an IANA time zone name such as America/New_York; when the field is empty, emails use UTC. Users see times formatted according to their browser locale when viewing in-app notifications.
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 is sent through Microsoft Graph from GrantFlow's service-level sender; no mail permission is needed in your tenant
- Template placeholders are sanitized before rendering to prevent injection
- Delivery logs retain records for audit compliance
Troubleshooting
| Issue | Solution |
|---|---|
| Emails not sending | Check that email notifications are enabled in Channel Settings and look for errors in the Delivery Log |
| Placeholders showing raw text | Check placeholder syntax uses the correct double curly brace format |
| Wrong timezone in emails | Set the Timezone on the Email tab of Channel Settings |
| Missing notifications | Check that the template for the event type is enabled; disabled templates show as skipped in the Delivery Log |
| System events not delivered | Verify system recipients are configured on the Email tab of 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