Creating a Script Plugin
ScriptRunner supports looking up its script roots from inside another 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.
ScriptRunner also supports storing the configuration of your scripts as code. You can bundle a configuration file into your plugin that details the configuration for a Script Listener, REST Endpoint, Script Fragment, or other configured script so that as soon as the plugin is installed, your script is automatically configured. In Jira, 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.
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. It can also help teams that make heavy use of ScriptRunner to customize their Atlassian applications implement software development practices for their script code, including version control, automated testing, code review, and continuous integration as they have need.
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.
You can either add plain scripts or "built-in scripts" which can be parameterised. Such scripts must implement the
com.onresolve.scriptrunner.canned.CannedScript interface, and must be added to specific packages in order to show up in the correct place in the UI. To add scripts to the Built-in Scripts menu, add them to the
See the sample plugin source code for further examples.
ScriptRunner YAML File
You can include a special
scriptrunner.yaml file that contains details of configured listeners, macros, hooks, UI fragments etc.
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.
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 value in the note field.|
The exporter may look like this:
On clicking Run the YAML snippet will be generated. Paste it in to your
script-runner.yaml file. You can manually edit the code yourself, though it’s generally easier to re-generate the YAML file using the Configuration Exporter script.
If you have modified compiled code or the YAML configuration file, you will need to reinstall the script plugin. Run
mvn package. Quick Reload should notice the updated jar and install the plugin.
If you have disabled Quick Reload, use
mvn package jira:install (or
bamboo:install as appropriate).
mvn package will create a plugin jar that you can install like any other plugin. This will be in the target directory.
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.
There are some limitations with creating a Script Plugin. Please give us feedback as this is a new feature.
If you disable or uninstall ScriptRunner, your script plugin will be disabled. It won’t be enabled automatically when you re-enable ScriptRunner.
Certain scripts cannot be created or configured via the scriptrunner.yaml file, such as Scripted Fields in ScriptRunner for Jira. The sample plugin contain an example of how to work around this (by creating a Scripted Filed in an upgrade task).
Have questions? Visit the Atlassian Community to connect, share, and learn with other Atlassian users and experts, including Adaptavist staff.
Want to learn more? Check out courses on Adaptavist Learn, an online platform to onboard and train new users for Atlassian solutions.