Custom JQL Functions

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 issue field and the in / not in operators.

The name jbExec itself is reserved and cannot be used as a registered function name.

Setup

  1. 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.
  2. Open the JQL Functions tab of the Admin Panel.
  3. 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.
  4. 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).

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:

  1. 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).
  2. 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.
  3. You edit the script source in the Console. Every JQL function bound to that script gets a refresh in the background.
  4. 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.


JiBrok Studio for Jira Cloud JiBrok Studio for Jira Cloud
Release notes
Core Features
Triggers
Extensions
Data Storage
Scripting Overview
JavaScript Engine
Python Engine
Groovy Engine
Scripting API
Administration
Guides