1.1.0-rc1

docs/confluence/03-zammad-sync-und-integration.md

@@ -0,0 +1,82 @@
+# Zammad Sync und Integration
+
+TicketTracker nutzt Zammad, ohne Zammad zu ersetzen. Zammad bleibt das führende Ticketsystem für Ticketstammdaten, Organisationen, Status und Prioritäten.
+
+## Persönlicher Zammad-Token
+
+Jeder Benutzer kann im Profil einen persönlichen Zammad API-Token speichern. Beim Speichern ruft TicketTracker Zammad ab, prüft den Token und speichert die Zammad User-ID.
+
+Der Token wird verschlüsselt in der Datenbank gespeichert.
+
+Der persönliche Token wird unter anderem für benutzerbezogene Zammad-Funktionen verwendet, zum Beispiel interne Notizen oder personenbezogene Synchronisierungen.
+
+## Admin-Zammad-Zugang
+
+Im Adminbereich wird der Zammad-Zugang für systemweite Synchronisierungen gepflegt.
+
+Der Admin kann Organisationen aus Zammad synchronisieren. Dabei werden lokale Organisationen angelegt, aktualisiert oder entfernt beziehungsweise von alten Verknüpfungen gelöst.
+
+## Ticketdaten aus Zammad
+
+TicketTracker kann Ticketdaten aus Zammad übernehmen:
+
+- Ticketnummer
+- Titel
+- Organisation
+- Work-Type, zum Beispiel Support oder Consulting
+- Status
+- Priorität
+- Owner
+- Teamspace-Projektinformationen
+
+Zammad-verwaltete Ticketstammdaten bleiben geschützt. Ticketnummer, Titel, Art und Organisation können dann in TicketTracker nicht beliebig überschrieben werden.
+
+## Consulting-Projekte aus Zammad
+
+Beim Zammad-Sync oder beim Anlegen eines Projekts können Consulting-Projektinformationen übernommen werden.
+
+Dazu gehören insbesondere:
+
+- Teamspace-Projekt-ID oder mehrere Teamspace-Projekt-IDs
+- Zammad-Owner
+- Projektstatus-Hinweise, zum Beispiel Review bei Abschlussstatus
+
+Die Teamspace-Projekt-ID aus Zammad ist die fachliche ID, zum Beispiel `EP-2026-A-035`. Für Teamspace-API-Abfragen speichert TicketTracker zusätzlich die interne Teamspace-API-ID.
+
+## Teamspace-Projekt-ID-Sync auf der Zammad-Sync-Seite
+
+Auf der Zammad-Sync-Seite gibt es den Sync für Teamspace-Projekt-IDs, Budgets und Positionen.
+
+Voraussetzungen:
+
+- Admin hat die Teamspace-Base-URL gespeichert.
+- Benutzer hat im Profil Teamspace-Geraete-ID und Geraetepasswort gespeichert.
+- Die Teamspace User-ID ist bekannt.
+- Das Projekt hat eine Teamspace-Projekt-ID.
+
+Der Sync speichert:
+
+- Teamspace-API-ID
+- Teamspace-API-URL
+- Gesamtbudget
+- Unterpositionen
+- Budgets und Istwerte der Unterpositionen
+- Stückpositionen
+
+## Interne Zammad-Notizen
+
+Beim Timerabschluss und beim manuellen Nachtragen kann TicketTracker einen internen Zammad-Article erzeugen.
+
+Der Article enthält die Tätigkeit und optional den `time_unit`-Wert. Im Profil kann eingestellt werden:
+
+- ob die interne Notiz standardmäßig aktiv ist
+- welcher Zammad-Zeitbuchungstyp vorausgewählt wird
+- ob `time_unit` auf 5, 10, 15 oder 30 Minuten aufgerundet wird
+
+Wenn Zammad nicht erreichbar ist oder die Notiz fehlschlägt, speichert TicketTracker die Session trotzdem. Die fehlgeschlagene Notiz wird geparkt und kann später im Profil erneut gesendet werden.
+
+## eMail-/Article-Import
+
+TicketTracker kann Zammad-Articles prüfen und daraus Sessions vorbereiten. Das ist besonders hilfreich, wenn Arbeit per eMail-Import ins Ticket kam.
+
+Solche Sessions können nachträglich geprüft, zugeordnet und bewertet werden. Wenn ein importierter Eintrag keinem Teamspace-Projekt zugeordnet ist, kann das im Projektdetail sichtbar werden.