docket.rocks
EN Workspace erstellen

Jira — Verbindung einrichten

Verbinde als Admin deine Jira-Site, danach verbindet jedes Teammitglied den eigenen Jira-Account mit einem Klick.

Zwei Dinge müssen einmalig passieren, bevor jemand Zeit auf Jira-Tickets tracken kann: Ein Admin verbindet deine Jira-Site, und jedes Teammitglied verbindet den eigenen Jira-Account — ein Klick und eine Bestätigung auf der Atlassian-Seite. Neu hier? Starte mit dem Überblick.

Service-Account-Token erstellen

(Nur für Admins. Einmalig für den Bot-/Service-Account.)

docket nutzt den Service-Account-Token, um deine Jira-Projekte, Issues und Worklogs zu lesen. Er schreibt nie etwas nach Jira — er liest nur.

  1. Melde dich in Jira mit dem Service-Account an (dein dedizierter Bot-Account).
  2. Gehe zu id.atlassian.com → Security → API tokens.
  3. Klicke auf Create API token.
  4. Vergib eine aussagekräftige Bezeichnung, z. B. docket – service account.
  5. Wähle genau diese zwei Scopes — mehr brauchst du nicht:
Scope Wofür
read:jira-user Token prüfen und Nutzerinfos lesen (z. B. Anzeigenamen für die Workload-Ansicht)
read:jira-work Projekte, Issues und Worklogs aus Jira lesen
  1. Klicke auf Create und kopiere den Token sofort — du kannst ihn danach nicht mehr ansehen.
  2. Füge den Token beim Einrichten der Verbindung in docket ein (Teil 1 unten).

Welchen Account nehmen? Ein dedizierter Service-Account („Bot“) ist dem Account einer echten Person klar vorzuziehen. Verlässt die Person das Unternehmen und wird ihr Account deaktiviert, bricht die Verbindung ab. Ein Service-Account bleibt unabhängig von Team-Änderungen aktiv.

Was der Service-Account in Jira braucht

Er liest nur, braucht also keine Schreib- oder Admin-Rechte – nur genug, um zu sehen, was docket spiegelt:

  • Zugang zu Jira – einen Jira-Platz in eurer Atlassian-Organisation.
  • Lesezugriff auf jedes Projekt, das du verknüpfst („Browse projects“). In einem team-managed Projekt fügst du den Account unter Project settings → Access mit der Rolle Viewer hinzu. In einem company-managed Projekt braucht er eine Projektrolle, die im Berechtigungsschema des Projekts „Browse projects“ hat – oft haben das ohnehin alle angemeldeten Nutzer.
  • „Browse users and groups“ (globale Berechtigung) – nur für die Suche nach Jira-Personen, wenn du sie docket-Nutzern zuordnest (siehe Fragen zu Accounts und Tokens weiter unten).

Ohne Lesezugriff auf ein Projekt meldet Jira keinen Fehler, sondern liefert einfach keine Issues. docket prüft das und zeigt es rot unter Project → Settings → Jira an.

Zeit schreibt jede Person über ihre eigene Verbindung nach Jira (Teil 2), sie braucht also selbst das Recht, auf dem Issue Zeit zu buchen – der Service-Account nicht.

Teil 1 — Admin: Jira-Site verbinden

(Nur für Admins. Einmalig pro Jira-Site.)

  1. Gehe zu Admin → Integrations.
  2. Klicke auf Add connection und fülle aus:
    • Name — eine Bezeichnung, die du wiedererkennst, z. B. „Company Jira“.
    • Site URL — https://yourcompany.atlassian.net (docket ermittelt die Jira-cloud_id automatisch daraus — mehr musst du nicht eingeben).
    • Service account email und API token — die Zugangsdaten des Bot-Accounts.
    • Time tracking backend — lass es auf Jira core worklogs, es sei denn, dein Team erfasst Zeit mit Tempo Timesheets (dann wähle Tempo und gib den Tempo-API-Token ein).
  3. Klicke auf Add connection — docket prüft die Zugangsdaten sofort gegen Jira und zeigt ein grünes active-Badge (erreichbar) oder ein rotes auth failed-Badge (E-Mail/Token falsch oder ohne Zugriff — korrigiere das über den ✎-Button (Edit)). Mit dem ↻-Button (Test) kannst du jederzeit neu prüfen, z. B. nachdem du den Token rotiert hast.

Teil 2 — Jedes Teammitglied: Jira-Account verbinden

(Jede Person, die Zeit auf Jira-Tickets buchen wird. Einmalig.)

docket schreibt deine Zeit als du nach Jira, die Stunden erscheinen in Jira also unter deinem Namen, nicht unter dem des Bots. Dafür verbindest du deinen eigenen Atlassian-Account:

  1. Öffne deine Profileinstellungen (dein Name → Settings) und such den Bereich Jira.
  2. Klicke auf Connect with Jira. Atlassian öffnet sich und fragt, ob docket für dich auf Jira zugreifen darf.
  3. Wähle deine Jira-Site und klicke auf Accept. Du landest wieder in docket.
  4. docket zeigt Connected as mit deinem Jira-Namen und eine ✓-/✗-Liste der Jira-Sites deines Workspace:
    • ✓ — deine Zeit auf den Projekten dieser Site wird nach Jira synchronisiert.
    • ✗ Not shared with docket yet — du hast diese Site auf der Atlassian-Seite nicht ausgewählt. Klicke auf Add another Jira site und wähle sie aus.
    • ✗ mit einer anderen Meldung — dein Atlassian-Account kommt an diese Site nicht heran (meist fehlt dir dort der Zugriff). Frag deinen Admin.

Wenn du diesen Schritt überspringst, kannst du in docket trotzdem Zeit auf Jira-Tickets buchen — sie wird nur nicht nach Jira übertragen. Diese Einträge werden mit „Not in Jira — connect your Jira account.“ markiert. Sobald du verbunden bist, klicke bei ihnen auf Retry, dann werden sie synchronisiert.

Wenn die Verbindung nicht mehr funktioniert (du hast sie in Atlassian widerrufen, oder sie wurde etwa drei Monate nicht genutzt), steht das im Jira-Bereich, und es erscheint ein Reconnect Jira-Button — ein Klick, und du bist wieder dabei. Außerdem verlangt Atlassian einmal im Jahr von allen, die Verbindung erneut zu bestätigen.

Trennen: Das Papierkorb-Icon neben „Connected as“ entfernt die Verbindung aus docket. Um docket den Zugriff komplett zu entziehen, entferne docket zusätzlich in deinem Atlassian-Profil unter Connected apps.

Alternative: ein persönlicher API-Token

Wenn Connect with Jira nicht angezeigt wird oder der Atlassian-Admin deines Unternehmens das Verbinden von Apps blockiert hat (Atlassian zeigt dann auf seiner Seite einen Hinweis), nutze stattdessen einen persönlichen API-Token:

  1. Gehe mit deinem eigenen Atlassian-Account zu id.atlassian.com → Security → API tokens.
  2. Klicke auf Create API token, vergib eine Bezeichnung, z. B. docket, und wähle genau diese zwei Scopes:
Scope Wofür
read:jira-user Token prüfen (docket checkt, ob er jede verbundene Site erreicht)
write:jira-work Deine Worklogs in Jira anlegen, ändern und löschen
  1. Klicke auf Create und kopiere den Token sofort — du kannst ihn danach nicht mehr ansehen.
  2. Klicke im Jira-Bereich von docket auf Use an API token instead, gib deine Atlassian email und den Token ein, lass den Scope auf Default (all connections) und klicke auf Save token.

Ein Token funktioniert für jede Jira-Site, auf die dein Atlassian-Account zugreifen kann.

Fragen zu Accounts und Tokens

Wo finde ich meine Jira-Account-ID? In den meisten Fällen brauchst du sie nicht — docket liest sie automatisch aus, wenn du deinen Jira-Account verbindest. Wenn ein Admin manuell einen docket-User einem Jira-User zuordnet (Admin → Integrations → Verbindung → User mapping), tippe einfach einen Namen oder eine E-Mail im Jira-User-Feld ein — docket durchsucht Jira live und trägt die accountId ein, sobald du einen Treffer auswählst. Dafür muss der Service-Account der Verbindung in Jira die globale Berechtigung „Browse users and groups“ haben (Jira-Admin → Global permissions → einer Gruppe geben, zu der der Service-Account gehört — volle Jira-Admin-Rechte sind dafür nicht nötig). Bleibt die Suche danach trotzdem leer, gib die accountId direkt ein:

  • Über dein Jira-Profil: Klicke auf deinen Avatar (in Jira oben rechts) → Profile. Deine Account-ID steht in der URL der Seite: https://yourcompany.atlassian.net/jira/people/5b10ac8d82e05b22cc7d4ef5
  • Über die REST API: Öffne, während du in Jira eingeloggt bist, https://yourcompany.atlassian.net/rest/api/3/myself im Browser — die JSON-Antwort enthält "accountId": "...".

Brauche ich für alle eine Jira-Lizenz? Ja — jede Person, die Zeit nach Jira bucht, braucht einen eigenen Atlassian-Account und verbindet ihn, weil ihre Stunden als sie selbst nach Jira geschrieben werden.

Was, wenn wir Tempo für die Zeiterfassung nutzen? Sag deinem Admin Bescheid — die Verbindung hat eine Tempo-Einstellung. Mit Tempo werden Worklogs über die Tempo-API mit dem Token der Verbindung geschrieben; die eigenen Verbindungen der Teammitglieder dienen dann nur dazu, herauszufinden, wer sie in Jira sind.

Ist meine Verbindung sicher? Deine Verbindung (bzw. dein API-Token) wird verschlüsselt gespeichert und nie wieder angezeigt. Nur du kannst sie verwalten; nicht mal Admins können sie sehen. docket fragt bei Atlassian nur an, was es braucht: das Lesen deiner Jira-Arbeit und Nutzerinfos sowie das Schreiben deiner Worklogs.

Weiter geht's: Projekt verknüpfen und mit dem Tracken loslegen.