Email Templates

Email templates represent one of the first features of this app. Its initial implementation only allowed for simple variables to be injected into the templates. They are now based SIL Template Language and therefore their usage got a lot easier than before.

To be short the email templates mechanism is prefered and recommended way of sending emails from SIL scripts. The send Email() routine packs powerful tools.

Email templates obey the same rules as those presented in the general STL page above and in the previous chapter with some notable differences, introduced just to make your life easier.

Just to re-assure you, the email templates preserve the same behavior as stated before:

1. Variable resolution within the template remains the same; variables in the last context are injected in the upper context of the template execution
2. Context behavior is the same: if you are in the issue context, you are allowed to use any issue variable you want, such as key, assignee, reporter, dueDate, etc. Otherwise you will need to refer issue fields by using issue_key.field notation (e.g. IMJ-321.key).

Make sure you read sendEmail() routine documentation to see how it is called, and notice that it has many overloads.

Mail Templates Base Directory

Unlike usual templates, presented before, email templates got their own base directory, and you can configure that directory here. This is both for historical reasons and because we recognized the importance of organizing mail templates in our integration projects. Under this directory, you may organize language folders, which will be used to internationalize your email messages. This feature is controlled in the above configuration screen (Mail language on: Receiver). The default is set on Sender which simply uses the declared language of the sender user, whoever s/he may be.

It is important to remember that mail templates are resolved in line to this special directory. Let's see how this works with a little example.

Suppose you are asking for template named template.tpl and the language may be English, French or Romanian. To internationalize that mail message, you need to create a folder structure having sub-directories named either with languageCode_countryCode or simply languageCode, where languageCode and countryCode are 2-letters ISO standards:

The resolution of the template 'template.tpl' for an English speaker coming from Great Britain will be picked up from MAIL_TEMPLATES_BASE/en_GB/template.tpl, where MAIL_TEMPLATES_BASE is, in our case, KEPLER_HOME/templates directory.

Exactly the same way the resolution for an US English speaker will be MAIL_TEMPLATES_BASE/en_US/template.tpl. However, for a Canadian English speaker, the template used is MAIL_TEMPLATES_BASE/en/template.tpl (selected in the image above).

If we look at the French support, you will see that above we use the same template for all the French speakers, no matter what country they come from. And if we look at the Romanian support, we'll see that, because the internationalization directory ('ro') is missing, it will default to the MAIL_TEMPLATES_BASE/template.tpl.

Additional Injected Variables

In addition to the variables from the context, sendEmail routine defines a few more variables,  injected into the topmost context, as strings in your template:

1. recipient - the recipient (s) - if there are more than 1 recipient, recipients are joined together with a comma between them

2. sender - the sender - but only if the sender is defined.

Usage Examples

Do you have cookies?

To exemplify the usage, let's write a post function:

string cookie = "We have cookies!";

sendEmail({"spam.receiver@kepler-rominfo.com"}, "Xmas", "basic_template.tpl");

And put a template into our base mail template directory, named basic_template.tpl:

Hello $recipient$,

This is a test template sent from $assignee$'s issue $key$. The summary  for this issue is: $summary$.

$assignee$ says that $cookie$

Variables from our script are exposed into the template (cookie seems unused, but it is not!). This template must run in an issue context, since it refers the pre-defined variables from the issue.

Bruce Wayne

Let's try to categorize our customers on either Batman's side, the evil side or neutral side. If we create a customfield customerId, which is a numeric code provided by the user, the following postfunction will complete a variable (custName) with the company name. In production systems, I suppose, you may want to get that customer name from a database (see the sql() routine). For this example, a bit of logic will allow us to distinguish between the Batman's owned corporation and ... eh, a phantom, evil, one:

string custName = "";

if(customerId == 1) {
  custName = "Evil Corporation";
} else if(customerId == 2) {
    custName = "Wayne Enterprises";
}

sendEmail("mysender@kepler-rominfo.com", "torecipient1@kepler-rominfo.com", "ccrecipient@kepler.ro", "Your issue:" + key, "template.tpl");

Now, customerId is either the name of the customfield or an alias to it (recommended).

Let's write our template, this time a html email:

<html>
<body>
Hello $reporter$ from $custName$, the sender $sender$ announces you that the assignee for issue $key$ is $assignee$ and that work has started
$!
//this is a simple script, not carrying too much meaning, but just used as an example.
for(number i = 0; i < 3; i++) {
    $
    <p>
        Hip!
    </p>
    $!
}
$
<p>
    Hooray!
</p>
</body>
</html>

Now, Hip! Hip! Hip! Hooray! will be put in your email (4 paragraphs). Use standard CSS to nicely format your html email messages.