Write Code

When writing code, you can refer to this page if you want to understand the fundamental features of ScriptRunner for Jira Cloud that are not necessarily visible on the UI but instead run in the background.

Static Type Checking

Static type checking (STC) provides information about whether your script is correctly written.

Groovy is a dynamic language, which means that method and property names are looked up when your code is run, not when it’s compiled (like Java).

Let’s look at the following simple, but complete, script:

groovy
foo.bar()

We call the method bar() on the object foo. This script compiles without errors, but you get a MissingPropertyExceptionwhen you run the script because foo hasn’t been defined. This behaviour is useful because there are circumstances that could make this code execute successfully, like an object called foo or a closure getFoo() being passed to the script’s binding.

Although Groovy is a dynamic language, we can compile scripts in a manner that checks method and property references at compilation. The STC feature shows you problems in your scripts when you are writing them, as opposed to when they execute.

When your scripts are executed, they are always compiled dynamically. When they are compiled for the STC, the resulting generated bytecode is thrown away.

Limitations

There are limitations to the type checker. It is possible to write code that shows errors, but it is valid and executes fine. Some of these situations are:

  • Using certain builders

  • Using closures where the parameter types can’t be inferred

However, if you write code like this, you probably use an IDE, which does not work with the STC.

Additionally, your code could have runtime errors that won’t be found until the code executes.

Example

If we were writing a condition where we wanted to check the number of issues returned from a search is zero, we might inadvertently write:

groovy
boolean empty = isssues.total = 0

STC is telling us that we are trying to set the total, rather than retrieve it. We meant to use the equality operator:

groovy
boolean empty = isssues.total == 0

Code areas will show a green dot, which tells us that the code is syntactically correct, and the methods and properties have been checked.

STC in the cloud will provide additional help for the script context, ensuring that properties access matches the JSON Schema provided by Atlassian.

Asynchronous execution

Asynchronous execution is at the heart of the Atlassian Connect Framework that ScriptRunner must use to extend Jira Cloud.

Jira fires webhooks when events and transitions occur and any user interface elements are loaded in iframes. It is not possible to veto, cancel or otherwise prevent Jira performing an action using ScriptRunner.

Scripts are written synchronously, that is, REST API calls are made in a blocking style (although async methods are provided too). For more information, you can refer to the About Jira Cloud Platform documentation which provides you with an excellent introduction to the Atlassian Connect framework.

Isolated Execution

All user provided code is executed in an isolated container. ScriptRunner for Jira Cloud is a service that is shared by many customers so isolation is very important when executing scripts. Isolation is a goal that has been core to the design of ScriptRunner for Jira from its inception.

Each customer has a container that exclusively belongs to them. It is not possible for the code of one customer to have been run in the container of another. Containers are also designed to be single use, however, it is possible that containers will be re-used for execution on occasion, but script writers should not rely on this. Disk storage in these containers is short-lived, therefore, any changes written to the disk will be discarded.

Scopes

When installing the add-on a list of permissions, or scopes, are presented that ScriptRunner for JIRA Cloud requires in order to run successfully. A list of the scopes required for each REST API endpoint that JIRA Cloud provides can be found here. Below is a detailed explanation of why we need each of those scopes:

ScopeDescription

Act on a JIRA user’s behalf, even when the user is offline

Scripts can be configured to execute as either the add-on, or as the user who initiated that script. For example, if a user transitions an issue, then the Workflow Post Function will be initiated by that user, so it makes sense to execute the Post Function as the user who transitioned the issue. This ensures that each user’s permissions are respected, and provides a much clearer history of who’s made changes to the issues in your system.

Administer JIRA

This scope allows for the creation, update and deletion of issue types and issue link types, as well as for creating custom fields when running a script as the ScriptRunner Add-on user.

Administer JIRA projects

This allows you to write scripts that execute as the ScriptRunner Add-on user for creating, updating or removing Projects, Components and Versions so that you don’t need to grant those permissions to the rest of your user base.

Delete JIRA data

This scope is required in order to delete issues, comments, worklogs, issuelinks etc while running a script as the ScriptRunner Add-on user.

Write data to JIRA

This scope is required in order to create issues, comments, worklogs etc while running a script as the ScriptRunner Add-on user.

Read JIRA data

This scope is required in order to view issues, comments, worklogs etc while running a script as the ScriptRunner Add-on user.