layout: default title: Setting up a dev environment ---

Writing a script by simply using the javadoc can be painful, or if you 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 14 with 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:

Configuration

1. Scripts container IDEA project

We have created a small maven project which can be used to store all your scripts in one single place. This project also comes with the maven dependencies to the Atlassian API’s that you need in order to get help from IDE when writing your scripts. To obtain it, open a terminal and run either of the following two git commands depending on the way you want to connect (HTTPS/SSH):

git clone https://bitbucket.org/Adaptavist/scripts-repository.git
git clone git@bitbucket.org:Adaptavist/scripts-repository.git

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 will see that some dependencies are marked in red. That is because you need to complete the following steps:

1.1. 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. (It should also work with Java 7)

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

  • Save changes.

1.2. Set Maven settings

  • In a terminal, run "atlas-version". 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).

  • 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 and paste the path you copied into the Maven home directory field. The screen should look like this:

IDEA Maven settings

  • Save changes.

1.3. Customise products 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 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:

<properties>
    <jira.version>6.4.7</jira.version>
    <bitbucket.version>3.10.2</bitbucket.version>
    <amps.version>5.0.13</amps.version>
    <groovy.version>2.4.3</groovy.version>
</properties>

2. Preparing your instance

Besides the fact that we want to be able to write scripts with the help of an IDE, we will probably like to be able to debug them too. Read this section to learn how to configure a new or an existing instance to be debuggable.

A) Use an existing instance

If you have a testing instance that you want to use to debug your script, you will need to add some instructions to it in order to open a debug port and set logging levels for the ScriptRunner add-on before starting the application.

  • Add the following lines right before the export JAVA_OPTS instruction in APP-FOLDER/bin/setenv.sh:

    JAVA_OPTS="$JAVA_OPTS -Dplugin.script.roots="PATH_TO_PROJECT/src/main/resources/" JAVA_OPTS="$JAVA_OPTS -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000"

    Where…​

    • PATH_TO_PROJECT: In the first part of this tutorial you cloned a repository using git clone. You will need to substitute PATH_TO_PROJECT with the path to that directory (i.e. /Users/scriptrunneruser/repo/scripts-repository).

    Be aware that those lines will not work in Windows, where you will need to modify the setenv.bat file instead.

  • The second thing we need to do is to set the logging level of ScriptRunner to debug. That can be done by adding the following line at the end of the log4j.properties file:

    log4j.logger.com.onresolve = DEBUG, console, filelog

    You can find the log4j.properties file under this folder: …​/amps-standalone/target/jira/webapp/WEB-INF/classes/

    The former line will only works for Jira. If you are developing for Bitbucket, the file you need to change is called logback.xml instead, and this is the content that you should add in order to see the debug log messages of ScriptRunner:

    <logger name="com.onresolve" level="DEBUG"/>
  • Start the application which now has a debug port opened and debug log levels set for ScriptRunner!

B) New app with atlas-run-standalone

If you do not have a testing instance available but want to create one easily, follow these steps:

  • Open a terminal and create a folder where you would like to store your application instance. For example, /Users/scriptrunneruser/atlassian-apps/jira/647/

  • Navigate into that folder and run the following command to create a fresh new Jira application:

    atlas-run-standalone --product APPLICATION --version VERSION --jvmargs "-Dplugin.script.roots=PATH_TO_CLONED_PROJECT/src/main/resources/ -DdisableJiraEmail=false -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"

    Where…​

    • APPLICATION: Is the name of the application that you want to start. Substitute APPLICATION with jira to start a new instance of jira. If you want to create a new bitbucket application, use bitbucket instead.

    • VERSION: Version of the application you want to start. The version 6.4.7 is a valid one for Jira.

    • PATH_TO_PROJECT: In the first part of this tutorial you cloned a repository using git clone. You will need to substitute PATH_TO_PROJECT with the path to that directory (i.e. /Users/scriptrunneruser/repo/scripts-repository).

    That command will create a new folder called "amps-standalone" that contains a new jira application installed and ready to be used.

  • The second thing we need to do is to set the logging level of ScriptRunner to debug. That can be done by adding the following lines at the end of the log4j.properties file:

    log4j.logger.com.onresolve = DEBUG, console, filelog
    log4j.additivity.com.onresolve = false

    You can find the log4j.properties file under this folder: …​/amps-standalone/target/jira/webapp/WEB-INF/classes/

    Note that the former line will only works for Jira. If you are developing for Bitbucket, the file you need to change is called logback.xml instead, and this is the content that you should add in order to see the debug log messages of Script Runner:

    <logger name="com.onresolve" level="DEBUG"/>
  • Terminate the execution of the application by pressing CTRL+D or CTRL+C in the terminal window where you run the atlas-run-standalone command previously.

  • Run the atlas-run-standalone command from the first point again. It needs to be called from the folder where you called it the first time you run it. If you call it from a different location, it will create a new jira instance.

3. 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 (i.e. Jira)

  • Set the debug port to 8000.

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

  • Provide a name (atlassian-jira.log) and the location of your logs:

    • When using an existing instance, it would be something like this: PATH_TO_HOME_DIRECTORY/log/atlassian-jira.log.

    • When using the atlas-run-standalone option, you will find them somewhere like this: …​/amps-standalone/target/jira/home/log/atlassian-jira.log.

  • The debug configuration should look 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

4. Install ScriptRunner

If ScriptRunner is not installed in your instance yet, you will need to install it. Just go to the Find new add-ons screen in the Administration area and search for its last public version. In case you want to install manually an older version of the add-on, you will find all available versions here:

5. Debugging a Groovy script

  • In IDEA Open the file FirstScript.groovy.

  • Add a breakpoint in the second line.

  • Go to the Administration page.

  • Click on Script Console.

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

  • Press Run.

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

  • If you click on the atlassian-jira.log tab from the debug area, you will see one log message.

    Debug log messages

  • Go back to the Atlassian application and check that the string has been shown. It should basically show something like this:

    First Script

6. Working with the APIs

One of the biggest benefits of writing your code in IDEA is that you can check 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 is the UserManager class able to do. Somewhere in the file, type userManager. and you will see the properties and methods available to be used. This is one of the biggest advantages of using IDEA.

    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 that 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, your class will then be fully resolved.

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.

Useful links