Page Comparison

Syntax

...

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

Since Starting with katl-commons commons 2.0.7, we also have support for attachments using one of two formsthe syntax is following:

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)

Or

sendEmail(JEmailMessage)

Description

...

Excerpt
Sends an email. to and cc are

To and cc are string arrays with any of email addresses, users or groups

...

. Email is sent to all the users of the groups.

...

From is optional. If missing the email

...

is 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. string (for instance "en", "fr", "en_US", "ro", etc.and so on). However, this is relevant only if you use templates , since these support internationalization. as they support localization.

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 starting with 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 to 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 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) is used for the sending of the email, by configuring it email sending. For the rest of the users the email will be is sent using the sender defined language. 

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

Parameters

...

Parameter name	Type	Required	Description
from	string	no

the from

From address
to	string []	yes

recipient

Recipient list
cc	string []	no	CC'ed recipient list
subject	string	yes

subject

Subject
body_or_template	string	yes

message

Message body, either direct or a template
language	string	no

the language

Language used to send the email(relevant only if you use templates)
issue_key	string	no

the issue

Issue to extract attachments from
regex_array	string []	if issue_key is present

name

Name patterns to match the attachments from the issue
wildcard_path_array	string []	no

absolute

Absolute paths containing wildcards for attaching files from disk

Or

Parameter name	Type	Required	Description
JEmailMessage	JEmailMessage	yes	Predefined email message structure. The structure contains the following fields
			Field Name	Field Type	Required	Description
			to	string []	yes	see above
			cc	string []	no	see above
			bcc	string []	no	see above
			subject	string	yes	see above
			message	string	yes

...

see above
from	string	no	see above
attachments	JEmailAttachment []	no	see above
plainText	boolean	no	forces sending email in plain text format

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

...

Code Block
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 Jira user having the defined language French and testJiraUser2 is a JIRA Jira user having the defined language German.

Code Block
string [] to = {"testJiraUser1", "testEmail@keplertestEmail@cprime.rocom", "testJiraUser2"}; string [] cc = {"testEmail2@keplertestEmail2@cprime.rocom"}; sendEmail("testFrom@keplertestFrom@cprime.rocom", to, cc, "testSubject.tpl", "testBody.tpl");

Result: It One email in French will be sent one email in French for to testJiraUser1, one email in German for testJiraUser2 and one email in the sender defined language for testEmail@keplertestEmail@cprime.rocom(as to) and testEmail2@keplertestEmail2@cprime.rocom(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 Jira user having the defined language French and testJiraUser2 is a JIRA Jira user having the defined language German.

Code Block
string [] to = {"testJiraUser1", "testEmail@keplertestEmail@cprime.rocom", "testJiraUser2"}; string [] cc = {"testEmail2@keplertestEmail2@cprime.rocom"}; sendEmail("testFrom@keplertestFrom@cprime.rocom", 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.

...

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.

Code Block
sendEmail("santa@keplersanta@cprime.rocom", {"jira-users"}, {}, "santa_subject.tpl", "santa_letter.tpl", "en_US", key, {"attachment.*"});

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

Code Block
sendEmail("santa@keplersanta@cprime.rocom", {"jira-users"}, {}, "santa_subject.tpl", "santa_letter.tpl", "en_US", 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.

Code Block
sendEmail("santa@keplersanta@cprime.rocom", {"jira-users"}, {}, "santa_subject.tpl", "santa_letter.tpl", "en_US", key, {"attachment1\\.txt", "attachment3atxt"});

...

Note
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.

Code Block
sendEmail("santa@keplersanta@cprime.rocom", {"jira-users"}, {}, "santa_subject.tpl", "santa_letter.tpl", {"C:/gifts/jira-users*.gift"});

Example 6 - JEmailMessage

...

You can also use the JEmailMessage structure type when sending an email. This option can make the code a little cleaner.

JEmailMessage email;
email.to = {"testJiraUser1", "testEmail@cprime.com", "testJiraUser2"};
email.subject = "Email to Santa";
email.message = "Dear Santa, I want a train.";

sendEmail(email);

Here is the same example that includes adding attachments to the email. This requires the use of the JEmailAttachment structure type.

JEmailMessage email;
email.to = {"testJiraUser1", "testEmail@cprime.com", "testJiraUser2"};
email.subject = "Email to Santa";
email.message = "Dear Santa, I want a train.";


for(string a in attach) {   
    JEmailAttachment att;
    att.name = a;
    att.file = getAttachmentPath(key, a);
    email.attachments += att;
}

sendEmail(email);

Notes

See

...

also