JQL Builder – Advanced Search

JQL Builder – Advanced Search — User guide

JQL Builder turns Jira's search language (JQL) into a form. Fill in the fields you care about and the app writes the JQL for you. You can see the query as you build it, check it, preview the results, and open it in Jira's own search.

Opening the app

The app needs no setup: install it and every user on the site can use it. Each user's saved and recent searches are private to them.

  1. Fill in fields. The form is grouped into Common fields, Other fields and Custom fields; click a section title to expand or collapse it. Use Find a field (status, assignee…) to jump to a field by name. If the filter hides fields you have filled in, a line above the form says how many — they are still part of the query.
  2. Pick an operator for a row (for example =, IN, ~, IS EMPTY, WAS, CHANGED). The app remembers the operator you last used per field.
  3. Choose how rows combine with Match: — all conditions (AND) or any condition (OR).
  4. Watch the JQL: line above the form. It updates as you type. Copy JQL in the row under it copies the query, for a board filter, a dashboard or an automation rule.
  5. Press Search to open the query in Jira's search, or Reset to start again. Reset says Form cleared. with an Undo button, in case you pressed it by mistake; the offer lasts until you next change the form.

To go straight to one work item, type its key (for example PROJ-1) in the Work item key box at the top and press Go.

Per-row extras:

Query options holds the sort order (Sort by:, with an optional second key) and the linked-work-item condition builder.

Custom fields

Choose + Add custom field and pick any custom field on your site. It gets its own row with the operators that field type supports. Remove takes the row out of the form without changing the field in Jira.

Writing JQL directly

Choose Edit JQL to type or paste JQL yourself. Validate JQL checks it against your site, and Beautify JQL reformats it over several lines.

To leave the editor, Load into form fills the fields from your JQL (and says what, if anything, the form could not hold), while Cancel goes back to the query the fields build and discards what you typed — with an Undo to bring it back.

Hints

A Hint — line under the query points out JQL that runs but probably does not do what you meant — for example that assignee != jsmith also leaves out unassigned work items, or that a text search with no project scans every project you can see. Hints never block anything; they disappear once the query changes.

Starting points

Saving and sharing

The More menu has:

Action What it does
Search in new tab Runs the search in a new browser tab, so the builder stays open in this one.
Save search Saves the form under a name (up to 20 per user). Saving under a name you already used replaces that search — the dialog says so first. Mark a saved search as a template to list it under Templates (both the menu and the tab). In Edit JQL mode your JQL is loaded into the form first; if the form cannot hold all of it, nothing is saved and a message says why.
Save as Jira filter Creates a normal Jira filter owned by you, shared with only you, everyone signed in, or a project (Share with). Using the name of a filter you already own replaces that filter's query instead — its sharing, subscriptions and boards are kept.
Import Jira filter Loads a filter into the form (see above).
Export / Import config Copies the whole form as text, or loads one someone sent you.
Back up saved searches Copies all your saved searches as one piece of text. Paste it into Export / Import config (here or on another site) and press Restore searches: searches whose names you already use are skipped, never replaced.
Share JQL link Gives a Jira search link for the current query.
Share full form link Gives a link that opens this app with the same form filled in.
Explain JQL Describes the current query in plain English — and, if Jira has already refused it, lists Jira's errors above the description.

After you load a saved search (or save one), a line above the JQL says Editing saved search with its name, and whether the form has Unsaved changes. Update writes the form back to that search; Save as… saves a copy under a new name.

JQL & History opens a panel with the JQL tools and three tabs:

On a dashboard

Add the JQL Builder – Search overview gadget to a Jira dashboard to show a query's approximate count, how broad it is, and a pie or bar breakdown by status, assignee, priority or type. In the gadget's settings, type JQL or start from one of your saved searches; Save checks the query with Jira first.

Site templates (Jira administrators)

Jira settings → Apps → JQL Builder – Site templates lists the templates everyone on the site sees. Add one with a name, optional description and tags, and its JQL (Check JQL asks Jira whether it is valid). Write currentUser() rather than naming a person — templates that name someone are refused, as they are shared with everyone.

Settings

The ⚙ Settings menu has:

Permissions and privacy

The app acts as you. It sees only the projects and work items you can already see in Jira, and it changes Jira only when you choose Save as Jira filter. It sends no data outside Atlassian. See PRIVACY.md for what is stored and for how long.

Troubleshooting

Symptom Why / what to do
Search is disabled Nothing is filled in yet, or Jira reported an error in the JQL — shown under the JQL: line. The message next to the button says which.
Count unavailable Jira won't count queries with no conditions (for example, only a sort order). Add a condition.
A field is missing It doesn't exist on your site. Turn on Show unsupported fields to see it anyway.
A custom field is missing from + Add custom field Jira lists only custom fields that are on at least one screen. Ask your Jira admin to add the field to a screen.

Support

Questions, bug reports, feature requests and data requests go to support@kashukov.com. Support hours are Monday–Friday, 9:00–18:00 GMT+2.

To get an answer faster, include:

You can also ask and browse answers on the Atlassian Community — the link is on the app's Marketplace listing.