So, maybe you’ve been using the IntelliJ integration, but you find yourself wanting more. Sure, the automatic code completion is nice, and connecting the IDE to Atlassian’s source code does wonders for your productivity. Still, you’re finding a few things difficult:

This guide is recommended for users that…​

Requirements

Before starting with the tutorial, install

In the past, we have told people that they could use a plain Maven installation, including the one built into IntelliJ IDEA. While that works well for building ScriptRunner for Jira scripts, there is a known problem using it for ScriptRunner for Bitbucket Server development (ATLASSDK-145). Your mileage may vary on which development tools work best for you. We’re working to provide a much more streamlined experience "out of the box", but until that arrives, using the Atlassian SDK is the most bulletproof way to make sure your local development environment Just Plain Works.

Our goal with this guide is to give useful tools to the average scripter without holding back more experienced developers. This guide is not a detailed guide on how to use tools like Git, IntelliJ, and Maven, but a quick-start for people who could benefit from connecting those tools to ScriptRunner without mastering them.

Hardware Requirements

Your memory needs will likely vary based on the Atlassian host application that you’re working with. For instance, Atlassian recommend 2 GB of RAM as a minimum for running a small installation of Jira Server, while for running Confluence they recommend 6 GB of RAM.

These instructions were tested on a virtual machine with 4 GB of RAM and 2 processor cores available. While that seemed a bit pokey, it was manageable. That said, human attention tends to be significantly more expensive than RAM. Seasoned Atlassian plugin developers recommend 16 GB of RAM on your development computer if possible, particularly as you run more and more things to test and debug your application (IntelliJ, the Atlassian application, one to four web browsers, etc.).

Checkout the sample projects

We have created a project which contains script plugins for the different homes of ScriptRunner (Jira, Confluence, Bitbucket Server, and Bamboo). The source code is available at https://bitbucket.org/Adaptavist/scriptrunner-samples/. You can import this project directly into IntelliJ. At the welcome screen, choose "Check out from Version Control" and choose "Git" from the drop-down menu. Enter the git URL (https://bitbucket.org/Adaptavist/scriptrunner-samples.git).

Checkout from Version Control on IDEA’s welcome screen

Enter the repository URL

Open the project

Set a JDK for the project

That done, you’ll want to configure the Java Development Kit as the SDK for the project. See IntelliJ’s documentation for more detail. In brief:

  • Click on File → Project Structure.

  • Under the Platform Settings heading, select SDKs.

  • Click on the + button and add your JDK.

  • Click on Project (Project Settings) and make sure that the Project SDK is set to your Java 8 SDK. (Use a Java 7 for older versions of the products)

  • Click on Modules (Project Settings) and make sure that the Module SDK is set to Java 8 in the Dependencies tab.

  • Save changes (Apply / OK).

Setup JDK as project SDK

Build and run Jira with the sample plugin

With that setup, we should be able to build one of the sample plugins. With Maven installed, you can run mvn jira:debug from the command line from within the jira subdirectory (or confluence:debug within the confluence directory, and so on for bamboo & bitbucket).

You can also run the maven goals from within IntelliJ. Add the Maven Projects sidebar to your view (View → Tool Windows → Maven Projects), then expand the "Maven Projects" menu on the left hand side. Under "JIRA Sample Plugin for ScriptRunner", drill down to Plugins → jira → jira:debug, and double-click the jira:debug goal to run it. Note that there are similar tasks for the other products (confluence:debug, bitbucket:debug, and bamboo:debug, specifically). The chief trouble with this approach compared to the command line is that the red "Stop" button may appear to be done before the Atlassian host application has shut down, so it can trip you up if you’re restarting your app. Start Jira in debug mode

That should start a locally running instance of JIRA at http://localhost:8080/jira.

To shut down Jira, you can hit CTRL+D on your keyboard (or CTRL+C for a "hard" shutdown) in the terminal.

You may see a message like the one below in the IntelliJ console:

[INFO] --- maven-jira-plugin:6.2.6:debug (default-cli) @ sr-sample-plugin-jira ---
[WARNING] Current version 6.2.9 is more recent than MPAC version 6.2.9. No action taken.
You are running AMPS plugin version 6.2.6 but your pom is using version no-version-defined
Would you like to have your pom updated? (Y/y/N/n) Y: :

Just answer 'n'.

Congratulations! You are now up and running with a ScriptRunner development environment. You can login to the local Atlassian application using the default credentials (admin as the username and password) and configure scripts as you normally would. Any script extension point that has a "File" option can point to a file inside the script plugin’s source tree. Any Groovy scripts in the src/main/resources directory are available, as that directory is automatically configured as one of your script roots.

As a quick test, navigate to the Script Console and switch to the file tab. Enter the path to the sample script that’s installed in each plugin, com/example/ScratchScript.groovy, and click Run. You should see the string returned by that script in the results tab. Click the logs tab, and you should see the log message as well.

Hungry for more? We thought you might be. Read on for some advanced configuration options that will make your scripting experience even better.

Project Structure

The base pom adds the following additional script roots: <module>/src/main/resources and <module>/src/test/resources, so any scripts added to these directories can be run from Script Console (or any other extension point such as workflow functions) without specifying a full path (just as you did with the ScratchScript.groovy file, above).

IDEA does not currently automatically mark the resources directory as source roots. To fix this right click on the directory in IDEA, and do Mark directory as → Source root.

Note that in the future we may also add the src/main/groovy directory as a source root. Currently it’s intended for classes that will get compiled, without the source file being included in your plugin. At the moment, only built-in scripts where the source is found in the plugin are automatically included.

If your aim is to create a script plugin for distribution to a production server or for a customer, continue reading at creating a script plugin. Also continue reading about script plugins to find out how to include configured extensions, such as scripted listeners, macros, hooks, UI fragments, etc.

Advanced IntelliJ IDEA Configurations

Any IDE worth its silicon provides way more than just auto-completion for scripting.

Create debug configuration in IDEA

A debugger, which lets you pause your code mid-execution, can be extraordinarily helpful for complex scripts. Let’s create a debug configuration for that.

  • Run > Edit Configurations.

  • Press the + button and select Remote.

  • Set a name for your debug configuration (e.g. JIRA)

  • Set the debug port to 5005.

  • Click on the Logs tab and press the + button.

  • Provide a name (eg JIRA log) and the location of your logs. They should be at the following locations. Replace <module> with the full path to the project subdirectory (e.g. /Users/me/code/scriptrunner-samples/jira/test-plugin or C:\Users\me\code\scriptrunner-samples\jira\test-plugin). Make sure to use the right path separator for your platform, too (Mac/Linux use /, Windows use \).

    • For JIRA: <module>/target/jira/home/log/atlassian-jira.log.

    • For Confluence, the log file won’t actually be put into the target directory, but will be written directly to the console tab in IntelliJ when you run the confluence:debug goal

    • For Bitbucket Server: <module>/target/bitbucket/home/log/atlassian-bitbucket.log

    • For Bamboo: <module>/target/home/logs/atlassian-bamboo.log

  • The debug configuration should look approximately like this:

Debug settings

  • Since you already started the application in the previous steps, you can click Run → Debug 'JIRA' to start debugging your application.

That action should start the debugger and a window like this one should show up in the lower area of IDEA:

Debugger started

Debugging a Groovy script

Okay, now that you’ve setup your debugger, what next?

  • In IDEA, open one of your groovy scripts or classes

  • Add breakpoint(s)

  • Execute your script via the script console, a workflow function, a listener, etc.

  • The debugger should stop the execution of the script in the breakpoint that you just set

  • You can use the inspector to look at the values of variables in your script mid-execution, step through the code, and even evaluate a Groovy code fragment in the middle of execution. Consult the JetBrains debugging documentation for further details.

Connecting IntelliJ IDEA with the Atlassian Source Code

One of the biggest benefits of writing your code in IDEA is that you can access the javadoc directly in the IDE instead of needing to go to the API’s documentation website.

If you have purchased a license from an Atlassian product, you will have access to the source download page.

Let’s create a new Groovy script to see this working.

  • Create a new file called UsersCount.groovy with the following code:

import com.atlassian.jira.component.ComponentAccessor
import com.atlassian.jira.user.util.UserManager

def userManager = ComponentAccessor.getUserManager() as UserManager
def usersCount = userManager.getAllUsers().size()

return "My instance contains " + usersCount + " users"
  • Go to the Jira Administration page → Script Console.

  • Click on the File tab and write the name of your script (UsersCount.groovy).

  • if you press Run, you should see a message saying "My instance contains X users".

  • Imagine you want to want to do something else related to users but you don’t know what the UserManager class os able to do.

Type userManager. and you will see the properties and methods available to be used.

Class information

The last step to have full access to the application API is to link your code to the application sources. In IDEA if you hold the Ctrl key (CMD in OSX) and click on a class name or method you will be redirected to the source file of the class. Try this for the UserManager class located at the end of line 4. You will see something like this:

Decompiled class

The decompiler is great and will already give you a lot of information about the class, but you can go even further and see the whole implementation of it.

Since you probably have access to the sources of the application, download the version you are working with and unzip it.

If you click the Choose Sources link and select the folder that contains the application source, the source for the class will be shown, and the IDE will provide better parameter names and inline javadoc.

You may have to do this multiple times. In fact you will have to do this once for each dependency such as jira-api or jira-core. In each case, just point to the root of the downloaded sources, select everything, and let IDEA work it out.

Advanced plugin configuration

There are a number of settings in the plugin’s pom.xml file that you may want to change to suit your needs while writing your scripts.

Customise product versions

The scriptrunner parent pom sets a lot of default values for the versions of the libraries to be used when writing your scripts. Those default values can be changed if you are going to write scripts for a different version of the Atlassian applications. You can change them by editing the <properties> section of your pom.xml.

For example, to set the Jira version to 7.4.5, your properties block might look like:

<properties>
    <jira.version>7.4.5</jira.version>
</properties>

You can similarly specify a product data version:

<properties>
    <jira.version>7.4.5</jira.version>
    <jira.data.version>7.4.5</jira.data.version>
</properties>

Adding additional applications

If you are writing a plugin for JIRA, you may require JIRA Software, or JIRA Service Desk. To do so, add additional configuration to the jira plugin, for example:

<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>maven-jira-plugin</artifactId>

    <configuration>
        <applications>
            <application>
                <applicationKey>jira-servicedesk</applicationKey>
                <version>${jira.servicedesk.application.version}</version>
            </application>
        </applications>
    </configuration>
</plugin>

Note that for the above example to work you’ll want to define a <jira.servicedesk.application.version> property in the pom.xml file’s <properties> block as described in Customise product versions.

A compatibility table that matches application versions to compatible product versions can be found on the Atlassian Marketplace (e.g. the Service Desk listing).

Changing the default http port

The base pom sets all applications to run on port 8080 for consistency, rather than their defaults. You can change that if you want:

<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>maven-jira-plugin</artifactId>

    <configuration>
        <httpPort>2990</httpPort>
    </configuration>
</plugin>

Going Further

The next time you want to create and debug a new script, you will just need to add a new Groovy script to your IDEA project and run the <product>:debug Maven goal to test it. As your script library grows, you may find you need even more out of your local development environment.

Development Lifecycle

Find copying and pasting scripts between the IntelliJ IDEA and the ScriptRunner web interface tedious? Us too. But there is a better way. Two of them, actually.

Connect IntelliJ to Your Script Root

You can connect your locally running IntelliJ IDEA directly to a test instance of your Atlassian application (Jira, Confluence, Bitbucket Server, or Bamboo). This will let you edit the files in your server’s script roots directly with all the benefits of IntelliJ.

Creating a Script Plugin

The whole environment you just setup is actually a full blown Atlassin plugin development environment under the hood. Surprise! Take a look at the documentation on creating a Script Plugin for more information on how to use that environment to develop and package your scripts for deployment in test & production instances.

Executing Tests

What if the fresh environment provided by your script plugin doesn’t map well to your production environment? For instance, maybe your script assumes the existence of a few custom fields, and reconfiguring those every time you restart Jira is tedious. Sure, you can avoid running the clean task for a while, but you’ll have to run clean if you want to test a new Jira version, which may be half of why you setup a development environment in the first place! And besides, it’s a pain to click through the same testing routine for all your scripts.

What if you could write a script that would automatically setup all the custom configuration that you needed (be they Jira issues & custom fields, Confluence spaces, Bitbucket repositories, or Bamboo plans) then verify that your script produced the expected results in that environment?

With automated testing in ScriptRunner, you can. In the project that you just setup, you can add tests under <module>/src/test/resources and run them via Admin → Built-in Scripts → Test Runner. See testing for more information.

External Tool for Running Scripts Against JIRA

One handy tool for debugging is adding an external tool in IntelliJ to run an arbitrary Groovy script against ScriptRunner.

If you don’t already have curl, you’ll need to download and install it.

Open IntelliJ’s preferences and navigate to Tools > External Tool. Click the plus button and create a new configuration called "Run in JIRA".

The key bits are:

You should have something similar to this:

Class information

When invoked, this will POST the body of the script file you’re working with to your locally running JIRA server and execute it, just as if you’d copy-and-pasted the code into the ScriptRunner console and hit 'Run'.

To invoke it, you can click Tools > External Tools > Run in JIRA. We recommend assigning it to a keyboard shortcut to make it easier to access.

Class information

Learn from other script plugins

We eat our own cooking around here, and we like to share our recipes. Check out the source code of the Template Comments for Jira Service Desk plugin (also available for installation on the Atlassian Marketplace).

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.