JQL Keywords Synchronization
When ScriptRunner for Jira Cloud is installed, an initial synchronization must be performed by an administrator. Although the administrator initiates the synchronization process, the issues are accessed as the ScriptRunner user.
ScriptRunner Enhanced Search augments each issue in your Jira instance with some additional metadata and provides a number of JQL keywords that you can use within your JQL queries to access this metadata. These keywords allow users to search for previously unavailable variables, such as the number of sub-tasks (
numberOfSubtasks). The metadata is stored within your Jira instance.
The 'Issue Updated' field on your issues is NOT affected by the metadata that we store against each issue.
The metadata that we store against each issue is automatically updated asynchronously whenever an issue is updated. This means that your search results may be out-of-date for a short while after you edit an issue.
To carry out the initial synchronization on the JQL Keywords Sync page:
- Navigate to the JQL Keywords Sync page from the Jira Administration menu by selecting Apps→ScriptRunner→JQL Keywords Sync.
- Click the Sync All Issues button, as shown below:
You can safely close the page or shut down your computer once the sync is in progress.
A list displays containing metadata that is stored for each issue, including:
a list of the link types (e.g. Blocks) for linked issues
the number of issue links
a list of link names (e.g. "is cloned by") for linked issues
number of attachments on the issue
list of file extensions from attachments
the date on which the first attachment was added to the issue
date on which the last (most recent) attachment was added to the issue
list of username that added attachments to the issue
number of subtasks of the issue
list of project roles that worklogs were restricted to
list of user groups that worklogs were restricted to
number of comments on the issue
date of the first comment on the issue
date of the last (most recent) comment on the issue
list of all dates on which comments were added to the issue
list of usernames that have added comments to the issue
list of project roles that comments have been restricted to
list of user groups that comments have been restricted to
the username of the person who last (most recent) made a comment on the issue
the project role that the last (most recent) comment was restricted to
the user group that the last (most recent) comment was restricted to
You may encounter issues that do not sync for instances where you have a workflow property setup that does not allow an add-on user to edit an issue if it was in the Resolved status.
It is good practice to check that you do not have any workflow properties setup to adjust permissions on an issue (jira.permission property). You can refer to Use workflow properties for more details.
Enhanced Search Syncing
JQL Keyword Sync
As outlined in the section above, a JQL Keyword sync is required once only after installing ScriptRunner for Jira Cloud. As this sync needs to update every issue in your instance, it can take a significant amount of time if your instance contains a large number of issues.
The metadata saved to your issues allows for faster recall when searching because many searches will find the metadata instead of calculating it on the fly each time you search. You may search directly for these keywords, or you may search using JQL functions that use this metadata. Many Enhanced Search functions will use the metadata saved to your issues to run searches.
When issues are updated (added or edited in some way) in Jira, the data stored in Enhanced Search needs to be updated so that your searches use the most updated information on your issues. The issue sync includes updating metadata and occurs every 1-5 minutes.
The results of a filter need to be accurate, so ensuring that the Jira filter (results of ES search) has the latest information from the original Enhanced Search filter is necessary. The filter sync occurs every 1-10min and fetches all users who own ES filters and sends a message to synchronise.
JQL Keyword Sync for Enhanced Search Functions
Although not all Enhanced Search functions require a JQL keyword sync, there are specific functions that do, including:
You should also be aware that all JQL aliases also require a JQL keyword sync.
The ScriptRunner user can only see comments and worklogs from the following groups:
Search results will be incorrect if the ScriptRunner user does not have permission to view:
Edit all issues (edit permission is required to store the additional metadata).
All comments, including those restricted to a particular group/role.
All worklogs, including those restricted to a particular group/role.
If worklogs and comments are restricted to a role, ensure the role is assigned to the group the ScriptRunner user belongs to under Project Settings.