- What it does
- Quick example
- Syntax
- Setup
- Script context
- Return formats
- Cache freshness
- Limits
- Permissions
- Disabling a JQL function
- Troubleshooting
- Related
What it does
Custom JQL functions let you extend Jira’s query language with logic written in JiBrok Studio. Users write issue in jbExec("yourFunctionName", arg1, arg2) in any JQL field; your script returns the set of matching issues, and Jira filters accordingly.
This is different from a Scripted Field. A Scripted Field stores a value on each issue. A JQL function takes a query parameter, runs your script, and produces a set of matching issues at search time. Use a JQL function when the matching logic involves linked-issue traversal, parent/child relationships, cross-issue computations, or arguments supplied by the user at search time.
Quick example
In JiBrok Studio, write a script that returns linked-issue keys:
// jqlFunction is a frozen top-level object provided by JiBrok Studio.
// jqlFunction.args holds the arguments passed in JQL after the function name.
const sourceKey = jqlFunction.args[0];
const linkType = jqlFunction.args[1] || 'Blocks';
const issue = await Issues.get(sourceKey);
if (!issue) return [];
// Each link has type (link type name), direction ("inward"/"outward") and key
return issue.links
.filter(l => l.type === linkType && l.direction === 'outward')
.map(l => l.key);
Register this script as the JQL function findBlockers. Then in any Jira search:
issue in jbExec("findBlockers", "PROJ-1", "Blocks")
Jira returns every issue that “PROJ-1” blocks.
Syntax
issue in jbExec("functionName", arg1, arg2, ..., arg10)
issue not in jbExec("functionName", arg1, ...)
- The first argument is the registered function name (case-insensitive).
- Up to 10 user arguments can follow.
- The function works with the
issuefield and thein/not inoperators.
The name jbExec itself is reserved and cannot be used as a registered function name.
Setup
- In the Console, write a script that reads arguments from
jqlFunction.args, add a JQL Function trigger to it and save. Set the script’s Run as to Application or a specific user - Current user is rejected, because searches and the scheduled cache refresh have no user context. - Open the JQL Functions tab of the Admin Panel.
- Click Add function, choose a name (1-64 characters, must start with a letter, then letters / digits / underscores), pick the script, optionally add a description. Only scripts with a JQL Function trigger are listed.
- Save. The function is available immediately in JQL across the whole site.
Script context
JiBrok Studio adds a frozen top-level jqlFunction object to the script scope:
| Field | Type | Description |
|---|---|---|
jqlFunction.name |
string | Lowercased function name. |
jqlFunction.operator |
string | in or not in. |
jqlFunction.args |
array | User arguments after the function name (up to 10), as a native JS array. |
The same data is also available as event.jqlFunction (kept for symmetry with other triggers’ event payload). Use whichever reads better in your script. Trigger parameters are not passed to JQL Function scripts.
Return formats
Three formats are accepted.
Array of issue keys
return ["PROJ-1", "PROJ-2", "PROJ-3"];
JiBrok Studio wraps these into issuekey in ("PROJ-1","PROJ-2","PROJ-3"). Invalid keys are dropped, duplicates removed. An empty array produces a fragment that matches nothing (or, with not in, everything).
Array of numeric issue IDs (recommended)
return [10001, 10002, 10003];
JiBrok Studio wraps these into id in (10001,10002,10003). Atlassian recommends this form because Jira’s internal search is optimised for numeric IDs over string keys. If your script already has IDs (for example from a jql/search API response), prefer this format.
The mode is decided by the first non-null element of the array. Mixed arrays drop the off-mode items.
JQL fragment as a string
return 'project = TEST AND status = Done AND created > -7d';
The fragment is wrapped in parentheses (and prefixed with NOT when the operator is not in). It is rejected if it contains forbidden characters (;, --, /* */, \), exceeds 8000 characters, or has unbalanced parentheses or quotes.
Returning anything else (object, mixed types, null) produces an error in Jira’s search UI.
Cache freshness
Forge caches each (functionName, args) result for 7 days. To avoid showing stale data, the cache is refreshed automatically and on demand:
- A scheduled job runs every 5 minutes. It iterates through every enabled JQL function and recomputes its precomputations. The upper bound on staleness is roughly the scheduler interval (plus the recompute time).
- You edit the function in the JQL Functions tab. If you change the bound script or the enabled flag, all cached precomputations for that function are recomputed and pushed back to Jira before the dialog closes.
- You edit the script source in the Console. Every JQL function bound to that script gets a refresh in the background.
- Click “Refresh cache” in the JQL Functions tab. Forces an immediate recompute.
Safeguards (so refreshes do not run away with your Jira API quota):
- A function can refresh at most once per minute. Repeated triggers within that window are skipped (you’ll see a “rate-limited” notice in the UI). The 5-minute scheduler is comfortably outside this window.
- If a function has more than 50 cached precomputations at refresh time, the refresh is skipped with a warning. Wait for the 7-day TTL or use the manual button after some entries expire.
- When a function is disabled or deleted, its cached entries are marked with an error message (“JQL function disabled” or “JQL function deleted”) so users see a clear reason instead of stale results.
Cost note: Atlassian’s precomputation API has no DELETE endpoint, so “invalidating” a cached result really means recomputing it and pushing the new value. Each refresh runs your script once per cached call. If your function has many cached calls and a fast-changing data set, the 5-minute scheduler still costs N script executions every interval - keep that in mind when picking which logic to expose as a JQL function.
Limits
| Limit | Value | Source |
|---|---|---|
| Max execution time per call | 22 seconds | Engine config |
| Max API calls per execution | 60 | Engine config |
| Max issue keys or IDs returned | 1000 (arrays are deduplicated, extra items are dropped) | Forge JQL function platform |
| Max raw JQL fragment length | 8000 characters | App-level |
| Result cache lifetime | 7 days | Forge precomputation cache |
| Max precomputations per refresh | 50 | App-level safety cap |
| Refresh rate limit | 1 per minute per function | App-level |
| Max user arguments | 10 | Forge platform limit |
Results are cached by (functionName, args). The same call returns the cached result for up to 7 days; the script does not re-run on every search.
Permissions
JQL function results are not permission-filtered by your script. Jira applies the user’s issue permissions after the function returns, so users only see the keys they’re allowed to see.
The function never runs as the searcher. It runs as the script’s Run as setting - Application or a specific user - and all script API calls use that identity’s permissions. You cannot bind a script with Run as: Current user to a JQL function trigger - searches and the scheduled refresh run without user context, so the setting is rejected.
Two users searching with the same JQL get the same cached value. The script returns the same set of candidate keys for everyone; Jira filters per-user via standard issue permissions. Do not use the script as a per-user permission gate.
Disabling a JQL function
- Switch off Enabled for the function in the JQL Functions tab. The function still parses but returns an error in Jira’s search UI.
- Switch off the JQL Function trigger type globally in Admin Panel -> Admin -> Triggers. All JQL functions stop responding.
- Delete the function entirely. Cached results are invalidated with a “JQL function deleted” message and expire within 7 days.
Troubleshooting
| Message in Jira search UI | Meaning | What to do |
|---|---|---|
| “JQL function … is not registered” | Name typo, or the function has not been created | Check the name (case is normalized to lowercase) and the JQL Functions tab |
| “Function must return an array of issue keys or a JQL fragment string” | Script returned an unsupported type | Add return [...] or return "..." to the script |
| “Script execution failed” | Runtime error in the bound script | Open the script’s Run History to see the error trace. Errors are cached for ~1 minute before re-evaluation, so retry after a short wait |
| “JQL function disabled” / “deleted” | Cache shows the invalidation message | Re-enable or recreate the function; cached entries are refreshed on next save |
To debug, enable audit for the JQL Function trigger type in Admin Panel -> Audit Log -> Trigger Types (off by default to avoid log volume). Each call then appears in Script Runs Audit with the resolved arguments.
Related
- Scripted Fields - per-issue computed values (different use case)
- Triggers overview - all JiBrok Studio trigger types
- Limits and quotas - full limits reference
- Permissions - app permission model
