Behaviours

In order to use the Behaviours feature, you must install the Behaviours - ScriptRunner for Jira Cloud companion app which is free to use for ScriptRunner customers.

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 you with options that enable 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

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 Core scopes and 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 is using IP allow-lists, you need to expand that to include the Atlassian Forge IP address range and all AWS IP ranges for the region you're in. Refer to Atlassian's IP addresses and domains for Atlassian cloud products and AWS IP Ranges for more details.

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

If ScriptRunner for Jira Cloud is already installed

  1. Log into your Jira instance as an admin. 
  2. Locate the Behaviours tab.
  3. Click Install Free App

    You are redirected to the Atlassian marketplace to install the Behaviours - ScriptRunner for Jira Cloud app.
  4. Click Get it now and follow the install prompts. 

    You are automatically taken back to the Behaviours Forge app page in Jira where you are required to allow the app to access Atlassian products. You are required to do this one time only.
  5. Click Allow Access

  6. Click Get StartedYou are now ready to start using the Behaviours feature and will be redirected to the Behaviours tab.

    From here, you can click Create Behaviour and follow the steps to create a behaviour in ScriptRunner for Jira Cloud.

If ScriptRunner for Jira Cloud is not installed

To use the Behaviours feature within ScriptRunner for Jira Cloud you will need to have both apps installed. However, the order in which these apps are installed isn't important.

  1. Go to the Atlassian Marketplace to install the Behaviours - ScriptRunner for Jira Cloud app. 
  2. Click Get it now and follow the install prompts. 

    You are automatically redirected to the Behaviours Forge app page in Jira where you are required to allow the app to access Atlassian products. You are required to do this one time only.
  3. Click Allow Access
  4. Click the Get ScriptRunner for Jira button

    You are redirected to the Atlassian Marketplace where you can purchase/install ScripRunner for Jira Cloud. 
    Once ScripRunner for Jira Cloud is installed, the Manage apps in Jira admin page displays.
  5. Open ScriptRunner for Jira Cloud and locate the Behaviours tab. You are now ready to start using the Behaviours feature.
    From here, you can click Create Behaviour and follow the steps to create a behaviour in ScriptRunner for Jira Cloud.

Before you start

Before setting up a behaviour, view our demo videos.



Understand Atlassian's UI Modifications API.

Behaviours Supported Fields

Behaviours can be applied to supported fields on the Global Issue Create view only. Additionally, modifications may only be made on the following supported fields:

Field TypeSupported FieldType
Jira System Fields

Summary

Description

Assignee

Priority

Labels


Custom FieldsCustom single select fieldscom.atlassian.jira.plugin.system.customfieldtypes:select
Custom multiple select fieldscom.atlassian.jira.plugin.system.customfieldtypes:multiselect
Custom paragraph (multi line text) fieldscom.atlassian.jira.plugin.system.customfieldtypes:textarea
Custom user picker fieldscom.atlassian.jira.plugin.system.customfieldtypes:userpicker
Custom multiple user picker fieldscom.atlassian.jira.plugin.system.customfieldtypes:multiuserpicker
Custom text fieldcom.atlassian.jira.plugin.system.customfieldtypes:textfield

Behaviours Supported Functions

Developing Behaviours on Cloud and adding more functionality to this feature remains a high priority for the ScriptRunner team. The table below highlights the functions that are currently supported in Behaviours for  Cloud. Comparatively, all of the functions are available in the ScriptRunner for Jira Server/Data Centre Behaviours feature.

Category

Supported capability

Supported on Cloud




Behaviours actions

Hide/show field

Y

Make field editable/read-only

Y

Change field name/title

Y

Change field description

Y

Make field required

N

Manage field options

N

Configuration mapping

Configuration support for ALL projects or ALL issue types

N









Affected fields






Custom fields




Single select fields

Y

Multiple select fields

Y

Text fields

Y

Paragraph fields

Y

User picker fields

Y

Multiple user picker fields

Y

Single select or multi select check box fields

N

Radio option fields

N

URL fields

N

Attachment fields

N



System fields

Description

Y

Priority

Y

Summary

Y

Assignee

Y

Labels

Y

Other system fields

N


Behaviours location

On ‘Create’ screen

Y

On ‘Transition’ screen

N

On ‘View’ screen

N


Supported platform

Jira Core and Jira Software

Company-managed projects

Y

Team-managed projects

N

Jira Service Management


N

Create a Behaviour

Some points worth noting about behaviours from the outset: 

  • The language used when writing the logic for behaviours scripts is Javascript and not Groovy.
  • Each behaviour's script cannot exceed 5,000 characters.
  • Complex scripts may affect the speed at which your behaviours run, and they may be slower than simple or efficient scripts. 
  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) that the behaviour will be applied to from the Projects drop down list. You must select at least one project.
  7. Select the type of issue you want to apply this behaviour to from the Issue Types drop down list. You must select at least one issue type.
  8. Click the Add Field button to choose the field the behaviour will affect - this is called the Affected Field. You will see the Select Affected Field pop up window displayed where you can choose an Affected Field

    The Affected Fields are fields that are being changed or altered. They are not the fields that act as triggers for the changes or alterations.


  9. Select the field from the Affected Field drop down list and click Next. You will now see the following screen:

  10. Determine when the behaviour script will run, either On load or On change (or both).

    WhenRuns
    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 would like to run the script after the user alters a field on the create screen, then 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 then changes the priority to High, the assignee would then auto-update to Jane.

  11. Enter your code within the Script box, as required. Alternatively, you can select an example script from the Insert Example Code drop down list and modify it 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 on change so that it runs when you need it to.
    Choosing to use the Insert Example Code script will replace anything that is already contained within the Script box. 
  12. Click Add to save your script for the Affected Field. You can also click the Back button to go back through your steps, or you can Cancel.
    If you would like to continue adding more affected fields, then 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.
    If you are creating behaviours for the first time since installing the ScriptRunner Behaviours app, then you are prompted to click the Allow Access button, as shown below:

    Atlassian’s initial beta release of the UI Modifications API requires each user to allow access to the Behaviours app. As such, the first time you create an issue where a behaviour is mapped, you will need to allow access to the Forge app (one time only).

    Granting access allows you to create issues on a screen that has been modified by the UI Modifications API. If access is not granted, then you will not be able to create an issue from screens that have been modified by a behaviour.

    Granting access is a temporary step; rest assured, Atlassian is working to improve the user experience and remove it. You can follow Atlassian’s ticket here.

    After access has been granted, the following screen displays: 

    Once you have clicked on the Accept button, you are returned to the Behaviours screen.

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.
  3. Edit the fields, as required, from within the Edit Behaviour screen.

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


  5. Make your required changes and click Next.
  6. Modify when the script runs and/or edit the script code, as required.
  7. Click Save to confirm the configurations for your behaviour, or you can Cancel. You can also click the Back button to go back through your steps, or you can Cancel.

Troubleshoot Behaviours

Behaviours are built on the UI Modifications API provided by Atlassian. Described below are some of the common errors that can occur as a result of using that API for the Behaviours feature.

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

Example Error

A common error that can occur within the ScriptRunner for Jira Cloud Behaviours feature happens when you set the wrong value type. That is, if you have a script that uses the setValue() method and the value of the field is set using the wrong data type, then you will see an error message displayed.

In this instance, you will see the error message appear on the Create issue screen when a behaviours script fails to run, as shown below:

Effect:

The result of this type of error means that all changes made in the UI do not take effect, and in turn, any behaviours that have been configured on other fields also do not run.

Resolution:

To resolve this error, you need to review the behaviours scripts mapped to the affected issue type and ensure that you are setting the correct value type for the field being set. The value types associated with each field are described on the Behaviours API page.

If you have set the wrong value type you will see a code linting error in your script. This highlights that the value being set is incorrect when writing your code, as shown below.

It's important to note that if you are setting the Description field, you will not see a warning if you set a string value and the Description field is using a Wiki Text Renderer (you can also set this field to use a Plain Text Renderer in the field configuration). In this case, we advise you to check the type configured for the Description field and set the value to Atlassian Document Format for a Wiki Text Renderer, or a string for a Plain Text Renderer.




On this page