Custom Status Mappings - OmniFocus Jira Sync

Status mappings control how Jira issue statuses are translated into OmniFocus task states. The plugin provides sensible defaults but allows full customization to match your workflow.

Default Status Mappings

Out of the box, the plugin uses these mappings:

Completed
Dropped
Active

Jira Statuses: Done, Closed, ResolvedOmniFocus State: Completed (checkmark)Tasks with these statuses are marked as complete in OmniFocus.

Jira Status: WithdrawnOmniFocus State: Dropped (gray)Tasks with this status are marked as dropped (canceled) in OmniFocus.

Default Constants

From the source code at jiraCommon.js:8-9:

jiraCommon.COMPLETED_STATUSES = ['Done', 'Closed', 'Resolved'];
jiraCommon.DROPPED_STATUSES = ['Withdrawn'];

These defaults work well for most Jira instances, which typically use “Done”, “Closed”, or “Resolved” for completed work.

How Status Mapping Works

During Sync

For each Jira issue, the plugin:

Reads the current status name (e.g., “Done”, “In Progress”)
Checks if the status is in the completed statuses list
Checks if the status is in the dropped statuses list
Applies the appropriate OmniFocus task state
Reopens tasks if their status changes from completed to active

Status Transition Logic

From jiraCommon.js:762-778:

const statusName = fields.status.name;
const statusMappings = jiraCommon.getStatusMappings(settings);
const shouldBeCompleted = statusMappings.completed.includes(statusName);
const shouldBeDropped = statusMappings.dropped.includes(statusName);

if (shouldBeCompleted && task.taskStatus !== Task.Status.Completed) {
  task.markComplete();
  updated = true;
} else if (shouldBeDropped && task.taskStatus !== Task.Status.Dropped) {
  task.drop(true);
  updated = true;
} else if (!shouldBeCompleted && !shouldBeDropped) {
  if (task.taskStatus === Task.Status.Completed || task.taskStatus === Task.Status.Dropped) {
    task.markIncomplete();
    updated = true;
  }
}

Reopening Tasks

If a Jira issue changes from a completed/dropped status back to an active status:

Jira: Done → In Progress
OmniFocus: Completed → Active (incomplete)

The task is automatically reopened and marked as incomplete.

Reopened tasks appear in the Reopened count in sync statistics.

Customizing Status Mappings

You can override the default mappings in Configure JIRA Sync.

Completed Statuses

Field: Completed Statuses (comma-separated) Example: Done, Closed, Resolved, Finished, Complete Add any Jira status names that should mark tasks as completed in OmniFocus.

Dropped Statuses

Field: Dropped Statuses (comma-separated) Example: Withdrawn, Canceled, Cancelled, Won't Do, Rejected Add any Jira status names that should mark tasks as dropped in OmniFocus.

Status names are case-sensitive. “Done” and “done” are different values.

Common Workflow Examples

Standard Scrum Workflow

Jira Statuses:

To Do
In Progress
In Review
Done

Configuration:

Completed Statuses: Done
Dropped Statuses: (leave empty)

Result:

“Done” issues → Completed in OmniFocus
All other statuses → Active in OmniFocus

Extended Completion States

Jira Statuses:

To Do
In Progress
Done
Closed
Resolved
Deployed

Configuration:

Completed Statuses: Done, Closed, Resolved, Deployed
Dropped Statuses: (leave empty)

Result:

Issues in “Done”, “Closed”, “Resolved”, or “Deployed” → Completed
Issues in “To Do” or “In Progress” → Active

Kanban with Won’t Do

Jira Statuses:

Backlog
Selected
In Progress
Done
Won’t Do

Configuration:

Completed Statuses: Done
Dropped Statuses: Won't Do

Result:

“Done” → Completed
“Won’t Do” → Dropped (grayed out)
All others → Active

Support Ticket Workflow

Jira Statuses:

New
Assigned
In Progress
Waiting for Customer
Resolved
Closed
Canceled

Configuration:

Completed Statuses: Resolved, Closed
Dropped Statuses: Canceled

Result:

“Resolved” or “Closed” → Completed
“Canceled” → Dropped
“New”, “Assigned”, “In Progress”, “Waiting for Customer” → Active

Status Mapping Validation

The plugin validates your status mappings:

Settings Override

From jiraCommon.js:226-235:

jiraCommon.getStatusMappings = (settings) => {
  const completed = (settings && Array.isArray(settings.completedStatuses) && settings.completedStatuses.length > 0)
    ? settings.completedStatuses
    : jiraCommon.COMPLETED_STATUSES;
  const dropped = (settings && Array.isArray(settings.droppedStatuses) && settings.droppedStatuses.length > 0)
    ? settings.droppedStatuses
    : jiraCommon.DROPPED_STATUSES;
  return { completed, dropped };
};

If you leave the status mapping fields empty, the plugin falls back to the default constants.

Parsing Logic

The configuration form parses comma-separated values:

const completedStatuses = completedStatusesInput
  .split(',')
  .map(s => s.trim())
  .filter(s => s.length > 0);

const droppedStatuses = droppedStatusesInput
  .split(',')
  .map(s => s.trim())
  .filter(s => s.length > 0);

Examples:

Done, Closed,  Resolved  , Finished

Case Sensitivity

Jira status names are case-sensitive:

Correct
Incorrect

Configuration: Done, Closed, ResolvedJira Status: DoneResult: ✓ Task marked as completed

Configuration: done, closed, resolvedJira Status: DoneResult: ✗ Task remains active (case mismatch)

Finding Exact Status Names

To find the exact status names used in your Jira instance:

Open a Jira Issue

Navigate to any issue in your Jira instance

Check the Status Field

Look at the current status (e.g., “In Progress”)

Click Status to View Workflow

Click the status to see all available statuses in the workflow

Copy Exact Names

Copy the exact status names including capitalization

Add to Configuration

Paste into the status mapping fields in Configure JIRA Sync

Skip Creation Logic

The plugin has special logic to avoid creating tasks for already-completed issues: From syncJira.js:40-41 and syncJiraFull.js:40-41:

const shouldSkipCreation = statusMappings.completed.includes(statusName) || statusMappings.dropped.includes(statusName);

If a Jira issue is already in a completed or dropped status during sync:

Existing task: Updated and marked completed/dropped
No existing task: Task creation is skipped

This prevents cluttering your OmniFocus with hundreds of already-completed tasks when you first configure the plugin.

Sync Statistics

Skipped issues appear in the Skipped count:

Sync completed successfully!

Created: 5
Updated: 12
Reopened: 2
Completed: 3
Skipped: 7

The 7 skipped issues were in a completed or dropped state and didn’t have existing tasks.

Advanced Status Mapping Scenarios

Multiple “In Progress” Statuses

Scenario: Your workflow has multiple active states. Jira Statuses:

To Do
In Development
In Review
In QA
Done

Configuration:

Completed Statuses: Done
Dropped Statuses: (empty)

Result:

All “In …” statuses keep tasks active
Only “Done” marks tasks as completed

You don’t need to explicitly list active statuses. Anything not in the completed or dropped lists is automatically active.

Regional Variations

Scenario: Your Jira instance uses non-English status names. Jira Statuses:

À faire
En cours
Terminé
Annulé

Configuration:

Completed Statuses: Terminé
Dropped Statuses: Annulé

Result:

“Terminé” → Completed
“Annulé” → Dropped
“À faire”, “En cours” → Active

Custom Workflow States

Scenario: You have custom statuses like “Blocked” or “Waiting”. Jira Statuses:

To Do
In Progress
Blocked
Waiting
Done
Won’t Fix

Configuration:

Completed Statuses: Done
Dropped Statuses: Won't Fix

Result:

“Blocked” and “Waiting” remain active (not completed or dropped)
OmniFocus doesn’t distinguish between “In Progress” and “Blocked” - both are active
Consider using tags or task names to indicate blocking in OmniFocus

Status Changes Over Time

Timeline Example

Issue Created

Jira Status: To DoOmniFocus: Task created, active

Work Begins

Jira Status: In ProgressOmniFocus: Task updated, remains active

Work Completed

Jira Status: DoneOmniFocus: Task marked as completedSync Stat: Completed +1

Issue Reopened

Jira Status: To DoOmniFocus: Task marked as incomplete (reopened)Sync Stat: Reopened +1

Canceled

Jira Status: Won’t FixOmniFocus: Task marked as droppedSync Stat: Updated +1

Best Practices

Match Your Workflow
Use Exact Names
Test After Changes
Keep It Simple

Configure status mappings to match how your team uses Jira:

Identify which statuses mean “work is done”
Identify which statuses mean “work is canceled”
List all variations (Done, Closed, Resolved, etc.)

Always use the exact status names from Jira:✓ Good: Done, Closed, Resolved✗ Bad: done, CLOSED, resolved

Troubleshooting

Tasks Not Completing

Issue: Jira issues are “Done” but OmniFocus tasks remain active. Solutions:

Verify “Done” is in the Completed Statuses list
Check case sensitivity (“Done” vs “done”)
Run a Full Sync to reprocess all tasks
Check Console.app for status mapping logs

Tasks Completing Unexpectedly

Issue: Tasks marked as completed when they shouldn’t be. Solutions:

Review your Completed Statuses list
Remove any status names that should be active
Common issue: Including “In Progress” or “Pending” by mistake
Run a Full Sync to fix task states

Dropped Status Not Working

Issue: “Won’t Do” issues aren’t being dropped in OmniFocus. Solutions:

Add “Won’t Do” to Dropped Statuses field
Verify exact status name (case-sensitive)
Save configuration and run a Full Sync
Check that status exists in your Jira workflow

Status Mapping Changes Not Applied

Issue: Changed status mappings but tasks still use old behavior. Solution:

After changing mappings, always run a Full Sync
Incremental sync only updates recently modified issues
Full sync reprocesses all tasks with new mappings

Implementation Reference

Status Check During Sync

Both incremental and full sync use the same status checking logic:

// From syncJira.js:40 and syncJiraFull.js:40
const statusMappings = lib.getStatusMappings(settings);
const shouldSkipCreation = statusMappings.completed.includes(statusName) || statusMappings.dropped.includes(statusName);

Task Creation Skip

// From syncJira.js:63-68 and syncJiraFull.js:63-68
if (!shouldSkipCreation) {
  lib.createTaskFromJiraIssue(issue, jiraUrl, tagName, settings, projectIndex, taskIndex);
  stats.created++;
} else {
  stats.skipped++;
}

Task Update with Status Change

// From jiraCommon.js:767-778
if (shouldBeCompleted && task.taskStatus !== Task.Status.Completed) {
  task.markComplete();
  updated = true;
} else if (shouldBeDropped && task.taskStatus !== Task.Status.Dropped) {
  task.drop(true);
  updated = true;
} else if (!shouldBeCompleted && !shouldBeDropped) {
  if (task.taskStatus === Task.Status.Completed || task.taskStatus === Task.Status.Dropped) {
    task.markIncomplete();
    updated = true;
  }
}

Status Mapping in Task Notes

The current Jira status is always included in task notes:

---
URL: https://yourcompany.atlassian.net/browse/PROJ-123
Status: In Progress
---

[Issue description here]

This allows you to see the raw Jira status even if the OmniFocus task state is different.

The status in notes is informational only. The actual OmniFocus task state is determined by your status mappings.

Getting Started

Usage

Reference

Resources

​Default Status Mappings

​Default Constants

​How Status Mapping Works

​During Sync

​Status Transition Logic

​Reopening Tasks

​Customizing Status Mappings

​Completed Statuses

​Dropped Statuses

​Common Workflow Examples

​Standard Scrum Workflow

​Extended Completion States

​Kanban with Won’t Do

​Support Ticket Workflow

​Status Mapping Validation

​Settings Override

​Parsing Logic

​Case Sensitivity

​Finding Exact Status Names

​Skip Creation Logic

​Sync Statistics

​Advanced Status Mapping Scenarios

​Multiple “In Progress” Statuses

​Regional Variations

​Custom Workflow States

​Status Changes Over Time

​Timeline Example

​Best Practices

​Troubleshooting

​Tasks Not Completing

​Tasks Completing Unexpectedly

​Dropped Status Not Working

​Status Mapping Changes Not Applied

​Implementation Reference

​Status Check During Sync

​Task Creation Skip

​Task Update with Status Change

​Status Mapping in Task Notes

Build docs developers (and LLMs) love

Default Status Mappings

Default Constants

How Status Mapping Works

During Sync

Status Transition Logic

Reopening Tasks

Customizing Status Mappings

Completed Statuses

Dropped Statuses

Common Workflow Examples

Standard Scrum Workflow

Extended Completion States

Kanban with Won’t Do

Support Ticket Workflow

Status Mapping Validation

Settings Override

Parsing Logic

Case Sensitivity

Finding Exact Status Names

Skip Creation Logic

Sync Statistics

Advanced Status Mapping Scenarios

Multiple “In Progress” Statuses

Regional Variations

Custom Workflow States

Status Changes Over Time

Timeline Example

Best Practices

Troubleshooting

Tasks Not Completing

Tasks Completing Unexpectedly

Dropped Status Not Working

Status Mapping Changes Not Applied

Implementation Reference

Status Check During Sync

Task Creation Skip

Task Update with Status Change

Status Mapping in Task Notes