Outlook-Verbindung: Methoden und funktioneller Hintergrund
Die Outlook-Verbindung synchronisiert Termine zwischen einem Microsoft 365 / Outlook-Kalender und i-Reserve. Die Verbindung kommuniziert direkt mit der Microsoft Graph REST API v1.0 über OAuth 2.0 — es wird kein EWS (Exchange Web Services) oder MSAL-SDK verwendet. Dieser Artikel beschreibt den funktionellen Hintergrund: welche Verbindungsmethoden es gibt, wie die Synchronisation funktioniert und welche Einschränkungen bestehen.
Zwei Verbindungsmethoden
Die Methode wird durch den Authentifizierungsmodus (config-key auth_mode) bestimmt. Beide Methoden können von derselben Azure-App bedient werden; es sind separate Berechtigungstypen in Entra ID.
| Delegiert (delegated) | Applikation (application / app-only) | |
|---|---|---|
| Wann | Ein persönlicher oder gemeinsamer Kalender | Viele Raum-/Ressourcen-Postfächer, in großem Umfang |
| Authentifizierung | Interaktives OAuth (authorization code). Ein Benutzer meldet sich an und erteilt die Zustimmung; i-Reserve bewahrt ein Access- und Refresh-Token auf. | Nicht-interaktiv (client credentials). Die App authentifiziert sich als sie selbst und ruft selbst ein app-only Token ab (~1 Stunde gültig, kein Refresh-Token). |
| Kalender-Quelle | Der Standardkalender des angemeldeten Benutzers (me/…). | Pro Raum-Postfach (users/{room-upn}/…), jeweils mit einem eigenen i-Reserve-Objekt verbunden. |
| Richtung | Bidirektional: inbound (Outlook → i-Reserve) und outbound (i-Reserve → Outlook). | Nur inbound. Outbound ist deaktiviert, weil ein app-only Token keinen angemeldeten Benutzer (me) hat. |
| Verbindung Objekt | Ein i-Reserve-Objekt. | Pro Raum ein eigenes Objekt (room → object-Tabelle). Skaliert auf Hunderte von Räumen pro Kunde. |
Faustregel: Verwenden Sie delegiert für einen Kalender und ein Objekt. Verwenden Sie applikation, sobald Sie Raum-/Ressourcen-Postfächer verbinden möchten — diese können sich nicht interaktiv anmelden und haben keine Lizenz, sodass delegiert dort nicht funktioniert.
Wie die Synchronisation funktioniert
Änderungen kommen nahezu in Echtzeit über eine Graph change-notification subscription (Webhook) herein; ein Cron-Prozess fängt verpasste Benachrichtigungen über Polling ab. Die Verbindung nutzt also bewusst beide Kanäle.
- Inbound liest mit einer Graph delta-query (calendarView/delta) über ein Zeitfenster von −90 Tagen bis +365 Tagen, paginiert über @odata.nextLink und bewahrt den @odata.deltaLink als Sync-Token auf. Pro Raum (application) gibt es ein eigenes Sync-Token und einen eigenen Webhook.
- Webhooks posten an einen öffentlichen Endpunkt. Eine Subscription verfällt nach 3 Tagen und wird vom Cron automatisch erneuert, sobald sie innerhalb von 2 Tagen verfällt. Im application-Modus gibt es eine Subscription pro Raum; Benachrichtigungen werden anhand der subscription-id geroutet, sodass genau der richtige Raum synchronisiert wird.
- Polling-Fallback: hatte ein Kalender länger als 30 Minuten keine Synchronisation, dann stellt der Cron eine inbound-Synchronisation in die Warteschlange, sodass verpasste Benachrichtigungen dennoch abgerufen werden.
Inbound: vom Outlook-Termin zur Buchung
Pro Outlook-Event bestimmt i-Reserve, ob es sich um eine Anlage, Änderung oder Stornierung handelt:
- Abgleich mit bestehender Buchung — zuerst über die gespeicherte externe event-id (Feld ires_field), als Fallback über einen [boeking_id]-Suffix im Betreff.
- Gelöscht / storniert (@removed oder isCancelled) → die verbundene Buchung erhält den Stornierungs-Status und wird entkoppelt (sofern nicht in einem lock-Status).
- Bestehende Buchung → Datum und Uhrzeit werden aktualisiert, gesteuert durch „Buchungs-Update zulassen“ und „Validierungsfehler ignorieren“. Buchungen, die über diese Verbindung angelegt wurden, folgen immer der Outlook-Änderung.
- Neu → es wird eine Buchung auf dem verbundenen Objekt angelegt (Kanal external/outlook), mit Betreff und Beschreibung als Anmerkung. Kann der Organisator einem bestehenden Kunden zugeordnet werden, dann wird dieser Kunde verbunden und (sofern eingestellt) der „Status mit Kunde“ verwendet.
Outbound (nur delegiert)
Im delegierten Modus pusht i-Reserve Termine nach Outlook auf Basis des Buchungsstatus: anlegen (POST me/events), aktualisieren (PATCH me/events/{id}) und löschen (DELETE me/events/{id}), gesteuert durch die Status „Kalendereintrag anlegen“ und „Löschen bei Status“. Optional wird ein Teams-Besprechungslink angelegt und der Kunde als Teilnehmer hinzugefügt.
Einschränkungen
- Outbound nur im delegierten Modus. Im application-Modus werden outbound-Trigger bewusst übersprungen und protokolliert.
- Der Zustand pro Raum (Sync-Token, Webhook) wird in der Verbindungskonfiguration gespeichert; dies skaliert auf Hunderte von Räumen, aber eine Verbindung = eine Azure-App/Tenant.
- Ein app-only Token lebt ~1 Stunde und wird automatisch erneuert; es gibt kein Refresh-Token.
- Es gibt keine Graph room-list (places) Auto-Discovery: Raum-UPNs werden manuell eingegeben.
