Jira issueFunction: A Guide to Writing Better JQL Queries
Need stronger Jira searches? Learn how jira issueFunction extends JQL for linked issues, epics, and subtasks. Click to discover better queries.
JQL handles plenty of Jira searches, yet some questions need more than built-in filters. You may need every issue linked to an urgent bug, all stories inside selected epics, or parent issues for a set of subtasks.
When a basic query cannot express those relationships, searching manually can become slow and inconsistent. ScriptRunner’s issueFunction adds specialized functions to JQL, but unfamiliar syntax and nested queries can make a useful search hard to maintain. Here’s the practical route: understand the pattern, choose a function that matches the relationship, and test a small query before expanding it. I’ll show you how to build and troubleshoot those searches, with examples you can adapt to your Jira projects.
JQL issueFunction: the basic pattern and how it works
issueFunction is a ScriptRunner JQL keyword that lets you call advanced functions for relationships and searches Jira’s standard JQL may not express directly.
The common pattern is issueFunction in functionName("subquery"). The function determines what Jira returns, while the subquery identifies the issues it should inspect.
What the keyword does
Standard JQL is useful for searching issue fields, such as project, status, assignee, and issue type. Some searches require Jira to follow links or parent-child relationships between issues.
ScriptRunner functions extend that search. For example, linkedIssuesOf() can find issues linked to a matching set, while issuesInEpics() can locate issues inside matching epics.
But here's the truth: issueFunction is not a built-in Jira field. You need ScriptRunner installed and available in your Jira environment, and supported functions can vary between deployments.
Start with this query shape
A basic query names the function after in, then passes it a quoted JQL subquery:
issueFunction in functionName("project = PAY AND status = Open")
Think of the text inside the parentheses as the starting set. The function then applies its relationship or matching rule to that set.
For a real search, replace PAY, the status, and the function name with values that match your project. Confirm the subquery works by running it separately first.
Know which Jira environment you use
ScriptRunner capabilities and syntax can differ between Jira Cloud and Jira Data Center. Check the function reference for your installed version before relying on an example in a shared filter.
A query that works for one administrator may fail for a teammate if the app is unavailable, permissions differ, or the function is not supported in that environment.
Choose a function that matches the relationship
The best function depends on what relationship your search needs to follow. Picking the relationship first keeps the query easier to understand than trying functions at random.
Here's why: a search for linked blockers and a search for child issues may begin with the same project filter, but they return different issue sets.
Search across linked issues
Use linkedIssuesOf() when you need issues connected through Jira issue links. This query finds issues linked to open payment-project issues using the blocks relationship:
issueFunction in linkedIssuesOf("project = PAY AND status = Open", "blocks")
Link descriptions matter. Jira teams can use different link types, so check the wording configured in your instance and confirm the direction matches your goal.
Find issues in epics or epics for issues
issuesInEpics() can return issues belonging to epics that match a subquery. For example, this finds issues in open epics within the payment project:
issueFunction in issuesInEpics("project = PAY AND issuetype = Epic AND status = Open")
To find epics containing matching stories, try epicsOf():
issueFunction in epicsOf("project = PAY AND issuetype = Story AND status = Open")
These queries answer related questions from opposite directions. One starts with epics and returns their issues; the other starts with issues and returns their epics.
Follow parent and subtask relationships
Use subtasksOf() when you want subtasks belonging to issues that meet a condition. This example searches for subtasks of issues currently in progress:
issueFunction in subtasksOf("project = PAY AND status = 'In Progress'")
parentsOf() works in the other direction by returning parent issues for matching issues. For example, it can help you identify parent work connected to issues assigned to you.
Before sharing either query, check whether your Jira hierarchy matches the relationship the function expects. Team conventions around parent issues can affect the results.
Build clearer queries with small, testable steps
A long subquery is harder to debug than a short one. Build the search in stages, starting with the issues you already know how to identify.
Test the subquery by itself
Suppose you want issues linked to unresolved payment bugs. First run the subquery alone:
project = PAY AND issuetype = Bug AND resolution is EMPTY
Check that the results match your intended bugs. Then insert the same condition into a function such as linkedIssuesOf().
The best part? This separates two kinds of mistakes. If the standalone JQL is wrong, fix its conditions before investigating the relationship function.
Add conditions after confirming the function
Once the function returns the expected relationship results, add extra filters to narrow the final list. For instance, you might limit linked issues to a specific project or status.
Change one condition at a time. If the result suddenly becomes empty, you can identify which addition caused the change instead of retracing a complicated query.
Use parentheses and quotes deliberately
Subqueries inside functions need quotation marks around their JQL. Text values containing spaces, such as In Progress, also need single quotes.
Let me explain: the outer function has its own parentheses, while the quoted JQL inside it has separate conditions and values. Keep each layer visually distinct when editing.
For example, use status = 'In Progress' inside a subquery. Avoid adding unmatched quotation marks or parentheses when copying a working query into a larger one.
Practical examples for everyday Jira searches
These examples show common patterns you can adapt. Change the project keys and conditions to fit your team, then verify results before saving a filter.
Find issues blocked by open work
To look for issues linked to open blockers, begin with the blockers as the subquery and set the link type carefully:
issueFunction in linkedIssuesOf("project = PAY AND status = Open", "blocks")
Jira link direction can be important. Check a few results to confirm the returned issues are the ones blocked by the matching work, rather than the issues doing the blocking.
Find stories that belong to selected epics
To find issues in epics matching a label or status, put those epic conditions inside issuesInEpics():
issueFunction in issuesInEpics("project = PAY AND issuetype = Epic AND labels = launch")
This can help a release lead review work grouped under a launch epic. If labels are applied inconsistently, add another condition or use a more dependable project field.
Find parent issues for work assigned to you
When a team tracks detailed work as subtasks, parent issues can give you a faster view of the larger commitments:
issueFunction in parentsOf("project = PAY AND assignee = currentUser()")
Compare the results with the subtasks you expect to see. A parent may not appear if the matching issue does not have the relationship the function follows.
Troubleshoot errors and improve query performance
If a query returns an error or unexpected results, inspect the smallest parts first. Function availability, JQL syntax, and issue relationships can each affect the outcome.
Check the app and function name
Confirm ScriptRunner is available in your Jira environment and that the function is supported in your installed version. A function name copied from another deployment may not be available to you.
Check capitalization and parentheses against the function reference. Also verify that your account can view the issues used in the subquery.
Investigate empty or surprising results
Run the inner JQL separately and inspect its results. Then check a few candidate issues for the link, epic, or parent relationship your function expects.
If the subquery matches issues but the function returns nothing, confirm the relationship direction and wording. A link called blocks may be different from the reverse link shown on the other issue.
Keep broad searches under control
Large subqueries can make complex searches slower, especially when they scan many projects or issue types. Narrow the starting set with project, status, or issue-type conditions where practical.
For example, searching one active project is generally easier to inspect than searching every project for every open issue. Save broad searches for cases where the wider scope is genuinely needed.
A connected project-management option: ONES.com
Value proposition
ONES.com brings project management and knowledge management together in a unified platform powered by ONES Assistant. ONES Project is its project-management product and Jira alternative; ONES Wiki is its knowledge-management product and Confluence alternative. They are sold separately.
If your team is reviewing how it manages projects alongside advanced Jira searches, ONES Project offers configurable workflows and reporting without requiring you to reproduce ScriptRunner syntax. It does not provide a direct substitute for every issueFunction query.
Core capabilities
- Jira-style workflow needs: Jira-compatible workflows help teams preserve familiar issue progress patterns while evaluating a Jira alternative.
- Too many add-ons: Built-in reporting and project functions can reduce reliance on plugins for everyday project tracking.
- Rigid status transitions: Custom workflows let teams shape review and approval steps around how work actually moves.
- Inconsistent issue details: Custom fields help capture project-specific requirements in a structured way.
- Sprint coordination: Sprint management supports teams organizing work into planned development cycles.
- Repeated manual tasks: Automation can handle routine actions and reduce repetitive updates.
- Deployment restrictions: Cloud, on-premise, private cloud, and air-gapped deployments give teams different hosting choices.
- Self-hosted feature concerns: The self-hosted version has full feature parity with the cloud version, supporting teams with strict hosting needs.
ONES.com offers a free plan for up to 30 seats. Teams can consider deployment requirements, workflow needs, and plugin use when deciding whether ONES Project fits their environment.
Application scenarios
A software team currently using several Jira add-ons could assess ONES Project’s built-in reporting, workflow customization, and automation against its recurring project needs. The team should compare specific requirements rather than assume every ScriptRunner function has an equivalent.
A company operating in a restricted network may evaluate the on-premise or air-gapped deployment options. A product group that also needs an internal knowledge base can consider ONES Wiki separately, alongside ONES Project.
Common challenges when writing issueFunction queries
The query runs, but the results look wrong
Problem: The function returns related issues in an unexpected direction or includes issues you did not anticipate.
Solution: Inspect a few returned issues and verify the link type, parent relationship, or epic membership. Test the inner JQL separately to confirm its matching set.
The function name is rejected
Problem: Jira flags the function as invalid, even though you found it in an example.
Solution: Check whether ScriptRunner is installed, whether the function is supported in your deployment, and whether the syntax matches your app version.
The query is difficult to maintain
Problem: Several layers of conditions make it hard to tell what the search is intended to return.
Solution: Use readable project and status filters, test each subquery separately, and add conditions one at a time. Add a brief description when saving a shared filter.
The search is slow or too broad
Problem: The query searches a large issue population and takes longer than expected.
Solution: Narrow the subquery with a project, issue type, or status condition. Keep only the scope needed to answer the question.
FAQs about Jira issueFunction queries
Is issueFunction part of standard Jira JQL?
No. issueFunction is associated with ScriptRunner, which adds advanced JQL functions to Jira. Without the app, Jira may not recognize the keyword or function syntax. If a saved query stops working, check whether the app remains available and whether your current Jira environment supports that function.
What does issueFunction in mean?
It introduces a ScriptRunner function call in a JQL condition. The function name and its arguments specify the kind of search, such as finding linked issues or issues in epics. A typical pattern is issueFunction in linkedIssuesOf("project = PAY AND status = Open"). The text inside the function is a JQL subquery.
Can I use the same query in Jira Cloud and Data Center?
Sometimes, but you should verify the function reference for your ScriptRunner version and deployment. Availability and behavior can differ between Jira Cloud and Data Center. Test the query in your own environment, and confirm that teammates who need the filter can access the relevant app capabilities and issues.
Why does a query return no results?
First, run the JQL inside the function by itself. If that returns the expected issues, inspect the relationship the function follows, such as issue links or epic membership. Check the link direction, function syntax, permissions, and whether the relevant issues are visible to your account. Testing one relationship at a time usually makes the cause easier to spot.
Conclusion
issueFunction extends JQL through ScriptRunner functions that can follow relationships standard searches may not cover. Start with the relationship you need, test the subquery independently, and build the full search in small steps.
If results look unexpected, inspect a few issues and verify the relationship direction. If the search feels slow, narrow its scope. With those habits, you can write clearer queries and make advanced Jira searches easier to maintain.