Behaviours

Installation Requirement

To use the Behaviours feature, you must install the Behaviours - ScriptRunner for Jira Cloud companion app. This app is free for ScriptRunner customers as it is already included with your ScriptRunner licence fee!

Before you start

Before setting up a behaviour, view our demo videos.


shortcut Watch Behaviours Videos


What are Behaviours?

Behaviours give you added control over fields in Jira. A field configuration customizes how fields behave across an instance. However, a behaviour in ScriptRunner for Jira Cloud allows you to take that field customization further, defining how fields behave for issues in a given project or issue context.

Behaviours provide options enabling you to customize how fields in Jira behave. Therefore, you can give your users clear direction when filling in fields on the Create Behaviour screen. For example, you may want to create a behaviour that hides a field for a specific user group until it's relevant for them to interact with that particular field. 

You can create a behaviour that will:

  • Prefill/preformat a template when an issue is created so users can easily follow it.

  • Change the name or description that is displayed for a field.

  • Hide or show a supported field only to people in a specific role.

    Hidden fields

    Note that hidden fields can still be submitted if a user edits the HTML form or modifies browser requests. 
  • Set a field value based on another supported field.

Behaviour Scripts

Some points worth noting about behaviour scripts: 

  • The language used when writing the logic for behaviour scripts is Javascript and not Groovy. You can refer to our scripting information for more details.
  • ScriptRunner can store up to 50,000 characters in scripts associated with a Behaviour. This includes the sum of all characters in all scripts in a single behaviour after compiling from TypeScript to JavaScript, plus our metadata. For more information, see data the POST request in Atlassian's documentation.
  • Complex scripts may affect the speed at which your behaviours run and may be slower than simple or efficient scripts.
  • There is a limit of 3000 behaviours at this time. 

How to use Behaviours

Behaviours in ScriptRunner for Jira Cloud can be used to reinforce your business processes. It's beneficial to think of a behaviour as one of your business rules or use cases and understand that it will only affect fields on projects and issue types specified by you.

Within the behaviours feature, you can choose to change or alter one or more fields. These are known as affected fields and are essential to initiate a behaviour. As such, they must be defined from the outset and are mandatory. Additionally, it is essential to determine the timing of when the script on the affected field should run: when the create screen first loads or when a change has been made to another supported field.

A fundamental difference between the ScriptRunner for Jira Server/DC and ScriptRunner for Jira Cloud behaviours feature is that the field selected is the trigger that causes the behaviour to run in ScriptRunner for Jira Server/DC. However, with ScriptRunner for Cloud, you choose an affected field first and then write a script with logic that will alter that field in your preferred way.

Install the app

Why?

There are currently two platforms on which Jira apps can be built: Atlassian Connect and the newer Atlassian Forge. ScriptRunner for Jira Cloud is built on the Connect platform, but this does not facilitate the Behaviours feature. Atlassian created an API called UI Modifications on the Forge platform, which made it possible for ScriptRunner to build behaviours. Therefore, this means that in order to use the Behaviours feature, a separate Forge app needs to be installed alongside ScriptRunner for Jira Cloud. 

As more capabilities become available in the UI Modifications API, more functionality can be built in ScriptRunner's Behaviours feature. 

How?

When installing the ScriptRunner Behaviours Forge app, a list of permissions, or Jira Software scopes, are presented for approval. This is required by the app in order to run successfully. You can refer to the Forge Scopes section for more information.

If your Jira instance uses IP allow-lists, you need to expand that to include the Atlassian Forge IP address range and all AWS IP ranges for your region. Refer to Atlassian's IP addresses and domains for Atlassian cloud products and AWS IP Ranges for more details. 

You will see a notification when you need to update your IP allow-list along with a list of the IP ranges to allow, as shown in the example below:

To install the ScriptRunner Behaviours app, you need to follow the steps below, depending on whether or not you already have an active, valid ScriptRunner for Jira Cloud instance installed: 



On this page