Create 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.

Script Plugins

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:

1. 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.

2. 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.

Descriptor File (YAML)

Inside the src/main/resources/ directory of each individual module (jira, 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.

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 confluence:install, 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.

Test

If you have written integration tests, they can be run using mvn verify. The command will:

1. Start a host application.

2. Run the integration tests inside the application.

3. 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.

Known Limitations

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.yaml file. Take a look below to see what is supported.

  Jira	Confluence	Bitbucket
  Event Listeners	Event Listeners	Event Listeners
  REST Endpoints	REST Endpoints	REST Endpoints
  Fragments	Fragments	Fragments
  	Macros	Pre-hooks
  	Jobs	Post-hooks
  		Merge Checks