Emails sent to users can be customized using templates defined at the site level. A subset can also be customized at the
project or folder level.
- Select Admin > Site > Admin Console.
- Click Email Customization.
- Select an Email Type from the pulldown to customize the templates. Available template types:
- Audit Processing Failure (see Compliance Settings)
- Change email address
- Request email address
- Register new user (with or without a bcc to Admin)
- Reset password (with or without a bcc to Admin)
- Issue update
- Pipeline jobs succeeded (digest form optional)
- Pipeline jobs failed (digest form optional)
- Message board notification (digest form optional)
- Report/dataset change (digest)
- Specimen request notification
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. You can test these settings by visiting
Admin > Site > Admin Console and clicking
Test Email Configuration.
Substitution Strings
Subject, as well as
From and the
Message can contain a mix of static text and substitution parameters. The
From field sets the sender's description, while the actual sender email address will be the one configured via site or project settings. 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 includes a full list of available substitution parameters with type, description, and current value if known, at the bottom of the email customization page. For example, some strings used in emails for user management:
- ^currentDateTime^ -- Current date and time in the format: 2017-02-15 12:30
- ^emailAddress^ -- The email address of the person performing the operation -- see Look and Feel Settings.
- ^errorMessage^ -- The error message associated with the failed audit processing -- see Compliance.
- ^homePageURL^ -- The home page of this installation -- see Site Settings.
- ^organizationName^ -- Organization name -- see Look and Feel Settings.
- ^recipient^ -- The email address on the 'to:' line.
- ^siteShortName^ -- Header short name -- see Look and Feel Settings.
- ^supportLink^ -- Page where users can request support.
- ^systemEmail^ -- The 'from:' address for system notification emails.
- ^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.
The list of parameters available varies based on which email type is selected from the dropdown. There are some specialized parameters providing more than simple substitution. For example, templates for
report and dataset notifications include a ^reportAndDatasetList^ parameter which will include a formatted list of all the changes which triggered the notification.
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.
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.
Folder Level Email Customizations
Email template customizations are generally done at the site level. Some like issue and message board notifications can also be customized at the project or folder level if required.
To open folder-level email customizations, navigate to the desired folder and edit the URL:
- Replace the controller "project" with "admin"
- Replace "begin.view?" with "customizeEmail.view?"
- For example, "localhost:8080/labkey/admin/home/customizeEmail.view?" is where you would email template changes that only apply to the 'home' project on a default locally installed server.
- Only the subset of templates available at that level will be included on the dropdown. Otherwise the interface available and parameters used are the same.
