Email Templates

Templates are available for notifications sent by email, with which you can define the content and presentation of the messages. Each template can be defined in several languages and in both HTML format and as a simple text message.

To edit the templates, you must be logged in with system administrator permissions. Then go to Administration > Templates > Email Templates.

Template Types

Each template is based on a template type. The following table describes the available template types for item-related notifications. Templates of the template type “Item change” are also available for workflows. Processing 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 email
Item plan/expense	Expenses changed
Comment added	Comment added
Reminder	Global reminder of due items
Send from item	Email sent from item
Item reminder	Item-related resubmission
E-Mail item creation rejected	Item could not be created by email

The following table describes the available template types for administrative or system-related notifications.

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

You can assign templates either globally or specifically for an item type or workspace type or even workspace-specific, by dragging it from the right workspace into the desired position in the second column. Each template comes in two variants: HTML and plain text. Each template can be made available in a range of locales. You can import and export complete template sets or individual templates.

Template Macro Language

Templates are written in the Freemarker macro language (see https://freemarker.apache.org/docs/index.html). The following list shows a part of the email HTML template for item changes, as it is delivered 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 variables are child variables of FieldChangeRows. This allows you to generate emails like the one shown below.

Template Attributes

The following attributes are available for email templates:

Variable	Description
changedBy	The person who caused the email event
changeDetail	A localized string, as described in the following code
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 has changed
isDeleteComment	True if a comment was deleted
isEditComment	True if a comment was edited
isManagerChanged	True if the manager has changed
isMove	True if the item was moved to a new item type or workspace
isOtherChanged	True for any change that was not explicitly specified
isReopen	True if a closed item was reopened
isResponsibleChanged	True if the responsible has changed
isStateChanged	True if the item state has changed
itemNo	The item number
longFieldChanges	A list of item attributes for “long” attributes like descriptions and comments
longFieldChanges.fieldChange	A single attribute
longFieldChanges.fieldChange.changed	True if this attribute has 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 has 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 submitter’s email, if item was created by email or if it was entered by another user
title	The item title
tokenExpression	For authorizing unknown email senders, see Email-Specific Access Permission

The following listing describes how the ChangeDetail variable is structured.

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;
}