Manage Email Templates

Allegra sends emails to inform users of changes to items or remind them of due dates. You can customize the appearance and content of these emails with templates.

To add or edit email templates, in the Administration perspective, go to Administration > Customize > Email Templates.

There are a number of predefined events that trigger emails. These are:

• Create item

• Change item

• Change budget or plan values

• Add a comment

There are also a number of system events that trigger emails. These are:

• Greeting a new user after registration

• Forgotten password

• Reminder email for due or overdue items

You can still create email templates for sending emails from an item and for plug-ins.

You can assign a template either globally or specifically for an item type or a workspace type, or even workspace-specific, by dragging it from the right workspace to the desired position in the second column.

Each template comes in two flavors: HTML and plain text. Also, each type of template can be provided in a number of locales. You can import and export complete template sets or only individual templates. import and export.

Templates are written in the FreeMarker macro language (see https://freemarker.apache.org/docs/index.html). The following listing shows part of the email HTML template for process changes, as 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 of the variables are child variables of fieldChangeRows. These can be used to create emails like the one shown below.

The following attributes are available:

Variable	Description
title	The item title
project	The workspace or project for this item
itemNo	The item number
marker	Default is [ Allegra <itemNo>]
submitterEmail	The submitter’s email, if the item was created by email or if it was submitted by another user
subject	Default is ${marker} [${project}] ${changeDetail}
changeDetail	A localized text string, as described in the following code
moreInfo	The link to the item within the Allegra system
isCreated	True if this item was just created
isCopy	True if this item was just copied
oldIssue	Only if copied: the original item number
isAddComment	True if a comment was added
isEditComment	True if a comment was edited
isDeleteComment	True if a comment was deleted
isOtherChanged	True for any change that was not specified more explicitly
isManagerChanged	True if the manager was changed
isResponsibleChanged	True if the editor was changed
isDateChanged	True if the start or end date was changed
isMove	True if the item was moved to a new item type or workspace
isStateChanged	True if the item state was changed
isResponsibleChanged	True if the responsible agent was changed
isClose	True if the item was closed
isReopen	True if a closed item was reopened
changedBy	The person causing the email event
createdBy	The person who created this item (in case of create)
shortFieldChanges	A list of the 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
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 has been changed
longFieldChanges.fieldChange.newShowValue	The new or actual attribute value
longFieldChanges.fieldChange.oldShowValue	The old attribute value

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