# Jira-Verbindung einrichten Ein Admin verbindet einmalig deine Jira-**Site**, und jedes Teammitglied verbindet einmalig den **eigenen Jira-Account**. Neu hier? Starte mit dem [Überblick](https://docket.rocks/doku/jira-integration). --- ## Service-Account-Token erstellen *(Admin, einmalig.)* docket liest mit diesem Token Projekte, Issues und Worklogs. Nach Jira schreibt er nie etwas. 1. Gehe, angemeldet als **Service-Account**, zu **[id.atlassian.com → Security → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens)**. 2. Klicke auf **Create API token**, vergib eine Bezeichnung (z. B. `docket service account`) und wähle **genau diese zwei Scopes**: | Scope | Wofür | |---|---| | `read:jira-user` | Token prüfen und Nutzerinfos lesen (z. B. Anzeigenamen für die Auslastung) | | `read:jira-work` | Projekte, Issues und Worklogs aus Jira lesen | 3. Klicke auf **Create** und kopiere den Token sofort. Atlassian zeigt ihn nur einmal an. 4. Füge ihn in docket ein (Teil 1 unten). > **Nimm einen eigenen Service-Account („Bot“)**, nicht den Account einer echten Person. Verlässt > die Person das Unternehmen und wird ihr Account deaktiviert, bricht die Verbindung ab. ### Was der Service-Account in Jira braucht Nur Lesezugriff, keine Schreib- oder Admin-Rechte: - **Zugang zu Jira**: einen Jira-Platz in eurer Atlassian-Organisation. - **„Browse projects“ auf jedem Projekt, das du verknüpfst.** 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 nötig, um Jira-Personen zu suchen, wenn du sie docket-Nutzern zuordnest (siehe *Fragen zu Accounts und Tokens* unten). Ohne Lesezugriff auf ein Projekt meldet Jira keinen Fehler, sondern liefert einfach keine Issues. docket erkennt das und zeigt es rot unter **Projekt → Einstellungen → Jira** an. Ihre Zeit schreibt jede Person über die 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 verbindet die Jira-Site *(Admin, einmalig pro Jira-Site.)* 1. Gehe zu **Administration → Integrationen** und klicke auf **Verbindung hinzufügen**. 2. Fülle aus: - **Name**, z. B. „Company Jira“. - **Site-URL**: `https://yourcompany.atlassian.net`. docket ermittelt daraus die Jira-`cloud_id`. - **E-Mail des Service-Accounts** und **API-Token des Service-Accounts** (der Bot-Account). - **Zeiterfassungs-Backend**: Lass es auf **Jira-eigene Worklogs**, außer dein Team erfasst Zeit mit **Tempo Timesheets**. Dann wähle Tempo und gib den Tempo-API-Token ein. - **Jira-Autoren ohne docket-Account** (standardmäßig an): Für jede Person, die in Jira Zeit erfasst, aber keinen docket-Nutzer hat, legt docket einen **Platzhalter-Nutzer** an, damit ihre Zeit in Budgets und Reports zählt (siehe [Wie Zeit aus Jira behandelt wird](https://docket.rocks/doku/jira-sync)). Die **Leistung, mit der ein neuer Platzhalter startet**, bestimmt den Satz, zu dem seine Zeit abgerechnet wird; pro Platzhalter kannst du sie später ändern. Ohne Leistung bleibt die Zeit nur lesbar. 3. Klicke auf **Verbindung hinzufügen**. docket prüft die Zugangsdaten sofort gegen Jira: Ein grünes **aktiv**-Badge heißt, Jira ist erreichbar. Ein rotes **Anmeldung fehlgeschlagen**-Badge heißt, E-Mail oder Token sind falsch oder haben keinen Zugriff (korrigiere das über ✎ **Bearbeiten**). Mit **↻ Verbindung testen** prüfst du jederzeit neu, z. B. nachdem du den Token rotiert hast. --- ## Teil 2: Jedes Teammitglied verbindet den eigenen Jira-Account *(Alle, die Zeit auf Jira-Tickets buchen, einmalig.)* docket schreibt deine Zeit als du nach Jira. Die Stunden erscheinen dort also unter deinem Namen, nicht unter dem des Bots. 1. Öffne in deinen **Profileinstellungen** (dein Name → Einstellungen) den Bereich **Jira** und klicke auf **Mit Jira verbinden**. 2. Wähle auf der Atlassian-Seite deine Jira-Site und klicke auf **Accept**. Du landest wieder in docket. 3. docket zeigt **Verbunden als** 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 **Weitere Jira-Site hinzufügen** und wähle sie aus. - **✗** mit einer anderen Meldung: Dein Atlassian-Account kommt an diese Site nicht heran, meist weil dir dort der Zugriff fehlt. Frag deinen Admin. > **Wenn du diesen Schritt überspringst**, kannst du trotzdem Zeit auf Jira-Tickets buchen, sie > wird nur nicht nach Jira übertragen. Diese Einträge sind mit **„Nicht in Jira — verbinde dein > Jira-Konto“** markiert. Sobald du verbunden bist, überträgt docket sie von selbst. **Wenn die Verbindung nicht mehr funktioniert** (du hast sie bei Atlassian widerrufen, oder sie wurde etwa drei Monate nicht genutzt), steht das im Jira-Bereich, zusammen mit einem **Jira neu verbinden**-Button. Außerdem verlangt Atlassian einmal im Jahr von allen, die Verbindung erneut zu bestätigen. **Trennen:** Das Papierkorb-Icon neben „Verbunden als“ entfernt die Verbindung aus docket. Um docket den Zugriff ganz zu entziehen, entferne docket zusätzlich in deinem Atlassian-Profil unter **[Connected apps](https://id.atlassian.com/manage-profile/apps)**. ### Alternative: ein persönlicher API-Token Nimm diesen Weg, wenn **Mit Jira verbinden** nicht angezeigt wird oder der Atlassian-Admin deines Unternehmens das Verbinden von Apps blockiert hat (Atlassian zeigt dann auf seiner Seite einen Hinweis): 1. Gehe mit deinem **eigenen** Atlassian-Account zu **[id.atlassian.com → Security → API tokens](https://id.atlassian.com/manage-profile/security/api-tokens)**, 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 | 2. Klicke auf **Create** und kopiere den Token sofort. Atlassian zeigt ihn nur einmal an. 3. Klicke im **Jira**-Bereich von docket auf **Stattdessen ein API-Token nutzen**, gib deine **Atlassian-E-Mail** und den Token ein, lass **Gilt für** auf **Standard (alle Verbindungen)** und klicke auf **Token speichern**. Ein Token gilt für jede Jira-Site, auf die dein Atlassian-Account zugreifen kann. --- ## Fragen zu Accounts und Tokens **Wo finde ich meine Jira-Account-ID?** Meist brauchst du sie nicht: docket liest sie aus, wenn du deinen Jira-Account verbindest. Ordnet ein **Admin** einen docket-User von Hand einem Jira-User zu (Administration → Integrationen → Verbindung → Nutzerzuordnung), tippt er einen Namen oder eine E-Mail ins Jira-User-Feld. docket durchsucht Jira live und trägt die accountId ein, sobald er einen Treffer auswählt. Dafür braucht der Service-Account in Jira die globale Berechtigung **„Browse users and groups“** (Jira-Admin → **Global permissions**, vergeben an eine Gruppe, zu der der Service-Account gehört; volle Jira-Admin-Rechte sind nicht nötig). Bleibt die Suche trotzdem leer, gib die accountId direkt ein. Du findest sie: - **in deinem Jira-Profil:** dein Avatar (in Jira oben rechts) → **Profile**. Die 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 unter ihrem Namen nach Jira geschrieben werden. **Was, wenn wir Tempo für die Zeiterfassung nutzen?** Dein Admin stellt die Verbindung auf **Tempo**. Worklogs werden dann über die Tempo-API mit dem Token der Verbindung geschrieben; die eigenen Verbindungen der Teammitglieder verraten docket nur, 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](https://docket.rocks/doku/jira-projekt-verknuepfen)**.