Scripted Fields

What are Scripted Fields?

You can use ScriptRunner Scripted Fields to customise how the information for an issue is displayed. They enable you to display information that would otherwise be unavailable for an issue by calculating or amalgamating data from one or more existing fields. Check out our examples for more details.

Scripted Fields will appear on either the Issue Content panel or Issue Sidebar, depending on your configuration choices.

How to use Scripted Fields

Scripted Fields are a type of calculated field, so you can display a calculated custom field using ScriptRunner scripts that run when an issue is viewed. Keeping the scripts as simple as possible is good practice to reduce loading time. Scripted Fields display in the issue-view.

Scripted Fields work by using the same process as other scripts, such as Script Listeners, where you write code that executes REST API calls to either the Jira Cloud Rest API or your own external REST API call.

Before you start

Create a Scripted Field

1. Navigate to ScriptRunner → Scripted Fields.
   Upon opening the Scripted Fields page, you are presented with either a list of previously created scripted fields, or if you have not previously created any, you will see a landing screen.

   1. Click Create Scripted Field from the previously created list. You can also choose to Edit or Delete your preferred scripted field via the Actions ellipsis on this page
      
      OR
   2. Click Create Scripted Field from the initial landing screen if none have been previously created.
      
      OR
   3. Click Add Examples from the initial landing screen to add two scripted field examples to your instance. From here, you can select your preferred example and either Edit or Delete it via the Actions ellipsis.

2. Enter the name of the scripted field in Field Name.
   NOTE: The Identifier field shows the unique identification key for the new scripted field.
   

3. Under Field Status, choose either Enabled or Disabled. When set to Enabled, the scripted field is active (on relevant issues/projects) as soon as it has been saved.

4. Select the Location the issue view where the new scripted field should appear, either the Issue Content panel or Issue Sidebar. To view scripted fields in the sidebar, click Open Scripted Fields.

   Scripted fields in the issue content may not appear by default when an issue is loaded. To view the scripted fields click the ScriptRunner icon under the issue summary.

5. Select one or more projects in Project/s. The scripted field only displays on the project/s specified.

6. Select all Issue Type/s where you want the scripted field to display.

7. Select the Field Type of your scripted field. Ensure you pick the correct field type for the data returned by your script. See Return Types for more information.

8. (Optional) Enter a Search Term if you want to use Scripted Fields when searching for issues with JQL. There are several conditions that must be met for Search Terms, including: they must be unique, case sensitive, and contain no whitespace. They cannot match any ScriptRunner reserved keywords, ScriptRunner Enhanced Search functions, or JQL reserved keywords. Existing search terms/Jira custom field names cannot be used. 

9. Enter a Script to Execute. This script is triggered when an issue is loaded. See the Examples drop down under the code field for common use cases that can be used, or edited, to meet your needs.

   Scripted fields in Jira Cloud do not dynamically update. The script triggers on issue load; therefore, changes to the field value are not reflected instantly, the issue must be reloaded.

10. Enter an issue key in Test Against Issue to test the scripted field before saving.

11. Click Save.

    Any changes to the Scripted Field configuration will require a re-test

Edit a Scripted Field

1. Navigate to ScriptRunner → Scripted Fields. A list of all previously created scripted fields is shown.
   You can check which projects have been chosen for each listener by clicking the relevant Project from the list.

2. Click Edit on the Actions ellipsis of the scripted field you wish to edit.

3. Edit the fields as required.

4. Click Save after all changes are complete. You can also click Revert to undo those changes

Return Types

The script for your field must return the correct data type.

For a text field, the script must return a single line String (no newline characters).

groovy
// This is OK
return "Hello World"
// This is not OK
return "Hello\nWorld"

For a number field, the script must return a numeric type, for example an Integer, Long, Float, Decimal, or BigDecimal.

For a date field, the script must return a LocalDate.

groovy
import java.time.LocalDate
import java.time.Month
return LocalDate.of(2020, Month.JUNE, 25)

For a datetime field, the script must return a ZonedDateTime.

groovy
import java.time.LocalDate
import java.time.LocalTime
import java.time.Month
import java.time.ZonedDateTime
import java.time.ZoneId
import java.time.ZoneOffset
return ZonedDateTime.now(ZoneId.of("America/New_York"))
// or
return ZonedDateTime.of(LocalDate.of(2020, Month.JUNE, 25), LocalTime.of(13, 45, 0), ZoneOffset.ofHours(-3))

For rich text scripted fields, you must use the Atlassian Document Format (ADF). You can refer to Atlassian's ADF Builder for further details. You can also watch our demo video showing how to display tables within scripted fields using rich text.

We've provided some ADF examples below:

• table with headings, 2 rows and 2 columns

groovy
[
  "version": 1,
  "type": "doc",
  "content": [
    [
      "type": "table",
      "attrs": [
        "isNumberColumnEnabled": false,
        "layout": "default",
        "localId": "58c619ab-f32c-4dfa-aa54-2b4b39643deb"
      ],
      "content": [
        [
          "type": "tableRow",
          "content": [
            [
              "type": "tableHeader",
              "attrs": [:],
              "content": [
                [
                  "type": "paragraph",
                  "content": [
                    [
                      "type": "text",
                      "text": "Header 1"
                    ]
                  ]
                ]
              ]
            ],
            [
              "type": "tableHeader",
              "attrs": [:],
              "content": [
                [
                  "type": "paragraph",
                  "content": [
                    [
                      "type": "text",
                      "text": "Header 2"
                    ]
                  ]
                ]
              ]
            ]
          ]
        ],
        [
          "type": "tableRow",
          "content": [
            [
              "type": "tableCell",
              "attrs": [:],
              "content": [
                [
                  "type": "paragraph",
                  "content": [
                    [
                      "type": "text",
                      "text": "Row 1 Column 1"
                    ]
                  ]
                ]
              ]
            ],
            [
              "type": "tableCell",
              "attrs": [:],
              "content": [
                [
                  "type": "paragraph",
                  "content": [
                    [
                      "type": "text",
                      "text": "Row 1 Column 2"
                    ]
                  ]
                ]
              ]
            ]
          ]
        ],
        [
          "type": "tableRow",
          "content": [
            [
              "type": "tableCell",
              "attrs": [:],
              "content": [
                [
                  "type": "paragraph",
                  "content": [
                    [
                      "type": "text",
                      "text": "Row 2 Column 1"
                    ]
                  ]
                ]
              ]
            ],
            [
              "type": "tableCell",
              "attrs": [:],
              "content": [
                [
                  "type": "paragraph",
                  "content": [
                    [
                      "type": "text",
                      "text": "Row 2 Column 2"
                    ]
                  ]
                ]
              ]
            ]
          ]
        ]
      ]
    ]
  ]
]

When you are in issue view, this table example appears as follows:

• paragraph

groovy
[
  "version": 1,
  "type": "doc",
  "content": [
    [
      "type": "paragraph",
      "content": [
        [
          "type": "text",
          "text": "This is a paragraph"
        ]
      ]
    ]
  ]
]

When you are in issue view, this paragraph example appears as follows:

text
return new groovy.json.JsonSlurper().parseText("""
{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "table",
      "attrs": {
        "isNumberColumnEnabled": false,
        "layout": "default",
        "localId": "58c619ab-f32c-4dfa-aa54-2b4b39643deb"
      },
      "content": [
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableHeader",
              "attrs": {},
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Header 1"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableHeader",
              "attrs": {},
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Header 2"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableCell",
              "attrs": {},
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Row 1 Column 1"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {},
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Row 1 Column 2"
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "tableRow",
          "content": [
            {
              "type": "tableCell",
              "attrs": {},
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Row 2 Column 1"
                    }
                  ]
                }
              ]
            },
            {
              "type": "tableCell",
              "attrs": {},
              "content": [
                {
                  "type": "paragraph",
                  "content": [
                    {
                      "type": "text",
                      "text": "Row 2 Column 2"
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
""")