Jira — sync behaviour & troubleshooting

What docket does on its own once a project is linked — and what to check when a ticket or a time entry doesn't look right.

---

How often does docket sync with Jira?

docket keeps itself up to date by checking Jira on a schedule (it doesn't rely on Jira notifying it):

What	How often
New & changed Jira tickets (title, status, assignee, due date, priority)	about every 5 minutes
Time logged directly in Jira (imported into docket)	about every 5 minutes
Tickets deleted or moved out of the Jira project	once a day (they're then closed in docket, tracked time kept)
First import when you link a project	right away in the background (can take a little while for large projects)

Pushing your docket time to Jira is not on this schedule — it's immediate. The moment you save, edit, or delete a time entry on a Jira ticket, docket syncs that single change to the Jira worklog straight away (and retries automatically if Jira is briefly unavailable).

So: browsing data (tickets, assignments, Jira-side time) refreshes within a few minutes; your own time bookings appear in Jira almost instantly.

---

Can I accidentally push the same time twice?

No. Every docket time entry is coupled to exactly one Jira worklog by a stored id:

• The first time an entry is pushed, docket creates a worklog in Jira and remembers its id.
• Every push after that (you edit the entry, you hit "Sync existing docket time to Jira now", you press it twice, an automatic retry fires) updates that same worklog — it never creates a second one. Pressing the sync button repeatedly is safe.

If you edit a time entry in docket: the change is pushed to the same Jira worklog (updated, not duplicated). If you delete it in docket, the worklog is deleted in Jira too.

If you edit a docket-pushed worklog directly in Jira: docket won't pull that change back — for time booked in docket, docket is the source of truth, and your next edit in docket would overwrite the Jira side again. (Time that was logged only in Jira is different: docket imports it read-only, and edits to it in Jira do update what docket shows.)

---

How do epics, stories and sub-tasks appear?

All on one flat level, each as a single docket ticket. Every Jira issue in the linked project — epic, story, task, bug, or sub-task — is mirrored as one ordinary docket ticket. docket does not reproduce Jira's hierarchy: there's no parent/child nesting, no epic grouping, and the Jira issue type isn't shown in docket. Use the Jira key (e.g. ABC-123) to tell them apart, and open the ticket in Jira if you need its type, parent, or epic. (Planning and structure live in Jira — docket just needs each issue as something you can book time against and report on.)

---

What about open and closed (done) issues?

Jira decides the status; docket follows. A mirrored ticket is:

• closed in docket when its Jira issue is in a Done status category, and
• open for anything else (To Do, In Progress, and every other non-done status).

Because Jira is the source of truth for linked projects, this is one-directional: close or reopen an issue in Jira and the docket ticket flips to match on the next sync (within a few minutes). You don't set status in docket — mirrored tickets are read-only there.

A few practical points:

• Both open and closed issues are imported. The first sync pulls the whole Jira project, so already-done issues come in as closed tickets too — useful, because time that was logged on them stays visible in docket's reports.
• Closed issues stay out of the Workload view. The Workload heatmap and the "assigned tickets" counts only include open tickets, so done work doesn't clutter them.
• You can still book time on a closed ticket — e.g. logging time after an issue was closed. It remains selectable in the time-tracking view, and closing an issue never removes its tracked time from docket's budget, Controlling or reports.
• An issue that is deleted or moved out of the Jira project (not just closed) is picked up by the daily check and closed in docket, again with its time kept.

---

Troubleshooting

Symptom	What it means / what to do
Connection shows auth failed	The service account's email/token is wrong or lost access. Admin: Edit the connection, re-enter the token, and Test again.
A time entry says Not in Jira	You haven't connected your personal token. See Part 2 of the setup, then click Retry on the entry.
A time entry says Jira sync failed	Usually a temporary Jira hiccup or a permissions change. Click Retry. If it keeps failing, check that your token still has access to that project.
My token shows ✗ for a site	Your Atlassian account can't reach that site, or you use a different account there. Add a token scoped to that connection, or ask the admin to grant access.
A Jira ticket isn't showing in docket	New issues sync within a few minutes. If it never appears, confirm the issue is in the linked Jira project and the connection badge is green.
Boards / Roadmap tabs disappeared	Expected — the project is linked to Jira, so planning happens in Jira. Unlink the project (Project → Settings → Jira → Unlink) to get them back.
I unlinked a project — did I lose data?	No. Mirrored tickets with booked time and all tracked time are kept; only empty mirrored tickets (no time booked, nothing imported) are removed. Syncing stops.
I linked the wrong Jira project	Unlink and link the right one — empty imported tickets are cleaned up automatically. If time was already booked, see linked the wrong Jira project.
A time entry was booked on the wrong project/ticket	Go to Timetracking → Reports, select the entries and use Move. On Jira-mirrored tickets the pushed worklog moves along (removed from the old issue, created on the new one).

---

Also worth knowing

Will editing a ticket in docket change Jira? Mirrored Jira tickets are read-only in docket. The only thing you add from docket is tracked time. Everything else is edited in Jira.

Still stuck? Start again from the overview, or check the connection setup.