Documentation

01 Getting started

TextToJQL adds a page to Jira's Apps menu. Open it, and you'll see a single text box: describe the issues you're looking for in plain English — for example, "overdue tasks assigned to me" or "bugs opened this week" — and click Generate JQL.

The app returns a real, ready-to-run Jira Query Language (JQL) string. If it's valid, a Search in Jira button appears — click it to run that exact search immediately, either in the same tab or a new one, depending on your saved preference (toggled next to the button).

02 Example queries

A "Try:" row under the text box offers a few starting examples — click one to load it into the box, then tweak it or generate it as-is. This row can be collapsed with the Hide examples / Show examples toggle once you no longer need it, keeping the page tidy.

A few phrasings TextToJQL handles well:

• "overdue tasks assigned to me"
• "overdue tasks assigned to Chris Phillips"
• "bugs opened this week"
• "issues with no assignee"
• "overdue tasks with no assignees"
• "highest priority issues, newest first"
• "issues that changed status to Done in the last 7 days"
• "all bugs in current sprints where not in progress"
• "all bugs in future sprints where not in progress"

TextToJQL also recognizes your own site's custom fields by name (not just standard fields like assignee, status, or priority) — see Custom fields below.

03 How validation works

Every query TextToJQL generates is checked against your Jira site's own JQL parser before it's shown to you — it isn't just a raw AI response. That check runs as you, so what you see is already scoped to what you're actually able to see in Jira. If the first attempt has a problem, the app automatically retries with the specific error fed back in, so what you see has already been confirmed to parse. If a query still can't be resolved after a couple of attempts, you'll see a plain-English explanation of what went wrong and a suggestion to rephrase — being specific about status, assignee, or dates usually helps.

If you want to see exactly what happened behind the scenes on a given query — each attempt's raw AI output, the sanitized JQL, and any validation errors — expand Show debug info underneath the result.

04 Requests & limits

To keep things fast and keep AI costs sane, a couple of simple limits apply — neither affects what data you can see, only how you send requests:

• 500-character cap. A request longer than that is rejected before anything is sent, with a message telling you the exact length and the limit so you can trim it.
• A short pause between requests. If you generate queries back-to-back, you may see "You're sending requests a little too quickly — please wait a few seconds and try again." Just wait a moment and try again — it isn't an error with your query.

05 Custom fields

TextToJQL keeps a cached mapping of your site's custom field names to their internal IDs, so a request naming a real field on your site (e.g. "Story Points") resolves correctly instead of falling back to generic text search. This mapping refreshes automatically once a day.

If a Jira admin has just added or renamed a custom field and doesn't want to wait for the daily refresh, a Refresh field cache button is available — visible only to users with Jira's "Administer Jira" permission, since it's the one action in the app with a real cost beyond everyday query generation.

06 Subscription status

TextToJQL is a paid-via-Atlassian app. Sites with 10 or fewer users use it at no cost; larger sites get a standard 30-day evaluation before billing begins. If a paid site's subscription lapses, query generation is paused with a message explaining that an active subscription is needed — site admins can check or renew the subscription from Jira's own app-management screen.

07 Uninstalling

Uninstalling TextToJQL automatically cleans up everything the app cached for your site — the custom-field mapping and every user's saved tab preference — as part of the removal process. See the Privacy Policy for full details on what's stored and for how long.

08 Support