Emails sent to users can be customized using templates defined at the site level. A subset of these templates can also be customized at the project or folder level. This topic describes how to customize the templates used to generate system emails.

Email Templates

  • Select (Admin) > Site > Admin Console.
  • Under Configuration, click Email Customization.
  • Select an Email Type from the pulldown to customize the templates. Available template types (not all are shown in all server configurations:
    • Change email address: The administrator also receives this notification.
    • Issue update
    • Message board daily digest
    • Message board notification
    • Pipeline job failed
    • Pipeline job succeeded
    • Pipeline jobs failed (digest)
    • Pipeline jobs succeeded (digest)
    • Project Review
    • Register new user: Template used for email to the new user.
    • Register new user (bcc to admin): When a new user is registered, this template controls what is sent to the admin.
    • Report/dataset change (digest)
    • Request email address: Sent when a user requests to change their email address. The administrator also receives this notification.
    • Reset password: Template for email sent to the user.
    • Reset password (bcc to admin): When a password is reset, this template controls what is sent to the admin.
Users of the Compliance features in the Enterprise Edition will also see: To support using ELN, you will also see:
    • Author change - added
    • Author change - removed
    • Review complete - approved
    • Review complete - returned
    • Review requested - co-authors
To support using Workflow Jobs in Sample Manager or Biologics, you will also see:
    • New or updated task comment - All users
    • Next task ready - task owner
    • Job assignment - Job owner
    • Job complete - Job & task owners
    • Job deleted - Job & task owners
    • Job reactivated - Job & task owners
    • Job start - Job subscribers
    • Job update - Job and task owners
    • Job update - Subscriber Copy

For your server to be able to send email, you also need to configure SMTP settings in your labkey.xml file. See SMTP Settings for more information. To test these settings:
  • Select (Admin) > Site > Admin Console.
  • Under Diagnostics, click Test Email Configuration.

Template Customization

To customize the template, complete the fields:

  • From Name: The display name for the sender, typically the short site name. The email "From" field will be populated with the one configured via site or project settings.
  • Reply To Email: If you prefer a different "Reply-To" address, supply it here.
  • Subject
  • Message

Substitution Strings

Message template fields can contain a mix of static text and substitution parameters. A substitution parameter is inserted into the text when the email is generated. The syntax is: ^<param name>^ where <param name> is the name of the substitution parameter.

Each message type template page includes a full list of available substitution parameters with type, description, and current value if known, at the bottom of the email customization page.

Standard Parameters

Most templates support these Standard Parameters:

  • ^contextPath^ -- Web application context path ("labkey" or "")
  • ^currentDateTime^ -- Current date and time in the format: 2017-02-15 12:30
  • ^folderName^ -- Name of the folder that generated the email, if it is scoped to a folder.
  • ^folderPath^ -- Full path of the folder that generated the email, if it is scoped to a folder.
  • ^folderURL^ -- URL to the folder that generated the email, if it is scoped to a folder.
  • ^homePageURL^ -- The home page of this installation -- see Site Settings.
  • ^organizationName^ -- Organization name -- see Look and Feel Settings.
  • ^siteEmailAddress^ -- The email address on the 'to:' line.
  • ^siteShortName^ -- Header short name -- see Look and Feel Settings.
  • ^supportLink^ -- Page where users can request support.
  • ^systemDescription^ -- Header description -- see Look and Feel Settings.
  • ^systemEmail^ -- The 'from:' address for system notification emails.

Custom Parameters

Most templates include a list of custom parameters underneath the standard list. These parameters are not always available in other template types, and there are some specialized parameters providing more than simple substitution. Examples (this is not an exhaustive list):

  • Register New User and Request Email Address
    • ^verificationURL^ -- The unique verification URL that a new user must visit in order to confirm and finalize registration. This is auto-generated during the registration process.
  • Report/dataset change
    • ^reportAndDatasetList^ -- Templates for report and dataset notifications include a ^reportAndDatasetList^ parameter which will include a formatted list of all the changes which triggered the notification.
  • Audit Processing Failure Available with the Enterprise Edition of LabKey Server:
    • ^errorMessage^ -- The error message associated with the failed audit processing. See Compliance. Note that this is the only template type that supports this parameter.

Format Strings

You may also supply an optional format string. If the value of the parameter is not blank, it will be used to format the value in the outgoing email. The syntax is: ^<param name>|<format string>^

For example:

^currentDateTime|The current date is: %1$tb %1$te, %1$tY^
^siteShortName|The site short name is not blank and its value is: %s^

Properties are passed to the email template as their actual type, rather than being pre-converted to strings. Each type has different formatting options. For example, a date field can be formatted in either month-first or day-first order, depending on local style.

For the full set of format options available, see the documentation for java.util.Formatter.

Use HTML in Templates

Some email templates support using HTML formatting in the message body to facilitate showing text links, lists, etc. For example, the default template for "Message board daily digest" reads in part:

<table width="100%">
<tbody>
<tr><td><b>The following new posts were made yesterday in folder: ^folderName^</b></td></tr>
^postList^
</tbody>
</table>
<br >
...

In the email, this will show the heading in bold and remainder in plain text.

If you want to use a combination of HTML and plain text in an email template, use the delimiter:

--text/html--boundary--
to separate the sections of the template, with HTML first and plain text after. If no delimiter is found, the entire template will be assumed to be HTML.

Message Board Notifications

For Message board notification emails, there is a default message reading "Please do not reply to this email notification. Replies to this email are routed to an unmonitored mailbox." If that is not true for your message board you may change the template at the site or folder level. You may also choose whether to include the portion of the email footer that explains why the user received the given email and gives the option to unsubscribe. Include the parameter ^reasonFooter^ to include that portion; the text itself cannot be customized.

Folder-Level Email Customizations

A subset of email templates, like those for issue and message board notifications, can also be customized at the project or folder level.

  • Issue update
  • Message board daily digest
  • Message board notification
To access folder-level customizations for any of these templates, the easiest path is to use a Messages web part. You can add one to any folder if you don't already have one.

  • Viewing the Messages web part, open the (triangle) menu.
  • Click Email to open the submenu, then Folder Email Template.
  • The interface and options are the same as described above for site level templates. Only the subset of template types that can be customized at the folder level are listed. Select one.
    • Issue update
    • Message board daily digest
    • Message board notification
  • Customize the template as needed, then click Save.
  • If you added an empty Messages web part to make these changes, you can remove it from the page after customizing your templates.

Test Email with Dumbster

During local development, you can use the dumbster module to test email behavior instead of or in addition to configuring the SMTP server. You can find dumbster in the testAutomation GitHub repository.

The dumbster module includes a Mail Record web part that you can use to test email that would be sent in various scenarios.

The Mail Record presents the sender and recipient email addresses, the date, text of the message, and links to view the headers and versions of the message such as HTML, Text-only, and Raw.

Once SMTP is configured and real email will be sent, be sure to remove the dumbster module from your deployment. Otherwise it will continue to capture any outgoing messages before they are emailed.

Related Topics

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand allcollapse all