motia/bitbylaw/steps/advoware_cal_sync/README.md

Advoware Calendar Sync

Dieser Abschnitt implementiert die bidirektionale Synchronisation zwischen Advoware-Terminen und Google Calendar. Für jeden Mitarbeiter in Advoware wird automatisch ein entsprechender Google Calendar erstellt und gepflegt.

Übersicht

Das System synchronisiert Termine zwischen:

• Advoware: Zentrale Terminverwaltung mit detaillierten Informationen
• Google Calendar: Benutzerfreundliche Kalenderansicht für jeden Mitarbeiter

Funktionalität

Automatische Kalender-Erstellung

• Für jeden Advoware-Mitarbeiter wird ein Google Calendar mit dem Namen AW-{Kuerzel} erstellt
• Beispiel: Mitarbeiter mit Kürzel "SB" → Calendar "AW-SB"

Bidirektionale Synchronisation

Advoware → Google Calendar

• Alle Termine eines Mitarbeiters werden aus Advoware abgerufen
• Neue Termine werden in den entsprechenden Google Calendar eingetragen
• Die Advoware-Termin-ID (frNr) wird als Metadaten gespeichert

Google Calendar → Advoware

• Termine aus Google Calendar ohne frNr werden als neue Termine in Advoware erstellt
• Die generierte frNr wird zurück in den Google Calendar geschrieben

Konfigurationsoptionen

• Vollständige Termindetails: Titel, Beschreibung, Ort werden synchronisiert
• Nur "Blocked": Termine werden nur als "beschäftigt" markiert (keine Details)

API-Endpunkte

Advoware

• GET /api/v1/advonet/Mitarbeiter - Liste aller Mitarbeiter
• GET /api/v1/advonet/Termine?kuerzel={kuerzel}&from={date}&to={date} - Termine eines Mitarbeiters

Google Calendar API

• Kalender-Management (erstellen, auflisten)
• Event-Management (erstellen, aktualisieren, löschen)

Step-Konfiguration

advoware_calendar_sync_step.py

• Type: api
• Path: /advoware/calendar/sync
• Method: POST
• Flows: advoware

Request Body:

{
  "full_content": true  // oder false für nur "blocked"
}

Setup

Google API Credentials

1. Google Cloud Console Projekt erstellen
2. Google Calendar API aktivieren
3. OAuth 2.0 Credentials erstellen
4. token.pickle Datei im Projektverzeichnis bereitstellen

Umgebungsvariablen

GOOGLE_CALENDAR_CREDENTIALS_PATH=token.pickle

Verwendung

Manueller Sync

curl -X POST "http://localhost:3000/advoware/calendar/sync" \
  -H "Content-Type: application/json" \
  -d '{"full_content": true}'

Automatischer Sync

Der Step kann über Cron-Jobs oder Events regelmäßig ausgeführt werden.

Datenmapping

Advoware → Google Calendar

{
  "summary": appointment.text || "Advoware Termin",
  "description": `Advoware Termin\nNotiz: ${appointment.notiz}\nOrt: ${appointment.ort}`,
  "location": appointment.ort,
  "start": {
    "dateTime": `${appointment.datum}T${appointment.uhrzeitBis || '00:00:00'}`,
    "timeZone": "Europe/Berlin"
  },
  "end": {
    "dateTime": `${appointment.datumBis || appointment.datum}T${appointment.uhrzeitBis || '23:59:59'}`,
    "timeZone": "Europe/Berlin"
  },
  "extendedProperties": {
    "private": {
      "advoware_frnr": appointment.frNr
    }
  }
}

Google Calendar → Advoware

{
  "text": event.summary,
  "notiz": event.description,
  "ort": event.location,
  "datum": event.start.dateTime.substring(0, 10),
  "uhrzeitBis": event.start.dateTime.substring(11, 19),
  "datumBis": event.end.dateTime.substring(0, 10),
  "sb": employee_kuerzel,
  "anwalt": employee_kuerzel
}

Fehlerbehandlung

• Google API Fehler: Automatische Token-Refresh, Fallback bei Authentifizierungsfehlern
• Advoware API Fehler: Retry-Logic, detaillierte Logging
• Netzwerkfehler: Timeout-Handling, Wiederholungsversuche
• Dateninkonsistenzen: Validierung vor Sync, Konfliktlösung

Monitoring

Logs

• Erfolgreiche Synchronisationen
• Fehlerhafte Termine
• Kalender-Erstellungen
• Performance-Metriken

Metriken

• Anzahl synchronisierter Termine
• Verarbeitete Mitarbeiter
• Fehlerquoten
• Sync-Dauer

Sicherheit

• OAuth 2.0 für Google API Zugriff
• Token-Speicherung in verschlüsselten Dateien
• Scoped API Permissions (nur Calendar-Zugriff)
• Audit-Logs für alle Änderungen

Erweiterungen

Geplante Features

• Inkrementelle Syncs (nur geänderte Termine)
• Konfliktlösungsstrategien (Advoware gewinnt, Google gewinnt, Manuell)
• Batch-Verarbeitung für Performance
• Webhook-Integration für Echtzeit-Syncs
• Mehrere Google-Accounts unterstützen

Integration mit anderen Systemen

• Outlook Calendar
• Apple Calendar
• Mobile Apps
• Notification-Systeme