On this page:
| Table of Contents |
|---|
Email Templates
Email templates represent one of the first features of this add-onapp. 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.
In short,Excerpt
, as you will see shortly. 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:
- Variable resolution within the template remains the same; variables in the last context are injected in the upper context of the template execution
- 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 normal 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' 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 relative 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' 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 MAILwhere MAIL_TEMPLATES_BASE is, in our case, KEPLER_HOME/templates directory. Similarly,
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 will be 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.
| Note | ||
|---|---|---|
| ||
If you need to send the same mail in multiple languages, do not mix templates used with the executeTemplate() routine with the sendEmail() routine. Keep them separate. Of course this is valid only if templates are different, if you use the same for both emails and something else, put them in the same place. |
...
Additional Injected Variables
...
In addition to the variables from the context, sendEmail routine defines in your template a few more variables, also injected injected into the topmost context, as strings in your template:
recipient - the recipient recipient (s) - if there are more than 1 recipient, recipients are joined together with a comma between them
sender - the sender - but only if the sender is defined.
Usage Examples
...
Do you have cookies?
...
To exemplify the usage, let's write a postfunctionpost function:
| Code Block |
|---|
string cookie = "We have cookies!";
sendEmail({"spam.receiver@kepler-rominfo.com"}, "Xmas", "basic_template.tpl");
|
... and let's And put a template into our base mail template directory, named basic_template.tpl:
| Code Block | ||
|---|---|---|
| ||
Hello $recipient$, This is a test template sent from $assignee$'s issue $key$. The summary for this issue is: $summary$. $assignee$ says that $cookie$ |
Again, variables from 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:
...