E-mail templates

sysman sysadmin

For notifications sent by e-mail there are templates that let you define the content and presentation of the messages. Each template can be defined in several languages and, for each language, both in HTML format and as a plain text message.

Go to Administration > Templates > E-mail templates.

Template types

Every template is based on a template type. The following table describes the template types available for item-related notifications. Templates of the template type “Item change” are also available for workflows. Editing a set of items does not trigger a notification event.

Template type	Event
Item change	Item created or changed
Item created by e-mail	Item created by e-mail
Item plan/expense	Expenses changed
Comment added	Comment added
Reminder	Global reminder of due items
Send from item	E-mail sent from the item
Item reminder	Item-related reminder
E-Mail item creation rejected	Item could not be created by e-mail

The following table describes the template types available for administration- and system-related notifications.

Template type	Event
Welcome	Welcome message after (self-) registration
Forgot password	Response to the “Forgot password” action
Calendar change	Calendar change
Two factor authentication	Code for two-factor verification
Plugin	Templates for plugins

You assign templates either globally, specifically for an item type or a workspace type, or even per workspace, by dragging them from the right-hand pane to the desired position in the second column. Each template comes in two variants: HTML and plain text. Each template can be provided in a number of locales. You can import and export complete template sets or just individual templates.

Editing and assigning e-mail templates

Changing an e-mail template

Template macro language

Templates are written in the Freemarker macro language (see https://freemarker.apache.org/docs/index.html). The following listing shows part of the HTML e-mail template for item changes as it is shipped with Allegra.

<#macro renderShortFields fieldChangeRows>
<#list fieldChangeRows as fieldChange>
<tr>
    <td align="right" bgcolor="#d8e1ed"
            style="width: 26%;">
            ${fieldChange.localizedFieldLabel}:
    </td>
    <#-- if copy we are not interested in the
        change compared to the original workItem -->
    <#if !fieldChange.changed>
        <#assign bgcolor=bgcolorCellNormal>
    <#else>
        <#assign bgcolor=bgcolorCellChanged>
    </#if>
    <td bgcolor="${bgcolor}" style="width: 37%;">
    ${fieldChange.newShowValue}
    </td>
    <td bgcolor="#edf0f6" style="width: 37%;">
    ${fieldChange.oldShowValue}
    </td>
    </tr>
</#list>
</#macro>

The template module provides a number of variables for the templates. Most of these variables are child variables of FieldChangeRows. They let you generate e-mails like the one shown below.

Template attributes

The following attributes are available for e-mail templates:

Variable	Description
changedBy	The person who caused the e-mail event
changeDetail	A localized text string as described in the code below
createdBy	The person who created this item (in the case of creation)
isAddComment	True if a comment was added
isClose	True if the item was closed
isCreated	True if this item has just been created
isCopy	True if this item has just been copied
isDateChanged	True if the start or end date was changed
isDeleteComment	True if a comment was deleted
isEditComment	True if a comment was edited
isManagerChanged	True if the manager was changed
isMove	True if the item was moved to a new item type or workspace
isOtherChanged	True for any change that was not specified more explicitly
isReopen	True if a closed item was reopened
isResponsibleChanged	True if the responsible was changed
isStateChanged	True if the item state was changed
itemNo	The item number
longFieldChanges	A list of item attributes for “long” attributes such as descriptions and comments
longFieldChanges.fieldChange	A single attribute
longFieldChanges.fieldChange.changed	True if this attribute was changed
longFieldChanges.fieldChange.newShowValue	The new or actual attribute value
longFieldChanges.fieldChange.oldShowValue	The old attribute value
marker	Default is [ Allegra <item number>]
moreInfo	The link to the item within the Allegra system
oldIssue	Only in the case of a copy: the original item number
project	The workspace or project for this item
shortFieldChanges	A list of item attributes for “short” attributes
shortFieldChanges.fieldChange	A single attribute
shortFieldChanges.fieldChange.changed	True if this attribute was changed
shortFieldChanges.fieldChange.newShowValue	The new or actual attribute value
shortFieldChanges.fieldChange.oldShowValue	The old attribute value
subject	Default is ${marker} [${{project}] ${changeDetail}
submitterEmail	The e-mail of the submitter if the item was created by e-mail or if it was entered by another user
title	The item title
tokenExpression	For authorizing unknown e-mail senders, see Email-specific access permission

The following listing describes how the changeDetail variable is constructed.

private String getSubjectSuffix(Integer workItemKey, String synopsis,
                                String newStateLabel, Locale actualLocale) {

    String subjectPatternKey = null;
    //the last complying flag wins
    if (isAddComment) {
        subjectPatternKey = "item.mail.subject.addComment";
    }
    if (isEditComment) {
        subjectPatternKey = "item.mail.subject.editComment";
    }
    if (isDeleteComment) {
        subjectPatternKey = "item.mail.subject.deleteComment";
    }
    if (isOtherChanged) {
        subjectPatternKey = "item.mail.subject.trail";
    }
    if (isManagerChanged) {
        subjectPatternKey = "item.mail.subject.managerChanged";
    }
    if (isResponsibleChanged) {
        subjectPatternKey = "item.mail.subject.responsibleChanged";
    }
    if (isDateChanged) {
        subjectPatternKey = "item.mail.subject.dateChange";
    }
    if (isMove) {
        subjectPatternKey = "item.mail.subject.move";
    }
    if (isStateChanged) {
        subjectPatternKey = "item.mail.subject.stateChange";
    }
    if (isClose) {
        subjectPatternKey = "item.mail.subject.closed";
    }
    if (isReopen) {
        subjectPatternKey = "item.mail.subject.reopen";
    }
    if (isCreated || isCopy) {
        subjectPatternKey = "item.mail.subject.new";
    }
    String changeDetail = "";
    Object[] subjectArguments = {workItemKey, //for new
            synopsis,
            newStateLabel, //for state change
            //newProjectLabel,
    };
    changeDetail = LocalizeUtil.
                getParametrizedString(subjectPatternKey,
            subjectArguments, actualLocale);
    return changeDetail;
}