JavaScript Custom Field Defaults - Since 4.1.14
- Ryan Clifton
- Andy Brook [Plugin People]
Summary
Within 4.1.14+ we have included JavaScript to be used within Custom Field Defaults. While in the custom field default edit screen, select Script value for the Field Value Type. Five new page elements should be displayed:
Elements
1 | Language | Used to determine the script language to use |
2 | Show script Context | Press this to get some additional information on the classes that are exposed for use |
3 | Test Case | This is the Test Case that the script will be tested against. |
4 | Evaluate | This will evaluate the Script against the selected Test Case and will output the relevant values. |
5 | Custom Field Value | This defines the value that will be given to the Custom Field once the script is evaluated. |
Setting Field Values
With this new method of defines Custom Field Default values you must use the following to define the value that will be set for the Custom field.
result.setValue("This is a custom field value");Also with this new method you are able to output some print commands which will be shown within the Output section when the Script has been evaluated. Below is an example of how to show output messages within the script.
print('Hello, World!\n');Script evaluation
Using values from the incoming email
Referring to $message will allow you to retrieve information using the methods available for Message (Java Mail API) objects. For example, lets say we want to get the value from an email's "References" header:
var references = message.getHeader("References");
var value = "";
for (i=0; i< references.length; i++)
{
print(references[i]);
var value = value + references[i];
}
result.setValue("References: " + value);Will render the Emails References (if it has one)
Useful specific email related values
context variable | Data Type | Description |
|---|---|---|
message | javax.mail.Message | the raw message object |
subject | java.lang.String | the Subject text |
| java.lang.String | The Mailbox catchEmailAddress |
fromAddress | javax.mail.InternetAddress | the from: address |
toAddresses | javax.mail.InternetAddress[] | the to: addressees |
ccAddresses | javax.mail.InternetAddress[] | the cc: addressees |
bccAddresses | javax.mail.InternetAddress[] | the bcc: addressees (don't expect many here!) |
allAddresses | javax.mail.InternetAddress[] | all addressees |
body | java.lang.String | the post processed (html > markup) content |
Setting a custom field value based on the sender domain
Using values from the related Jira Issue
This only applies if the email is commenting on an issue
If the email is determined to be commenting on an existing issue, you can retrieve information from it by referring to issue and using methods available for TemplateIssue (JIRA API) objects. For example, we could get the issue priority:
This currently results in an error when using the Custom Field Validation. However, this functions correctly at run time (when processing incoming mail). We have a internal ticket to resolve this. Note: This class may be change to use relatedIssue instead.
Using values from LDAP queries
The jemhUtils class has LDAP querying capabilities, available in Script Field Processor (javascript) and Custom Field Default (JavaScript, shown below) contexts. See Using LDAP in Script Field Processor for available LDAP methods and definitions for LDAPUser.
Example JavaScript
Example edit time preview
Using values from a JSON Object retrieved via JIRA REST API
The invokeLocalRest method added to $jemhUtils enables the velocity script to send GET requests to the JIRA REST API. The method returns a JSONObject, which if the REST call was successful will contain data that the script can manipulate to extract the value required. In this example we will try to retrieve issue data via the REST API for a hard-coded issue and get the ID of the issue.
The previously linked REST API documentation shows us what we can expect the response data to look like. Here is an excerpt of the JSON data that our example JIRA would return for issue TEST-1:
Configuration
Go to the Project Mapping where you want the custom field value to apply. Create a new custom field default (as explained earlier on this page) and edit it. Change the Field Value Type to Script Value and enter your JavaScript. Here is an example script:
Note that the above is a very simple example of what is possible - it checks that the REST call was successful and renders the ID value.
Authentication
If the sender of an email is found to be a JIRA user, they will be the used for authenticating the REST call. If the sender does not have a JIRA user account, the Profile's Default Reporter is used instead. If no default reporter is set and the sender is not a JIRA user, then the REST call will not succeed.
Additional examples
See the following pages for some additional JavaScript examples: