Canopy
Table Of Contents
Canopy
Table Of Contents

Message templates

The message template system allows you to build custom templates for in-app notifications and emails sent by Canopy. Canopy uses a subset of the Jinja2 templating language for building dynamic content in the messages.

Configuration

A message template takes the following values:

  • Title

  • Message type

  • Template content: plain text and/or rich text (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:

image0

The following screenshot shows the rich text variant:

image1

If you want to disable a particular message, add (DISABLED) to the end of the template’s Message type. Message types are strings used to look up templates. Therefore changing the text to something other than a supported value will effectively disable it. However, we recommend using a sensible tag to ensure it can be easily enabled again in the future.

Templating 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 table contains all context objects and their fields, which are available to templates.

Object field

Type

asset.asset

String

asset.description

String

company.account_manager

User object

company.abbreviation

User object

company.name

String

contact.email

String

contact.external_id

String

contact.name

String

example.asset

String

example.example

String

example.rating

String

example.title

String

example.tool

String

finding.assets

List of asset objects for the finding

finding.cvss2_score

String

finding.cvss2_vector

String

finding.cvss3_score

String

finding.cvss3_vector

String

finding.examples

List of example objects

finding.rating

Finding rating string (Options: Critical, High, Medium, Low, Info)

finding.status

Finding status string (Options: Open, Partially Resolved, Resolved, Out-Of-Scope, False Positive)

finding.title

String

finding.tool

String

phase.all_findings

List of all findings

phase.assets

List of asset objects for the phase

phase.company

Company object

phase.description

String

phase.end_date

Date

phase.findings

List of finding objects for the phase

phase.id

Integer

phase.location

String

phase.location_notes

String

phase.project

Project object

phase.reference

String

phase.report_due_date

Date

phase.sponsor

Contact object

phase.start_date

Date

phase.status

Phase status string (Options: New, Scheduled, Active, Completed, Suspended, Cancelled)

phase.technical_lead

User object

phase.title

String

phase.type

String

portal.last_sync

Date and time

portal.name

String

portal.url

String

project.company

Company object

project.end_date

String

project.id

Integer

project.reference

String

project.report_due_date

String

project.status

Project status string (Options: New, Scheduled, Active, Completed, Suspended, Cancelled)

project.start_date

String

project.title

String

report.authors

List of User Objects

report.due_date

Date

report.id

Integer

report.lead_author

User Object

report.project

Project object

report.reference

String

report.title

String

scheduleentry.activity

String

scheduleentry.end_date

Date

scheduleentry.phase

Phase object

scheduleentry.start_date

Date

sow.expiry_date

Date

sow.id

Integer

sow.reference

String

sow.status

Statement of Work status string (New, Open, Pending, Won, Lost, Cancelled)

sow.title

String

userprofile.email

String

userprofile.external_id

String

userprofile.landline

String

userprofile.name

String

Custom fields can also be accessed as defined in Canopy on clients, projects, phases and findings, and will be output as strings.

Usage examples

To access a single field, for example the phase reference of the current phase, you can simply use the following syntax:

{{ phase.reference }}

The following example shows how to output a list of assets associated with the phase for a message template linked to a phase (e.g. email.phase_scheduled):

{% for asset in phase.assets %}
  * {{asset.asset}}
{% endfor %}

The following example shows how one can output the assets associated with all findings (e.g. email.phase_progress_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 topics specific to message templates for emails.

Email subject fields

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. For example:

Subject: Update for phase {{phase.reference}}

Phase {{phase.title}} ({{phase.reference}}) is now {{phase.status}}.

For a phase with reference P-123, an email generated with the above template would have the following subject Update for phase P-123.

The last line of the template will be rendered to form the body of the email.

The subject can be specified in either the plain text or rich text content. When both are present, the former is used.

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.

Supported message templates

The message templates below are currently supported in Canopy.

Each section describes the use of the template, who the recipients of rendered messages are, and (importantly) the context data provided to the template when it is being rendered. If applicable, it also describes generated attachments.

Note

All email recipients can be modified by the user sending the email in the Canopy UI.

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 the lead author) of 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, for Completed phases.

Recipients

  • To

    • Phase sponsor

    • All contacts associated with the phase

  • CC

    • Phase manager

    • Technical lead on the phase

    • The client’s account manager

Context data

phase

Phase object from which the email is sent.

current_user

User profile of the Canopy user sending the email.

email.phase_progress_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’s account manager

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’s account manager

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’s account manager

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’s account manager

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

  • To

    • 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 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 author 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 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.

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

action_user

User profile of the user that requested the PR.

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

action_user

User profile of the user that requested the PR.

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 Writing plugins.

Table Of Contents

arrow_back
Previous
Findings Knowledge Base
 arrow_forward
Next
Substitution variables