ScriptRunner Enhanced Search JQL Queries

Without access to underlying databases, the only way to carry out a search to retrieve data is by using the Search API. The ScriptRunner Enhanced Search feature works by making simple queries to available APIs and processing the results in various ways (using pattern matching, comparing, aggregation etc.).

You can perform searches based on applied filters to view JQL queries which can be run as one-off searches or saved and shared, as outlined below:

  1. Select Apps→ScriptRunner Enhanced Search from the Jira menu bar located at the top of your page.

    Alternatively, you can select Enhanced Search from the left navigation when viewing a project.
  2. Enter your JQL query into the JQL Search bar and click the Search button.

    You also have the option to click the '+' insert function button and choose from the Available Functions list provided. Enhanced Search provides you with custom JQL functions.

  3. Select the function from the Available Functions list within the Functions tab. Depending on the function chosen, you may be required to enter or select subquery details to generate valid JQL for that function. For example, a subquery "project = EXAMPLE" tells the linkedIssuesOf function that it should find issues linked to the results of that subquery.
  4. Click the Add to query button.
  5. (Optional) You can also view the account IDs of users in your Jira instance within the Insert Functions and Users screen. To do so, select the user from the Users tab, view their account ID and click the Add to query button.
  6. Click Search. You are returned to the JQL Search page with a list of results displayed for the function.
  7. Check your query has returned the desired results before continuing and rerun if necessary.
  8. Customize the Results table view by clicking Choose Columns and checking the columns you wish to display.
  9. Click the Save as filter button to save this filter so you can reuse it at a later stage.

  10. Name the filter and enable the Sync Filter toggle so you can use it in dashboards and Jira Software Boards.
    Navigate to Apps→ScriptRunner for Jira→Settings, and scroll to the Filter Sync Interval Period, where you can specify how often ScriptRunner synchronizes your filters. 

    The default interval is five minutes. The maximum allowed interval is an hour. We recommend you to use the default value unless you notice that filter synchronizing makes too many requests to your Jira instance and causes a performance problem.

    Once created, new filters are not synchronized by default. All new filters are synchronized after the default interval of 5 minutes when the Sync Filter option is selected in the Filter Creation Screen. If the Sync Filter option is disabled, the filter does not automatically sync and must be manually synced from the Search screen using the Sync Filter button.

    Every 'X' minute, ScriptRunner will check if something has changed in your Jira issues or if another user has changed the ScriptRunner add-on settings recently. If that check is positive, then filters are synced with the changes made to the issues in your Jira instance.

    Filters are always run with the same set of permissions as the user who created the filter.

    You must make sure that the ScriptRunner Add-On User has the Global Permission to Browse Users in order for this feature to work.

    If you want to update or delete these Enhanced Search filters, use the ScriptRunner Enhanced Search page instead of the Jira filters user interface.

  11. Choose who to share the filter with from the three options provided: share with all, share with a project, or a user group:

    • Checking Share With All shares the filter with all users logged into the Jira Cloud instance.

    • Selecting one or more projects under Choose Projects makes the saved filter available within the selected project(s).

      If you need to use the results of your Enhanced Search filter inside a standard Jira filter such as a dashboard, Scrum, or Kanban board, then you can do this as follows:

      1. Create the filter on the enhanced search page.
      2. Save the filter and share it (This creates a copy of the filter as a standard Jira filter where we synchronise the list of issue keys returned by the enhanced search filter.)
      3. Use the JQL below to access the results of this filter in the feature where you need to reference it.

        filter=‘NameOfHisSharedESFilter’


        Selecting one or more groups under Choose Groups shares the filter with all members of the selected group(s).

  12. Click SaveTo see all saved filters, navigate to Filters→View All Filters.

Saved Filters

You can access your Enhanced Search JQL queries that have been saved as filters from the top left Saved Filters section of the Enhanced Search page. Any of your saved filters can be shared with other users. However, only the owner of a filter can make edits to it.

If you share a filter with another user, they can only view the JQL. In order to modify the filter, they will need to contact the owner of that filter or create a new filter using the JQL, in which case they will then become the owner.

From here, you can understand and work with saved filters in several ways:


FunctionDescription
1Created By You/Shared With YouIndicates filters that are private or shared with you. Any of your saved filters can be shared with other users, however, only the owner of a filter can make edits to it.
2Sort ByUse the drop down list to sort alphabetically.
3Show details/Hide detailsView or hide the owner of a shared filter and other basic information.
4Shared/PrivateIndicates that this is, or is not, a shared filter. You can edit either of these types of filter.
5Delete FilterClick Show details to delete a saved filter. You can only delete a filter that you have created.
6New FilterCreate a new filter search.
7Edit FilterModify an existing saved filter's details, including how it is shared.

Recently, we've made some performance and reliability improvements, which means we do not update the search results for Enhanced Search saved filters that have not been used in Jira for 2 months or more. Specifically, using the saved filter refers to viewing it in a Jira search, a dashboard or an agile board powered by the filter, or other such instances, such as being part of a Confluence macro that uses the filter. Note that viewing the search results for those saved filters does not count as actually using them.

Troubleshooting Tips

If you see an error message informing you that "Function 'X' does not exist", then you should check that you have entered a space after the comma in the query you are running.

Occasionally you may see a red X warning next to your filter indicating there is an issue with it.

You can hover over the warning triangle to find out further information on the cause of the warning.

If hovering over the warning does not indicate an issue related to missing fields or projects, then this could indicate that the filter needs to be re-synchronized. You can re-synchronize the filter by running the search again and clicking the Sync Filter button, and check to see if the warning is removed. Refer to the Get Help section if you continue to see warnings with your filter.


Related Content

On this page