Search for Work Items

Learn how to use Issues.search with Jira Query Language (JQL), request only the fields you need, and loop through results, limit them, or stop early.

With HAPI, you can search for work items with JQL using the Issues.search method, and process the results as an asynchronous stream.

Pattern for searching work items with HAPI

When you search for work items with HAPI, you can follow this basic pattern:
Import Issues from @scriptrunnerhq/hapi/issues.
Call Issues.search with a JQL string and an options object.
Specify which fields you need in the fields option (by default, only the ID is returned).
Iterate over the results using a for await ... of loop.
Optionally use options like maxResults, or break early from the loop based on a condition.

The following example shows this general pattern:

import * as Issues from '@scriptrunnerhq/hapi/issues'
 
export default async function () {
  // Run a JQL search and iterate through matching work items
  for await (const issue of Issues.search('project = SPACE_KEY', {
    // Specify the fields you plan to use
    fields: ['key', 'summary'],
    // You can also set maxResults or other options here
    // maxResults: 50,
  })) {
    // Access fields you requested above
    console.log(issue.key + ': ' + issue.fields.summary)
  }
}

You can use the same Issues.search pattern to:

Run basic JQL queries and work with selected fields.
Limit how many work items you process.
Stop early when you've found what you need.

In-app example scripts

The following examples are available in-app:

Search work items (basic): Shows how to run a JQL search (for example, all issues in a project) and iterate through results using for await ... of, while specifying required fields like key and summary.
Search work items with limits and early exit: Demonstrates how to:
- Use the maxResults option to cap how many work items are returned.
- Break out of the for await ... of loop early when a condition is met (for example, when an issue has an assignee).