JQL Sync Status and Add-on User Permissions
To enable some of the functionality provided by the enhanced search feature, extra data is added to issues (in hidden properties) to allow for faster searches. The ScriptRunner app needs to read and then write to Jira issues to perform the syncing of metadata.
It is worth noting that sync status is cached for up to 10 minutes. For up-to-date results, go to the JQL Keywords Sync page.
JQL Sync Status
When Enhanced Search for Jira Cloud is installed, an administrator must perform an initial synchronisation before the JQL keywords work in Jira's native JQL search. Note that initial synchronization is also required after migrating from ScriptRunner for Jira Server to Cloud.
The JQL Sync Status, which is always visible from the Enhanced Search editor, indicates the current status of the syncing. The table below describes what each status represents:
Status | Description |
|---|---|
| FULLY SYNCED | The information used by Enhanced Search to run enhanced queries has been updated for all projects. |
SYNC IN PROGRESS | An administrator has triggered syncing of all issues. |
NOT SYNCED | Syncing of issues is disabled, or Enhanced Search has just been installed and a sync has not yet been started. An administrator needs to turn on syncing to ensure the Enhanced Search functions have the information they need. |
PARTIALLY SYNCED | This indicates that there are some projects that Enhanced Search cannot synchronise, which is due to missing privileges required to read and write issues. See below for further details. |
| LOADING | The information required to display the status is being fetched. This may take a few minutes if you have many projects. |
There may be a delay in the correct display of the PARTIALLY SYNCED / FULLY SYNCED status on the Enhanced Search page in the event of changes to the project privilege settings. This is due to the caching of the privilege data.
Partially Synced Status
The first step in investigating the cause of a Partially Synced status is to visit the JQL Keywords Sync page. As an administrator, you can either navigate to Settings→ Apps→ JQL Keywords Sync or click the JQL Sync Status label:
The project table lists privilege issues per project on the JQL Keywords Sync page, as shown below:
Having identified a project and understood the associated warnings, it is also worth determining if the project is Company Managed or Team Managed.
Fixing Permission Warnings
The table below lists permission warnings that may be shown, along with detail on what the warning means and options for updating the relevant permissions.
| Warning | Company/Team Managed | Description |
|---|---|---|
Please check that the add-on user has the ‘edit issues’ permission for this project. | Company-Managed projects | In order to synchronise keywords, the add-on user needs to write extra information onto issues and therefore needs the ‘edit issues' permission. This permission can be granted by editing the Project Permission Scheme associated with the project. One approach would be to grant Edit Issues to the ‘atlassian-addons-admin’ role. |
Please check the add-on user is associated with a project role that has 'Browse Projects' permission. | Company-Managed projects | The add-on user needs Browse Projects to list the issues within a project. This permission can be granted by editing the Project Permission Scheme associated with the project. One approach would be to grant Browse Projects to the ‘atlassian-addons-admin’ role. |
| Team-Managed projects | In the first instance, check the project access level for your project. | |
The add-on does not appear to match any member of the [Level Name] level of the issue security scheme. | Company-Managed projects | This message is only shown for company-managed projects that also have issue-level security in place. Issue-level security can ‘hide’ issues from the add-on user if it is not granted for all levels you have created. Ideally, the ‘atlassian-addons-admin’ role should be granted for each level of your scheme. |
Please check the add-on permissions - it was not possible to retrieve the members of the Issue Security Scheme. | Company-Managed projects | This message is only shown for company-managed projects that also have issue-level security. It does not necessarily indicate a syncing problem - only that the add-on user doesn’t have a full view of the permissions in place. The ‘Administer Jira’ (global permission) is required to retrieve issue security scheme members. The add-on user has this permission by default through the 'atlassian-addons-admin' role. |
Please check your Issue Level Security Scheme setup - no Security Level members could be found. | Company-Managed projects | This message is only shown for company-managed projects that also have issue-level security. It does not necessarily indicate a syncing problem - only that the add-on user doesn’t have a full view of the permissions in place. It may be shown while issue-level security is being configured. Check that the project is using the correct issue security scheme and that the scheme levels are set up correctly. |
The add-on may be granted access to Security Level [Level Name] based on a Group, but this could not be checked as the permission to see groups has not been granted. | Company-Managed projects | This message is only shown for company-managed projects that also have issue-level security. It does not necessarily indicate a syncing problem - only that the add-on user could not check if it is a group used by the security scheme. Only permission to access Jira is required - so this error is unlikely to be shown. |
The add-on may be granted access to Security Level [Level Name] based on a Project Role, but this could not be checked as the permission to see project roles has not been granted. | Company-Managed projects | This message is only shown for company-managed projects that also have issue-level security. It does not necessarily indicate a syncing problem - only that the add-on user could not check if it is in a role used by the security scheme. In order to access Project roles, the add-on requires either ‘Administer Jira’ (global permission) or ‘Administer Projects’ (project permission) |
Add-on User
The add-on user is the user that is created for the add-on (ie ScriptRunner or Enhanced Search), which has the permissions granted for the add-on. The add-on user should have the same account ID for all instances.
- For Enhanced Search for Jira Cloud, the ID is “5d51aee1dbb98c0d9c22cfe3”.
- For ScriptRunner for Jira Cloud's Enhanced Search feature, the ID is “557058:d2e5bd5c-dc49-41eb-a6f0-5e01093666c1”.