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.

    Search run-time

    Searches can run for up to two minutes, with a progress bar indicating the status. We recommend simplifying your query as much as possible and using our Tips for Writing JQL Queries to reduce the run time.

  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 groups under Choose Groups shares the filter with all members of the selected group(s).

    • 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’
  12. Click Save. To see all saved filters, navigate to Filters→View All Filters.

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