Creating a Script Plugin
A script plugin is some ScriptRunner scripts and their configuration bundled as an Atlassian app.
Using a script plugin gives you two practical advantages, compared to configuring your scripts as normal through the ScriptRunner UI:
Configuration as Code
ScriptRunner supports storing the configuration of your extension points as code. You can bundle a descriptor file (YAML) into your script plugin that details the configuration for an extension point(s) so that as soon as the plugin is installed, your item is automatically configured.
For example: You are able to provide an event listener, which uses a script inside a script root, and ship these files in a plugin. Upon the plugin’s installation, ScriptRunner detects it and installs all the items listed in the descriptor file.
Upon disabling or removing the script plugin, these items are also removed.
A Custom Script Root
ScriptRunner supports looking up its script roots from inside another plugin. This means that it can automatically add the root of another plugin to its collection of script roots. This allows event listeners, built-in scripts, and other extension points to be loaded directly from those script roots.
Who This is For
Atlassian Experts and partners who would like to deliver a fully functional business process to a customer, without having to manually copy scripts to their server.
Developer teams which would like to implement common software development practices for their ScriptRunner scripts.
Some examples include version control, automated testing, code review, and continuous integration.
Creating a Script Plugin
The process to create a script plugin is outlined on Setting up a Development Environment. For a basic plugin, it is only necessary to follow the guide up until the Advanced IntelliJ IDEA Configurations section.
For a more advanced plugin, read on.
Descriptor File (YAML)
src/main/resources/ directory of each individual module (
confluence, etc.) you will find a
scriptrunner.yaml file. This is the descriptor file which contains the details of all your configured extension points. This file is where ScriptRunner looks for all the items that it will automatically configure upon the script plugin’s installation.
There should be an example item already present in the file, like the one shown below.
The code that needs to go inside the YAML file can be automatically generated using ScriptRunner’s Configuration Exporter built-in script.
The Quick Reload Plugin
If you ever modify any compiled code or the YAML descriptor file, you will need to re-install the Script Plugin in order to see your changes.
Normally, this is done by running
mvn package to build a new jar, then running
mvn jira:install (or
bitbucket:install as appropriate) to install the new jar into your application.
The ScriptRunner Samples project comes bundled with the Quick Reload Plugin, which will notice the updated jar (after running
mvn package) and automatically re-install the plugin into your application.
If you have written integration tests, they can be run using
mvn verify. The command will:
Start a host application.
Run the integration tests inside the application.
Shut down the application.
The above command runs your whole test suite.
If you would like to run just one test, you can start your application with
mvn <app>:debug. Then once your app started, run your tests directly from IntelliJ by clicking the Run icon next to your test.
There are some limitations with creating a script plugin:
If you disable or uninstall ScriptRunner, your script plugin is also disabled. It won’t be re-enabled automatically when you re-enable ScriptRunner. You have to enable it manually.
Certain extension points cannot be created or configured via the
scriptrunner.yamlfile. Take a look below to see what is supported.
Jira Confluence Bitbucket
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.