Built-In Scripts Tutorial
As an administrator, you likely handle lots of tasks in your Jira instance. Many of these tasks can be a bit tedious. And like most of us, you want to make your life easier and handle more tasks automatically- that’s where ScriptRunner built-in scripts come in. While ScriptRunner provides extended functionality in many different ways, its built-in scripts offer several options to automate or simplify different processes in Jira. Also, built-in scripts, as their name indicates, are built into ScriptRunner, so you don’t need to work with Groovy to get them running.
Built-in scripts for the global Jira instance are part of the ScriptRunner functionality in the administration section of Jira. You access these global built-in scripts from the Built-in Scripts page (Administration>ScriptRunner>Built-In Scripts).
About Built-In Scripts
A ScriptRunner built-in script is a type of automated functionality that allows a Jira administrator to handle something quickly and automatically that would have been a manual process. These particular built-in scripts, found at the global level of ScriptRunner, help a Jira administrator handle tasks that would affect many projects or the whole Jira instance. For example, you can use the Bulk Import Custom Field Values built-in script to import several custom fields values or use the List Scheduled Jobs built-in script to see a list of all scheduled jobs for a Jira instance. There are other built-in scripts available as part of ScriptRunner functionality, specifically in workflow functions, but those are not accessible at the global administration level.
For each built-in script, you may need to update menu selections, or you may just need to run the script. In this example for the Bulk Fix Resolutions script, you do need to update a couple of menus to bulk change resolutions from one resolution status to another.
Why Use a Built-In Script?
Built-in scripts allow you to automate actions that would otherwise be manual as well as provide you with quick information on some parts of your Jira instance. Because these scripts are built-in, they are an excellent way for Jira administrators without groovy knowledge to access functions through the user interface of Jira. There are also built-in scripts that extend some of the bulk edit functionality that you find in Jira, allowing you to quickly handle tasks such as changing a set of resolutions fields automatically saving you time and effort that you can put into other tasks.
Some other cool functionality available as built-in scripts include reviewing your script registry, viewing your server log files, and listing your scheduled jobs. While these built-in scripts don’t complete any actions, they allow you to review information about your system easily. For example, you can use Script Registry to view all Groovy scripts used across your Jira instance. So, if you need to audit your ScriptRunner use and see where both built-in scripts and custom Groovy scripts are used, you can do that with this built-in script. This built-in script provides a list of results broken into multiple tabs, with numbers indicating how many scripts are in use. This particular script could be useful if you want to quickly view where different ScriptRunner scripts are in action, as well as potentially identify problems in custom scripts.
Default Built-In Scripts
The number of available built-in scripts you have depends on what Jira applications you have installed and what version of ScriptRunner you are running, as new built-in scripts are added regularly. (The version used here is 5.3.7.) For any of the scripts, a summary is provided on the page, and if you need more information or would like a fleshed out example, most have a link to the documentation via the question mark icon. The 17 built-in scripts available in this version (with Service Management also installed) are:
Bulk Fix Resolutions
Change Dashboard or Filter Ownership
Copy Custom Field Values
Escalation Service
Reindex Issues
Bulk Copy SLA Configuration
Split Custom Field Contexts
Configuration Exporter
View Server Log Files
Bulk Import Custom Field Values
Clear Classloader or Jira Internal Caches
Copy Project
Generate Events
Script Registry
Switch to a Different User
List Scheduled Jobs
Unit Test Runner
These built-in scripts are a mix of scripts that need you to enter some information, like a filter ID or a project key, and scripts that you can just run and see the output.
Examples of Built-in Scripts
Bulk Fix Resolutions
Let’s check out the Bulk Fix Resolutions script to get an idea of how built-in scripts work.
At Great Adventure, the server team imported a project from their test instance, and their resolution status, Upgraded, didn’t carry over, so they need to change all Done statuses to Upgraded. This is causing problems for the project manager; her reports are incomplete. She could fix it manually, but that would take far too much time. You can easily run the Bulk Fix Resolutions script to correct the errors. This script will take the issues in a filter and alter their resolutions all at once.
From the ScriptRunner page in the Administration console, choose Built-in Scripts.
Next, click Bulk Fix Resolutions.
Set the filter as appropriate, and choose the proper resolution. In the following image, the Filter ID field has a filter created to find all the issues that have been resolved incorrectly, and the New Resolution field is set as
Upgraded
.Click Run, and the results appear. This function can be extremely useful for a quick fix to multiple issues that have the incorrect resolution. If you wanted to ensure that this action was carried out on a regular basis, you could use the Escalation Service built-in script, which we’ll look at next.
Escalation Service
Let’s say that there’s an issue edit request that you keep seeing pop up in your queue. It seems like every few days you’re getting the same request. To automate periodic changes to a set of issues defined by a filter, you could use the Escalation Service built-in script.
From the ScriptRunner page in the Administration console, choose Built-in Scripts.
Next, click Escalation Service.
Click Add New Service.
Enter the appropriate information in the fields:
Description is the name of the service. A good descriptive name is priceless…
JQL Query is the search string that will produce the issues that need modification. This could be copy and pasted from a filter.
As User is looking for which user will execute the alteration. Double-check to make sure that this user has the appropriate permissions.
Interval/Cron Expression defines how often / what day of the week the escalation service runs. For help creating a Cron expression, see here. The following example will run at 8:00am every Monday morning.
Action allows you to choose from a wide range of pre-defined actions and workflow transitions in your Jira instance.
Additional Issue Actions allows you to insert an in-line or external script into the service. Use Expand Examples to access some useful recipes, or head over to the documentation for more.
Transition Options allow you to choose which transition operations you’d like to forego.
To run the service immediately, click Run Now. To allow the service to run at it’s set time, click Add Service. You see a result screen after either option is selected.
Built-in Scripts are a quick and convenient way to solve a lot of administrators and users requirements. From powerful administrative tasks such as View Server Log Files to fine tuned automation with the Escalation Service, built-in scripts are easy to set up and run.