Skip to end of banner
Go to start of banner

sendEmail

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Availability

This routine is available since katl-commons 1.0, changed in 1.1.14 (for JIRA 4.3.x and 4.4.x) and 2.0.7 (for JIRA 5.x) .

Syntax:

sendEmail([from], to, [cc], subject, body_or_template, [language])


Since katl-commons 2.0.7, we also have support for attachments using one of two forms:

sendEmail(from, to, cc, subject, body_or_template, language, issue_key, regex_array)

sendEmail(from, to, cc, subject, body_or_template, language, wildcard_path_array)

Description:

Sends an email. to and cc are string arrays with any of email addresses, users or groups, in which case an email will be sent to all the users of the groups.from is optional; if missing the email will be sent from the default email address configured in JIRA.

The last parameter is the language and it is available in the full form of the routine. To pass the language, you must specify the sender, to, cc, subject, body and finally the language, as a string  (e.g. "en", "fr", "en_US", "ro", etc.). However, this is relevant only if you use templates, since these support internationalization. For example, an email sent with language "en" will look for templates in the folder called "en", inside the default template directory. If no such template is found, it will use the one in the default directory. Also, since katl-commons-1.1.1, a default template placed in the default directory is mandatory for each template name used in your SIL programs. For example, if you want to use a template "t.tpl" using language "en_US",it is not only necessary to have "t.tpl" in the "en_US" folder, but you must also have a file "t.tpl" in the default directory.

If you don't specify the language parameter and you use templates, by default the messages are sent in the sender defined language. For the users that are JIRA users(to or cc are user names and not email addresses) it can be used the language defined in the user profile(for each user) for the sending of the email, by configuring it. For the rest of the users the email will be sent using the sender defined language.

 

Starting from version 4.0, the engine automatically detects HTML or plain text messages.

Parameters:

Parameter name

Type

Required

Description

from

string

no

the from address

to

string []

yes

recipient list

cc

string []

no

CC'ed recipient list

subject

string

yes

subject

body_or_template

string

yes

message body, either direct or a template

language

string

no

the language used to send the email(relevant only if you use templates)

issue_keystringnothe issue to extract attachments from
regex_arraystring []if issue_key is presentname patterns to match the attachments from the issue
wildcard_path_arraystring []noabsolute paths containing wildcards for attaching files from disk

Alias:

For historical reasons, this routine may be named 'sendEmailFrom'

Starting with version 4.0, 'sendHtmlEmail' was registered as an alias, too (there is no need for sendHtmlEmail anymore)

Example:

Example 1:

sendEmail("projectmanager", "teamleader1", "Transition executed", currentUser() + " has executed a transition");
// here we have to, cc, subject and body.
// The from and language parameters were omitted.

Example 2:

If SendEmailLanguage has the value receiver_language, testJiraUser1 is a JIRA user having the defined language French and testJiraUser2 is a JIRA user having the defined language German

string [] to = {"testJiraUser1", "testEmail@kepler.ro", "testJiraUser2"};
string [] cc = {"testEmail2@kepler.ro"};
sendEmail("testFrom@kepler.ro", to, cc, "testSubject.tpl", "testBody.tpl");

Result: It will be sent one email in French for testJiraUser1, one email in German for testJiraUser2 and one email in the sender defined language for testEmail@kepler.ro(as to) and testEmail2@kepler.ro(as cc).

Example 3:

Is similar with example 2, but here the language parameter is used.

If SendEmailLanguage has the value receiver_language, testJiraUser1 is a JIRA user having the defined language French and testJiraUser2 is a JIRA user having the defined language German

string [] to = {"testJiraUser1", "testEmail@kepler.ro", "testJiraUser2"};
string [] cc = {"testEmail2@kepler.ro"};
sendEmail("testFrom@kepler.ro", to, cc, "testSubject.tpl", "testBody.tpl", "en_US");

Result: It will be sent one email in English(because of the en_US language parameter).

Example 4:

This example will demonstrate the ability to attach files (to the email) selected from the attachments of the issue using regex patterns.

We will assume that the issue has three attachments: attachment1.txt, attachment2.txt and attachment3atxt (note that this last one does not have a dot to separate the extension).

Now let's see a few examples of regex patterns that will match some of the attachment. Note that we will use key to specify the current issue, but feel free to use any other issue key.

sendEmail("santa@kepler.ro", {"jira-users"}, {}, "santa_subject.tpl", "santa_letter.tpl", key, {"attachment.*"}); 

This will match all of the attachments. Since we are using regex patterns, attachment.* will match anything that starts with attachment.

sendEmail("santa@kepler.ro", {"jira-users"}, {}, "santa_subject.tpl", "santa_letter.tpl", key, {"attachment.\\.txt"}); 

This will match attachment1.txt and attachment2.txt. The first dot will match any character (the 1 and 2). Note that the second dot is escaped using double backslashes and will not match attachment3atxt.

sendEmail("santa@kepler.ro", {"jira-users"}, {}, "santa_subject.tpl", "santa_letter.tpl", key, {"attachment1\\.txt", "attachment3atxt"}); 

This will match attachment1.txt and attachment3atxt.

Don't forget to use double backslashes when escaping special characters in regex patterns.

Example 5:

You can also attach files directly from disk by specifying absolute paths. Note that you can also use * (anything) and ? (any single char) as wildcards.

sendEmail("santa@kepler.ro", {"jira-users"}, {}, "santa_subject.tpl", "santa_letter.tpl", {"C:/gifts/jira-users*.gift"}); 

Notes:

If you would like to use templates for emails, see the Mail Configuration page, as well as detailed explanations linked our template engine: SIL Template Language. Specifically, read Email Templates page.

See Also:

 

  • No labels