Handbuch Calendar Sync

Einrichtung, Funktionsweise und Betrieb der Termin-Synchronisation zwischen Ihrer Terminsoftware und Microsoft Outlook. Alle Screenshots stammen aus einer Demo-Installation mit erfundenen Daten.

1. Überblick

Calendar Sync ist eine Middleware. Sie steht zwischen der Terminsoftware und Microsoft 365 bzw. Exchange und hält Termine in beide Richtungen synchron:

Richtung	Was passiert
Terminsoftware → Outlook	Jeder Termin einer gemappten Ressource (Mitarbeiter, Raum, Gerät) erscheint als Termin im zugeordneten Outlook-Kalender. Betreff ist die Terminnummer, Details stehen im Termintext.
Outlook → Terminsoftware	Eigene Outlook-Termine (Status „gebucht") blockieren automatisch die Verfügbarkeit in der Terminsoftware als Sperrzeit. So entstehen keine Doppelbuchungen.

Beteiligte Systeme:

• Terminsoftware: führendes System für Kundentermine. Die Middleware spricht deren Calendar-API an und empfängt Ereignisse per Webhook.
• Microsoft 365 / Exchange: Kalender der Mitarbeitenden, Räume und Geräte. Anbindung über Microsoft Graph (Standard) oder Exchange Web Services (EWS, für Exchange Online mit OAuth oder On-Premises).
• Calendar Sync Middleware: Docker-Container mit eigener PostgreSQL-Datenbank, Admin-Oberfläche und mehreren Hintergrunddiensten.

2. Kommunikationswege

Jede Richtung hat einen schnellen Weg (Push per Webhook) und ein Sicherheitsnetz (aktives Nachfragen). Fällt der schnelle Weg aus, übernimmt das Sicherheitsnetz automatisch. Änderungen kommen dann verzögert an, gehen aber nicht verloren.

Terminsoftware ↔ Middleware

Kanal	Beschreibung
Webhook der Terminsoftware Push, sofort	Die Terminsoftware ruft POST /api/appointment-events auf, gesichert über den Header X-API-Key. Verarbeitet werden appointment_confirmed, appointment_reserved, appointment_requested (Anlegen), appointment_move (Ändern), appointment_canceled und appointment_canceled_not_confirmed_intime (Löschen). Unbekannte oder deaktivierte Tenants werden mit 200 ignored beantwortet, damit die Terminsoftware nicht endlos wiederholt.
Termin-Polling Sicherheitsnetz	Alle 60 Sekunden fragt die Middleware pro Ressource nach Terminen, die sich seit der letzten bekannten Änderung geändert haben (Wasserzeichen mit 2 Minuten Überlappung). Sind die Webhooks aller Tenants gesund, wird auf 5 Minuten gedrosselt. Nach einem Ausfall wird ab dem Wasserzeichen alles nachgeholt.
API der Terminsoftware Ausgehend	Die Middleware liest Termine und Ressourcen und schreibt Sperrzeiten (block_availability). Zugangsdaten sind die pro Tenant hinterlegte Base-URL und der zugehörige API-Key. HTTPS ist Pflicht.

Outlook ↔ Middleware

Kanal	Beschreibung
Outlook-Webhook Push, sofort	Pro Mapping besteht eine Graph-Subscription (Laufzeit 2 Tage, automatische Erneuerung alle 12 Stunden) bzw. eine EWS-Push-Subscription. Microsoft meldet Änderungen an die öffentliche HTTPS-URL der Middleware. Mehrere Meldungen zum selben Termin werden für 10 Sekunden gesammelt (Debounce), damit ein Termin nur einmal verarbeitet wird.
Delta-Abfrage Sicherheitsnetz	Alle 60 Sekunden (gesund: 5 Minuten) holt die Middleware pro Kalender die Änderungen seit dem letzten Delta-Link. Beim ersten Lauf wird das Fenster von 1 Monat zurück bis 6 Monate voraus vollständig gelesen.
Graph / EWS Ausgehend	Anlegen, Ändern und Löschen von Terminen in den gemappten Kalendern. Jeder von der Middleware erzeugte Termin trägt eine unsichtbare Markierung, an der die Middleware ihre eigenen Termine wiedererkennt.

Die Warteschlange

Alles, was per Webhook oder Polling erkannt wird, landet zuerst als Eintrag in einer dauerhaften Warteschlange in der Datenbank. Ein Hintergrunddienst arbeitet sie der Reihe nach ab. Das hat zwei Vorteile: Ein Neustart verliert nichts, und Fehler werden kontrolliert wiederholt.

Status	Bedeutung
PENDING	Wartet auf Verarbeitung (oder auf den nächsten Wiederholungsversuch).
PROCESSING	Wird gerade verarbeitet.
COMPLETED	Erfolgreich abgeschlossen. Auch „nichts zu tun" (z. B. keine Änderung) endet hier.
FAILED	Fehlgeschlagen, wird automatisch wiederholt. Fehlertext steht am Eintrag.
DEADLETTER	Alle Versuche verbraucht. Wird nicht mehr automatisch versucht, nur noch per Erneut einreihen.

Wiederholungen: Ein fehlgeschlagener Eintrag wird bis zu 5-mal versucht. Die Wartezeiten dazwischen wachsen: 5 Sekunden, 30 Sekunden, 2 Minuten, 10 Minuten. Nach dem fünften Fehlschlag geht der Eintrag in Dead Letter.

3. Sync-Regeln

Situation	Verhalten
Termin wird in der Terminsoftware gebucht	Outlook-Termin erscheint im Kalender jeder gemappten Ressource des Termins (Mitarbeiter, Raum, Gerät), typisch innerhalb weniger Sekunden.
Termin wird in der Terminsoftware verschoben oder storniert	Outlook-Termin wandert mit bzw. verschwindet. Unveränderte Termine werden per Inhaltsvergleich erkannt und nicht erneut geschrieben.
Mitarbeitende legt eigenen Outlook-Termin an	Der Zeitraum wird in der Terminsoftware als Sperrzeit blockiert (Notiztext konfigurierbar, Standard „Outlook-Sync"). Verschieben verschiebt die Sperrzeit, Löschen hebt sie auf. Termine mit Status „frei" blockieren nicht.
Mehrere Outlook-Termine überlappen	Werden zu einer zusammenhängenden Sperrzeit zusammengefasst.
Serientermin in Outlook	Wird für die nächsten 6 Monate (pro Tenant einstellbar) in einzelne Sperrzeiten aufgelöst. Alle 12 Stunden wird der Horizont automatisch nachgezogen.
Termin der Terminsoftware wird in Outlook verschoben	Die Terminsoftware ist führend. Die Middleware setzt den Termin auf die Originalzeit zurück und ergänzt einen Hinweis im Termintext. Kein Fehler, sondern gewollt.
Termin der Terminsoftware wird in Outlook gelöscht	Der Termin wird in Outlook automatisch wiederhergestellt. Die Buchung in der Terminsoftware bleibt bestehen.

Nicht Teil der Lösung: keine Einladungen oder E-Mails an Kundinnen, keine Teilnehmerverwaltung, keine Anhänge, keine Kundendaten in Outlook.

4. Einrichtung Schritt für Schritt

Die Server-Installation (Docker Compose, Reverse Proxy, Secrets) beschreibt das README des Projekts. Dieses Kapitel setzt eine laufende Middleware voraus und führt vom ersten Login bis zur Abnahme.

Schritt 1: Erster Login

Beim allerersten Start legt die Middleware automatisch einen SuperAdmin an, sofern noch kein Benutzer existiert:

• Benutzername: admin, oder der Wert aus Security:BootstrapAdmin:Username in der appsettings.json.
• Passwort: der Wert aus Security:BootstrapAdmin:Password (mindestens 10 Zeichen). Fehlt er oder ist er zu kurz, wird ein Zufallspasswort erzeugt und einmalig im Server-Log ausgegeben. Danach ist sofort eine Passwortänderung Pflicht.

# Generiertes Passwort im Container-Log finden
docker logs rc_calendarsync 2>&1 | grep "generated password"

Schritt 2: Azure-App registrieren (Graph und Exchange Online)

Im Azure-Portal unter Microsoft Entra ID → App-Registrierungen → Neue Registrierung:

1. Name z. B. CalendarSync, Kontotyp „Nur Konten in diesem Organisationsverzeichnis".
2. Anwendungs-ID (Client ID) und Verzeichnis-ID (Tenant ID) notieren.
3. Unter Zertifikate & Geheimnisse einen geheimen Clientschlüssel erzeugen (Laufzeit max. 24 Monate). Wert sofort kopieren und das Ablaufdatum dokumentieren.
4. API-Berechtigungen → Anwendungsberechtigungen:
   • Provider Microsoft Graph: ausschließlich Calendars.ReadWrite. Empfohlen: den Zugriff per ApplicationAccessPolicy auf die synchronisierten Postfächer begrenzen (Anleitung im Techniker-Einrichtungsguide, Kapitel 2.1). Der Verbindungstest fragt dann nach einem freigegebenen Postfach, solange noch keine Zuordnung besteht.
   • Provider Exchange Online (EWS + OAuth): Office 365 Exchange Online → full_access_as_app
5. Administratorzustimmung erteilen (globaler Admin). Ohne Zustimmung scheitert später der Verbindungstest.

Für Exchange On-Premises mit Basic Auth entfällt dieser Schritt. Dort werden EWS-URL und ein Service-Account mit Impersonationsrecht benötigt. Dieser Weg ist als experimentell gekennzeichnet.

Schritt 3: Webhook in der Terminsoftware einrichten

Damit Änderungen aus der Terminsoftware sofort ankommen, dort in der Admin-Oberfläche unter Einstellungen → Terminbuchung → Webhooks einen neuen Endpoint anlegen:

URL	http://rc_calendarsync:5052/api/appointment-events (interner Docker-Name, wenn beide Systeme im selben Stack laufen), sonst die öffentliche URL der Middleware plus /api/appointment-events.
API-Key	Identisch zu Security:ApiKey in der appsettings.json der Middleware.
Events	Mindestens appointment_confirmed, appointment_move, appointment_canceled.

Ohne diesen Webhook funktioniert der Sync trotzdem, dann aber nur über das Polling im 60-Sekunden-Takt.

Schritt 4: Tenant anlegen

Tab Tenants → + Tenant anlegen (nur SuperAdmin). Ein Tenant entspricht einem Mandanten in der Terminsoftware. Ein Assistent führt in drei Schritten durch die Einrichtung: Zugang & Ressourcen, Kalender-Provider, Einstellungen & Prüfen. Jeder Schritt wird geprüft, bevor es weitergeht; gespeichert wird erst am Ende. „Abbrechen, Entwurf behalten" merkt sich die Eingaben ohne API-Key und Secret.

Feld	Wert
Tenant UID	GUID des Mandanten in der Terminsoftware. Muss exakt der tenant_uid im Webhook entsprechen.
Tenant Name	Freier Anzeigename.
Base URL der Terminsoftware	z. B. https://termine.kunde.de/m/mandant. Nur HTTPS.
API-Key der Terminsoftware	API-Key mit Rechten zum Lesen von Terminen und Ressourcen sowie zum Schreiben von Sperrzeiten.
Reminder (Minuten)	Erinnerungszeit der erzeugten Outlook-Termine, Standard 15.
Sperrzeit-Notiz	Notiztext für aus Outlook erzeugte Sperrzeiten, Standard „Outlook-Sync".
Provider	Microsoft Graph (Standard), Exchange Online (EWS + OAuth) oder Exchange On-Premises (EWS, Basic Auth).
Directory (Tenant) ID / Application (Client) ID / Client Secret	Werte aus Schritt 2. Bei On-Premises stattdessen EWS-URL, Service-Account und Passwort.
Secret gültig bis	Ablaufdatum des Client Secrets aus Microsoft Entra ID. 30 Tage vorher erscheint ein Hinweis im Dashboard, nach Ablauf ein kritischer Eintrag.
Sync-Richtung	Beidseitig (Standard), nur Terminsoftware → Outlook oder nur Outlook → Terminsoftware.

Der Assistent prüft beide Seiten vor dem Anlegen: die API der Terminsoftware (Schritt 1) und die Anmeldung beim Kalender-Provider (Schritt 2). Später lässt sich die Verbindung jederzeit auf der Detailseite des Tenants mit Verbindung testen prüfen; das Ergebnis steht dort als „Letzter Test". Einstellungen ändert Einstellungen bearbeiten auf derselben Seite.

Schritt 5: Ressourcen den Outlook-Kalendern zuordnen

Tab Kalender-Mappings → Tenant auswählen. Die Tabelle listet alle Ressourcen der Terminsoftware; ein Mapping verbindet eine Ressource mit genau einem Outlook-Kalender.

1. In der Zeile der Ressource auf Kalender zuordnen klicken (Tab „Ohne Zuordnung" zeigt nur offene Ressourcen).
2. E-Mail-Adresse (UPN) des Zielpostfachs eingeben, z. B. raum1@kunde.de, oder ein bekanntes Postfach anklicken, und Kalender laden. Funktions- und freigegebene Postfächer sind unterstützt.
3. Beim gewünschten Kalender auf Zuordnen klicken. Bereits belegte Kalender sind markiert. Wird das Postfach schon in einem anderen Tenant synchronisiert, erscheint eine Warnung, denn zwei schreibende Tenants führen zu Konflikten (HTTP 409).
4. Sync sofort aktivieren angehakt lassen, sonst wird das Mapping pausiert angelegt. Eine Zuordnung lässt sich im Hinweis unten rechts mit „Rückgängig" zurücknehmen.

Ist der Kalender nicht auffindbar, hilft Kalender-ID manuell eingeben. Der klassische Dialog über + Neues Mapping steht weiterhin zur Verfügung.

Alternativ steht die Ansicht Drag & Drop zur Verfügung: Outlook-Postfächer oben hinzufügen, dann Ressourcen per Ziehen auf Kalender legen.

Schritt 6: Webhooks erstellen

Im Tab Kalender-Mappings auf Webhooks erneuern klicken. Für jedes aktive Mapping wird eine Subscription bei Microsoft angelegt. Nach kurzer Zeit zeigt die Spalte Webhook bei jedem Mapping AKTIV. Die Subscriptions werden danach automatisch alle 12 Stunden verlängert.

Schritt 7: Abnahme

Die Einrichtung gilt als abgenommen, wenn diese sechs Tests bestanden sind:

#	Aktion	Erwartung
1	In der Terminsoftware Termin auf gemappte Ressource buchen	Outlook-Termin erscheint innerhalb weniger Sekunden
2	In Outlook privaten Termin (Status „gebucht") im gemappten Kalender anlegen	Sperrzeit in der Terminsoftware innerhalb ~10 Sekunden
3	Termin aus #1 in der Terminsoftware verschieben	Outlook-Termin wandert mit
4	Termin aus #1 in Outlook verschieben	Termin springt zurück, Hinweis im Termintext
5	Termin aus #1 in Outlook löschen	Termin wird automatisch wiederhergestellt
6	Termin aus #1 in der Terminsoftware stornieren	Outlook-Termin verschwindet, Sperrzeit aus #2 bleibt

Für bestehende Termine anschließend im Tab Sync Status einen Initialen Sync über den gewünschten Zeitraum starten (siehe Sync Status).

5. Die Oberfläche

Die Admin-Oberfläche ist unter der URL der Middleware erreichbar. Welche Tabs sichtbar sind, hängt von der Rolle ab (siehe Benutzer & Rollen). Ein Banner oberhalb der Karten warnt, wenn eine Terminsoftware nicht erreichbar ist.

Tenants

Verbindungen zu den Mandanten der Terminsoftware mit URL, Provider und Zugangsdaten. Testen prüft beide Seiten der Verbindung. Export und Import (nur SuperAdmin) übertragen Tenants und Mappings als JSON zwischen Installationen. Secrets werden dabei nie exportiert und müssen nach einem Import neu eingegeben werden.

Kalender-Mappings

Zuordnung Ressource ↔ Outlook-Kalender pro Tenant, umschaltbar zwischen Tabelle und Drag & Drop. Kopfzeile:

• Webhooks erneuern: alle Subscriptions des Tenants neu anlegen. Erste Maßnahme, wenn Outlook-Änderungen nicht mehr ankommen.
• Termin testen: spielt einen einzelnen Termin per Termin-UID Schritt für Schritt durch (Termin laden, Mapping finden, Anmeldung beim Kalender-Provider, nach Outlook schreiben) und zeigt, wo es abbricht, samt Lösungshinweis. Im Modus Nur prüfen wird nichts geschrieben, im Modus Prüfen und schreiben landet der Termin bei Erfolg in Outlook. Jeder Test steht im Audit Log.
• + Neues Mapping: klassischer Dialog, alternativ zur Zuordnung in der Tabelle.

Ein Mapping pausieren stoppt den Sync für diese Ressource sofort, lässt aber bereits erzeugte Outlook-Termine und Sperrzeiten stehen. Lösen entfernt nur die Zuordnung, räumt ebenfalls nichts auf. Ein Klick auf den Ressourcennamen öffnet die Detailseite des Mappings mit den letzten Syncs und den Kenndaten.

Sync Status

Erste Anlaufstelle bei Problemen. Pro Tenant und Zeitraum:

• Aktive Mappings: Anzahl der Ressourcen mit eingeschaltetem Sync.
• Synchronisiert / Fehlgeschlagen: abgeschlossene bzw. aktuell fehlgeschlagene Vorgänge im gewählten Zeitraum.
• Queue (Pending): wartende Einträge. Dauerhaft über 50 deutet auf eine Störung hin.
• Dead Letter: endgültig fehlgeschlagene Einträge, die manuell geprüft werden müssen.
• Letzte Aktivitäten: die letzten 20 Vorgänge mit Richtung, Auslöser (Quelle), Termin, Ressource und Status.
• Initialer Sync: bestehende Termine der Terminsoftware eines Zeitraums nach Outlook übertragen. Bereits synchronisierte Termine werden übersprungen, außer „Bereits synchronisierte aktualisieren" ist angehakt. Die Ressourcenauswahl kann leer bleiben (alle).
• Nachsynchronisierung (Outlook → Terminsoftware): liest die ausgewählten Outlook-Kalender komplett neu ein (Zeitraum: 1 Monat zurück bis 6 Monate voraus), indem der Delta-Link zurückgesetzt wird. Die Mapping-Auswahl kann leer bleiben (alle). Die gefundenen Änderungen laufen über die Warteschlange; der Fortschritt ist unter „Letzte Aktivitäten" sichtbar. Idempotent — bereits synchronisierte Termine bleiben unverändert. Bei großen EWS-Kalendern kann der Lauf einige Minuten dauern.

Die Spalte Quelle zeigt, wie ein Vorgang ausgelöst wurde:

Termin-Webhook	Die Terminsoftware hat die Änderung sofort gemeldet.
Termin-Polling	Änderung beim regelmäßigen Nachfragen erkannt (Sicherheitsnetz).
Outlook Webhook	Microsoft hat die Kalenderänderung gemeldet.
Outlook Delta	Änderung per Delta-Abfrage erkannt (Sicherheitsnetz).
Nachprüfung	Automatische Kontrolle einige Sekunden nach einem Schreibvorgang, ob zwischenzeitlich weitere Änderungen eingingen.
Manuell / Bulk-Sync	Über „Termin testen" (Modus „Prüfen und schreiben") bzw. „Initialer Sync" ausgelöst.
Nachsync	Über „Nachsynchronisierung" (Outlook → Terminsoftware) ausgelöst.
series-materialization	Regelmäßige Auflösung von Outlook-Serienterminen in Sperrzeiten.

Datenbereinigung (nur SuperAdmin)

Damit die Datenbank nicht unbegrenzt wächst, entfernt die Middleware einmal täglich alte Einträge. Gelöscht wird nur nach Alter und Zustand:

Daten	Voreinstellung
Sync Log, abgeschlossene Vorgänge	30 Tage
Sync Log, fehlgeschlagene Vorgänge	90 Tage, damit die Fehlersuche Zeit hat
Aufgehobene Termin-Verknüpfungen	90 Tage
Termin-Verknüpfungen nach Terminende	30 Tage nach dem Terminende, samt gesichertem Verfügbarkeitsstand
Audit Log	90 Tage

Die geltenden Fristen und der letzte Lauf stehen im Tab Sync Status im Abschnitt „Datenbereinigung". Jeder Lauf, der etwas entfernt hat, erscheint zusätzlich im Audit Log als RetentionCleanup mit den Zahlen je Kategorie. Läuft die Bereinigung und findet nichts, entsteht kein Eintrag.

Die Fristen legt der Techniker in der Konfiguration fest. Jede Kategorie lässt sich einzeln abschalten, dann bleiben diese Daten unbegrenzt erhalten. Für das Audit Log ist das je nach Aufbewahrungspflicht zu prüfen.

Sync Log

Vollständiges Protokoll aller Vorgänge eines Tenants, filterbar nach Status (Tabs), Suchbegriff, Zeitraum und Richtung, mit CSV-Export. Ein Klick auf eine Zeile klappt die Details direkt darunter auf: Fehlermeldung, Verlauf der Versuche und Kennungen. Bei fehlgeschlagenen oder abgebrochenen Einträgen erscheint Erneut einreihen; „Alle Details" öffnet die vollständige Ansicht mit Nutzdaten.

Audit Log (nur SuperAdmin)

Wer hat wann was geändert oder ausgelöst: Tenant- und Mapping-Änderungen, Benutzeranlage, manuelle Syncs (inkl. Nachsynchronisierung, OutlookResyncTriggered), Webhook-Erneuerungen, Dead Letters, fehlgeschlagene Logins sowie Systemereignisse wie DeltaQueryFailed und RetentionCleanup. Greift die Middleware korrigierend in Outlook ein, steht auch das hier: OutlookEventReverted (in Outlook verschobener Termin zurückgesetzt), OutlookEventRecreated (in Outlook gelöschter Termin wiederhergestellt) und OutlookEventOrphanDeleted (Outlook-Termin ohne gültigen Termin in der Terminsoftware entfernt bzw. nicht wiederhergestellt) — jeweils nur mit Termin-UID, Outlook-Ereignis-ID, Auslöser und Ergebnis, nie mit Betreff oder Text. Die Spalte Quelle unterscheidet Aktionen von Benutzern („api") und automatische Vorgänge („system").

Benutzer (nur SuperAdmin)

Benutzerkonten anlegen, Rollen pro Tenant vergeben, Passwörter zurücksetzen, Konten deaktivieren. Neue Benutzer erhalten ein temporäres Passwort und müssen es beim ersten Login ändern. Nach 5 Fehlversuchen wird ein Konto 15 Minuten gesperrt; ein SuperAdmin kann die Sperre auf der Detailseite des Benutzers aufheben. Der Tab „Rollen & Rechte" zeigt, was jede Rolle darf.

6. Verbindungsabbrüche und Wiederaufnahme

Grundprinzip: Nichts geht verloren, die Kommunikation nimmt sich selbst wieder auf. Erkannte Änderungen liegen dauerhaft in der Warteschlange und werden wiederholt. Nicht erkannte Änderungen werden über Polling bzw. Delta-Abfrage nachgeholt, sobald die Gegenseite wieder erreichbar ist. Manuelle Eingriffe sind nur in den unten markierten Fällen nötig.

7. Manuelle Eingriffe

Aktion	Wo	Wirkung
Erneut einreihen	Sync Log, am Eintrag	Setzt den Eintrag zurück auf Pending mit null Versuchen. Funktioniert auch bei Dead Letter. Vorher die Ursache beheben, sonst scheitert er erneut.
Initialer Sync	Sync Status	Überträgt alle aktiven Termine der Terminsoftware eines Zeitraums nach Outlook, optional nur für ausgewählte Ressourcen. Bereits verknüpfte Termine werden übersprungen, außer „Bereits synchronisierte aktualisieren" ist gesetzt. Läuft sofort mit Fortschrittsanzeige. Einsatz: Ersteinrichtung, neues Mapping, Nachholen nach Datenverlust.
Nachsynchronisierung	Sync Status	Liest die ausgewählten Outlook-Kalender komplett neu ein (1 Monat zurück bis 6 Monate voraus), indem der Delta-Link zurückgesetzt wird. Änderungen laufen über die Warteschlange. Idempotent — bereits Synchronisiertes bleibt unverändert. Einsatz: verpasste Outlook-Änderungen, verworfener Delta-Link, Kontrolle nach Störungen. Bei großen EWS-Kalendern kann der Lauf einige Minuten dauern.
Termin testen	Kalender-Mappings, Sync Log	Prüft einen einzelnen Termin per Termin-UID Schritt für Schritt (Termin laden, Mapping finden, Anmeldung, Schreiben) und zeigt, wo es abbricht. Im Modus „Prüfen und schreiben" wird der Termin bei Erfolg sofort nach Outlook geschrieben und das Ergebnis gemeldet (erstellt, aktualisiert oder warum nicht).
Webhooks erneuern	Kalender-Mappings	Meldet alle Subscriptions des Tenants ab und legt sie neu an. Erste Maßnahme bei verzögertem Sync von Outlook zur Terminsoftware oder nach Änderungen an Reverse Proxy oder Zertifikat.
Testen	Tenants	Prüft Kalender-Provider und API der Terminsoftware, bei Graph immer über ein Postfach (erste Zuordnung oder abgefragte Adresse). Setzt bei Erfolg den Auth-Schutzschalter zurück und stellt Dead-Letter-Einträge mit Auth-Fehlern automatisch wieder ein.
Mapping deaktivieren	Kalender-Mappings	Stoppt Polling, Delta-Abfrage und Webhook-Erneuerung für diese Ressource. Vorhandene Outlook-Termine und Sperrzeiten bleiben unverändert stehen.
Mapping löschen	Kalender-Mappings	Entfernt nur die Zuordnung. Outlook-Termine, Sperrzeiten und die Subscription bei Microsoft werden nicht aufgeräumt.
Tenant deaktivieren	Tenants, Bearbeiten	Sofortstopp aller Ein- und Ausgänge für den Mandanten. Daten bleiben erhalten, Subscriptions laufen innerhalb von 2 Tagen aus.
Tenant löschen	Tenants	Löscht Konfiguration, Azure-Zugangsdaten und Rollenzuordnungen. Nicht rückgängig zu machen, nur per Datenbank-Backup wiederherstellbar.
Export / Import	Tenants	Konfiguration als JSON sichern oder auf eine andere Installation übertragen. Ohne Secrets, ohne Laufzeitdaten. Import mit Vorschau (Dry Run) und den Modi „merge" und „replace".

8. Benutzer und Rollen

Rolle	Vergabe	Darf
SuperAdmin	pro Benutzer, global	Alles: alle Tenants, Tenants anlegen und löschen, Benutzerverwaltung, Audit Log, Export und Import.
Tenant-Admin	pro Benutzer und Tenant	Zugewiesenen Tenant bearbeiten, Mappings anlegen und ändern, Syncs auslösen, Webhooks erneuern.
Read-Only	pro Benutzer und Tenant	Zugewiesenen Tenant nur ansehen: Status und Sync Log. Keine Schreib-Knöpfe.

• Ein Benutzer kann pro Tenant eine andere Rolle haben. Nicht zugewiesene Tenants sind für ihn unsichtbar.
• Passwörter haben mindestens 10 Zeichen. Es gibt keinen E-Mail-Reset; ein SuperAdmin setzt ein temporäres Passwort.
• Der Login ist pro IP-Adresse auf 10 Versuche in 5 Minuten begrenzt. Danach antwortet der Server mit „Too Many Requests".
• Der API-Key in der appsettings.json schützt nur den Webhook-Eingang der Terminsoftware, nicht die Oberfläche.

9. Was tun, wenn …

Symptom	Erste Schritte
Termin aus der Terminsoftware fehlt in Outlook	Bis zu 5 Minuten warten (Polling). Sync Status: Warteschlange oder Fehler? Ist das Mapping der Ressource aktiv? Bei Bedarf „Termin testen" mit der Termin-UID.
Outlook-Termin blockiert die Terminsoftware nicht	Liegt der Termin im gemappten Kalender (nicht in einem Unterkalender)? Status „gebucht", nicht „frei"? Webhook-Status prüfen, ggf. Webhooks erneuern.
Ganztagstermin blockiert die Terminsoftware nicht	Outlook legt Ganztagstermine standardmäßig mit dem Status „frei" an. Auf „gebucht" umstellen, dann entsteht die Sperrzeit über den ganzen Tag.
Termin springt in Outlook zurück	Kein Fehler: Termine der Terminsoftware sind in Outlook schreibgeschützt. Änderungen dort vornehmen.
Sync dauert Minuten statt Sekunden	Webhooks fallen aus, das Polling übernimmt. Öffentliche URL, Zertifikat und Webhook-Konfiguration der Terminsoftware prüfen. Webhooks erneuern.
Viele Dead-Letter-Einträge mit gleichem Fehler	Systematisches Problem: Fehlertext lesen. AADSTS → Secret erneuern. Timeout → Netz. 404/ErrorItemNotFound → Termin oder Postfach existiert nicht mehr.
Verbindungstest: „Postfach erforderlich"	Kein Fehler: Für Graph gibt es ohne Zuordnung keinen zulässigen Aufruf. Im Dialog ein freigegebenes Postfach eingeben oder zuerst eine Kalender-Zuordnung anlegen.
Verbindungstest: 403 / „Access is denied"	Das Postfach ist nicht von der ApplicationAccessPolicy der App abgedeckt. Techniker: Test-ApplicationAccessPolicy ausführen, Postfach der Policy-Gruppe hinzufügen, bis zu 30 Minuten warten.
Verbindungstest: „Key not found in key ring"	Der Verschlüsselungsschlüssel (Volume cs_dpkeys) fehlt. Secret im Tenant neu eintippen und speichern; das verschlüsselt mit dem aktuellen Schlüssel neu.
Anmeldung schlägt fehl	SuperAdmin setzt das Passwort im Tab Benutzer zurück. Gar kein Zugang mehr: Bootstrap-Admin (Kapitel 4, Schritt 1) über den Techniker.
Tenant oder Knöpfe fehlen in der Oberfläche	Rolle prüfen. Read-Only sieht keine Schreib-Knöpfe, nicht zugewiesene Tenants sind unsichtbar.
Alles rot, nichts synct	Terminsoftware erreichbar? Azure-Secret abgelaufen? Container läuft? Techniker mit Runbook einbeziehen.

Für alles, was Serverzugriff erfordert (Container-Logs, Neustart, Datenbank, Konfigurationsdateien), gilt: Techniker kontaktieren. Die Prozeduren stehen im Operations-Runbook des Projekts.

10. Glossar

Tenant	Ein Mandant der Terminsoftware mit eigener URL, eigenem API-Key und eigener Microsoft-Anbindung.
Ressource	Buchbare Einheit in der Terminsoftware: Mitarbeiter, Raum oder Gerät.
Mapping	Zuordnung einer Ressource zu genau einem Outlook-Kalender eines Postfachs.
Sperrzeit	Zeitraum, in dem eine Ressource in der Terminsoftware nicht buchbar ist. Wird aus Outlook-Terminen erzeugt.
Webhook	Sofortige Benachrichtigung eines Systems an ein anderes über eine Änderung (Push).
Subscription	Bei Microsoft registrierte Anmeldung für Webhooks zu einem Kalender. Läuft bei Graph nach 2 Tagen ab und wird automatisch erneuert.
Polling	Regelmäßiges aktives Nachfragen bei der Terminsoftware nach geänderten Terminen (Sicherheitsnetz).
Delta-Abfrage	Regelmäßiges Abholen aller Kalenderänderungen bei Microsoft seit dem letzten bekannten Stand (Sicherheitsnetz).
Warteschlange / Queue	Dauerhafte Liste aller zu verarbeitenden Vorgänge in der Datenbank.
Aufbewahrungsfrist	Zeitraum, nach dem die Middleware alte Protokolldaten selbsttätig löscht. Einstellbar je Datenart, siehe Datenbereinigung.
Dead Letter	Vorgang, der nach 5 Versuchen endgültig fehlgeschlagen ist und nur noch manuell neu gestartet wird.
Schutzschalter (Circuit Breaker)	Automatische Pause der Microsoft-Abfragen eines Tenants nach wiederholten Anmeldefehlern.
Graph / EWS	Die beiden Microsoft-Schnittstellen für Kalenderzugriff: Microsoft Graph (Microsoft 365) und Exchange Web Services (Exchange Online oder On-Premises).
Bootstrap-Admin	Der beim ersten Start automatisch angelegte SuperAdmin.

← Zurück zur Admin-Oberfläche