Skip to content
English
Customer portal
Contact us
  • There are no suggestions because the search field is empty.

05.07 Customizing Email Templates

The Notification Extra ships with editable email templates for risk events (new risk, update, mitigation, review, close, comment), audit events, and document events. Customize the subject and body via a WYSIWYG editor; insert pre-defined variables (, , etc.) for dynamic content.

Requires: Notification Extra

Email template management, the WYSIWYG editor, the variable-substitution engine, and the trigger functions for sending notifications all live in the Notification Extra at simplerisk/extras/notification/. Without the Extra activated, SimpleRisk has no in-app email-template surface; the only emails produced are the password-reset and similar core auth flows that use hardcoded templates.

Why this matters

The default notifications work — a new risk goes in, the risk owner gets an email saying "A new risk has been submitted." Most programs eventually want them better. The default subject lines are functional but not branded; the body text is generic; the call-to-action ("Click here to review") doesn't tell the recipient what they're being asked to do beyond clicking. Email is also where SimpleRisk meets the user outside the application; for many stakeholders (executives, occasional reviewers), the email is the entire SimpleRisk experience for weeks at a time. Investing in the templates pays back in stakeholder engagement.

The honest scope to know up front: the templates control wording, not behavior. You can change "A new risk has been submitted" to "A new risk awaits your review (please assess by [date])," but you can't change when the email fires (that's the trigger logic in the Notification Extra) or who receives it (that's the per-event recipient logic). For different timing or different recipients, the path is operational discipline (changing how risks get assigned) or potentially custom development.

The other thing worth knowing: variable substitution is via a specific syntax. The Notification Extra uses HTML-span-based variables (e.g., a span with class="variable" data-id="risk.subject" becomes the risk's subject when the email is rendered). The WYSIWYG editor exposes a variable picker; using it produces the right markup. Don't try to type the variable syntax manually — the editor handles the markup, and a typo becomes a literal string in the sent email.

The third thing: the Notification Extra and email-server configuration are separate. The Extra controls templates and triggers; the SMTP server, sender address, and authentication settings are configured separately (typically under Configure → Settings → Email or via the dedicated email-config UI). For an email to actually send, both have to be configured: the SMTP gateway and the template that defines what to send.

Before you start

Have these in hand:

  • Admin access to Configure → Notification (the Notification Extra's admin page).
  • A working SMTP configuration. Without it, templates are well-defined but emails don't go anywhere. See Email and the Notification Extra for SMTP setup.
  • A clear list of which templates to customize. The Notification Extra ships with templates for ~20 events; you don't have to customize all of them. Start with the high-volume ones (new risk, mitigation, review) where the template wording matters most.
  • Brand and tone guidance for the program's external communications. Email templates are a brand surface; consistent voice across the program's emails matters for recipient trust.
  • A test inbox you control to receive sample notifications during template development. Don't iterate templates against real users' inboxes.

Step-by-step

1. Activate the Notification Extra

Sidebar: Configure → Extras → Notification Extra → Activate. The activation creates the email-template tables and registers the notification trigger functions. If already active, skip.

2. Confirm SMTP is configured

Without working SMTP, no email goes out regardless of how good the templates are. Confirm via:

  1. Configure → Settings → Email (or the equivalent SMTP configuration page).
  2. The required values: SMTP host, port, encryption (TLS/SSL), username, password, sender address.
  3. Most installs use a dedicated SMTP service (SendGrid, Mailgun, AWS SES, the corporate Exchange / Office 365 with appropriate auth) rather than the local PHP mail() function — production-grade delivery requires the dedicated service.
  4. Use the Send Test Email button (or equivalent) to verify the configuration end-to-end before customizing templates.

If the test email doesn't arrive, fix SMTP first. See Email and the Notification Extra for the configuration walk-through.

3. Open the Notification admin page

Sidebar: Configure → Notification (or the equivalent label the Extra surfaces). The page lists the available templates by event type:

  • Risk lifecycle: new_risk, risk_update, risk_close, risk_comment.
  • Mitigation: new_mitigation, mitigation_update.
  • Review: risk_review.
  • Compliance: audit_* templates (audit-cycle events).
  • Document: document_* templates (document approval, expiration, renewal).

Each template has a name, a subject, and a body. The list is the menu of what you can customize.

4. Customize a template

  1. Click the template you want to edit.
  2. The template detail page shows the Subject field and the Body field (a WYSIWYG editor).
  3. Edit the subject as plain text with optional variable substitution.
  4. Edit the body in the WYSIWYG editor. Use the Insert Variable menu (the variable picker) to add dynamic content.

Available variables (the exact set depends on the event type but typically includes):

  • Risk-related: risk.id, risk.subject, risk.status, risk.calculated_risk, risk.owner, risk.team.
  • User-related: recipient.name, recipient.email, submitter.name.
  • Date / time: event timestamp, due date.
  • Links: a deep link back to the risk in SimpleRisk (risk.url or similar).

Each variable renders as a styled chip in the editor (a span with class="variable"); at send time, populate_template_variable() substitutes the actual value.

Save the template. The next email of that event type uses the new template.

5. Test the customized template

Don't trust the editor; send a test:

  1. Trigger the event in a non-production environment (or carefully in production with a test risk you'll delete).
  2. Receive the resulting email at your test inbox.
  3. Confirm: - Subject reads correctly with substituted variables. - Body renders correctly (HTML, formatting, no broken layouts). - All variables substituted (no literal strings). - Links work and point at the right place.
  4. Iterate until the template renders as intended.

6. Customize tone and branding

Beyond variable substitution, customize:

  • Greeting: "Hello " — most templates allow a personal greeting that improves recipient engagement.
  • Call to action: instead of "Click here to review," try "Please review this risk by [date]. Click here to open the risk in SimpleRisk."
  • Sender identification: include "From the [Program Name] team" in the body so recipients know which program is reaching out.
  • Footer: include contact info ("Questions? Reply to this email or contact [program-team@example.com]") and an unsubscribe path if appropriate (note: Core SimpleRisk doesn't have a per-user notification opt-out; the unsubscribe path may be "contact the admin" rather than a self-serve link).

For HTML templates, you can include logos, branded styling, and structured layouts. Test rendering in major email clients (Outlook, Gmail web, Gmail mobile, Apple Mail) — HTML rendering varies, and a layout that looks good in Gmail web may break in Outlook.

7. Localize templates if your user base is multi-language

The Notification Extra's templates are text + HTML you write. They're not auto-translated by the localization system (see Language and Localization). For multi-language deployments:

  • The pragmatic approach is to write templates in the program's working language (typically English) and accept that emails are in that language regardless of recipient locale.
  • For programs that genuinely need per-locale templates, the workaround involves either custom code or the Customization Extra in combination with conditional logic in the template body — neither is straightforward; consider whether the per-locale email is worth the maintenance cost.

8. Document and version-control the templates

Templates are configuration; treat them like configuration:

  • Document the templates in your operations runbook (subject, body, variables used).
  • Snapshot the template content periodically so changes can be rolled back if needed.
  • For backup-restore: the templates are in the Extra's tables; standard database backups capture them. See Database Backup and Restore.

After upgrades, re-verify that customized templates still work; SimpleRisk upgrades don't typically modify customer templates, but new variable types or template-engine changes occasionally affect rendering.

9. Plan for template-related operational events

A few patterns to plan for:

  • Sender reputation issues: high-volume notifications from a poorly-warmed sender domain can land in spam. Use a dedicated sender domain with proper SPF/DKIM/DMARC configuration; warm up gradually.
  • Recipient overload: a default configuration that emails every committee member on every risk event produces email fatigue. Tune the per-event recipient logic to send to who actually needs to act, not to everyone associated with the risk.
  • Template-rendering failures: if a variable references data that doesn't exist (e.g., the template includes but the risk has no owner), the rendered email may have empty fields or broken HTML. Test edge cases.
  • Email delivery failures: track bounces and delivery failures via your SMTP provider's interface; SimpleRisk doesn't surface delivery failures in the application.

Common pitfalls

A handful of patterns recur with email templates.

  • Customizing templates without configuring SMTP first. Templates without a working SMTP go nowhere. Configure SMTP, send a test, then customize templates.

  • Typing variable syntax manually instead of using the editor's picker. Manual typing produces typos that render literally in the email. Use the Insert Variable menu.

  • Treating the WYSIWYG output as portable HTML. The editor produces HTML that renders in major email clients but isn't pure web-standard HTML. Pasting into a different system (a web page, an internal docs page) produces messy output. Treat the templates as email-only content.

  • Including images hosted on internal servers. Recipients on external networks can't load the images; the email looks broken. Either inline images as base64 (bloats the email) or host on a publicly-accessible CDN.

  • Including links that require authentication without a fallback. A "Click here to review" link to SimpleRisk requires the recipient to be logged in; if they aren't, they hit the login page. Include text that explains what they're being asked to do, so the recipient understands the request even before logging in.

  • Sending too-frequent notifications. Alert fatigue produces ignored emails. Tune the events that fire emails; not every risk update warrants a notification. The Notification Extra's per-event toggles let you suppress noise.

  • Forgetting that template changes apply forward, not backward. Old emails sent with the previous template are gone; the new template only affects future emails. There's no "re-send all my notifications with the new template" path.

  • Testing only in your own inbox. Your inbox client renders things one way; recipients use other clients. Test in Outlook, Gmail web, Gmail mobile, and (if relevant) Apple Mail before going live.

  • Including sensitive data in email bodies. Risk descriptions can contain sensitive information; emailing them increases the surface. Consider whether the email needs the full description or just a notification + deep link to view in SimpleRisk.

  • Not coordinating template changes with stakeholders. A program board member who's been receiving "Risk Submitted" emails for two years suddenly receives "Risk Awaiting Your Review — Action Required by Friday" emails. Communicate the change so they know the format shifted, not the urgency.

  • Editing the template that fires for an event you didn't intend to change. With ~20 templates, it's easy to edit risk_update when you meant new_risk. Check the template name carefully before saving.

Related

Reference

  • Permission required: check_admin for the Notification admin page where templates are managed.
  • API endpoint(s): None specific to template management; templates are configured through the admin UI.
  • Implementing files: simplerisk/extras/notification/index.php (the Notification Extra's main file — setup_notification_template_tables(), populate_template_variable(), notify_risk_owner(), notify_risk_submitter(), etc.); simplerisk/admin/notification.php (the admin UI surface).
  • Database tables: The Notification Extra's template-storage table (table name: typically notifications or notification_templates; check the install). Stores template_name, subject, body, etc.
  • config_settings keys: notification (Extra-active flag); NOTIFY_ON_* per-event toggles for whether each event fires a notification; SMTP settings (smtp_host, smtp_port, smtp_encryption, smtp_user, smtp_pass, mail_from, etc.) — separately configured.
  • Variable syntax: HTML span with class="variable" data-id="..." — produced by the WYSIWYG editor's variable picker. Don't type manually.
  • External dependencies: A working SMTP gateway (SendGrid, Mailgun, AWS SES, on-prem SMTP server, Office 365, etc.); appropriate sender-domain configuration (SPF, DKIM, DMARC) for production deliverability.