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!

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.

    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.

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


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. 


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: 

Before you start

Before setting up a behaviour, view our demo videos.

Understand Atlassian's UI Modifications API.

Behaviours Supported Fields

Developing Behaviours on Cloud and adding more functionality to this feature remains a high priority for the ScriptRunner team! Behaviours can be applied to Sub-tasks and the supported fields outlined below for the Global Issue Create and Issue views.

Modifications may only be made on the supported fields depending on your selected view:

Create View Supported Fields

date picker(tick)(tick)(tick)(tick)(tick)(tick)(error)
fix versions(tick)(tick)(tick)(tick)(tick)(tick)(error)
issue type(error)(error)(error)(tick)(error)(error)(tick)
multiple select(tick)(tick)(tick)(tick)(tick)(tick)(tick)
multiple user picker(tick)(tick)(tick)(tick)(tick)(tick)(error)
radio buttons(tick)(tick)(tick)(tick)(tick)(tick)(tick)
single select(tick)(tick)(tick)(tick)(tick)(tick)(tick)
text field(tick)(tick)(tick)(tick)(tick)(tick)(error)
user picker(tick)(tick)(tick)(tick)(tick)(tick)(error)


date time picker(tick)(tick)(tick)(tick)(tick)(tick)



Issue View Supported Fields

Hidden fields

When the text (single), select list (single and multiple), checkbox, radio and number fields are set to read only but have no value in Issue View, they will be hidden.
Field / methodssetName
multiple select(tick)(tick)(tick)(tick)(tick)(error)(tick)
radio buttons(tick)(tick)(tick)(tick)(tick)(error)(error)
single select(tick)(tick)(tick)(tick)(tick)(error)(tick)
text field(tick)(tick)(tick)(tick)(tick)(error)(error)
fix versions(tick)(tick)(tick)(tick)(tick)(error)(error)
date picker(tick)(tick)(tick)(tick)(tick)(error)(error)
date time picker(tick)(tick)(tick)(tick)(tick)(error)(error)
user picker(tick)(tick)(tick)(tick)(tick)(error)(error)
multi user picker(tick)(tick)(tick)(tick)(tick)(error)(error)

Fields/Methods Not Supported

We continually strive to support the functionality provided by Atlassian. Here's a link to Atlassian's UI Modifications guide, where you can find further information. You should also note that Issue View fields only work on company-managed Jira Software.

Supported Platforms

PlatformSupported CapabilitySupported on Cloud

Jira Software 

Company-managed projects


Team-managed projects


Jira Work Management

Company-managed projects


Create View

Currently, the Behaviours feature is supported on Create view only. Support for Issue view is coming soon.

Team-managed projects


Jira Service Management


Behaviour Scripts

Some points worth noting about behaviour scripts: 

  • The language used when writing the logic for behaviour scripts is Javascript and not Groovy.
  • 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. 

Create a Behaviour

  1. Navigate to ScriptRunner → Behaviours.
    If you have previously created behaviours, you will see a list displayed. You can edit or delete any of these via the Actions ellipsis next to the behaviour you want to modify or delete.
  2. Click the Create Behaviour button. The following screen displays:

  3. Enter a name in the Behaviour Name field.
  4. Enter a brief summary of the behaviour's purpose in the Behaviour Description box.
  5. Check the Enable Behaviour option, as required. By default, the behaviour is set to Enabled, meaning that the behaviour is active as soon as it has been saved.
  6. Select the project(s) to which the behaviour will be applied from the Projects drop down list. At least one project must be selected, and you have the option to select All projects if required. 
  7. Select the type of issue you want to apply this behaviour to from the Issue Types drop down list. At least one issue type must be selected, and you have the option to Select all issue types if required, which displays the maximum issue types available.

    Behaviours mapping note

    You should note that when the 'All projects' option is selected, and a project is added or removed from your instance, it will still be mapped to all projects in that instance. However, if you select all current issue types to map to and a new issue type is created, you must manually add this to the mapping, as it is not automatically added.
  8. Click the Add Script button. You will see the Add Field Script pop-up window displayed where you can add the behaviour script.

  9. Determine when the behaviour script will run by choosing either On Change or On Load (or both) from the Run the script options.

    On load

    The script will run when the create screen initially loads.

    You'll want to choose this option when you want the affected field to populate immediately upon opening the create screen. 

    For example, a field name or field description is changed, or a value is pre-populated into the field.

    On change

    The script will run when the specified supported field change happens. You may want to run the script initially when it loads AND if a change has occurred.

    You'll want to choose this option when you've added a condition to the logic and identified a trigger that will update the affected field. So, if you want to run the script after the user alters a field on the create screen, you should choose the On change option.

    For example, initially, you could set the assignee field to Bob, so all new bugs are assigned to him, but if the user changes the priority to High, the assignee would auto-update to Jane.

  10. Choose to run the script on either the Create View or Issue View (or both) from the and on the options. Refer to the Supported Fields/Methods, as not all field types are supported for issue view.

  11. Enter your code within the script box, as required. Note that you can directly open the API documentation from here. 
    Alternatively, you can select an example script from the Example Scripts option and modify the code as required, ensuring that you:
    • edit any variables, like custom field names, roles, or groups, in the example code so it's relevant to your instance.
    • choose the right time to run your script on: load and/or change so that it runs when needed.
    You can scroll or search for scripts by name in the Example Scripts and use the Copy Code button for scripts you'd like to paste into the Script box. 
  12. Click Save Script to save your behaviour scriptor you can Cancel. Once saved, you will see the details displayed within the Behaviours Scripts table:

    You can use the Action ellipsis menu to Edit or Delete the script. If you want to continue adding more behaviour scripts, these must be defined separately, as outlined in the steps above. You can c
    ontinue to add these to the table and add the logic needed until your business requirements are met for this behaviour.
  13. Click Save to confirm the configurations for your behaviour, or you can Cancel.

You can use the Behaviour Logs to view data related to ScriptRunner for Jira Cloud Behaviours that have run in your Jira instance.

Edit a Behaviour

Follow the steps below to edit a behaviour in ScriptRunner for Jira Cloud:

  1. Navigate to ScriptRunner → Behaviours. You will see a list of previously created behaviours.
  2. Click Edit from the Actions ellipsis next to the behaviour you would like to modify. From here, you can also Delete a behaviour.

    You can open any links in the table to display a pop-up window that provides you with more information and an edit option.
  3. Edit the fields, as required, from within the Edit Behaviour screen.

    You can also delete each of the individual Behaviour Scripts via the Actions ellipsis
  4. Click Edit next to the Affected Field you want to edit, and you will see the Edit Field Script window displayed:

  5. Make your required changes, such as modifying when the script runs and the type of view used and/or editing the script code.
  6. Click Save to confirm the configurations for your behaviour, or you can Cancel.

On this page