ScriptRunner supports looking up its script roots from another plugins-2 plugin. In other words, it can automatically add the root of another plugin to its collection of script roots. Built-in scripts (admin scripts, but also hooks, listeners etc) are loaded from the script roots.

It also supports looking up a special descriptor file which describes how any plugin extension points are configured. Therefore you can ship new built-in scripts which are already configured upon installation.

This can be useful for Atlassian Experts and partners who would like to deliver a fully functional business process to a customer, without them having to copy scripts to their server.

You should also be able to provide someone a workflow, which references scripts like com/atlassianexpert/acme/custy/Foo.groovy, and ship these files in a plugin.

ScriptRunner will detect the plugin and automatically add it to its list of script roots, and install the listeners, macros etc…​ upon disabling or removing the script plugin these items will also be removed.

Creating a Script Plugin

The first step is to open one of the samples as discussed in setting up a development environment. Ensure that you are able to follow all the instructions on that page before continuing.

Fork that repository and start working in the relevant product-specific sub-directory, or copy the pom to a new directory.

Start Work

You can either add plain scripts or "built-in scripts" which can be parameterised, implementing CannedScript. Don’t forget to add your canned scripts to the correct package. See the sample plugin for examples. In addition to the product-specific samples plugin there is a "common" plugin, which has examples of extensions that are available in all supported Atlassian products.

ScriptRunner YAML File

You can include a special scriptrunner.yaml file that contains details of configured listeners, macros, hooks, UI fragments etc.

The scriptrunner.yaml file should be at the root of the jar file (put it in src/main/resources in your source project), if present at all.

It contains the information required to configure the built-in extension points such as listeners, hooks, macros etc. It is not really intended to be human-editable, although you can tweak it.

To create it, use Admin → Built-in Scripts → Configuration Exporter. Select the items that you wish to generate the YAML for.

In order to disambiguate one item from another the note field is used, and only those items with notes are shown. So make sure any configuration item you want to export has a note field.

The exporter may look like this:

config-exporter

On clicking Run the YAML snippet will be generated. Paste it in to your script-runner.yaml file.

Maven Goals

If you have modified compiled code or the YAML configuration file, you will need to reinstall the script plugin. Run atlas-mvn package. Quick Reload should notice the updated jar and install the plugin.

If you have disabled Quick Reload, use atlas-mvn package jira:install.

Running atlas-mvn package will creating a plugin jar that you can install like any other plugin.

Testing

Running atlas-mvn integration-test will run the application, and then execute any tests you have written, inside of the application.

See also Running Tests from your IDE.

Caveats

There are some problems with this at the moment, please give us feedback as this is a new feature.

  • If you disable ScriptRunner plugin your script plugin will be disabled, and won’t be enabled automatically when you re-enable ScriptRunner

For how-to questions please ask on Atlassian Answers where there is a very active community. Adaptavist staff are also likely to respond there.

Ask a question about ScriptRunner for JIRA, for for Bitbucket Server, or for Confluence.