Script Rule
- Ryan Clifton
Summary
Script rules allow custom logic to be used to determine a matching project mapping via user-made scripts. This enables routing of emails in event the most complex business. Support for JavaScript code is built in - alternatively it is possible to install additional runtime engines to be used instead.
Script rules are an advanced feature and therefore at least a basic understanding of JavaScript and Project Mappings is required in order to use the feature effectively.
Creating a Script Rule
Go to Profile > A Non-default Project Mapping > Script Rules and press New Script Mapping.
This will then open the configuration for the New Script Mapping. Here you enter the relevant Script and Language and then press Save.
Now you will be able to configure the other tabs within the Script Rule. e.g. Issue, Email and Custom Field Defaults.
Once everything is configured and saved, you will be able to view the Script Rule config within the Script Rule Summary.
Configuration Options
Show script context
This displays the context for script rule execution.
Script
This is where the custom script is entered. This script is used to determine whether the email should be matched by this Script Rule.
Language
This defines the language that the Script Rule will use when creating and running the script. Support for JavaScript (Nashorn) code is built in - alternatively it is possible to install an additional runtime engine which can be used instead.
See the following page for information about installing additional scripting languages: Install a Scripting runtime Engine (Nashorn, Groovy, Graal) | Summary
Debugging a Script Rule
Script rule behaviour and matching outcome can be tested against example email content provided via JEMH Test Cases. From the edit view of an existing script rule you can execute a script live against a provided test case and review the match result and any console output generated by the script execution.
Add debug output to script
From a JEMH Project Mapping either create or edit an existing script mapping rule and enter your desired script content. For debugging purposes the print() method can be used to output variable values or other information:
Validate against test case
A test case associated with the current JEMH profile can be selected to run the current script content against. A list of available test cases are shown in the Test Case field:
Once a test case has been selected the Check Rule button can be used to run the current script content against the selected test case:
The match status of the executed script will be shown in the lozenge to the right of the Check Rule button and any console output produced by the executed script will be shown in a text box below the test case selector along with the total execution time of the script:
Example Script Rules
For some example Scripts see: Example Script Rules
How to drive creation of multiple issues in other projects from a Script Rule
since 3.3.12 (requires Jira 8.0+)
We have now made it possible to use the Rule Script in the same way that could be done with the Script Field Processor (see Create multiple issues from a single email ).
The Script
Here is an example script which uses nothing more than the presence of ‘hello’ to exist in the email subject, insert your own logic there. As before we use {{jemhUtils.createResultSet()}} to create a holder for a new set of values that will be used to drive issue creation. The requirement in this (Rule drive) scenario is that there must be a value stored against {{project}}, without which the set of values will be ignored. By defining a value for the {{project}} JEMH will fill in additional fields from the JEMH Project Mapping for the related project (or Default Project Mapping if none are found). Its important to validate any supplied data here is actually valid, e.g. issueType, priority, reporter.
The use of ‘comment’ might seem odd here, its how we use email body content to become either the description, or comment, depending on circumstance.
if (subject.contains('hello'))
{
result.setMatch(true);
resultMap.put("lables", "labelx,labely");
resultMap.put("priority", "highest");
print('adding result set to EMVT project');
var newResultSet = jemhUtils.createResultSet();
newResultSet.put("project", "EMVT");
newResultSet.put("summary", "Create an issuein EMVT");
newResultSet.put("issueType", "task");
newResultSet.put("priority", "highest");
newResultSet.put("reporter", "admin");
newResultSet.put("comment", "Create an issue in EMVT \n"+body);
print('adding result set to KP project');
newResultSet = jemhUtils.createResultSet();
newResultSet.put("project", "KP");
newResultSet.put("summary", "Create an issue in KP");
newResultSet.put("issueType", "bug");
newResultSet.put("priority", "highest");
newResultSet.put("reporter", "admin");
newResultSet.put("comment", "Create an issue in KP \n"+body);
print('adding result set to TASK project');
newResultSet = jemhUtils.createResultSet();
newResultSet.put("project", "TASK");
newResultSet.put("summary", "Create an issue in TASK");
newResultSet.put("issueType", "task");
newResultSet.put("priority", "lowest");
newResultSet.put("reporter", "admin");
newResultSet.put("comment", "Create an issue in TASK \n"+body);
}
Edit time verification of rule match and creation of additional resultSets
The validation of the script can be done at edit time, the result of all {{print('….')}} script methods are shown (including script rule match outcome, which is great for debugging:
Viewing the script created results
The result will show the primary resultSet (1) below, and if the script creates additional resultSets, they are also shown (2, 3, 4):
Validation - running the Test Case
After executing the JEMH Test Case against the Profile containg the Project Mapping Rule script above, the summary shows the primary and additional issues created:
For additional debugging, the resultMaps generated are also stored in the Report detail, which shows the result after applying values for the Project Mapping field values