Google Calendar-Verbindung: Methode und funktionaler Hintergrund

Die Google Calendar-Verbindung synchronisiert Termine zwischen einem Google Calendar (Google Workspace oder ein normales Google-Konto) und i-Reserve. Die Verbindung kommuniziert direkt mit der Google Calendar API v3 über OAuth 2.0. Dieser Artikel beschreibt den funktionalen Hintergrund: die Verbindungsmethode, wie die Synchronisation funktioniert und welche Einschränkungen bestehen.

Verbindungsmethode: delegiertes OAuth

Die Verbindung arbeitet mit delegierter Authentifizierung (OAuth 2.0 Authorization-Code-Flow): Ein Google-Benutzer meldet sich einmalig an und erteilt die Zustimmung, woraufhin i-Reserve ein access_token + refresh_token speichert und die Tokens automatisch erneuert. Es gibt keinen Service-Account- oder Domain-wide-Delegation-Modus (anders als bei Outlook, das auch einen app-only Modus für Raum-Postfächer kennt). Die Verbindung ist also benutzerorientiert: Sie arbeitet aus den Kalendern, auf die dieser eine Benutzer Zugriff hat.

Angeforderte Scopes:

• https://www.googleapis.com/auth/calendar.readonly — Kalender auflisten und Termine lesen.
• https://www.googleapis.com/auth/calendar.events — Termine erstellen, ändern und löschen.

Die Zustimmung wird mit access_type=offline (liefert das Refresh-Token) und prompt=consent angefordert.

Mehrere Kalender: Objekt → Kalender-Mapping

Eine Verbindung kann mehrere Google-Kalender bedienen über ein Objekt → Kalender-Mapping: Pro i-Reserve-Objekt wählen Sie, zu welchem Google-Kalender (calendar-id) Termine gehen. Ein Platzhalter (*) dient als Standardkalender für Objekte ohne eigene Regel. Für outbound wird der Kalender des Objekts der Buchung verwendet; für inbound wird der Kalender verfolgt, der zum Inbound-Objekt gehört (oder der erste verbundene Kalender).

Anders als bei der Outlook-Verbindung gibt es kein separates Raum-/Ressourcen-Postfach-Konzept; Ressourcen verbinden Sie, indem Sie den betreffenden Google-Kalender einem i-Reserve-Objekt zuordnen.

Wie die Synchronisation funktioniert

Die Verbindung ist bidirektional und verwendet sowohl Push als auch Polling.

• Inbound (Google → i-Reserve) liest über events.list auf calendars/{calendar-id}/events mit einem Sync-Token für inkrementelle (Delta-)Synchronisation; beim ersten Durchlauf ein Fenster von −90 bis +365 Tagen. Paginierung über nextPageToken, das nextSyncToken wird für die nächste Runde gespeichert.
• Push: i-Reserve registriert einen Google watch-channel (events/watch), der Änderungen an einen öffentlichen Endpunkt pusht. Der Channel läuft ab und wird vom Cron automatisch erneuert, sobald er innerhalb von 2 Tagen abläuft. Benachrichtigungen werden anhand der Channel-ID geroutet.
• Polling-Fallback: Hatte ein Kalender länger als 30 Minuten keine Synchronisation, dann stellt der Cron eine Inbound-Synchronisation in die Warteschlange, damit verpasste Benachrichtigungen dennoch abgeholt werden.
• Echo-Prävention: Während der Verarbeitung von Inbound-Events werden Outbound-Trigger bewusst unterdrückt, sodass eine eingehende Änderung nicht sofort wieder zu Google zurückgepusht wird (keine Endlosschleife).

Inbound: vom Google-Termin zur Buchung

1. Abgleich mit bestehender Buchung — zunächst über die gespeicherte externe Event-ID (Feld ires_field, default external_id), als Fallback über einen [boeking_id]-Suffix im Titel.
2. Storniert (Event-Status cancelled) → die verbundene Buchung erhält den Storno-Status und wird getrennt (sofern zulässig).
3. Bestehende Buchung → nur Datum/Uhrzeit werden aktualisiert; der Buchungsstatus bleibt. Zulässig, wenn das Event über diese Verbindung erstellt wurde (Kanal external), oder wenn “Buchungsaktualisierung zulassen” aktiviert ist. Mit “Validierungsfehler bei Update ignorieren” werden Änderungen auch bei einem Konflikt angewendet (andernfalls als Bemerkung protokolliert).
4. Neu → es wird eine Buchung auf dem verbundenen Objekt erstellt (Kanal external/google), mit Termin-Titel/-Beschreibung als Bemerkung, im eingestellten “Inbound-Status”.

Outbound: von der Buchung zum Google-Termin

Auf Basis des Buchungsstatus erstellt i-Reserve Termine (POST events), aktualisiert sie (PATCH events/{id}) oder löscht sie (DELETE events/{id}), gesteuert durch “Erstellen bei Status” und “Löschen bei Status” (der Storno-Status löscht immer). Zusätzliche Möglichkeiten:

• Google Meet-Link erstellen (optional) und die Join-URL in einem Buchungsfeld speichern. Bei einem Update wird ein bestehender Meet-Link beibehalten (nicht erneut generiert).
• Erinnerungen: eine Popup- und/oder E-Mail-Erinnerung, in Minuten vor Beginn.
• Kunde als Teilnehmer hinzufügen (optional) auf Basis der Kundendaten.

Einschränkungen

• Nur delegiert (ein OAuth-Benutzer). Kein Service-Account / Domain-wide Delegation; Ressourcen verbinden Sie über das Objekt→Kalender-Mapping.
• Die Verbindung arbeitet innerhalb des Zugriffs dieses einen Benutzers und innerhalb der Google Calendar API-Quota des Projekts.
• Das Inbound-Matching fällt bei fehlender externer ID auf einen [boeking_id]-Titel-Suffix zurück; ein wiederverwendeter Titel kann theoretisch die falsche Buchung treffen — das ires_field ist die zuverlässige Verbindung.