Bouw een Nextcloud-app op de Conduction-stack, Deel 3: Schema-gedreven integraties

Dit is Deel 3 van de zesdelige DeskDesk-tutorial. Deel 2 bedraadde de desk- en booking-schema's. Deel 3 zorgt dat die boekingen verschijnen in de Nextcloud Calendar van elke gebruiker, zonder dat je een controller, een event listener of per-app calendar-lijmcode schrijft.

De truc: OpenRegister levert al een ICalendarProvider (RegisterCalendarProvider) die elk schema met een calendarProvider-blok blootstelt als een virtuele kalender. Jij declareert het blok op het booking-schema. NC Calendar toont de events. Dat is het hele verhaal.

Waarom geen OpenConnector of een eigen listener?

Als je voor het eerst "synchroniseer DeskDesk-boekingen naar Nextcloud Calendar" hoort, is je instinct waarschijnlijk een van:

1. Schrijf een OpenConnector-flow die luistert naar BookingCreatedEvent en POSTet naar het CalDAV-endpoint
2. Maak een subclass van IEventListener<BookingCreatedEvent> in PHP en bouw een CalDAV-event met de hand
3. Laat de frontend POST /remote.php/dav/... als de gebruiker op Opslaan klikt

Alle drie werken. Alle drie zijn fout voor deze case, omdat ze NC Calendar behandelen als een bestemming waar je naartoe pusht. OpenRegister stelt elk schema al beschikbaar als kalender, je pusht nergens naartoe; je declareert dat het booking-schema een kalenderbron is.

Hetzelfde patroon geldt voor:

Anti-pattern: handgecodeerde <App>CalendarSync.vue, <App>NotesService, <App>MailSidebar.vue. Gebruik de providers.

Stap 1: Voeg het calendarProvider-blok toe

Open lib/Settings/deskdesk_register.json en voeg een configuration-blok toe aan het booking-schema:

"booking": {
  "slug": "booking",
  "title": "Booking",
  /* ... existing properties ... */

  "configuration": {
    "calendarProvider": {
      "enabled": true,
      "dtstart": "start",
      "dtend": "end",
      "titleTemplate": "Desk {desk} · {user}",
      "color": "#003a8c"
    }
  }
}

De vijf velden:

• enabled, true stelt het schema beschikbaar als virtuele kalender.
• dtstart, naam van de property die het event-start bevat. We gebruiken de start-property die al op elke booking staat.
• dtend, hetzelfde, maar voor het einde. Optioneel, bij ontbreken valt OpenRegister terug op een zinnige default (volgend uur voor date-time, einde-dag voor date-only).
• titleTemplate, string-template voor de event-summary. Tokens in {braces} worden opgelost tegen de properties van het object. We gebruiken Desk {desk} · {user}. Om relaties op te lossen (de desk-property is een uuid die wijst naar een desk-object), neem _extend=relations op als de calendar provider ophaalt, zie de OpenRegister-kant.
• color, hex-kleur van de kalender. We gebruiken cobalt-blauw (--c-blue-cobalt).

Dat is de hele wijziging. Geen ander bestand hoeft aangeraakt te worden.

Stap 2: Herimporteer de configuratie

Schema's in OpenRegister hebben een versie. De schema-versie ophogen + de import opnieuw draaien is de canonieke manier om ze in place bij te werken. Hoog de info.version van het bestand op (0.2.0 → 0.3.0) en de version van het booking-schema:

"info":  { "version": "0.3.0" },
"booking": { "version": "0.3.0", /* ... */ }

Trigger daarna de import op dezelfde manier als in Deel 2:

docker exec nextcloud php occ app:disable deskdesk
docker exec nextcloud php occ app:enable deskdesk

(Of doe een POST /api/settings/load als je admin-settings al bedraad hebt.)

Stap 3: Verifieer in NC Calendar

Open /apps/calendar/. Je zou een nieuwe entry in de kalenderlijst moeten zien:

• Booking, cobalt-blauwe kleur, alleen-lezen badge, in bezit van je gebruiker

Klik erop. De seed-boekingen uit Deel 2 (de maandag focus-werk-sessie, de dinsdag sprint-planning-meeting, de tentatieve rustige ochtend) verschijnen als events. Klik op één. De popover toont het bureau + gebruiker-titel + de start/eind-tijden.

Als je de kalender niet ziet:

• Bevestig dat OpenRegister zijn provider heeft geregistreerd: docker exec nextcloud php occ config:list | grep openregister
• Zorg dat je booking-schema configuration.calendarProvider.enabled: true heeft na de herimport
• Check nextcloud.log op RegisterCalendarProvider-meldingen

Hoe het werkt onder de motorkap

OpenRegister's RegisterCalendarProvider implementeert Nextcloud's ICalendarProvider-interface. Bij elke Calendar API-request:

1. Lijst elk schema op met configuration.calendarProvider.enabled === true
2. Voor elk, retourneer een RegisterCalendar (een lichte ICalendar-implementatie)
3. Als de gebruiker die kalender opent, query OpenRegister naar objecten waarvan dtstart in het gevraagde bereik valt
4. Transformeer elk object naar een iCalendar VEVENT via CalendarEventTransformer, met toepassing van de titleTemplate

Per-object ACL's bewaken event-inhoud. De provider omzeilt multi-tenancy bij het oplijsten van schema's (zodat cross-tenant-kalenders werken), maar elk individueel event blijft gegateerd door RBAC.

Hetzelfde patroon wordt gevolgd door de spec.

Wat je hiermee gekocht hebt

Activity (NC Activity) is al bedraad. Blader naar /apps/activity/ en je ziet je booking-creates / -updates. De dashboard-activity-widget + e-maildigest tonen beide DeskDesk-events. Nul code aan jouw kant.

Mail Smart Picker ook: plak in NC Mail een bureau-URL (/apps/deskdesk/desks/desk-3-east-12) en de picker resolvet hem naar een rich-preview-kaart met het bureau-label + zone + uitrusting.

Je hebt DeskDesk effectief geïntegreerd in vier Nextcloud-apps met één JSON-blok. Dat is de schema-gedreven discipline die zich uitbetaalt.

Troubleshooting

Wat volgt