Skip to main content
JQL (Jira Query Language) is a powerful query language that lets you filter which Jira issues get synced to OmniFocus. The plugin uses your JQL query as the foundation for all syncs.

​
How JQL Queries Work

Your JQL query determines which issues are synced:
  1. Configure your base JQL query in Configure JIRA Sync
  2. The plugin executes this query against Jira’s REST API
  3. For incremental syncs, a time filter is automatically appended
  4. Results are fetched with pagination (100 issues per page)
  5. Each matching issue creates or updates an OmniFocus task
The plugin automatically handles pagination. Your query can return thousands of issues - all will be synced.

​
Common Query Patterns

​
My Unresolved Issues

Fetch all your open issues that haven’t been resolved yet: 
assignee = currentUser() AND resolution = Unresolved
This is the most common pattern and works well for most users.
The resolution field indicates whether an issue has been resolved, regardless of its status. Using resolution = Unresolved ensures you see all active work, even if the issue status is “In Progress”, “To Do”, “Waiting”, etc.

​
Current Sprint

Sync issues assigned to you in active sprints: 
sprint in openSprints() AND assignee = currentUser()
Use this if you work in Scrum and only want to focus on current sprint work.

​
High Priority Issues

Focus on your most important tasks: 
assignee = currentUser() AND priority in (High, Highest)
Priority values are case-sensitive and may vary by Jira instance. Common values: Highest, High, Medium, Low, Lowest.

​
Specific Project

Sync issues from a particular project: 
project = PROJ AND assignee = currentUser()
Replace PROJ with your project key (e.g., MYTEAM, ENG, SUPPORT).

​
Multiple Projects

Sync issues from several projects: 
project in (PROJ1, PROJ2, PROJ3) AND assignee = currentUser()

​
By Label

Filter issues with specific labels: 
labels = important AND assignee = currentUser()
Or multiple labels: 
labels in (urgent, important) AND assignee = currentUser()

​
By Issue Type

Sync only specific issue types: 
assignee = currentUser() AND type in (Bug, Task)
Common issue types: Task, Bug, Story, Epic, Sub-task.

​
Advanced Query Patterns

​
Combining Multiple Criteria

Create complex filters by combining conditions with AND: 
project = PROJ AND assignee = currentUser() AND resolution = Unresolved AND priority in (High, Highest)
This syncs only high-priority, unresolved issues from project PROJ that are assigned to you.

​
OR Conditions

Use OR to broaden your criteria: 
assignee = currentUser() OR reporter = currentUser()
This syncs issues you’re assigned to OR issues you reported.
When mixing AND and OR, use parentheses to control precedence:
(assignee = currentUser() OR reporter = currentUser()) AND resolution = Unresolved

​
Excluding Issues

Use != or NOT IN to exclude specific values: 
assignee = currentUser() AND status != Done AND priority != Low

​
Date Ranges

Filter by creation or update date: 
assignee = currentUser() AND created >= -7d
This syncs issues assigned to you created in the last 7 days. Common date expressions:
  • -7d: Last 7 days
  • -1w: Last week
  • -2w: Last 2 weeks
  • -1M: Last month

​
Epic and Parent Issues

Sync issues belonging to specific epics: 
parent = PROJ-123 AND assignee = currentUser()
Or sync issues from multiple epics: 
parent in (PROJ-123, PROJ-456) AND assignee = currentUser()

​
Custom Fields

Query custom fields using their ID: 
assignee = currentUser() AND cf[10001] = "High Value"
  1. Go to Jira Settings → Issues → Custom fields
  2. Click on the custom field name
  3. Look at the URL - the ID is in the format customFieldId=10001
  4. Use cf[10001] in your JQL query

​
Query Testing

Before saving your JQL query in the plugin configuration, test it in Jira:
1

Open Jira's Issue Search

Navigate to Filters → Advanced issue search in Jira
2

Enter Your JQL Query

Type or paste your JQL query into the search box
3

Run the Query

Click Search to see matching issues
4

Verify Results

Confirm the results match your expectations
5

Save to Plugin

Copy the working query to Configure JIRA Sync in OmniFocus
The plugin’s Test Connection feature validates your query syntax before saving.

​
Incremental Sync Query Modification

During incremental sync, the plugin automatically modifies your query: 
assignee = currentUser() AND resolution = Unresolved
From the source code at jiraCommon.js:273-285: 
let finalJql = jql;
if (!fullRefresh && lastSyncTime) {
  const date = new Date(lastSyncTime);
  const formattedTime = `${year}-${month}-${day} ${hours}:${minutes}`;
  finalJql = `(${jql}) AND updated >= "${formattedTime}"`;
}
You don’t need to add the time filter yourself - the plugin handles this automatically for incremental syncs.

​
Query Validation

The plugin validates your query during configuration using Jira’s REST API: 
// From jiraCommon.js:804-820
const searchUrl = `${baseUrl}/rest/api/3/search/jql`;
const params = {
  jql: jqlQuery,
  maxResults: 1,
  fields: ['key']
};
The validation:
  • Tests authentication with /rest/api/3/myself
  • Executes your JQL query with maxResults: 1
  • Returns the total issue count matching your query
  • Shows clear error messages if the query is invalid

​
Common Query Errors

​
Syntax Errors

Error: assignee currentUser()Fix: assignee = currentUser()Always use = or other comparison operators.

​
Permission Errors

If your query returns a 403 Forbidden error:
  • You may not have permission to view certain projects
  • Your Jira account may lack “Browse Projects” permission
  • Contact your Jira administrator for access

​
Query Performance Tips

​
Be Specific

Narrow queries perform better: 
resolution = Unresolved

​
Use Indexed Fields

These fields are typically indexed and perform well:
  • assignee
  • project
  • status
  • priority
  • resolution
  • created
  • updated

​
Avoid Text Searches

Text searches are slow: 
text ~ "keyword" AND assignee = currentUser()
Use specific fields instead: 
summary ~ "keyword" AND assignee = currentUser()

​
Real-World Query Examples

assignee = currentUser() 
AND resolution = Unresolved 
AND type in (Bug, Story, Task) 
AND sprint in openSprints()
Syncs active sprint work (bugs, stories, tasks) that’s unresolved.

​
Resources

For more information on JQL syntax:
JQL syntax may vary slightly between Jira Cloud and Jira Server/Data Center. This plugin is designed for Jira Cloud (REST API v3).

Build docs developers (and LLMs) love

Get started for freeTalk to us