Skip to main content

​
Configuration

Before you can sync Jira issues to OmniFocus, you need to configure the plugin with your Jira credentials and preferences.

​
Initial configuration

1

Open configuration

In OmniFocus, navigate to Automation → Plug-Ins → Jira Sync and run Configure JIRA Sync (the gear icon).
2

Enter Jira URL

Enter your Atlassian instance URL in the JIRA URL field.
https://yourcompany.atlassian.net
The URL must start with https:// for security. Do not include trailing slashes.
3

Generate API token

Create a Jira API token:
  1. Visit https://id.atlassian.com/manage-profile/security/api-tokens
  2. Click Create API token
  3. Give it a label like “OmniFocus Sync”
  4. Copy the generated token
API tokens are more secure than passwords and can be revoked independently if needed.
4

Enter credentials

Fill in your Jira credentials:
  • JIRA Account ID: Your Jira account email or ID
  • JIRA API Token: Paste the token you generated
Credentials are stored securely in macOS Keychain via OmniFocus’s Credentials API.
5

Configure JQL query

Enter a JQL query to filter which issues to sync. For example:
assignee = currentUser() AND resolution = Unresolved
This syncs all your open, unresolved issues. See JQL queries for more examples.
6

Set OmniFocus tag

Enter a tag name to apply to all synced tasks:
Work:JIRA
Use colons to create nested tags (e.g., Work:JIRA creates a “JIRA” tag under “Work”).
7

Test connection

Click Save. The plugin will test your connection and display:
  • Your authenticated user name
  • The number of issues found matching your JQL query
If successful, your configuration is saved.

​
Configuration fields

The configuration form includes these fields:

​
Required fields

​
jiraUrl
string
required
Your Jira instance URL. Must start with https://.Example: https://yourcompany.atlassian.net
​
accountId
string
required
Your Jira account ID or email address.Example: [email protected]
​
apiToken
password
required
Your Jira API token generated from Atlassian’s security settings.
​
jqlQuery
string
required
JQL query to filter which issues to sync.Example: assignee = currentUser() AND resolution = Unresolved
​
tagName
string
required
Tag name to apply to synced tasks. Use colons for nested tags.Example: Work:JIRA

​
Optional fields

​
enableProjectOrganization
boolean
default:"false"
When enabled, tasks with Jira parent issues (epics) are grouped into OmniFocus projects named [PARENT-KEY] Parent Summary.
​
defaultProjectFolder
string
Default folder path for created projects when project organization is enabled. Use colon-separated paths for nested folders.Example: Work:Jira:EpicsLeave empty to create projects at the root level.
​
completedStatuses
string
Comma-separated list of Jira status names that mark tasks as completed.Default: Done, Closed, ResolvedExample: Done, Closed, Resolved, Finished
​
droppedStatuses
string
Comma-separated list of Jira status names that mark tasks as dropped.Default: WithdrawnExample: Withdrawn, Cancelled

​
Advanced configuration

​
Project organization

Enable Project Organization to automatically group tasks by their Jira parent issue:
  1. Check the Enable Project Organization checkbox
  2. Optionally set a Default Folder for Projects using colon-separated paths
  3. Click Save
When enabled:
  • Tasks with a parent issue are placed in an OmniFocus project named [PARENT-KEY] Parent Summary
  • Projects are created in the specified folder path (or at root level if empty)
  • Tasks without parent issues remain in your inbox
This feature is useful for organizing tasks by epic or parent story in Jira.

​
Custom status mappings

You can customize how Jira statuses map to OmniFocus task states: Completed statuses (default: Done, Closed, Resolved): 
Done, Closed, Resolved, Finished
Dropped statuses (default: Withdrawn): 
Withdrawn, Cancelled
Status names are case-sensitive and must match exactly as they appear in Jira.

​
Data storage

The plugin stores configuration data in two secure locations:

​
Credentials (macOS Keychain)

Stored under com.omnifocus.plugin.jira-sync:
  • Jira account ID
  • Jira API token

​
Settings (OmniFocus Preferences)

Stored in OmniFocus preferences under jiraSync.settings:
  • Jira URL
  • JQL query
  • Tag name
  • Project organization settings
  • Status mappings
  • Last sync timestamp
No data is sent anywhere except to your configured Jira instance. The plugin is read-only and never modifies Jira issues.

​
Updating configuration

You can update your configuration at any time:
  1. Run Configure JIRA Sync again from Automation → Plug-Ins → Jira Sync
  2. Modify any fields you want to change
  3. Click Save
The plugin will test the connection again and save your updated settings.
Changing the JQL query will affect which issues are synced in future syncs. Existing tasks in OmniFocus are not automatically deleted.

​
Troubleshooting

​
Authentication error

If you see an authentication error:
  1. Verify your Jira URL is correct and includes https://
  2. Regenerate your API token at https://id.atlassian.com/manage-profile/security/api-tokens
  3. Run Configure JIRA Sync again with the new token

​
Invalid JQL query

If your JQL query fails:
  1. Test the query in Jira’s issue search (Filters → Advanced issue search)
  2. Verify it returns the expected issues
  3. Update the query in the configuration

​
No issues found

If the connection test reports 0 issues:
  1. Your JQL query might be too restrictive
  2. Test the query directly in Jira to see what it returns
  3. Try a simpler query like assignee = currentUser()

​
Next steps

Learn JQL queries

Discover JQL patterns to filter issues effectively

Start syncing

Run your first sync and understand incremental vs. full refresh

Build docs developers (and LLMs) love

Get started for freeTalk to us