planer/docs/handbuch/integrationen.md

# Integrationen

Was von außen hereinkommt — und was diese Instanz hinausgibt. Du findest den
Überblick im Menü unter **Integrationen**.

![Die Seite Integrationen](../bilder/integrationen-hell-schreibtisch.png)

Welche Integration es überhaupt gibt, hängt an der Instanz und ist nicht
verhandelbar:

|                | Firma  | Daheim   |
| -------------- | ------ | -------- |
| Zammad         | ja     | nein     |
| Wartungsplaner | ja     | nein     |
| Telegram       | nein   | ja       |
| Spiegel        | sendet | empfängt |

Eine Integration, die deine Instanz nicht vorsieht, lässt sich auch mit
vollständiger Konfiguration nicht anschalten. Das steckt in der Anwendung,
nicht in einer Einstellung, die sich versehentlich verstellen ließe.

## Was jede Integration mit deinen Aufgaben darf

Für alle gilt dieselbe Regel — und die ist wichtiger als jedes Detail
darunter:

| Führt das Ursprungssystem         | Führst du                                        |
| --------------------------------- | ------------------------------------------------ |
| Titel, Notiz, Verweis, Fälligkeit | Bereich, Projekt, Priorität, geschätzter Aufwand |

Wer ein Ticket in einen Bereich einsortiert und den Aufwand schätzt, muss
sich darauf verlassen können, dass der nächste Abgleich das nicht wegräumt.
Umgekehrt: Ändert sich drüben der Titel, zieht er hier mit.

Dieselbe Sache ergibt nie eine zweite Aufgabe. Der Planer merkt sich zu jeder
Aufgabe, woher sie kam und unter welcher Kennung.

## Zammad

Tickets, auf die der Suchausdruck passt, werden zu Aufgaben. Voreingestellt
sind die dir zugewiesenen offenen Tickets; der Ausdruck steht in der
Konfiguration (`ZAMMAD_ABFRAGE`) und versteht Zammads Suchsyntax.

- Der Titel wird `#Nummer Betreff`, der Verweis führt direkt ins Ticket.
- Ein Ticket, das Zammad als geschlossen meldet, hakt der Planer ab.
- **Geschrieben wird nach Zammad nichts.** Ein Ticket schließt man im
  Ticketsystem — sonst weiß die Kollegin nicht, warum es plötzlich zu ist.

Der Token gehört einem Benutzer und sieht genau das, was dieser Benutzer
sehen darf. Der Planer umgeht keine Rechte.

## Wartungsplaner

Noch nicht angebunden. Die Aufnahmestelle steht bereit — es fehlt allein das
Abholen, und dafür muss die Schnittstelle feststehen. Auf der Seite
**Integrationen** ist der Punkt als offene Lücke sichtbar, damit er nicht in
Vergessenheit gerät.

## Telegram

Drei Dinge in einem Kanal.

### Chat verbinden

1. Unter **Integrationen** auf **Chat verbinden**.
2. Der achtstellige Code erscheint. Er gilt **zehn Minuten** und genau
   **einmal**.
3. Schick ihn dem Bot — als Nachricht oder als `/start ABCD2345`.
4. Der Bot bestätigt, und der Chat erscheint in der Liste.

> **Warum der Umweg?** Wer nicht in der Liste steht, bekommt vom Bot keine
> Antwort — auch keine Fehlermeldung. Sonst könnte jeder, der die Kennung des
> Bots kennt, herausfinden, dass es dich gibt. Der Code ist der Beweis, dass
> jemand mit Zugang zur Anwendung diesen Chat wirklich will.

### Erfassen

Jede Nachricht an den Bot wird eine Aufgabe. Lange Texte werden gekürzt; der
Rest landet in der Notiz und geht nicht verloren. Die Aufgabe hat keinen
Bereich — sie liegt also in der **Inbox** und will einsortiert werden.

### Melden und abhaken

Ist Telegram in den [Benachrichtigungen](benachrichtigungen.md) als Weg
eingeschaltet, kommen Meldungen auch hier an. Geht es um genau eine Aufgabe,
hängt darunter ein Knopf **✓ Erledigt** — ein Druck, und sie ist abgehakt,
ohne die Anwendung zu öffnen.

Mehr kann der Knopf nicht. Löschen oder Verschieben aus einem Chat heraus
wäre zu leicht versehentlich getroffen.

Je Chat lässt sich einzeln einstellen, ob er Meldungen bekommt: Das Glöckchen
in der Liste schaltet um.

## Der Spiegel

Die Firma schickt nach Hause, nicht umgekehrt. Zwei Dinge gehen hinüber.

**Belegungen.** Wann dienstlich Zeit verplant ist — ohne Titel, ohne Aufgabe,
ohne Kunde. Daheim erscheinen sie in der Wochenansicht als gestreifte Balken
mit der Aufschrift „Dienstlich belegt" und zählen gegen die Tageskapazität.
So kollidiert die private Planung nicht mit der dienstlichen, und trotzdem
verlässt kein Firmeninhalt die Firma.

**Markierte Aufgaben.** Nur was du an der Aufgabe ausdrücklich zum Spiegeln
freigibst, geht mit Titel hinüber. Das ist eine Einzelentscheidung je
Aufgabe, kein Schalter für alles: Wer versehentlich einen ganzen Bereich
spiegelt, schickt Kundennamen nach Hause.

Was der Sender nicht mehr schickt, verschwindet auch drüben. Wird ein
Zeitblock in der Firma ausgeplant, ist die Sperre daheim beim nächsten Lauf
weg — sonst stünde dort für immer eine Blockade, die es längst nicht mehr
gibt.

## Wann läuft was

| Integration | Takt            |
| ----------- | --------------- |
| Telegram    | alle 2 Minuten  |
| Zammad      | alle 15 Minuten |
| Spiegel     | alle 15 Minuten |

Wer dem Bot etwas schickt, erwartet die Aufgabe gleich in der Liste. In
Zammad ändert sich dagegen nichts im Minutentakt.

Warten muss man trotzdem nicht: Auf der Seite **Integrationen** stößt
**Jetzt abrufen** einen Lauf von Hand an. Das lohnt vor allem direkt nach dem
Einrichten — sonst wüsstest du erst beim nächsten Takt, ob die Zugangsdaten
stimmen.

## Wenn etwas klemmt

Unter jeder Integration steht, wann sie zuletzt geglückt ist und woran sie
zuletzt gescheitert ist. Nach dem dritten Fehlschlag hintereinander gilt sie
als **gestört** — und dann meldet sich der Planer auch, sofern du den Anlass
„Ein Kalender lässt sich nicht abgleichen" eingeschaltet hast.

Erst nach dem dritten Mal: Ein Netz hustet, ein Anbieter hat Wartung. Beim
ersten Fehlschlag zu melden hieße, dich für Dinge zu wecken, die sich von
selbst erledigen.

| Symptom                                  | Ursache                                                                           |
| ---------------------------------------- | --------------------------------------------------------------------------------- |
| „Nicht eingerichtet" trotz Konfiguration | Die Instanz sieht diese Integration nicht vor                                     |
| Zammad findet nichts                     | Der Suchausdruck passt auf kein Ticket — in Zammad selbst probieren               |
| Der Bot antwortet nicht                  | Der Chat ist nicht verbunden, oder der Code war abgelaufen                        |
| Der Spiegel wird abgelehnt               | Verschiedene Geheimnisse, oder die Uhren laufen mehr als fünf Minuten auseinander |

---

Zurück zum [Handbuch](README.md).