Patchman: Email template editing

Knowledgebase Article

Patchman: Email template editing

For each message that is sent out by Patchman on behalf of your organization, you can fully customize the layout and contents. The layout and contents are specified on a per-policy basis, giving you the flexibility to provide different experiences for different users.

Each template consists of two parts:

• A HTML template. This is the message most users will see when they open their email client and gives you the ability to include images and rich text layouts. However, note that most email clients are very limited in their HTML capabilites. By default, we will inline all CSS for you when rendering the email, but you should still verify the emails render like you expect them to in the most popular email clients.

• A text template. This is the simplified version of your HTML template and can only contain simple text. This is used by all clients that don't support HTML. When editing your HTML template (base templates excluded), we will automatically try to get a text template out of it.

When editing your template, you can choose between a simple rich text editor and an HTML editor. While the rich text editor can be useful, it could get complex when using lots of Mustache tags (see below). If this is the case, we recommend switching to the HTML editor when you want more advanced capabilities.

We also show a live preview using an example Mustache context, but note that this rendering is only indicative and the actual email may look different (due to email client limitations, but also due to CSS inlining). To verify the rendering of your email templates, you could use the 'Send test email' option. This will send a message to your own email address, allowing you to view how your email is actually rendered.

Base templates

Since you may want to use the same base template for all mails in the same policy, we offer you the ability to specify a base template for both HTML and text templates. This allows you to dumb-down the actual mail templates to the message itself and focus less on its presentation.

Base templates must contain a placeholder for the actual message contents and a placeholder for the Patchman branding. Please ensure that the branding is visible and not obscured by any other element. Since base templates can get very complex, we do not offer a full editor for these kind of templates. If you do not know anything about HTML, you could stick to the default template we provided for you, or build one yourself, for instance using Zurb's Ink.

Special tags

To include information in the email templates, we use Mustache, which is a very simple template engine. Below you'll find a short primer on Mustache's syntax. If you need more information, you can find the full documentation online.

Variables

Using {{var}} will display the value of the variable. If it is not available, an empty string will be displayed instead: Dear {{username}},

Verbatim

If you need to include a variable unescaped (e.g. in text templates), use {{&var}} instead.

Sections:list

When the variable is a list, you can use sections to repeat the same block multiple times. Inside the section, you can access the attributes of the individual list items: {{#detections}} We found a detection of {{name}}. {{/detections}}

Sections: conditional

Similarly, sections work as conditional statements. When a variable is optional, the data within the section is only shown when the variable is available: {{#definition_multiple}} The detection consists of {{definition_count}} vulnerabilities {{/definition_multiple}}

Sections: invert

If you need to invert the statement, i.e. show a message in the case of an empty list or untrue variable, you can use the caret: {{^definition_multiple}} The detection consists of only one vulnerability. {{/definition_multiple}}

Comments If you need to place a comment in your template, you can do so using {{! comment }}

Partials

You can include partials using {{>partial}}. A partial is a subtemplate and is used only by the policy generic templates to include the sub-templates. You must always include the {{>content}} and {{>branding}} partial in your templates.

Template Context

The following data is available in all templates:

username The username of the affected user.

domains A list of all domains of this user.

domain A single comma-separated string of affected domains

affected_domains A list of all domains with detections of this user

affected_domain A single comma-separated string of affected domains

server_hostname The hostname of the detection's server

server_ip_address The IP address of the detection's server.

detections A list of detections:

.domains - A list of domains affected by this detection

.domain - A single comma-separated string of affected domains

.definitions - A list of definitions that are found in this file.

.name - The name of this definition .type - The type of this definition

.definition_count - The amount of definitions

.definition_multiple - A boolean indicating whether multiple definitions were found

.directory - A single comma-separated strin gof affected directories.

.directories - A list of all directories affected.

.applications - A list of all software applications

.application - A single comma-separated string of applications

.files - A list of affected file paths

.file - A single comma-separated string of file paths