Merge branch 'docupdate-integratie' into fix/configuration-docs

README.md

@@ -1,11 +1,13 @@
 # Over de WOO en Open Woo App
 
-> **WooBinar**
->
-> Meer weten over deze oplossing? Dat kan! Vanuit de aangesloten leveranciers worden regelmatig webinars georganiseerd.
+> **Ondersteuning en bijeenkomsten**
 >
+> Meer weten over deze oplossing? Dat kan! Hiervoor hebben we een appart [slack kanaal](https://samenorganiseren.slack.com/archives/C067Q3UE9F0) binnen commonground. We helpen je daar graag verder
+> 
+> Tevens worden vanuit de aangesloten leveranciers worden regelmatig webinars georganiseerd.
+> 
 > Terug kijken afgelopen webinars?
-> [xxllnc Woobinar 17-11-2023](https://www.youtube.com/watch?v=NCnLDEoPh5A)
+> - [xxllnc Woobinar 17-11-2023](https://www.youtube.com/watch?v=NCnLDEoPh5A)
 
 De Wet Open Overheid (WOO) is een initiatief gericht op het verbeteren van de openbaarheid van overheidsinformatie. Het doel is om overheidsinformatie beter toegankelijk te maken voor iedereen. Meer informatie over de Wet Open Overheid kan [hier](https://www.open-overheid.nl/themas/wet-open-overheid/) worden gevonden.
 
@@ -17,7 +19,7 @@ De implementatie van de Wet Open Overheid brengt twee kernuitdagingen met zich m
 2. **Proactieve Publicatie:**
    Overheden moeten informatie proactief te publiceren. Dit betekent dat publicatie onderdeel moet worden van het normale werkproces. Hiermee is het richting de toekomst niet haalbaar om Woo-publicaties handmatig via een apart systeem (bijvoorbeeld CMS website) te laten verlopen.
 
-Deze uitdagingen kunnen niet effectief worden aangepakt met een enkel Content Management Systeem (CMS) of door levering vanuit één systeem. Handmatige publicatie van alle overheidsinformatie zou een aanzienlijke personele inzet vereisen, wat onpraktisch is. Daarbij komt dat de verscheidenheid aan publicatietypen vaak verdeeld is over meerdere systemen, wat de situatie verder compliceert.
+Deze uitdagingen kunnen niet effectief worden aangepakt met een enkel Content Management Systeem (CMS) of door levering vanuit één systeem. Handmatige publicatie van alle overheidsinformatie zou een aanzienlijke personele inzet vereisen, wat onpraktisch is. Daarbij komt het voor dat verscheidende categorieën vaak verdeeld zijn over meerdere systemen, wat de situatie verder compliceert.
 
 ## Oplossing
 
@@ -30,7 +32,7 @@ De Open Woo-app biedt een geïntegreerde oplossing die bestaat uit een aantal ho
    Een interface waarmee belanghebbenden binnen een organisatie naar relevante informatie kunnen zoeken.
 
 3. **Koppelvlak:**
-   Een module die in staat is om informatie uit verschillende systemen te verzamelen, waardoor een gecentraliseerde toegang tot diverse publicatietypen mogelijk wordt.
+   Een module die in staat is om informatie uit verschillende systemen te verzamelen, waardoor een gecentraliseerde toegang tot diverse categorieën mogelijk wordt.
 
 4. **CMS-module:**
    Een aanvullende module voor het handmatig invoeren van informatie die niet automatisch kan worden opgehaald, en voor het beheren van de gepubliceerde pagina's.
@@ -73,8 +75,8 @@ De Woo specificeert een aantal categorieën (zie configuratie) die door een orga
 ## Praktijk voorbeelden
 Op dit moment wordt de OpenWoo.app al door een aantal organisaties gebruikt
 
-| Organisatie | Type | Woo Pagina | Woo Bron(en) | Zaaksysteem | Status |
-|-------------|------|------------|--------------|-------------|--------|
+| Organisatie | Type | Woo Pagina | Woo Bron | Status |
+|-------------|------|------------|--------------|--------|
 | [Noordwijk](https://www.noordwijk.nl/) | Gemeente |  [Pagina](https://conductionnl.github.io/woo-website-noordwijk/) | Zaaksysteem.nl  | Acceptatie | 
 | [Tubbergen](https://www.tubbergen.nl/) | Gemeente |[Pagina](https://conductionnl.github.io/woo-website-tubbergen/) | Zaaksysteem.nl  | Acceptatie | 
 | [Epe](https://www.epe.nl/) | Gemeente |[Pagina](https://open.epe.nl/) | Zaaksysteem | Productie  |

docs/Architectuur.md

@@ -1,75 +1,109 @@
 # Architectuur
 
-## Woo Publicatie Object
-
-Het Woo Publicatie Object vormt de kern van zowel de Woo API als de Woo-website. Dit object bevat alle essentiële informatie over een Woo-publicatie, inclusief metadata, publicatiedatum, bijlagen en andere relevante eigenschappen. Het dient als de centrale entiteit waaromheen de functionaliteiten van de API en de website zijn gebouwd. Door deze gecentraliseerde aanpak is het eenvoudiger om Woo-publicaties efficiënt te beheren, op te halen en weer te geven, en draagt het bij aan een coherente en gestroomlijnde gebruikerservaring.
+## Opzet
 
-Toegepaste norm: [NL API Strategie over property namen](https://docs.geostandaarden.nl/api/cv-hr-API-Strategie-20190213/#veldnamen-in-snake_case-camelcase-uppercamelcase-of-kebab-case)
+OpenWoo.app bestaat in essentie uit een aantal componenten die samenwerken rondom een integratievoorziening, het lijnt daarmee uit met de architectuurlagen van Common Ground. Daarbij is de keuze aan de ontsluitende overheid welke componenten van welke leveranciers zij inzet. Het is daarmee bewust de bedoeling dat de inrichting per overheid kan verschillen, zodat deze beter in het landschap van die betreffende overheid past. Binnen de OpenWoo.app kennen we momenteel de volgende componenten:
 
-## Varianten
+> **Hulp nodig?**
+>
+> Hiervoor hebben we een appart [slack kanaal](https://samenorganiseren.slack.com/archives/C067Q3UE9F0) binnen commonground. We helpen je daar graag verder.
 
-### Open Webconcept variant
+### Open Webconcept-variant zonder integratie
 
-Met deze variant kunnen Woo-verzoeken en convenanten eenvoudig worden beheerd vanuit de bestaande webomgeving en CMS door middel van een directe koppeling met de gateway. Dit vereist geen extra installatie of beheerinspanningen van de organisatie, op voorwaarde dat er al een OpenWebconcept-installatie met de benodigde plugins beschikbaar is. Dit biedt een serverloze en kostenefficiënte oplossing door het hergebruik van bestaande Common Ground-componenten.
+Met deze variant kunnen Woo-verzoeken en convenanten eenvoudig worden beheerd vanuit de bestaande webomgeving en CMS . Dit vereist geen extra installatie of beheerinspanningen van de organisatie, op voorwaarde dat er al een OpenWebconcept-installatie met de benodigde plugins beschikbaar is.
 
 **Nadelen:**
 
 - Woo-verzoeken en convenanten moeten handmatig worden geüpload in de CMS-omgeving.
-- De zoekbalk wordt niet ondersteund.
+- De integrale zoekvraag wordt alleen ondersteund op de in WordPress aanwezige gegevens.
 
-![OpenWeb Architecture](https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/openweb.svg)
+![OpenWeb Architecture](https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/OpenWebconceptZonder.svg)
 
-### Common Gateway variant
+### Open Webconcept met integratie
 
-Deze variant maakt het mogelijk om de front-end te koppelen aan een Common Gateway-installatie met de Open Woo-plugin. Dit biedt de mogelijkheid om direct te koppelen aan het zaaksysteem, waardoor Woo-verzoeken en convenanten automatisch kunnen worden gepubliceerd. Dit bespaart handmatig werk en vermindert de kans op fouten. De zoekbalk wordt in deze variant wel ondersteund. Het is tevens mogelijk om gegevens uit andere bronnen te integreren, zoals een raadsinformatiesysteem of een Open Webconcept CMS.
+Het is ook mogelijk om een bestaande Open Webconcept-omgeving te combineren met de integratievoorziening. In dat geval gebruikt de integratievoorziening Open Webconcept, zowel als bron als dat het naar Open Webconcept toe publiceert. Dit betekent dat de organisatie de voordelen van de integratievoorziening kan benutten, terwijl de bestaande Open Webconcept-omgeving kan worden gebruikt om Woo-verzoeken en convenanten te beheren.
 
-**Nadelen:**
+**Nadelen**
 
-- De organisatie moet de Common Gateway zelf installeren of als SaaS afnemen.
+- Er moet een integratievoorziening worden geïnstalleerd of afgenomen
 
-![Commongateway Architecture](https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/commongateway.svg)
+![OpenWeb Architecture](https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/OpenWebconceptMet.svg)
 
-### Ophalen informatie
+### (Losse) Frontend met integratie
 
-De Open Woo-plugin "scraped" elke nacht alle relevante zaken. De stappen zijn als volgt:
+Er zijn diverse frontends die in theorie direct kunnen koppelen op de OpenWoo.app API.
 
-1. Ophalen van alle zaaktypen.
-2. Per zaaktype worden de beschikbare eigenschappen gecontroleerd (zie inrichting zaaksysteem).
-3. Voor elk zaaktype dat aan de voorwaarden voldoet, worden de zaken opgehaald.
-4. Per zaak wordt gecontroleerd of er een publicatiedatum is; zo ja, wordt de zaak opgenomen in de index.
-5. Zaken die niet zijn gevonden in bovenstaande loop maar wel in de index staan, worden verwijderd.
+**Voordelen**
+
+- De frontend hoeft maar één API te koppelen voor toegang tot meerdere bronnen.
+- De gebruiker kan een integrale zoekvraag over meerdere bronnen heen stellen (bijvoorbeeld aan zowel een zaaksysteem als een raadsinformatiesysteem).
+- Als de frontend zelf een CMS is, kan deze ook als bron dienen (voor bijvoorbeeld nieuwsberichten en categorieomschrijvingen)
+- Componenten zijn te combineren (bijvoorbeeld de losstaande NL Design React voorkant op de Open Webconcept-verzoeken en -convenanten plugins).
+
+**Nadelen**
 
-Dit proces zorgt ervoor dat het zaaksysteem leidend is en dat zaken zowel kunnen worden gepubliceerd als gedepubliceerd.
+- Er moet een integratievoorziening worden geïnstalleerd of afgenomen
 
-## Federatie via OpenCatalogi
+**Beschikbare componenten voor frontend**
+| Component | Framework | Open Source | Leveranciers | Beschrijving |
+|-------------|------|------|------------|--------------|
+| OpenWOO Site  | NL Design (React) | Ja | [Conduction](https://conduction.nl/) | Een losse NL Design zoekpagina in de huisstijl van uw organisatie |
+| OpenWoo Plugin | Wordpress | Ja | [Yard](https://www.yard.nl/), [Acato](https://acato.nl/) | Een NL Design weergave component voor wWordPress-websites |
+| Open Gemeente | Typo-3 | Ja | [Open Gemeente](https://www.opengemeenten.nl/) | Een weergave component voor Typo3-websites |
+| SIM Drupal | Drupal | ? | [Sim Groep](https://www.simgroep.nl/) | Een weergave component voor Drupal |
 
-OpenWoo.app maakt gebruik van het federatieve stelstel van OpenCatalogi om de verschillende varianten te kunnen ontsluiten. Dit betekent dat organisaties zelf kunnen bepalen welke variant ze willen gebruiken en dat ze niet afhankelijk zijn van een centrale partij.
+> **notice**
+> Voor Open Source componenten bent u natuurlijk niet beperkt tot deze leveranciers, dit zijn de op dit moment bij ons bekende leveranciers.
+>
+> Weet u niet welk frontend framework uw organisatie op dit moment gebruikt? Kijk dan eens op [digimonitor](https://www.digimonitor.nl/cms-en/gemeenten/).
+>
+![OpenWeb Architecture](https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/LosseFrontend.svg)
 
-## Landelijke API
+### Bronnen met integratie
 
-Iedereen kan de landelijke API bevragen om alle Woo-verzoeken en convenanten op te halen. De API is gebaseerd op de [NL API Strategie](https://docs.geostandaarden.nl/api/cv-hr-API-Strategie-20190213/).
+Als er wordt gekozen voor het implementeren van het integratievoorziening, wordt het mogelijk om geautomatiseerd te publiceren vanuit meerdere bronnen.
 
-(wordt nog aangevuld)
+Dit bespaart handmatig werk en vermindert de kans op fouten. Tevens ondersteunt het gebruik van het integratiemechanisme de integrale zoekvraag en is het mogelijk om ook gegevens uit andere bronnen te integreren, zoals een raadsinformatiesysteem of een Open Webconcept CMS.
 
-## Componenten
+**Nadelen**
 
-Een variant bestaat uit een aantal componenten die samen de functionaliteit van de variant vormen. Deze componenten zijn:
+- Er moet een integratievoorziening worden geïnstalleerd of afgenomen
 
-- [Woo API]()
-- [Woo Website]()
-- [Woo Plugin]()
-- [Woogle](https://woogle.wooverheid.nl/search?q=*)
-- [Raadsinformatie Systeem]()
-- [KOOP-index]()
-- [Common Gateway]()
-- [Open Webconcept CMS]()
-- [Zaaksysteem]()
+**Beschikbare componenten voor bronnen**
+| Component | Framework | Open Source | Leveranciers | Beschrijving |
+|-------------|------|------|------------|--------------|
+|Zaaksysteem.nl | ZGW | Ja | [Xxllnc](https://xxllnc.nl/) |--------------|
+|RX Fundament | ZGW | Nee | [Roxit](https://www.roxit.nl/) |--------------|
+|Decos Join | ZGW | Nee | [Decos](https://www.decos.com/nl) |--------------|
+|Open Zaak | ZGW | Ja | [Maykin media](https://www.maykinmedia.nl/nl/) |--------------|
 
-Alle componenten worden getest met [zaaksysteem.nl](https://xxllnc.nl/zaakgericht/), Rx.Fundament en Decos JOIN
+![OpenWeb Architecture](https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/Bronnen.svg)
 
-## Verschil OpenWoo.app en de OpenWoo plugin
+### Hoe werkt dat scrapen vanuit de integratievoorziening?
 
-De OpenWoo.app is een verzameling van componenten die samen een oplossing vormen voor het publiceren van Woo-verzoeken en convenanten. De OpenWoo plugin is een onderdeel van deze oplossing en kan worden gebruikt om Woo-verzoeken en convenanten te publiceren vanuit een Open Webconcept CMS. De OpenWoo plugin is een onderdeel van deze oplossing en kan worden gebruikt om Woo-verzoeken en convenanten te publiceren vanuit een Open Webconcept CMS.
+De integratievoorziening "scraped" elke nacht alle relevante informatie en bouwt hier een organisatie-specifieke index over op. De stappen zijn als volgt:
+
+1. Ophalen van alle zaaktypen.
+2. Per zaaktype worden de beschikbare eigenschappen gecontroleerd (zie inrichting zaaksysteem).
+3. Voor elk zaaktype dat aan de voorwaarden voldoet, worden de zaken opgehaald.
+4. Per zaak wordt gecontroleerd of er een publicatiedatum is; zo ja, wordt de zaak opgenomen in de index.
+5. Zaken die niet zijn gevonden in bovenstaande loop, maar wel in de index staan, worden verwijderd.
+
+Dit proces zorgt ervoor dat het zaaksysteem leidend is en dat zaken zowel kunnen worden gepubliceerd als worden gedepubliceerd.
+
+## Federatie (via OpenCatalogi)
+
+OpenWoo.app maakt gebruik van het federatieve stelsel van [OpenCatalogi](https://opencatalogi.nl/) om verschillende integratievoorzieningen samen te binden. Hierbij verhoudt de organisatiespecifieke voorziening zich tot wat we binnen OpenCatalogi een catalogus noemen.
+
+Dat betekent dat de integrale zoekvraag ook organisatie-overstijgend kan worden gesteld aan meerdere organisatie tegelijkertijd zonder dat er noodzaak is voor een landelijke index, dit concept is verder uitgewerkt in [koophulpje.nl](https://koophulpje.nl/) waarbij ook een voorziening is gerealiseerd voor het genereren van `robot.txt` en `sitemap.xml` bestanden.  De facto is hiermee dus ook een landelijke Woo-API gerealiseerd met de beperking dat deze alleen organisaties bevat die participeren in OpenWoo.app
+
+De reden dat we hebben gekozen voor OpenCatalogi is dat in deze `variant` van FSC géén PKI of overige certificaten nodig zijn. Dat lijnt beter uit met de gedachte dat dit open data betreft die conform de wet juist anoniem toegankelijk zou moeten zijn.
+
+![OpenWeb Architecture](https://raw.githubusercontent.com/ConductionNL/woo-website-template/main/docs/Federatie.svg)
+
+## Woo Publicatie Object
+
+Het Woo Publicatie Object vormt de kern van zowel de Woo API als de Woo-website. Dit object bevat alle essentiële informatie over een Woo-publicatie, inclusief metadata, publicatiedatum, bijlagen en andere relevante eigenschappen. Het dient als de centrale entiteit waaromheen de functionaliteiten van de API en de website zijn gebouwd. Door deze gecentraliseerde aanpak is het eenvoudiger om Woo-publicaties efficiënt te beheren, op te halen en weer te geven, en draagt het bij aan een coherente en gestroomlijnde gebruikerservaring.
 
 ## Roadmap
 

docs/Bronnen.puml

@@ -0,0 +1,29 @@
+@startuml
+title Integratie op bronnen
+
+' User Interface Component
+interface "Een of meerdere afnemers" as Afnemer
+
+' Backend Components
+component "Integratie" as Integratie
+component "Zaaksysteem" as Zaaksysteem
+component "CMS" as CMS
+component "Raads informatie systeem" as Raadsinfo
+component "eDepot" as eDepot
+component "DMS" as DMS
+component "VTH" as VTH
+
+' Relationships
+Afnemer -down-> Integratie : Directly connected
+Integratie -down-> CMS : Scrapes periodically\nUses as source
+Integratie -down-> Zaaksysteem : Scrapes periodically\nUses as source
+Integratie -down-> Raadsinfo : Scrapes periodically\nUses as source
+Integratie -down-> eDepot : Scrapes periodically\nUses as source
+Integratie -down-> DMS : Scrapes periodically\nUses as source
+Integratie -down-> VTH : Scrapes periodically\nUses as source
+
+' Notifications
+CMS -up-> Integratie : Notifies of changes or deletes
+Zaaksysteem -up-> Integratie : Notifies of changes or deletes
+
+@enduml