Tutorial

Sending emails

cplaceJS also provides an api to send emails from inside a script. This api features a powerful templating mechanism which enables you to generate dynamic emails in a breeze.

Note: In order for this api to work as expected sending emails with cplace has to be enabled and configured properly.

Let's say we're writing an email notification for some development process where the developer can request someone else to review the result for higher tier clearance. Our script will be executed inside a change listener whenever the status attribute cf.cplace.issue.status is set to be in review and shall notify whoever is referenced as reviewer about the request.

Table of contents
  1. Basic command
  2. Templating
  3. Template conditions
  4. Internationalization
  5. Setting the sender

Basic command

The most basic call provides just the mandatory properties to, subject and message:

cplace.actions().sendMail({
    to: 'mustermann@test.tricia',
    subject: 'Review for issue #1337',
    message: 'Hello Mustermann, issue #1337 is ready for review.'
});

This will use the configured email account from the configuration.txt as the sender (people will probably be receiving emails from someone named cplace).

Templating

The basic mail will most likely not match any of our requirements other than an email being sent, so let's enhance our code by setting the properties depending on the issue the listener was fired for:

var issue = changeEvent.getEntity();
var reviewer = issue.get('cf.cplace.issue.reviewer');
cplace.actions().sendMail({
    to: reviewer.getBuiltinFeatureValue('login'),
    subject: 'Requested review for ' + issue.getName(),
    message: 'Hello ' + reviewer.getName() + ', your review was requested for ' + issue.getName()
});

We get the reviewers email address by reading the builtin login feature which holds the user's address and then replace some parts of the subject and the message to make that dependant to the triggering page. This can be optimized even further by using the featured templating/substitution mechanisms:

    ...
    subject: 'Requested review for $issueName$',
    message: 'Hello $reviewerName$, $developerName$ requested your review on $issueName$',
    substitutions: {
        issueName: issue.getName(),
        reviewerName: reviewer.getName(),
        developerName: cplace.utils().getCurrentUser().getName()
    }
    ...

This way the template reads way better and everything is tidied up and drawn together.

Template conditions

The cplaceJS template substitution can also differ different states conditions and behave different if needed. The syntax for that may seem a bit confusing so we will look at it step by step:

Each condition is split into three control-parts:

  1. $[condition$ marks the beginning and the positive case
  2. $]condition[$ divides the positive and negative cases and the negative case and
  3. $condition]$ marks the end of the condition

When constructing conditions it is helpful to write this underneath like this

$[condition$
    value_if_true
$]condition[$
    value_if_false
$condition]$

and then collapse it to one line:

$[condition$ value_if_true$]condition[$ value_if_false$condition]$

So if we want to put an URGENT: marker in front of the subject if the developer has marked the issue as urgent we would do

$[isUrgent$
    URGENT:
$]isUrgent[$

$isUrgent]$

and then collapse to

$[isUrgent$ URGENT: $]isUrgent[$$isUrgent]$

Now we can put this into our subject line and add the substitution:

    ...
    subject: '$[isUrgent$URGENT: $]isUrgent[$$isUrgent]$Requested review for $issueName$',
    message: 'Hello $reviewerName$, $developerName$ requested your review on $issueName$',
    substitutions: {
        issueName: issue.getName(),
        reviewerName: reviewer.getName(),
        developerName: cplace.utils().getCurrentUser().getName(),
        isUrgent: issue.get('cf.cplace.issue.isUrgent')
    }
    ...

Internationalization

The send mail api is (other than the send notification) not capable of internationalizing displayed texts. So before you send out emails be sure the recipients are actually able to understand them and write the template and substitutions in an appropriate language.

Setting the sender

In a last step we want to now set the developer triggering the script as the sender of the email. This way the reviewer can directly reply to the developer (or just see who triggered the email). For this we use the same methods as we used for the reviewerName earlier:

var currentUser = cplace.utils().getCurrentUser();
cplace.actions().sendMail({
    fromAddress: currentUser.getBuiltinFeatureValue('login'),
    fromName: currentUser.getName(),
    ...
});

So in the end we get something that should look like this:

var issue = changeEvent.getEntity();
var reviewer = issue.get('cf.cplace.issue.reviewer');
var currentUser = cplace.utils().getCurrentUser();

cplace.actions().sendMail({
    fromAddress: currentUser.getBuiltinFeatureValue('login'),
    fromName: currentUser.getName(),
    to: reviewer.getBuiltinFeatureValue('login'),
    subject: '$[isUrgent$URGENT: $]isUrgent[$$isUrgent]$Requested review for $issueName$',
    message: 'Hello $reviewerName$, $developerName$ requested your review on $issueName$',
    substitutions: {
        issueName: issue.getName(),
        reviewerName: reviewer.getName(),
        developerName: currentUser.getName(),
        isUrgent: issue.get('cf.cplace.issue.isUrgent')
    }
});