83a154a4a5
- steps/advoware_cal_sync/advoware_calendar_sync_step.py: Bidirektionale Sync zwischen Advoware und Google Calendar
- Automatische Kalender-Erstellung für jeden Mitarbeiter (AW-{Kuerzel})
- Konfigurierbare Sync-Optionen (volle Details vs. nur 'blocked')
- Google Calendar API Integration mit OAuth
- Mitarbeiter- und Termin-API Integration
- Umfassende Fehlerbehandlung und Logging
- steps/advoware_cal_sync/README.md: Detaillierte Dokumentation
- requirements.txt: Google API Dependencies hinzugefügt
- motia-workbench.json: Neuer advoware_cal_sync Flow
161 lines
4.4 KiB
Markdown
161 lines
4.4 KiB
Markdown
# 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:**
|
|
```json
|
|
{
|
|
"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
|
|
```env
|
|
GOOGLE_CALENDAR_CREDENTIALS_PATH=token.pickle
|
|
```
|
|
|
|
## Verwendung
|
|
|
|
### Manueller Sync
|
|
```bash
|
|
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
|
|
```javascript
|
|
{
|
|
"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
|
|
```javascript
|
|
{
|
|
"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 |