Custom JQL Functions
The benefit of using ScriptRunner for JQL functions (rather than writing your own) is you get the ability to return a Lucene query using the issueFunction custom field (fast) rather than a list of literals (very slow). Any changes you make to the script are automatically recompiled when you execute it.
Caution though, this is harder than most other customizations. You will almost certainly require a working IDE.
There are two types of custom functions in essence:
A query on issues, where you should return a lucene query object
A query on anything else, eg users, projects, components, where you return a list of pointers to these objects
There is an example below of each type.
Use one of the examples below, and modify it to suit.
Modify the class name to something of your choice
Specify arguments if required
Implement argument validation
Click the scan link at ScriptRunner → JQL Functions.
The scan function is only required when you first add a JQL function to a running Jira instance. From this point on it will automatically be loaded when Jira starts, so you should never need to click the scan link more than once per function you add. See Scanning for JQL functions for more information on scanning.
When you are happy, test in the issue navigator. Make sure you test your error handling by entering incorrect parameters, the wrong number of parameters, and as different users.
You can modify the code, when you re-run the query via the issue navigator (or REST etc), your new code will be automatically recompiled. As always, tail the log while you are working, so you can see compilation errors etc.
Scanning for JQL functions
For the scanning process to recognize your class as a JQL function you must either:
com.onresolve.jira.groovy.jql.JqlQueryFunctionfor functions that utilize issueFunction (and have a
com.onresolve.jira.groovy.jql.JqlValuesFunctionfor functions that return a list of QueryLiterals from the getValues() method.
To make life easy you should extend
You need to implement
getArguments(), which simply provide information to the drop-down list, but otherwise have no functional effect.
Your function must reside under the
com.onresolve.jira.groovy.jql package for it to be found. You can create these directories under one of your script roots as follows:
- Navigate to ScriptRunner → Script Editor.
- Select the Add Folder icon.
- Enter com/onresolve/jira/groovy/jql.
- Select Add.
This creates the nested folder structure needed.
- Add the JQL function script under the jql folder calling it the same name as the class name in the script.
JQL Alias Example
Sometimes you will have a complex query that is required for, for example, generating release notes. Expecting users to type it all correctly is unlikely to work. This function allows you to take a complex query, and parameterize it to something simpler.
In this contrived example, running
issueFunction in releaseNotes(1.1), will actually run
project = JRA and fixVersion = 1.1 and affectedVersion = 1.1.
In the real world, the real query would likely be much more complex.
Note that the validator validates the aliased query, so we can trap errors like the user providing a version that doesn’t actually exist.
Project Versions Example
This JQL function returns issues that have a fix or affects version where the version is not released, but the start date, if present, is in the past.
We suppose this might let you infer what will be released soon. It would be used as in:
fixVersion in versionsStarted(). It is not really intended to be useful, just a guide.
Because this function is applicable to Version fields (ie fix and affects versions, single and multi version custom fields), we implement
JqlFunction rather than
JqlQueryFunction, and need to return a list of
QueryLiteral. See the notes below the code.
- No arguments for this function
- We must specify the type that we are returning
- Versions not released, having a start date, and the start date is before today
- Filter just those current user has permission to see the project of
- Create the
QueryLiteralfrom the version identifier
Custom function to return the last Friday of any given month - on Answers