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.

../../_images/mailTemplate11.png

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.

../../_images/mailTemplate2.png
../../_images/mailTemplate3.png

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.

../../_images/mailTemplate4.png

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