Integration with ScriptRunner for Jira

Adaptavist's ScriptRunner for Jira is a collection of powerful but easy-to-use workflow functions, JQL functions, listeners, and services, enabling the automation of a wide range of tasks in Jira and other tools in the Atlassian ecosystem. Project Configurator currently supports ScriptRunner Behaviours, Workflows, Resources, Script Fields, REST Endpoints, Jobs, Fragments, and Listeners. We continue to develop more integrations with the aim to fully support all ScriptRunner features soon.

Minimum Version Requirements

Refer to the table below to confirm the minimum version requirements of Project Configurator (PCJ) and ScriptRunner for Jira (SR4J) needed to make the most of our latest integrations.

ScriptRunner Behaviours

Project Configurator handles the migration of ScriptRunner for Jira behaviours. Behaviours give you more control over fields in Jira. A field configuration customizes how fields behave, based on the issue operation screen they appear on.

However, behaviour in ScriptRunner allows you to take that field customization further, defining how fields behave for issues in a given project or issue context.

You can create behaviours to:

• Make a field mandatory depending on other data entered on the issue screen.

• Make a field read-only dependent on the user role or group.

• Conduct server-side validation of field data before the issue screen is submitted.

• Set a field value depending on other issue screen data.

When generating an export file, Project Configurator detects any behaviours you have configured related to the exported projects and includes them in the export file.

To learn more about ScriptRunner behaviours, see the ScriptRunner documentation.

ScriptRunner Workflows

Project Configurator handles the migration of ScriptRunner for Jira workflows, whether built-in or scripted. ScriptRunner for Jira Server uses scripted versions of workflow functions to extend and customize the automated tasks available in Jira workflows.

These workflow functions include scripted validators, scripted conditions, and scripted post functions. As with many features of ScriptRunner, you can select from built-in options, you can customize the built-in functions, or you can write your own.

These scripted workflow functions allow you to do a lot more with your Jira workflows and further enhance your automation. For each of the Jira workflow functions, ScriptRunner for Jira provides scripted versions, so that you can suit your workflows to your exact needs.

There are three main types of scripted functions: script validator, script condition, and script post function. When generating an export file, Project Configurator detects and correctly handles any ScriptRunner conditions, validators, or post functions in the exported workflows. When importing this file, these workflows are either created or updated in the target instance.

To learn more about ScriptRunner workflows, see the ScriptRunner documentation.

ScriptRunner Resources

ScriptRunner resources enable you to set up local or external database connections that you can then use in scripts, for example, in a post-function to update a sales database with a link to the current ticket. Project Configurator migrates all resources that are part of a script field. 

For more information on setting up resources, see ScriptRunner's Resources documentation.

ScriptRunner Script Fields

Project Configurator supports the migration of ScriptRunner Script Fields.

To learn more about these features, refer to the ScriptRunner documentation. Cases in which custom field values are implicated when migrating data are described below.

How the field values are handled by Project Configurator

Database Picker
If the stored value is referencing an external database, the migration occurs, and the reference is valid in the target instance, provided that the target instance also has access to the external database.

If the stored values are referencing the local Jira database, ensure that the script fields do not reference local IDs in the export file. The values will be migrated but not mapped to objects in the target instance. If you are planning on migrating data, it is recommended that you reference project names instead of their unique IDs. Refer to the ScriptRunner documentation to learn more about using the Database Picker Script Field.

LDAP Picker
Since the stored values reference objects in external servers, they can be migrated and remain consistent in the target instance, provided that the target instance also has access to the LDAP server. Refer to the ScriptRunner documentation to learn more about using the LDAP Picker Script Field.

Issue Picker
The stored value is the ID of the referenced issue. For example, where issue AAA-1 has an issue picker field that points to issue BBB-7, consider AAA-1 the owner issue and issue BBB-7 the referenced issue. This can be migrated only if the owner and referenced issues belong to the same project that is being migrated. This limitation is due to Jira’s built-in data transfer technology that handles one project at a time. Project Configurator calls it for each project being migrated.

If the referenced issue already exists in the target instance in a different project, the migration will not be possible. It is important to note that in all circumstances, data can only be imported into empty projects. When there is a value for an issue picker field that cannot be imported, a warning is displayed. In this case, it is recommended that you check the import trace following complete project imports to assess the relevance of any data that could not be migrated.
Refer to the ScriptRunner documentation to learn more about using the Issue Picker Script Field.

Remote Issue Picker
Like the LDAP Picker field, references to issues in the Remote Issue Picker fields are linked to an external Jira server and can, therefore, be migrated without any translation or mapping, provided that the target instance has access to the instance holding the remote issues. Refer to the ScriptRunner documentation to learn more about using the Remote Issue Picker Script Field.

ScriptRunner REST Endpoints

You can define REST endpoints in ScriptRunner for several purposes, for example, to receive notifications from external systems. Project Configurator exports all ScriptRunner REST endpoints irrespective of how they may be used by the exported projects.

For more information on using script REST endpoints, see the ScriptRunner documentation. 

ScriptRunner Jobs

ScriptRunner Jobs allows you to run your own code at regular intervals, for example, to delete inactive users on a monthly basis. Project Configurator migrates all ScriptRunner job types: custom jobs, escalation services, and issue archiving jobs. Like REST endpoints, all jobs are migrated, irrespective of how they relate to any exported projects.

See the ScriptRunner documentation to learn more about how you can use different job types.

ScriptRunner Fragments

Fragments are used to make changes to your Jira UI, for example, to add a banner to a Jira issue or a new menu item in the More Actions menu. Any ScriptRunner fragments added to your instance can be exported using Project Configurator.

See the ScriptRunner documentation to learn more about using ScriptRunner to customize the appearance of your Jira instance.

ScriptRunner Listeners

A listener is an automated procedure or function in ScriptRunner that waits (or listens) for a specific event to occur in Jira and then carries out an action if the event occurs. Project Configurator supports the migration of both types of listeners: built-in or custom. 

See the ScriptRunner documentation to learn more about where to use Listeners.

Example migration 

Here, we have included an example of how seamlessly Project Configurator handles the migration of ScriptRunner features. This short demonstration video explains how to set up a simple behavior in ScriptRunner and migrate the change to a target Jira instance.

Open