Message templates
The message template system allows you to build custom templates for in-app notifications and emails sent by Canopy. Canopy uses the a subset of the Jinja2 templating language for building dynamic content in the messages.
Message template configuration
A message template takes the following values:
- Title
- Message type (see list above)
- Template content: plain text and/or rich text (i.e. HTML)
A number of default message templates are shipped with Canopy, which can be modified by administrators and technical managers via the list at Templates → Messages.
The following screenshot shows a message template being edited for plain text content:
The following screenshot shows the rich text variant:
If you want to disable a particular message, add the (DISABLED)
text to the end of the template. See the above example using: email.report.workflow.reset(DISABLED)
. The message types are text matched in the back-end, so changing the text to something other than the supported type will disable it. However, we recommend using a sensible tag to ensure it can be easily enabled again in the future.
Message template language
Message templates are written in the Jinja2 templating language. It allows for the dynamic replacement of variable strings with context-specific values, such as inserting a report lead author's name, among other functions.
Context objects and their fields
The following contains all context objects and their fields, which are available to templates.
Object field | Type |
---|---|
| String |
| String |
| User object |
| String |
| String |
| String |
| String |
| String |
| List of asset objects for the finding |
| List of example objects |
| rating_type (Options: Critical, High, Medium, Low, Info) |
| status (Options: Open, Partially Resolved, Resolved, Out-Of-Scope, False Positive) |
| String |
| List of all findings |
| List of asset objects for the phase |
| Company object |
| String |
| Date |
| List of finding objects for the phase |
| Integer |
| Project object |
| String |
| Date |
| Contact object |
| Date |
| User object |
| String |
| Date and time |
| String |
| String |
| Company object |
| Integer |
| String |
| Project status (Options: New, Scheduled, Active, Completed, Suspended, Cancelled) |
| String |
| Date |
| Integer |
| Project object |
| String |
| String |
| String |
| Date |
| Phase object |
| Date |
| Date |
| Integer |
| String |
| Statement of Work status (Open, Pending, Won, Lost, Abandoned) |
| String |
| String |
| String |
| String |
Custom fields can also be accessed as defined in Canopy on company, project, phase and finding objects, and will be output as type strings.
Usage examples
To access a single field, for example the phase reference of the current phase, you can simply use the following:
{{ phase.reference }}
The following example shows how to get a list of assets associated with the phase for a message template linked to a phase (e.g. email.assessment_scheduled):
{% for asset in phase.assets %} * {{asset.asset}} {% endfor %}
The following example shows how one can access the assets associated with findings (e.g. email.daily_update message template):
{% for finding in phase.findings %} * {{finding.title}} ({{finding.rating}} {{finding.status}}) {% for asset in finding.assets %} * {{asset.asset}} {% endfor %} {% endfor %}
Email message templates
Currently all message templates are templates for email messages. This could change in the future.
This section covers email-specific topics regarding message templates.
Email subject fields in message templates
The template for an email's subject is defined by the first line of the message template, which starts with "Subject:". That line and all subsequent empty lines are removed from the template to make the template for the email body.
The subject can be specified in either the plain text or rich text content. When both are present, the former enjoys precedence.
Plain text and rich text
If a message template has both plain text and rich text content, both will be rendered and included in the email. The version that the email recipient sees, depends on their email client settings. See also the section on email subjects.
If only rich text content is specified, a default plain text message of "This is an HTML email." is included. This message can be customised by changing the RICH_TEXT_EMAIL_PLAIN_TEXT_DEFAULT
setting in Canopy's admin section. This setting is created the first time that an email is sent with only rich text content.
Message templates used in Canopy
email.comment.new.report
The template for emails sent periodically to notify users of new comments on reports that they are involved with.
Recipients
A separate email is sent to all authors (including lead author) associated with all reports for which there are new comments, excluding the comment author.
Context data
reports
: List of reports on which there are new comments.recipient
: User profile of the recipient of the email.
email.phase_completed
A template for emails that are manually sent from the phase view UI in Canopy, for Completed phases.
Recipients
To:
- Phase sponsor
- All contacts associated with the phase
CC:
- Phase manager
- Technical lead on the phase
- The client company's account manager
All recipients can be modified by the user sending the email in the Canopy UI.
Context data
phase
: Phase object from which the email is sent.current_user
: User profile of the Canopy user sending the email.
email.phase_daily_update
A template for emails that are manually sent from the phase view UI in Canopy, for Active phases.
Recipients
To:
- Phase sponsor
- All contacts associated with the phase
CC:
- Phase manager
- Technical lead on the phase
- The client company's account manager
All recipients can be modified by the user sending the email in the Canopy UI.
Context data
phase
: Phase object from which the email is sent.current_user
: User profile of the Canopy user sending the email.
email.phase_scheduled
A template for emails that are manually sent from the phase view UI in Canopy, for Scheduled phases.
Recipients
To:
- Phase sponsor
- All contacts associated with the phase
CC:
- Phase manager
- Technical lead on the phase
- The client company's account manager
All recipients can be modified by the user sending the email in the Canopy UI.
Context data
phase
: Phase object from which the email is sent.current_user
: User profile of the Canopy user sending the email.
email.phase_starting
A template for emails that are manually sent from the phase view UI in Canopy, for Active phases.
Recipients
To:
- Phase sponsor
- All contacts associated with the phase
CC:
- Phase manager
- Technical lead on the phase
- The client company's account manager
All recipients can be modified by the user sending the email in the Canopy UI.
Context data
phase
: Phase object from which the email is sent.current_user
: User profile of the Canopy user sending the email.
email.phase_suspended
A template for emails that are manually sent from the phase view UI in Canopy, for Suspended phases.
Recipients
To:
- Phase sponsor
- All contacts associated with the phase
CC:
- Phase manager
- Technical lead on the phase
- The client company's account manager
All recipients can be modified by the user sending the email in the Canopy UI.
Context data
phase
: Phase object from which the email is sent.current_user
: User profile of the Canopy user sending the email.
email.report.due_today
The template for emails sent to inform report lead authors of reports that are due on the day.
Recipients
Due report's lead author.
Context data
report
: Report that is due today.recipient
: Report lead author's user profile.
email.report.generated
The template for emails sent to inform report lead authors that a report has been generated.
Recipients
A separate email is sent to:
- the Canopy user that initiated the report generation,
- all technical managers of all phases included in the generated report.
Context data
report
: Report that was generated.recipient
: User profile of the email recipient.
email.report.overdue
The template for emails sent periodically to notify lead authors of an overdue report.
Recipients
A separate email sent to the lead of each overdue report.
Context data
report
: Report that is overdue.recipient
: Report lead author's user profile.
email.report.overdue_summary.account_managers
The template for emails summarising overdue reports, sent periodically to account managers.
Recipients
The account manager of the client company that will eventually receive the report.
Context data
reports
: List of reports that are overdue.recipient
: User profile of the account manager of the report's client company.
email.report.overdue_summary.technical_managers
The template for emails summarising overdue reports, sent periodically to technical managers.
Recipients
A separate email is sent to each active technical manager Canopy user.
Context data
reports
: List of reports that are overdue.recipient
: User profile of the recipient technical manager.
email.report.pr_required
The template for notification emails sent to potential report PR reviewers, when a report becomes available for review.
Recipients
A separate email is sent to each Canopy user who has been granted the PR reviewers role.
Context data
report
: Report that is available for PR review.recipient
: User profile of the recipient reviewer.
email.report.qa_required
The template for notification emails sent to potential report QA reviewers, when a report becomes available for review.
Recipients
A separate email is sent to each Canopy user who has been granted the QA reviewers role.
Context data
report
: Report that is available for QA review.recipient
: User profile of the recipient reviewer.
email.report.synced.distributionlist
The template for emails sent to contacts on a report's distribution list, to notify that a report has been synced to a Canopy portal, and is available for download.
Recipients
A separate email is sent to each contact on a report's distribution list, for each report that was synced to a Canopy portal.
Context data
report
: Report that was synced to the portal.portal
: Portal that the report was synced to.recipient
: Contact being notified of the available report.
email.report.workflow.*
Templates for emails sent a report's workflow state changes. This applies to all of the following message template types:
email.report.workflow.accept_pr
email.report.workflow.accept_qa
email.report.workflow.approve_pr
email.report.workflow.cancel
email.report.workflow.complete
email.report.workflow.create
email.report.workflow.redo_pr
email.report.workflow.reject_pr
email.report.workflow.reject_qa
email.report.workflow.request_pr
email.report.workflow.request_qa
email.report.workflow.reset
Recipients
The lead author of the report that transitioned in its review workflow.
Context data
report
: Report that transitioned.action_user
: User profile of the Canopy user that triggered the workflow transition.recipient
: User profile of the report's lead author.
email.scheduler.new_assignment
The template for emails sent to Canopy users, to notify them of being assigned to project phase via the scheduler.
Recipients
The Canopy user that was assigned to project phase on the scheduler.
Context data
phase
: Project phase that the recipient has been assigned to.entry
: Schedule entry that was created.
Attachments
- An iCalendar file, created from the schedule entry information, which the recipient can import into their calendar software.
email.scheduler.phase_updated
The template for emails sent to Canopy users, to notify them of the rescheduling of a scheduled phase or their assignment thereto.
Recipients
A separate email is sent to each Canopy user whose scheduled assignment changed because of the rescheduling.
Context data
phase
: Project phase that the recipient has been assigned to.entry
: Schedule entry that was created.
Attachments
- An iCalendar file, created from the updated schedule entry information, which the recipient can import into their calendar software.
email.scheduler.project_updated
The template for emails sent to Canopy users, to notify them of the rescheduling of a scheduled project. This likely implies the rescheduling of associated project phases, and all user assignments to those project phases.
Recipients
A separate email is sent to each user that is assigned to any phase of the rescheduled project.
Context data
project
: Project that was rescheduled.entries
: List of schedule entries for the user that was affected by rescheduling the project.
Attachments
- An iCalendar file, created from the schedule entries, which the recipient can import into their calendar software.
email.sow.generated
The template for emails sent to inform interested users that a SoW has been generated.
Recipients
A separate email is sent to:
- the Canopy user that initiated the SoW generation,
- all Canopy users that have permissions on the SoW that was generated.
Context data
sow
: SoW that was generated.recipient
: User profile of the email recipient.
email.sow.synced.distributionlist
The template for emails sent to contacts on a SoW's distribution list, to notify that a SoW has been synced to a Canopy portal, and is available for download.
Recipients
A separate email is sent to each contact on a SoW's distribution list, for each SoW that was synced to a Canopy portal.
Context data
sow
: SoW that was synced to the portal.portal
: Portal that the report was synced to.recipient
: Contact being notified of the available report.
Message template plugins
Canopy ships with the following plugins that can be used:
Plugin name | Description | Related documentation (where applicable) |
---|---|---|
email auto-cc | The email auto CC (and BCC) plugin allows users to set default CC/BCC email addresses, and optionally link these to message templates. This allows users to control default recipients of emails (e.g. notify your SOC when a test is due to start). | Email auto-CC |
For custom plugin development, see the Writing plugins.