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 your application and Intellij IDEA (the free community edition is fine) with ScriptRunner and groovy.

This tutorial is recommended for users that…​

Requirements

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

Now edit this file to include the follow repositories:

  <repositories>
    ...
    <repository>
      <id>adaptavist-external</id>
      <url>https://nexus.adaptavist.com/content/repositories/external</url>
      <snapshots>
        <enabled>true</enabled>
        <updatePolicy>never</updatePolicy>
        <checksumPolicy>warn</checksumPolicy>
      </snapshots>
      <releases>
        <enabled>true</enabled>
        <checksumPolicy>warn</checksumPolicy>
      </releases>
    </repository>

    <repository>
      <id>adaptavist-external-snapshots</id>
      <url>https://nexus.adaptavist.com/content/repositories/external-snapshots</url>
      <snapshots>
        <enabled>true</enabled>
        <updatePolicy>never</updatePolicy>
        <checksumPolicy>warn</checksumPolicy>
      </snapshots>
      <releases>
        <enabled>true</enabled>
        <checksumPolicy>warn</checksumPolicy>
      </releases>
    </repository>
    ...
  </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
mvn jira:debug

When we specify mvn commands we will say mvn, but if you are using the Atlassian SDK you might write 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.

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 → SDKs (Platform Settings).

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

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) and paste the path you copied earlier into the Maven home directory field.

The screen should look like this:

IDEA Maven settings

Save changes.

Customise product versions

After completing the former steps, those maven dependencies (in the pom.xml file) that where 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:

<properties>
    <jira.version>7.2.1</jira.version>
    <jira.data.version>7.2.1</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>

Debugging

Run atlas-debug or 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:

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

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

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 (not the value shown in the image below).

  • 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: <module>/target/jira/home/log/atlassian-jira.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 any application is installed correctly.

Check 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 etc, continue reading to creating a script plugin. Also continue reading about script plugins to find out how to include configured extensions, such as listeners, macros, hooks and UI fragments etc.

Debugging a Groovy script

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

  • Add breakpoint(s)

  • Execute your script, for instance via the console, or a workflow function or 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 for multiple times. In fact you will have to do this once for each dependency such as jira-api, jira-core. In each case just point to the root of the downloaded sources, select everything, and let IDEA work it out.

Summary

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 anymore, so 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.