Writing a script in vi or notepad, simply using the javadoc on the Atlassian website can be very painful. Equally, if your code is complex and logging statements are not enough you may feel the need for a symbolic debugger. Here are some instructions for setting up a locally running instance of JIRA, Confluence, or Bitbucket Server and Intellij IDEA (the free community edition is fine) with ScriptRunner and groovy.

This tutorial is recommended for users that…​


Before starting with the tutorial, please ensure that you have installed all the software listed below:

Update your settings file

Some artifacts can only be retrieved through Adaptavist’s maven repositories. You will need to update your maven settings.xml.

Locate your maven user settings file

  • In a terminal, run atlas-version or mvn -X. The execution of that command will give you the path to your maven installation directory:

Result of executing atlas-version in a terminal

Copy the path to your maven installation (you can see it underlined in the image).

Inside that path, there’s a subdirectory named conf that contains a settings.xml file. Edit that file to include the following repositories:

    <!-- Atlassian repositories will be listed above this line -->
    <!-- Adaptavist repositories are below -->

    <!-- End of Adaptavist maven repositories -->

Checkout one of the sample projects

We have created several small maven projects which are script plugins.

These projects also have the maven dependencies for the Atlassian API’s that you need in order to get help from IDE when writing your scripts.

Change directory to the relevant product you are working on, eg jira/test-plugin (there are also sample plugins for Confluence and Bitbucket).

You should verify that you can get all the dependencies by running, for example:

cd jira/test-plugin
atlas-mvn jira:debug

That should start a locally running instance of JIRA at http://localhost:8080/jira. Don’t worry about exploring it for now. You can use CTRL+D in the terminal to shut it down gently, or CTRL+C to just kill it.

You may see a message like the one below:

[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'.

When we specify mvn commands we will use atlas-mvn.

There is not much difference between a standard maven installation and the AMPS SDK. If you want to work with a regular maven installation, just modify your settings.xml to include the Atlassian repositories, and be aware that instead of running say atlas-create-jira-plugin you would run mvn jira:create.

Once you have the project in your workstation, open IntelliJ IDEA and import it by going to File → Open and then selecting the pom.xml file in the specific plugin’s directory.

You may see that some dependencies are marked in red. That is because you need to complete the following steps:

Set a JDK for the project

  • 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).

Set Maven settings in IDEA

The next step is to set the maven home directory in IDEA. To do that, go to IntelliJ IDEA → Preferences and then click on Build, Execution, Deployment → Build Tools → Maven (or search for maven). There, paste the path you copied earlier into the Maven home directory field.

The screen should look like this:

IDEA Maven settings

Save changes.

At this point, IntelliJ IDEA may prompt you that some maven projects need to be re-imported. Re-import them, or enable auto-import.

Customise product versions

After completing the former steps, those maven dependencies (in the pom.xml file) that were showing up in red should now appear as resolved.

If they still show up in red, right click on the Project name > select Maven > click Reimport > wait a short while until IDEA downloads the dependencies.

Note that the project base pom sets some default values for the versions of the libraries to be used when writing your scripts. Those default values should be changed if you are going to write scripts for a different version of the Atlassian applications. You can change them by going to the end of the pom.xml file, where you will find a section called properties.

Modify the versions - add the properties if not already present, for example:


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:



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


Run atlas-debug or atlas-mvn jira:debug (or confluence:debug, bitbucket:debug etc).

When it has finishing deploying the application, you should be able to open it in your browser.

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



Create debug configuration in IDEA

Coming back to IDEA where we already have a project configured, the next step would be to create a debug configuration:

  • 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. Instead, the logs will print to the terminal where you run the atlas-debug command. You can output them to a file using standard shell methods like atlas-debug > atlassian-confluence.log and then point IntelliJ’s debugger there.

    • For Bitbucket Server: <module>/target/bitbucket/home/log/atlassian-bitbucket.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

Start Working

After logging in to JIRA, check that any applications you added to the process (JIRA Software, Service Desk, etc.) are installed correctly.

Check that ScriptRunner is installed correctly, eg by running 1 + 1 in the Script Console.

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.

You can add tests under <module>/src/test/resources and run them via Admin → Built-in Scripts → Unit Test Runner. However be sure to put them in a package, and then set the package in the test runner - see testing for more information.

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 scripts 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 listeners, macros, hooks, UI fragments, etc.

Debugging a Groovy script

  • 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

Executing Tests

You can execute your tests inside the application directly from the IDE - Running Tests from your IDE.

Working with the APIs

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


After all the previous steps you have set up an environment to write your Groovy scripts easily.

There is no need to repeat all the steps. 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 start the debugger to test it.

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.