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