Synchronising Keywords

When Enhanced Search for Jira Cloud is installed, an administrator must perform an initial synchronisation (sync) before the JQL keywords work in Jira's native JQL search. To do this, follow the instructions provided below, or take a look at our short video presentation:

Initial Synchronisation Estimate

You must carry out an initial JQL Keyword sync once only after installing Enhanced Search. The length of time that this sync will take is based on the following calculation:

(<number of issues in instance> * 0.00029) / 50

Based on this calculation, we can estimate a timeline for your initial sync. For example, if your instance has:

  • 1,000,000 issues we estimate it will take 5.8 days to complete the initial sync.
  • 2,000,000 issues we estimate it will take 11.6 days to complete the initial sync.

Perform an Initial Synchronisation

  1. Navigate to the Sync Keywords page, where you will see a yellow notification informing you that an initial sync is required. There are several ways to navigate to the Sync Keywords page:

    • Click Go to Sync Keywords on the Welcome to Enhanced Search for Jira Cloud post-install page.

    • Navigate to the Manage Apps screen. Find Enhanced Search and click Get Started to view the Welcome to Enhanced Search for Jira Cloud post-install page. From this page click Go to Sync Keywords.

    • If this is the first synchronization, a banner and link appear when opening Enhanced Search.

    • Navigate to the sync page with a direct URL.

  2. Click Sync All Issues. All issues in the projects listed under Synchronisation are synchronised.

You can safely close the page or shut down your computer once the sync is in progress.

Currently, instances that contain more than 500,000 issues may take a significant amount of time to sync. In some cases, this can take several weeks. If your instance falls into this category, we strongly advise you to create a Support ticket so we can keep track of the initial sync with you.

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

  • the number of attachments on the issue

  • a list of file extensions from attachments

  • the date on which the first attachment was added to the issue

  • the date on which the last (most recent) attachment was added to the issue

  • a list of usernames that added attachments to the issue

  • the number of subtasks of the issue

  • a list of project roles that worklogs were restricted to

  • a list of user groups that worklogs were restricted to

  • the number of comments on the issue

  • the date of the first comment on the issue

  • the date of the last (most recent) comment on the issue

  • a list of all dates on which comments were added to the issue

  • a list of usernames that have added comments to the issue

  • a list of project roles that comments have been restricted to

  • a 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 here for more details.

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:

  • addedAfterSprintStart

  • linkedIssuesOf

You should also be aware that all JQL aliases also require a JQL keyword sync.

Permissions

Enhanced Search for Jira Cloud users can only see comments and worklogs from the following groups:

  • jira-core-users

  • jira-servicedesk-users

  • jira-software-users

  • jira-servicemanagement-users-<sitename>
  • jira-workmgmt-users-<sitename>
  • jira-software-users-<sitename>

Search results will be incorrect if permissions are not granted 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 Enhanced Search for Jira Cloud user belongs to under Project Settings.

Issue synchronisation failures are usually caused by permissions issues. Check the administrator user has permission to edit and view the issues before synchronisation.

JQL Sync Status and Add-on User Permissions

To enable some of the functionality provided by Enhanced Search for Jira Cloud, extra data is added to issues (in hidden properties) to allow for faster searches.

It is worth noting that sync status is cached for up to 10 minutes. For up-to-date results, go to the JQL Sync Keywords 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.

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 SYNCEDThe information used by Enhanced Search to run enhanced queries has been updated for all projects.

SYNC IN PROGRESS

An administrator has triggered the 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 must turn on syncing to ensure the Enhanced Search functions have the necessary information. 

PARTIALLY SYNCED

This indicates that there are some projects that Enhanced Search cannot synchronise because of missing privileges required to read and write issues.

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.

WarningCompany ManagedTeam  ManagedDescription

Please check that the add-on user has the ‘edit issues’ permission for this project.

Y

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.

See: Jira documentation on Permission Schemes

Please check the add-on user is associated with a project role that has 'Browse Projects' permission.

YY

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.

See: Jira documentation on Permission Schemes


Y

In the first instance, check the project access level for your project.

See: Team-managed project permissions

The add-on does not appear to match any member of the [Level Name] level of the issue security scheme.

Y

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.

See: Configuring Issue Security Schemes

Please check the add-on permissions - it was not possible to retrieve the members of the Issue Security Scheme.

Y

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.

See: Managing Global Permissions

Please check your Issue Level Security Scheme setup - no Security Level members could be found.

Y

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.

See: Configuring Issue Security Schemes

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.

Y

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 permission to see project roles has not been granted.

Y

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)

See: Configuring Issue Security Schemes

Add-on Users

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.

On this page