Script Roots

Previously when entering a file to be run (console, workflow function, script field etc) you were required to give the full script path, or the path relative to the catalina.base directory.

This version introduces the concept of script roots - these are directories in whose files and subdirectories you can keep your scripts. The advantages of this is that changes to dependent classes will be detected automatically, and get automatically recompiled. Note - the one exception is when you first change a dependent class without having changed the class/script that’s actually called (a JQL function, workflow function etc). In this case, make some irrelevant change like adding a space to a comment to the calling script. After having done this, changes to the base or dependent class will trigger recompilation of both.

When the plugin is first installed it will create a directory called "scripts" under your Jira home directory, and register it as one of its script roots. This should be sufficient for most users and no other configuration need be made. This is a logical place to store your scripts, as it’s preserved during Jira upgrades, and by definition will be accessible by all nodes in a clustered Jira.

You can create subdirectories for your scripts, perhaps dividing them up into the business processes they support. You can also create supporting or utility classes to be used by them, but ensure they have the correct package, otherwise you will get a compilation error.

For instance, a script and a class:

<jira-home>/scripts/foo.groovy

groovy
import util.Bollo

log.debug ("Hello from the script")
Bollo.sayHello()

<jira-home>/scripts/util/Bollo.groovy 

groovy
package util

public class Bollo {
    public static String sayHello() {
        "hello sailor!!!"
    }
}

Absolute paths outside of script roots will continue to work, although changes to dependent classes may not get picked up.

Upgrading from previous versions

In previous versions of ScriptRunner, relative paths were resolved to the container working directory, ie $catalina.base on Tomcat.

This is no longer the case,​ relative paths will be resolved relative to each of the script roots until a file is found. If you don’t wish to change all your paths, you can add a new script root, pointing to either the working directory, or better, to where you had your scripts.

For instance, let’s say your jira instance is in /usr/opt/jira, and you had your scripts in /usr/opt/scripts. Therefore you would have referred to them as ../scripts/foo.groovy.

Now you will add a new property pointing to your scripts dir:

set JAVA_OPTS=%JAVA_OPTS% -Dplugin.script.roots=/usr/opt/scripts

Resolving ../scripts/foo.groovy relative to this script path will have the same result.

If you have multiple roots then use a comma to delimit them.

If you are working on a script locally before deploying to production, you can set breakpoints in scripts or classes and attach the debugger.

If you are working on the plugin it makes sense to add the src and test directories from the checkout, so you can work on the scripts without having to recompile.

set JAVA_OPTS=%JAVA_OPTS% -Dplugin.script.roots=checkout-directory\src\main\resources,checkout-directory\src\test\resources

Script root search

ScriptRunner has the ability to search for scripts contained within your configured script roots. Wherever you were able to enter the path of a script to run, you can now search for the script directly in the script file input. You can search by script name, or traverse the sub-directory structure to find the script you’re looking for!

To help you easily find the scripts you’re looking for, here are a few tips:

Find a script by name

If you know the name of the script root you can simply start typing the name of the script you want in the normal file entry:

  1. Start typing the name of the script you want to find

  2. After typing the first character, the search will return results that you can select from

    If there are too many results, simply keep typing characters to refine the search.

  3. When your script is found, either:

    • Highlight the script you want by moving down to it with the keyboard (down key) then press "Enter"

      OR

    • Use the mouse to left-click the script you wish to select

  4. The script will now be loaded for use and the static-type checking will begin

If you don’t know the name of the file, but suspect that exists somewhere in one of your script roots, you can browse the directory structure under those roots until you find it:

  1. Start typing the name of the sub directory you want to browse in your script root

  2. After typing the first character, the search will return results that you can select from

    If there are lots of directories returned, you can simply keep typing to refine the search. As you add characters to your search phrase, the results will be refined.

  3. Once you find the directory you wish to check inside:

    • Left-click the desired directory

      OR

    • Press the "Down" key on the keyboard to highlight the entry, then press the "Tab" key

  4. Now you will see a list of scripts and subdirectories in that directory!

  5. Repeat that process until you find the script you are looking for

When you navigate into a directory, the results will only show the scripts in that directory. If you want to search ALL scripts, just remove all characters from the input and start again.

You can use tab completion to navigate the directory structure. If you go too far, simply remove the characters to the previous slash and then the search should come back with the correct results.

Result Types

This table demonstrates the different types of result that the search could return.

IconDescription

An executable groovy script

A sub-directory within one of your script roots

Referring to classes in the script root

When writing scripts you may find that there is certain logic which you reuse over and over. Rather than redefining the same logic in all the places where you want to use it, you could instead create a utility class to store the logic. You can then call that class in all the places where you want to use this logic. In this example, we use the Script Editor to demonstrate how to create a helper class, and then how to call that class from other scripts.

  1. In ScriptRunner, go to Script Editor. 
  2. Create your helper classes folder structure.
  3. Add the new class inside the last folder you created.
    Make sure your class name matches the file name without the '.groovy' extension.
  4. Give your new class a package name.
    The package name must match the folder structure with a '.' separating each level. In this example we have created a Utility class:
  5. Go to the ScriptRunner function where you want to use this Utility class.
  6. Import the class into your script using the import keyword, followed by the package name, and then the class name. For example import Utils.MessageUtils.MessageGenerator.
  7. Your script is now correctly referenced and you can proceed with your function or task.



On this page