AgendWrapper - ICS-Proxy fuer Nextcloud-Kalender

Dolibarr-Modul das als ICS-Proxy zwischen Nextcloud und Dolibarr fungiert. Loest das Problem, dass Dolibarrs eingebauter iCal-Parser die VTIMEZONE-Definitionen von Nextcloud nicht korrekt verarbeiten kann.

Was macht das Modul?

• Holt Kalender-Daten von Nextcloud via CalDAV (mit Basic Auth)
• Konvertiert alle Zeitzonen-spezifischen Zeiten (DTSTART/DTEND mit TZID) nach UTC
• Entfernt VTIMEZONE-Bloecke aus dem ICS
• Stellt sauberes ICS ueber einen Proxy-Endpunkt bereit
• Dolibarr kann diesen Endpunkt als externe Kalenderquelle einbinden

Voraussetzungen

• Dolibarr >= 19.0
• PHP >= 7.4 mit curl-Erweiterung
• Nextcloud-Instanz mit CalDAV-Zugang

Installation

1. Modul nach htdocs/custom/agendwrapper/ kopieren
2. In Dolibarr als Admin einloggen
3. Unter Admin > Module das Modul "AgendWrapper" aktivieren
4. Das Modul befindet sich in der Kategorie "Schnittstellen"

Konfiguration

1. Modul-Einstellungen

Unter Admin > Module > AgendWrapper > Einstellungen:

Feld	Beschreibung	Beispiel
CalDAV Basis-URL	Nextcloud CalDAV URL ohne Kalendername	https://cloud.example.de/remote.php/dav/calendars/user/
Benutzername	Nextcloud-Login	meinuser
Passwort	Nextcloud-Passwort (wird verschluesselt gespeichert)
Kalender 1	Pfad-Segment des ersten Kalenders	firmenkalender
Kalender 2	Pfad-Segment des zweiten Kalenders (optional)	privatkalender
Cache-Dauer	Wie lange gecachte Daten gelten (Standard: 300 Sekunden)	300
API-Key	Sicherheitsschluessel fuer den Proxy-Endpunkt	Button "Schluessel generieren"

2. Verbindung testen

Auf der Einstellungsseite den Button "Verbindung testen" klicken. Bei Erfolg wird die Anzahl der gefundenen Events angezeigt.

3. Proxy-URLs in Dolibarr eintragen

Die Einstellungsseite zeigt die fertigen Proxy-URLs an. Diese muessen in Dolibarr eingetragen werden:

1. Gehe zu Admin > Agenda > Externe Seiten
2. Trage die Proxy-URL als Kalender-URL ein:

   http://dein-dolibarr/custom/agendwrapper/proxy.php?cal=1&key=DEIN_API_KEY
   

3. Vergib einen Namen und eine Farbe
4. Speichern

4. Lokale URLs erlauben

Da der Proxy lokal laeuft, muss Dolibarr lokale URLs erlauben. Setze die Konstante:

• Admin > Konfiguration > Sonstiges: AGENDA_EXT_CALENDAR_IP_MODE = 2

Oder per SQL:

INSERT INTO llx_const (name, entity, value, type, visible, note)
VALUES ('AGENDA_EXT_CALENDAR_IP_MODE', 1, '2', 'chaine', 0, 'Lokale+externe URLs erlauben')
ON DUPLICATE KEY UPDATE value='2';

Funktionsweise

Nextcloud CalDAV (?export, Basic Auth)
  --> IcsProxy: Fetch + VTIMEZONE entfernen + Zeiten nach UTC
  --> Cache-Datei (konfigurierbare Dauer)
  --> proxy.php (API-Key-gesichert)
  --> Dolibarr ICal-Parser (sauberes UTC-ICS, keine Zeitzonen-Probleme)
  --> Kalenderansicht

Dateien

Datei	Beschreibung
proxy.php	HTTP-Endpunkt, liefert bereinigtes ICS
class/IcsProxy.class.php	Kernlogik: Fetch, Zeitzonen-Konvertierung, Cache
admin/setup.php	Einstellungsseite
agendwrapperindex.php	Statusseite (Cache-Info, Proxy-URLs)

Cron-Job (optional)

Das Modul registriert einen optionalen Cron-Job "AgendWrapper Cache aufwaermen", der den Cache regelmaessig aktualisiert. Standardmaessig deaktiviert. Aktivierung unter Admin > Geplante Aufgaben.

Hintergrund: Das VTIMEZONE-Problem

Nextcloud liefert ICS-Dateien mit komplexen VTIMEZONE-Definitionen (RRULE-basierte Sommerzeit/Winterzeit-Transitionen). Dolibarrs eingebauter iCal-Parser (ical.class.php) unterstuetzt nur ein vereinfachtes VTIMEZONE-Modell mit festen Offsets. Das fuehrt zu:

• Import-Fehlern beim Einlesen der Kalender
• PHP-Warnings ("Trying to access array offset on int")
• Falsch dargestellten Uhrzeiten

Der AgendWrapper loest das, indem er alle Zeiten ueber PHPs DateTime/DateTimeZone-Klassen korrekt nach UTC konvertiert und die VTIMEZONE-Bloecke komplett entfernt.

Lizenz

GPLv3 oder (nach Wahl) eine spaetere Version. Siehe COPYING.

Autor

Eduard Wisch - Alles Watt laeuft