Contents

JQL support is a long awaited feature that we added to Power Scripts™ v4.0 and it helps you leverage power of JQL and work around Jira limitations. There are two flavors of searching, one based on simple boolean expressions and another based on already saved scripts.

Simple Issue Language™ JQL Support page

You can access this page from Administration > SIL JQL Support. Here you can set the number of results that will be displayed for every user group.

• JQL Default Value — set the default value, that is the number of issues that will be returned by a JQL query for a user that is not a member of any listed group. Defaults to 1000.
• Unlimited — if selected, the results will not be limited but this might cause performance issues.
• Operations — In the table you can view the values for the groups already configured. You can edit and delete those rules.
• For a given user, the number of returned results is calculated as the maximum between the default value and the maximum value of the groups where the user belongs.

Searching issues

One of JQL limitations where users struggle the most is the inability to search for simple expressions. For instance, you can't search for issues where the reporter is the same as the assignee. This is due to the fact that JQL expressions are evaluated once at the beginning of the search and that it accepts only <field> <operator> <constant> expressions in search.

silJQLExpression / expression

Let's see what silJQLExpression can do.

silJQLExpression(sil_boolean_expression, JQL_filter)

This JQL fragment accepts two parameters: the first one is any SIL™ boolean expression which will be run on each matching issue, the other is a JQL expression used for initial results filtering on which the expression is applied. silJQLExpression can only be applied on issues, it cannot be used to search another object types in Jira.

Starting with version 4.1.1 of Power Scripts™, an alias exists for the silJQLExpression: due to the popular request, we named it expression

expression(sil_boolean_expression, JQL_filter[, param1[, param2, .....]])

In the following example, we're searching for all bugs in the TEST project that have the same user as the reporter and assignee:

key in silJQLExpression('reporter == assignee', 'project = TEST and issueType = \"Bug\"')

This script does the following:

1. Runs the filter JQL, if provided. If empty, it will get all the issues from all the projects to which the user has access.
2. If there are issues, it generates a simple script starting with the expression you provided.
3. For each issue, it runs the script; if expression is true, key is retained.
4. It returns the keys array back to the JQL so it can further processed by some other JQL expressions.

Considering performance during search

Notice that the filtering is of paramount importance, although you can provide an empty string there, this is really not recommended.

For instance, the following JQL is valid and serves the same purpose as above:

key in silJQLExpression('reporter == assignee', 'project = TEST') and  issueType = "Bug"

However, this is not quite right. The expression will be evaluated on all issues from that TEST project, and this is not really desirable when you have another filter condition to apply. Re-writing it in the first form avoids this, so be cautious when you see clauses linked by AND on the same level as the silJQLExpression construct.

More Complex JQL

You can construct any arbitrary JQL starting with this expression:

key in silJQLExpression('reporter == assignee', 'project = TEST and  issueType = "Bug"') or (project = CCIR and issueType="Epic")

silJQL and silJQLList

What if the expression you are looking for is much more complicated? What if the expression is in fact a big chunk of logic and you need to obey to it to find your issues? We introduced two more JQL expressions:

• silJQL
• silJQLList

silJQL(path_to_sil_file, param1, param2, ...)
silJQLList(path_to_sil_file, param1, param2, ...)

Both expressions receive the path to a SIL™ file as first argument, and (optionally) parameters to run that script. The difference between them is that silJQL returns a single result, while silJQLList returns a list of results.

Therefore silJQL can use operators like =,  !=, >=, <= ... while silJQLList can use operators like in, not in, and so on.

silJQL - single issue search

Let's see an example to see what these expressions can do. At first, we'll create a script in a file using SIL™ Manager, and name it test.sil.

string [] keys = selectIssues("project = " + argv[0] + " and issueType = 'Bug'"); //we receive a parameter representing the project
number ndx = random(size(keys)); //get a random number as index
return keys[ndx]; //return the key, randomly picked. a little evil, but ... funny!

After we saved the file, let's use our newly created script in search:

key = silJQL("test.sil", TEST)

Performing the search several times, you will see that the searched issue changes, depending on that random value.

You will notice that we passed the project as a parameter to the SIL™ script, and that the file will be resolved normally relative to the root (silprograms). You can pass any parameters you like there. The script runs in the Jira context, and not in the issue context.

silJQLList - multiple issue search

The following example is returning more than one ticket:

string [] keys = selectIssues("project = " + argv[0] + " and issueType = 'Bug'");
string [] ret;
for(string k in keys) {
    if(%k%.id % 3 == 0) { ret += k; } //if the id is divisible with 3, it's selected
}
return ret;

Now we'll save it as test1.sil and perform the following JQL:

key in silJQLList("test1.sil", TEST)

The results returned will look like the following image:

Performance during search

When you build filtering expressions, keep in mind that the overall performance of the script impacts the search performance.

Other searches with silJQL and silJQLList

Using silJQL and silJQLList you can also get other values, not just issue keys. For instance, consider the following script:

string [] additionalIT;

//.....very complex logic
additionalIT += "Sub-Task";
//... more complex logic

return "Bug", "Task", additionalIT;

If you perform a search using the silJQLList, but you base the query term on the issuetype this time, then the issue types will be filtered from the values returned from that nice SIL™ script.

project = TEST and issueType in silJQLList("test_issty.sil") and status in (Open, Reopened, "To Do", "In Progress")

You can use the same technique with statuses, components, and so on.

Additional notes

Search performance can be further improved either by using pre-defined JQL functions or by using functional indexing, we added both features in the version 4.1.1 of Power Scripts™ for Jira:

• Experimental JQL features
• Pre-defined JQL functions