Scripted Fields

Use Scripted fields to create custom fields with dynamic content. They let you display information that isn’t directly available on a work item by calculating or aggregating data from one or more existing fields. You could use a scripted field to:

• Show a value from a linked instance

• Show a value calculated from the values of other work item fields

• Show a value calculated from the values of fields in other work items

Scripted fields appear on any screens you assign them to.

Available scripted fields

The following scripted fields are available:

• String: Show a text value generated by a script.
• Multi-string: Show multiline text generated by a script.
• Number: Show a number calculated by a script.
• User: Show a single user determined by a script.
• Multi-user: Show multiple users determined by a script.
• Group: Show a single group determined by a script.
• Multi-group: Show multiple groups determined by a script.
• Date and time: Show a date and time calculated by a script.
• Date: Show a date calculated by a script.

Output and logging

When you run a script, the output panel shows:

• Anything logged with console.log(...)
• The final value returned by your script with return

Use console.log(...) for messages, intermediate values, or debugging, and include a return statement for the main result you want to display. When testing, each time you select Run, the output panel is cleared and refreshed with the latest logs and return value.

Execution history

Saved scripted fields keep a full execution history, so you can review when they were run, and what the output was, making it easier to audit and troubleshoot. Execution history is stored for two weeks before it is refreshed. 

Create a scripted field

You can create scripted fields directly in ScriptRunner, or create them in Jira like any other custom field and then configure the script in ScriptRunner. To create a scripted field in ScriptRunner:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Scripted fields.
4. Select Create.
5. Enter a Name and, optionally, a Description.
6. Select the Field type you wish to create. For more information, see the available scripted fields above.
   

   You can’t change the Field type after a scripted field has been created. If you need a different field type with similar behavior, create a new scripted field and configure it separately.

7. Choose who you want the script to Run as. Select whether the scripted field runs with ScriptRunner app permissions or as a specific user.
8. Write your script.
   

   To help you write scripts, you can use the scripted field examples, use HAPI, or select Example scripts directly in the script editor.

9. Optional: Select Test to test your script against JSON data and make sure it works as expected (see Test a scripted field for more details).
   • You can load test data for a specific work item, edit it, and optionally save it for reuse in future tests of this scripted field.
   • If the script performs updates (for example, creates or edits work items), those changes are applied to your Jira instance.
   • Test in a non‑production environment first.
   • Use the Output panel to review results and troubleshoot any errors.
10. Select Save. 
    

    Custom field ID

    The custom field ID is automatically generated when you create a scripted field. 

11. Associate your new field with relevant screens. See Atlassian's documentation for more information.

Test a scripted field

You can test your scripted fields against test data for work items before using them on real screens. This lets you confirm that your script behaves as expected for a specific work item. Test data is the JSON data that identifies the work item and scripted field context your script runs against. For scripted fields, the JSON data typically includes:

• id: the internal ID of the work item your script will run against.
• context: the numeric ID of the scripted field context in which the script is executing. This lets ScriptRunner resolve context‑specific configuration (for example, different behavior per project or work type).

Test your scripted field as follows:

1. When creating a scripted field, select Test. A testing panel displays. 

2. Enter a work item key (for example, ABC-123) to load JSON data. This generates JSON data like the example above, identifying the work item and context your script will run against.

3. Optional: Edit the test data if necessary. This is useful if you want to simulate running the script against a different work item ID or context without changing your actual configuration.

4. Select Run. The Output panel shows:

   • Anything logged with console.log(...)
   • The final value returned by your script with return

5. If necessary, edit your script and test again until the output matches your expectations.

   If your script performs updates (for example, creates or edits work items, comments, or links), those changes are applied to your Jira instance even when running tests. Always test destructive or bulk‑update logic in a non‑production environment first.

6. Optional: Save the test data. The saved test data can be reused for future tests of the same scripted field, so you do not need to re‑enter or reconstruct it each time.

Edit a scripted field

To edit a scripted field:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Scripted fields.
4. Find your scripted field in the list and select Edit.
5. Modify the scripted field as needed.
6. Optional: Select Test to test your script against JSON data and make sure it works as expected (see Test a scripted field for more details).
   • You can load test data for a specific work item, edit it, and optionally save it for reuse in future tests of this scripted field.
   • If the script performs updates (for example, creates or edits work items), those changes are applied to your Jira instance.
   • Test in a non‑production environment first.
   • Use the Output panel to review results and troubleshoot any errors.
7. Select Save. 

Find the custom field ID for a scripted field

The custom field ID is automatically generated when you create a scripted field. To find the custom field ID:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Scripted fields.
4. Find your scripted field in the list and select Edit.
5. The field ID displays as a read-only field on the page.

Enable and disable a scripted field

Disabling a scripted field pauses its script so it no longer calculates a value. The field will appear disabled and empty wherever it is used, but it remains on your screens and contexts, and its configuration is preserved. When you enable the field again, its script runs as normal and the value is recalculated and displayed. This is a safe way to pause a field temporarily without deleting it.

To enable or disable your scripted field:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. In ScriptRunner, select Scripted fields.
4. Locate the scripted field you want to enable or disable.
5. Open the ellipsis (…) menu for that scripted field and select Disable or Enable.

Delete a scripted field

Remove scripted fields you no longer need to keep your list organized and reduce clutter. When you delete a scripted field, it’s removed from work items and screens so users can no longer see or use it, but it isn’t permanently removed. You can still access it in ScriptRunner (using the Deleted filter) or in the Deleted fields area of the Jira admin settings, and restore it later if needed. The custom field ID is retained and will be the same if you restore the field.

To delete a scripted field:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Scripted fields.
4. Find the scripted field you want to remove.
5. Open the ellipsis (…) menu for that scripted field.
6. Select Delete.
7. When prompted, confirm that you want to delete the scripted field. 

Restore a deleted scripted field

When you restore a scripted field, it becomes active again in Jira and ScriptRunner. Its full execution history is available, it’s re‑added to all the screens and work items it was associated with before deletion, and it keeps the same custom field ID it had originally.

To restore a deleted scripted field:

1. In Jira administration, select Marketplace apps.
2. Under Apps, select ScriptRunner.js.
3. Select Scripted fields.
4. Use the filter and select Deleted to view deleted scripted fields.
5. Find the scripted field you want to restore.
6. Open the ellipsis (…) menu for that scripted field.
7. Select Restore.