Email Template Configuration

Polarity Server Emails

Overview

The Polarity Server automatically sends emails to subscribed users when certain events occur:

• On demand to test SMTP settings;

• When a user’s account is created;

• To facilitate automated local user account password resets;

• To notify local users of a password reset;

• To notify users of access to use an Integration;

• To notify users of access to an Annotation Channel;

• To notify a user who annotated an entity of a new comment to their annotation;

• To notify a user who commented on an annotation of a new comment on the same annotation;

• To notify a user who annotated an entity that their annotation was upvoted.

These events are “functional triggers”.

For a description of the functional triggers and the templates associated with them, see Reference A (below).

Requirements

The adjustments must be made by a user with command line access to the Polarity Server and permissions to make changes to the files and directories under the base installation directory of the Polarity Server.  By default, this location is /app, and this document will use this location in all examples and procedures for simplicity.

For the Polarity Server to distribute these automated notifications via email, the SMTP settings must be configured.  The email templates are stored in the Polarity Server container.  Users are subscribed to all email notifications by default.

For information on configuring SMTP settings in the Polarity Server, see the documentation here:

https://knowledge.threatconnect.com/docs/configuring-smtp

NOTE

The email templates within the Polarity Server container are not configurable, as the containers are ephemeral.

Email Templates

The email templates are embedded Elixir (EEX) files, which allows you to embed Elixir code (specifically variables, such as <%= username %>) inside text or HTML templates.  These templates are filled out on demand and distributed via the SMTP server configured in the Polarity Server settings.

Email Template Files

There are three email template files for each functional trigger:  

• plain text

• HTML-formatted

• a subject line template

The email template filenames cannot be customized or changed.

It is optional to include all templates in the customized template directory.  Any templates not included in the customized template directory will use the default template installed with the Polarity Server should it be needed.

Text Email Templates

Plain text email templates offer no formatting options and are commonly used in email previews.  This is a sample email template to notify users of a new Annotation Channel:

Hello <%= full_name %>,

Looks like <%= creator_username %> has created a new channel called 
<%= channel_name %> that you have access to.
To view more information on the channel and subscribe, click below:
View this channel in Polarity: 
"<%= host %>/channels?channelFilter=<%= channel_name %>"

Notice there are several variables listed in the email template, denoted with the leader “ <%=“ and concluded with “ %>”. Each of these variables would be replaced with the expected information from the user accounts and Annotation Channels data in the Polarity Server’s database when the email is assembled and sent.

HTML Email Templates

The HTML formatted email templates offer a wide variety of HTML formatting options.  The following example is the same email template from above in HTML format:

<p>
Hello <%= full_name %>,

Looks like <%= creator_username %> has created a new channel called 
<%= channel_name %> that you have access to.
To view more information on the channel and subscribe, click below:
</p>

<p>
  <a href="<%= host %>/channels?channelFilter=<%= channel_name %>">View this channel in Polarity</a>
</p>

The variables are the same as the text version. The only difference is the addition of HTML elements to make the email more accessible and actionable by the recipient.

Email Subject Line Templates

To ensure the email includes an appropriate subject line, there are templates specifically for these for each functional trigger.  The following example is the subject line template included for the two email formats above:

Polarity - <%= creator_username %> has created a new channel <%= channel_name %>

Note

For a full list of variables available for each template, see Reference B (below).

Polarity Server Adjustments

There are three required adjustments for the Polarity Server to use custom email templates:

1. The customized email templates must be placed in a location accessible to the Polarity Server.

2. The Docker service template file must include the location of the custom email templates as a volume under the Polarity Platform container.

3. The Polarity Server environment file requires a variable describing the location to find the custom email templates.

Custom Email Template Location

For simplicity and consolidation, we recommend placing the custom email templates in a directory under the Polarity Server base installation directory.  The directory /app/emails is the location used in this document.  

The directory and its contents must be owned by the designated Polarity user.  The installed default of user 31337 and group 31337 is used in this document.

The EEX files may be downloaded as a package from Polarity.  Contact your Polarity Customer Success Manager for more information.

Docker Service Template File

The /app/docker-compose.yml file must have a reference to the new location for the custom emails directory.  It must be listed in the correct format as a volume under the services.app.volumes block.

Polarity Server Environment File

A new environment variable must be added to the Polarity Server’s environment file, located at /app/.env.  The value of this variable will be the location of the custom email template files as it will be found mounted within the container.  

The default value for this variable will be /app/emails in this document.

Example Installation Procedure

This procedure covers installation on a “standard” Polarity Server (Polarity Server installed in the /app directory and using the Docker Engine for container management).

1. Download the email template package to the Polarity Server.

   1. Contact your Polarity Customer Success Manager for the link.

2. Extract the email template package to the /app/emails directory.

   1. mkdir /app/emails
      tar xzf polarity-email-templates.tgz -C /app/emails

3. Optional:  Edit the email templates, as needed.

4. Change the ownership of the /app/emails directory to user / group 31337.

   1. chown -R 31337:31337 /app/emails

5. Edit the /app/.env file to add the new pointer variable.

   1. Add the following line anywhere in the /app/.env file:

      1. POLARITY_CUSTOM_EMAILS_FOLDER=/app/emails

         NOTE

         This line can be placed anywhere in the /app/.env file.

   2. Save and close the /app/.env file.

6. Edit the /app/docker-compose.yml file to add the new volume entry.

   1. Find the services.app.volumes block.

   2. (You should see entries for /app/integrations, /app/license, and /app/certs already in this block.)

   3. Add the line below at the same indentation as and immediately following the previous lines in this block:

           - ./emails:/app/emails:z

   4. Save and close the /app/docker-compose.yml file.

7. Restart the Polarity Server containers to effect the changes.

   1. cd /app && ./down.sh && ./up.sh

FAQ

Q:  Can I add variables to the email templates?

A: No, the only variables that are made available to the template during the prescribed functional trigger are in the default template already.  You may find these variables listed by template (see below).

Q:  Can I rename the email template files?

A:  No, the template file names are referenced directly by the system and cannot be changed.

Q: Can I add email templates or new functional triggers?

A:  No, the functional triggers defined in the system are static.  However, if you have an idea for a new functional trigger, please reach out to your Customer Success Manager or email Support@Polarity.IO.

Q:  Can I add more text and/or HTML objects to the email templates?

A: Yes! Feel free to customize the template by including additional text, image references, links, or other elements that suit your organization’s needs.

References

Reference A - Functional Triggers and Associated Templates

This file is an embedded PDF.  Please contact CustomerSuccess@Polarity.io if you have any questions or issues.

Reference B - Variables Available by File

This file is an embedded PDF.  Please contact CustomerSuccess@Polarity.io if you have any questions or issues.

If you have any questions or issues, please contact your Customer Success Manager or email Support@Polarity.io.