The power of ScriptRunner

As you read in this previous post, a “plain” Jira instance already has ways to get data in and out. In Jira Server, you can also query the database to get data out (DON’T ever write directly in the Jira database!), which can be useful for reporting.

But one tool power up Jira a lot more, and it’s ScriptRunner. I had to work on a Jira instance without ScriptRunner once, and it’s more work.

Let’s go over each part of ScriptRunner, and explain how they help. As with Jira, ScriptRunner is available for Cloud and for Server. And, of course, the Cloud edition is less powerful than the one for Server, since Jira Cloud exposes less functionality to apps.

This publication will focus on ScriptRunner for Jira Server. A latter publication will talk about ScriptRunner for Jira Cloud.

First, the good old Script Console. It’s a small Groovy IDE built in Jira (akin to the IDE in AWS Lambda), with code completion, Javadoc lookup and syntax error checks.

With this editor, you can call all public APIs from Jira, which is more complete than the REST API, but only available from Java or Groovy.

Where do start with the API and the console? With the ComponentAccessor class. This class allows you to load all the major components of Jira, like the IssueManager or the ProjectManager.

An example? This is how you can list all projects in a Jira instance, and listing its name, key and the project lead’s name.

import com.atlassian.jira.component.ComponentAccessor
def projectManager = ComponentAccessor.getProjectManager()
projectManager.getProjectObjects().each { project ->
    log.warn project.name << "\t" << project.key << "\t" << project.projectLead.displayName
}

The output will show up in the console’s log tab (which is limited to 300 lines).

You can even add user input to your scripts! This is not a feature that I used in the past, but it can be useful to allow users to run scripts with variants.

Scripts can be inline, or you can write them in a file, and run them from the editor. This is useful if you have than one Jira instance, or if you want to write Groovy classes that share code with scripts. Writing the scripts in a file also allow you to run them as a service (more on this later).

Second feature, Behaviours. This is quite a powerful feature of ScriptRunner. With it, Jira can show or hide fields when a screen (form) popup, or when a specific condition is reached. You can also have Ajax requests made in the form.

For example, let’s say that the list of values for a field depends on another field . Jira does have a two-level selection field, but what if one of the lists is dynamic, i.e. it comes from a database or a Web service? You can use Behaviours to fetch the values from the database, and that query can use the value of the other field to filter out the fetched values. You can even query a LDAP or Active Directory server, and fetch an user or group from the directory based on a value from the Jira screen.

Another good example is the good old “Other” value in a list. What if you want the user to enter a value in another field if the selection from the list is “Other”? Without Behaviours, the screen will have to show the “Other value” field, and the user could enter a value in it, even if it’s not useful. With Behaviours, you hide the “Other value” field, and add a trigger to show it only when “Other” is selected in the list.

If you need dynamic forms when users edit or create issues, Behaviours is the way to go.

One of the main features that made people to use ScriptRunner is to have custom workflow functions. You can use them as validators, in a post-function or a condition.

Many workflow apps exists in the Marketplace, but with ScriptRunner, you can write ANY logic, as long it’s Groovy code, as long it’s not code that can take a lot of time to run.

Again, you can write your own workflow functions in an in-house Jira app, but it’s easier to do with ScriptRunner.

The next big feature of ScriptRunner is Jobs. You can create services, written in Java, to achieve the same thing in a “plain” Jira server, but it is a lot easier to write them in Groovy, and without having to deploy a Java class.

Write your script in the Script Console, test it, and when it’s ready, save it to a file, put it in JIRA_HOME/scripts on your server, and in the UI, specify at which interval the script should run. Easy as this.

Jobs are quite useful to automate tasks, like auto-archiving projects (with the Datacenter edition of Jira) that were not updated in the last year, or to send an email each month to project admins that contains the list of users that can access their project, and ask them to verify if that list is valid (in my experience, a LOT of teams don’t cleanup user access when someone leaves a team, hence the automated reminder).

Jobs can take over regular Jira services, and you can also use ScriptRunner listeners instead of the Jira ones. Again, this is mainly for easy of development, you use Groovy and built-in utilities to write the listeners instead of Java code that must be compiled and deployed.

Scripted Fields can be useful, if you need to display data from a database, LDAP/AD server, or display a calculated value based on the value of other fields, like the difference between two dates.

The Database Picker field is useful if you need to fetch information from an external database. You might need to add the JDBC driver for the database, but that’s about it. And JDBC drivers are available for most databases, including… CSV files.

The Custom Script Field allows Jira to display the value in many formats, and the value is calculated from a Groovy script, so you can basically do anything, even HTTP requests with Groovy’s built-in HTTP classes.

Other scripted fields are available, check them out to see if they can be useful for your projects.

Let’s go over all the other features of ScriptRunner for Jira Server:

• If you need to customize the UI of Jira, it can be done with a Jira app (plugin), and frankly, it’s not hard to do. But it’s even easier to do with ScriptRunner, because you don’t even need the Atlassian SDK and a Maven project to make the app and deploy it.
• Additional JQL functions, and an easier way to write your own JQL functions (you can create custom functions in a Jira app, but again, it’s easier with ScriptRunner).
• Escalation Services. Can be useful for non-Service Desk projects.
• REST Endpoints. Want to extend the REST API coming with Jira? This is the way (ok, again, you can do it in a Jira app, but it requires more work). Those endpoints are often paired with Behaviours, so that the heavy work is done in the endpoint instead of the code in Behaviours.
• Mail handler. Its power up the mail handler functionality of Jira, by running Groovy scripts when analyzing the incoming email. Because, let’s face it, the built-in incoming mail handlers in Jira are quite simple and not flexible (have a look at Email This Issue for an alternative for incoming and outgoing email handling).

As you see, ScriptRunner makes it easy to use and expand Jira features. If you want a more dynamic Jira, ScriptRunner is the app to install. But it’s not cheap, it’s cost efficient when you need to use at least 3 of its features or need complex automations that Webhooks, listeners and Automation in a “plain” Jira Server can’t do.