# Welkom bij NL Portal Vind snel je weg in de NL portal informatiepagina. Of je nu op zoek bent naar een architectuur overzicht of welke support er beschikbaar is, je vindt het allemaal hier. | ![Getting started](/files/CfRjyKaEKPbqkiipvAOb) | ![Support](/files/mSeZC6xfeGPAVDWFtNfZ) | ![Architectuur](/files/ylOt3kgcamAKe54CNrqm) | | ------------------------------------------------ | --------------------------------------- | -------------------------------------------- | | **Getting started** | **Support** | **Architectuur** | | Bekijk hoe je zo snel mogelijk aan de slag bent. | Stel al je vragen. | Hoe is NL Portal opgebouwd? | # Wat is NL Portal ### **Wat is het?** NL Portal is een open source Mijn Omgeving voor gemeentelijke- én andere overheden. Inwoners en bedrijven kunnen hierop een veilige manier inloggen om informatie te vinden die voor hun relevant is. Zo kan je • Je persoonlijke gegevens en adresgegevens raadplegen;\ • Producten en diensten inzien die je bij de gemeente afneemt, Op één centrale plek, waar je 24/7 terecht kunt. In deze wat verouderde video van de lancering wordt de achtergrond uitgelegd. {% embed url="" %} ### **Productvisie** Het heeft drie doelen, voor drie doelgroepen: 1. Gemak voor burgers en ondernemers. 2. Efficiëntie in de uitvoering voor overheden. 3. Voldoen aan wet- en regelgeving voor beleidsmakers. **Gemak voor burgers en ondernemers** We zijn gewend geraakt aan het gemak van online diensten. Een bestelling die vandaag wordt geplaatst en morgen of zelfs vandaag al wordt geleverd, is nu de norm. Burgers en ondernemers verwachten dezelfde efficiëntie van de overheid. NL Portal helpt hierbij door eenvoudig online aanvragen te kunnen indienen, inzicht te hebben in de afhandeling, toegang hebben tot producten en diensten online en snelle levering te ervaren. Kijk naar de **Efficientie in de uitvoering voor overheden** Overheden hebben een enorme informatiestroom te verwerken. Dat moet sneller, met minder fouten en met minder mensen. Door automatisering kan een deel van de informatiestroom geautomatiseerd verwerkt worden, waardoor tijd vrij wordt gespeeld voor burgers en ondernemers die persoonlijke aandacht verdienen. NL Portal zorgt voor gestandaardiseerde digitale communicatie met burgers en ondernemers. De verwerking van data wordt daardoor vereenvoudigd. Kwaliteit in = kwaliteit uit. NL Portal volgt de standaarden vanuit het Common Ground project 'Samenwerkende Portalen' - elk backoffice systeem dat deze standaarden volgt kan communiceren via NL Portal. **Voldoen aan wet- en regelgeving voor beleidsmakers** De wet- en regelgeving stelt hogere eisen aan digitale diensten van overheidsinstellingen. Toegankelijkheid, beveiliging, omgang met persoonsgegevens, auditing, taalgebruik, data-integriteit, beschikbaarheid en snelheid. BIO, ISO, AVG, WCAG, DigiD Assessment. NL Portal heeft tot doel 'uit de doos' technisch voldoen aan eisen. NL Portal heeft de volgende uitgangspunten: * Open standaarden, open source licentie EUPL 1.2; * Compatible met diverse formulierapplicaties; * Frontend UI gebaseerd op [NL Design System](https://nldesignsystem.nl/); * Voldoet aan alle web toegankelijkheidsrichtlijnen (WCAG); * Onafhankelijk van proces- of zaak management systemen; * Horizontal schaalbaar. ### **Functionaliteiten** Op dit moment kent NL Portal de volgende functionaliteiten * Koppeling met DigiD en eHerkenning * DigiD en eHerkenning zijn vertrouwde systeem voor gebruikers, verhoogt de beveiliging door betrouwbare identiteitsverificatie, en biedt gemak doordat veel mensen al een DigiD hebben. * Bezoekers kunnen nieuwe zaken aanmaken; * Inwoners en bedrijven kunnen via dit proces de start van een nieuwe zaak initiëren; * Bezoekers kunnen altijd de actuele status van hun zaken zien; * Track & trace-service waar inwoners en medewerkers aanvragen kunnen volgen. Deze service is vooral gericht op het bieden van inzicht in gegevens en minder op interactie. ![track-and-trace](/files/PHgUVuovVj0R4uEzXNIg) * Bezoekers kunnen Taken krijgen in NL Portal * Hiermee kunnen inwoners direct zelf zaken regelen bij de gemeente. Deze service laat acties zien die nog door een inwoner of een medewerker moeten worden uitgevoerd. Inwoners kunnen hier bijvoorbeeld extra gegevens aanleveren voor een lopende zaak en in de toekomst kunnen ze een betaling doen in NL Portal. * Bezoekers kunnen bestanden downloaden * Bezoekers kunnen de documenten die gekoppeld zijn aan hun zaak downloaden. Dit kunnen bijvoorbeeld de besluitdocumenten zijn. * Bezoekers hebben een profielpagina * Binnen NL Portal is onder andere een profielpagina component. Deze profielpagina kan koppelen met HaalCentraal en zo de informatie uit de basisadministratie tonen. ![profiel](/files/k3Wr1zqp4ytC6KknPAxy) # Architectuur ### Scope NL Portal is een Nederlands, open source "Mijn Omgeving"-platform, primair bedoeld voor\ gebruik door overheden. Het faciliteert de interactie met klanten en ketenpartners. Klanten\ in deze context zijn personen of organisaties die een verzoek indienen. Ketenpartners zijn\ organisaties die bijdragen aan de afhandeling van het verzoek. NL Portal verzorgt zelf geen zaakafhandeling, is geen formulierencomponent en fungeert niet\ als website of content management systeem. Het werkt echter wel samen met deze componenten\ voor interactie. ### Common Ground & Platform Generieke Dienstverlening NL Portal is ontwikkeld op basis van de [Common Ground](https://commonground.nl/) -principes, een initiatief\ van de Nederlandse gemeentes. De informatiearchitectuurprincipes zijn als volgt: * **Component-gebaseerd**: NL Portal is een onafhankelijk functionerend component.\ Het fungeert als "Mijn Omgeving" voor burgers en ondernemers, en communiceert met andere\ componenten via gestandaardiseerde interfaces. * **Open**: NL Portal is open source en wordt in een open ontwikkeld. * **Vertrouwd**: Informatiebeveiliging staat centraal in de ontwikkeling. * **Eenmalige vastlegging**: Data-opslag in NL Portal is geminimaliseerd; data wordt\ opgehaald bij de bron, primair de Common Ground-datalaag en secundair andere gegevensbronnen. * **Regie op gegevens**: Burgers kunnen gegevens inzien, waar mogelijk aanpassen, verzoeken\ indienen, taken uitvoeren en berichten ontvangen. Dit is de essentie van NL Portal:\ inzicht in gegevens en eenvoudige communicatie met de overheid. * **Standaarden**: Er wordt primair gebruik gemaakt van open standaarden. ### Platform Generieke Dienstverlening NL Portal wordt ingezet als onderdeel van het Platform Generieke Dienstverlening, een Common Ground-initiatief dat invulling geeft aan de gedachte van Common Ground. Dit platform bestaat uit een referentiearchitectuur en referentiecomponenten, die samen een dienstverleningsplatform vormen. Het omvat onder andere componenten voor het bouwen van formulieren, zaakafhandeling, logging, archivering en een portaal. Twee belangrijke uitgangspunten binnen deze architectuur zijn: * **Componenten in plaats van monolieten**: Hierdoor kunnen in de toekomst componenten\ worden vervangen zonder het gehele platform te vervangen. * **Data gescheiden van business logica**: Dit betekent dat data niet in componenten zit,\ maar in een gestandaardiseerd formaat op een gescheiden locatie wordt opgeslagen, wat het eenvoudiger maakt om componenten te vervangen. Deze architectuur is niet specifiek voor de Nederlandse gemeentes, maar is gebaseerd op\ universele architectuurprincipes, waarbij de microservices-architectuur een basis vormt. # 5-lagenmodel Het 5-lagenmodel van Common Ground is een architectuuraanpak ontwikkeld door de Nederlandse gemeenten om de gemeentelijke IT-architectuur te moderniseren en efficiënter te maken. Twee belangrijke aspecten zijn: 1. Het scheiden van data en applicaties. Door data in een gestandaardiseerd formaat op te slaan in een datalaag, wordt voorkomen dat dat in applicaties zit, waardoor de *lockin* op applicaties wordt verminderd én data-duplicering wordt voorkomen. 2. Het gebruik van componenten in plaats van monolitische silo-applicaties, waardoor componenten vervangbaar zijn en er minder afhankelijkheid ontstaat van één leverancier van een totaaloplossing. NL Portal is een component binnen dit model. Hieronder weergegeven in laag 5, de 'interactielaag'. ![5-lagen-model](/files/Xma7mMt9796fJq8PWCQY)*5 lagen model Common Ground* ### Scope NL Portal NL Portal heeft als doel de communicatie met klanten (belanghebbenden) en ketenpartners te verzorgen. NL Portal voorziet in: * Berichten * Taken * Inzicht in Zaakdossiers * Inzicht in Mijn Gegevens (BRP) * Track & trace van Zaken * Inzicht domein-specifieke gegevens (in ontwikkeling) ### Buiten scope * Informatieverstrekking. (CMS) * Authenticatie. (bijv. SIAM of Keycloak) * Notificaties (email, sms, whatsapp). (bijv. NL Notify) * Zaakafhandeling (bijv. GZAC) # Integraties ### Integratie-componenten Integraties kunnen worden toegevoegd. De volgende integraties worden meegeleverd: 1. [**OpenZaak**](https://openzaak.org/). Ingelogde gebruikers hebben inzage in hun Zaken zoals vastgelegd in OpenZaak. 2. [**Documenten API**](https://vng-realisatie.github.io/gemma-zaken/standaard/documenten/index). Documenten worden geupload en gedownload via de Documenten API specificatie. Deze wordt ondersteund door OpenZaak en DMS-en. 3. [**HaalCentraal Basisregistratie Persoonsgegevens**](https://haalcentraal.pleio.nl/). Na inlog met DigiD worden BRP gegevens opgehaald. 4. **HaalCentraal Handelregister**. Na inlog met eHerkenning worden KVK gegevens opgehaald. 5. [**Objects API**](https://vng.nl/projecten/overige-objecten-registratie-api). Voor informatie-arm notificeren van Verzoeken, Taken en Berichten. 6. [**Keycloak**](https://www.keycloak.org/). Voor authenticatie, eventueel gekoppeld aan SIAM / TMA / DigiD / eHerkenning. 7. [**OpenKlant 1.0**](https://vng-realisatie.github.io/gemma-zaken/standaard/klantinteracties/index). Voor de opslag van klantgegevens binnen een organisatiedomein. # Zaak Mijn lopende zaken worden getoond voor klanten. De informatie wordt uit de bron OpenZaak gehaald. Voor natuurlijk personen gebeurt dit op basis van het BSN, voor organisaties op basis van het KVK-nummer. De architectuur gaat uit van het gebruik van 1 installatie van OpenZaak binnen de organisatie. Alle interne zaak- en taakapplicaties registreren de zaak-meta gegevens in OpenZaak, waarmee deze inzichtelijk worden voor de klant. Van een Zaak wordt de meta-informatie getoond, zoals aanvraagdatum, zaakstatus en behandelaar. Verder gekoppelde informatie, waaronder documenten. ![zaak-meta-informatie](/files/xLHKnEoOT23hcVaH3IJv) #### Track & Trace Een onderdeel van het zakenoverzicht is de Track & Trace functionaliteit. Organisaties worden veel gebeld en gemaild met verzoeken voor informatie met betrekking tot lopende zaken. Met track en trace willen we dit inzichtelijk maken zodat mensen weten wat de huidige status is, en idealiter ook nog hoe lang het nog duurt tot de zaak is afgerond. In NL Portal kunnen we gedetailleerde zaakstatussen en substatussen tonen en daarbij ook een tijdslijn van de verwachte doorloop. # Mijn gegevens NL Portal bevat een module waarmee een inwoner zijn of haar informatie die vastgelegd is in de Basis Registratie Personen kan bekijken. Deze informatie wordt opgehaald uit de Basis Registratie met de [Haal Centraal BRP](https://vng.nl/projecten/haal-centraal-gegevens-ophalen-bij-basisregistraties) connectie. ![mijn-gegevens](/files/oGs4xqNIswXbP6i2CTvD)*Schermafbeelding van klantportaal.denhaag.nl functionaliteit mijn gegevens* # Product Een product is het mogelijk resultaat van een verzoek. Het formaat van een product is gestandaardiseerd in een JSON formaat. Het verzoek kan worden aangemaakt via een component naar keuze, in veel gevallen een zaak- of taakafhandelapplicatie. Voorbeelden van producten zijn een vergunning of rijbewijs. ![product](/files/MLcOCugebvzYjyVdSSli)*Producten worden nog gestandaardiseerd, deze worden tijdelijk opgeslagen in de Objects API, het plan is om de Producten- en Dienstencatalogus in 2025 te realiseren. NL Portal zal hierop aansluiten.* # Patronen NL Portal integreert zowel met de datalaag als met omliggende componenten. In deze paragraaf worden eerst algemene principes uitgelegd. NL Portal ondersteunt twee manieren van integratie: synchrone en asynchrone communicatie. ### Synchrone Communicatie Synchrone communicatie is een stijl waarbij de vragende service wacht tot er een antwoord komt van de antwoordende service. Er is direct contact tussen twee services. Dit is een veelgebruikte en eenvoudige aanpak. Synchrone communicatie betreft vaak calls naar een REST API, maar dat is niet noodzakelijk. **Voordelen:** * **Eenvoudig en goedkoop:** Synchrone communicatie is makkelijk te implementeren en kosteneffectief. * **Breed ondersteund:** De meeste componenten bieden standaard een REST API aan. **Nadelen:** * **Afhankelijkheid:** NL Portal wordt afhankelijk van de snelheid van de antwoordende service. Als bijvoorbeeld een PDF-generatie door service X vijf seconden duurt, moet NL Portal (en de gebruiker) die tijd wachten. * **Moeilijk te vervangen:** Omdat NL Portal rechtstreeks verbonden is met systeem X, is het moeilijk om X te vervangen door een gelijksoortige dienst zonder aanpassingen. * **Schaalbaarheid:** Het is lastig om op te schalen. NL Portal vraagt expliciet aan systeem X om een taak uit te voeren. Het toevoegen van een extra systeem X' om de werklast te verdelen werkt niet direct 'uit de doos'. ### Asynchrone Communicatie Asynchrone communicatie is een stijl waarbij de vragende service niet wacht op een antwoord. Er is geen direct contact tussen de services; sterker nog, de services kennen elkaar niet. Het principe is gebaseerd op gebeurtenissen ('events'). Een service meldt dat er iets is voorgevallen zonder te weten wat daarop moet gebeuren. Andere services abonneren zich op deze 'events'. Als er een event plaatsvindt waarop zij moeten handelen, doen ze dat. Binnen de Common Ground-gemeenschap is gekozen voor *informatiearme* asynchrone communicatie. Dit betekent dat de informatie ('payload') van het bericht niet in de notificatie wordt vastgelegd, maar in een apart bericht. De notificatie verwijst naar dit bericht. **Voorbeeld: het Verzoek** ![informatie-arm](/files/MVoT9UACdnT3QIbyuug7) 1. Vanuit NL Portal wordt een Verzoek in de vorm van een object in de Objects API geplaatst. 2. De Objects API notificeert het notificatiecomponent. 3. Het afhandelcomponent is geabonneerd op notificaties van een bepaald type en wordt op de hoogte gebracht van het feit dat er een nieuw bericht is. 4. Het afhandelcomponent vraagt het verzoek op uit de Objects API. # Verzoek Een verzoek is de informatie en trigger die mogelijk leidt tot het leveren van een product of dienst. Een verzoek kan afkomstig zijn van een klant in de vorm van een natuurlijk persoon, een gemachtigde of een organisatie. Het formaat van een verzoek is gestandaardiseerd in een JSON formaat. Het verzoek kan worden aangemaakt via een component naar keuze, in veel gevallen een formulierencomponent, maar ook een scanstraat of een zaakafhandelsysteem van een organisatie kunnen verzoeken indienen. ![verzoek](/files/7L6UDFEMvDnytw3HRuZS)*Van verzoek via de zaak naar een product* ### Sequence diagram Indien er documenten (enkelvoudig zaakinformatieobject) horen bij een verzoek, dan worden deze eerst vastgelegd in via de Documenten API. Vervolgens wordt het verzoek ingediend, met daarin verwijzingen naar de bijbehorende documenten. De vastlegging vindt plaats in de Objecten API. *Note: mogelijk wordt deze in de toekomst vervangen door een verzoeken API.* De Objecten API notificeert de notificatie componenten, die het juiste component in het achterliggende landschap notificeert. ![sequence-diagram-verzoek](/files/Mj9KzUVBh3BYj5kyxDk3)*Sequence diagram 'verzoek'* # Externe Taak In zaakafhandeling kan het nodig zijn om (aanvullende) informatie op te vragen bij de klant of ketenpartner. Dit kan middels de externe taak. Een taak kan zijn het aanleveren van aanvullende gestructureerde informatie, het aanleveren van documenten (zaakinformatieobjecten) of het doen van een betaling. Het formaat van een externe taak is gestandaardiseerd in een JSON formaat. De externe taak kan worden aangemaakt via een component naar keuze, in veel gevallen een zaakafhandelcomponent of taakapplicatie. ### Sequence diagram Er is nog geen sequence diagram beschikbaar. # Authentication en authorization Standaard werkt NL Portal met zowel DigiD als eHerkenning. **DigiD** DigiD is een digitale identiteit waarmee inwoners van Nederland zich kunnen identificeren\ bij verschillende online diensten van de overheid en andere organisaties, zoals\ zorgverzekeraars en pensioenfondsen. Het staat voor Digitale Identiteit. Met een DigiD\ kunnen burgers veilig en eenvoudig inloggen op websites van overheidsinstanties en\ diverse andere instellingen. **eHerkenning** eHerkenning is een digitale identificatiedienst in Nederland, vergelijkbaar met DigiD,\ maar specifiek ontworpen voor bedrijven en organisaties. Het biedt een gestandaardiseerde\ manier voor bedrijven om zich veilig en betrouwbaar online te identificeren bij\ overheidsdiensten en private partijen. # Features NL Portal heeft veel functionaliteiten out of the box, en is volledig modulair uitbreidbaar. Alle functionaliteiten zijn optioneel en kunnen aan of uitgezet worden. ### Beveiligde omgeving Bezoekers van de NL Portal kunnen in een beveiligde omgeving inloggen om hun gegevens in te zien. NL Portal gebruikt keycloak als access management service en kan gebruik maken van bijvoorbeeld digid, eHerkenning of ADFS. ### Profielpagina Binnen NL Portal is onder andere een profielpagina component. Deze profielpagina kan koppelen met HaalCentraal en zo de informatie uit de basisadministratie tonen. ![profiel.png](/files/l25daZB0rvZN0DMTu31A) ### Zaakinformatie Binnen NL Portal draait alles om zaken. NL Portal kan de zaakinformatie van een gebruiker realtime tonen en geeft ook de status van de zaak weer. Zo weet een gebruiker altijd waar hij aan toe is en hoeft hij niet telefonisch contact op te nemen. ![zaakstatus.png](/files/tM0rxBbiyxneqAsST7F8) ### Veilige bestandsuitwisseling In NL Portal kun je eenvoudig en veilig bestanden uitwisselen met de klant. Dit kan zowel gaan om het veilig toesturen van een bestand vanuit de organisatie naar de klant of de klant kan veilig een bestand uploaden naar de organisatie. Dit bestand wordt gekoppeld aan de juiste zaak en voorzien van de nodige metadata. Veilig en AVG proof. ### Design system NL Portal gebruikt NL Design system als frontend. In dit design system zijn alle technische voorbereidingen voor het voldoen aan webtoegankelijkheidsregels zoals WCAG al getroffen. Daarnaast is het eenvoudig test stylen in de eigen huisstijl. ![dhams](/files/vrjmGTaFK9I6CEv9fWDQ) # Object filtering Het is mogelijk om te bepalen welke Documenten een gebruiker te zien krijgt op een zaak pagina. Zaak Informatieobjecten worden gefilterd voor dat ze geretourneerd worden. ## Configuratie Deze functionalitiet maakt gebruik van twee whitelists in de spring properties van jouw applicatie. Beide properties hebben zijn eigen [opties en standaardwaardes](#opties). Standaardwaardes worden gebruikt als deze properties niet configureerd zijn. 1. `nl-portal.zgw.zakenapi.zaak-documenten.status-whitelist` 2. `nl-portal.zgw.zakenapi.zaak-documenten.vertrouwelijkheidsaanduiding-whitelist` ### Opties De volgende opties zijn van toepassing bij de whitelists en zijn gebaseerd op de [enkelvoudiginfromatieobject](https://openzaak.ritense.opengem.nl/documenten/api/v1/schema/#tag/enkelvoudiginformatieobjecten) Documenten API specificatie. | Status | Standaardwaarde | | ----------------- | :-------------: | | ter\_vaststelling | | | in\_bewerking | | | definitief | X | | gearchiveerd | X | | Vertrouwelijkheidaanduiding | Standaardwaarde | | --------------------------- | :-------------: | | openbaar | X | | beperkt\_openbaar | X | | intern | X | | zaakvertrouwelijk | X | | vertrouwelijk | | | confidentieel | | | geheim | | ### Voorbeeld De volgende spring properties zorgen ervoor dat alle Informatieobjecten die bij jouw Zaak horen worden geretourneerd. ```yaml nl-portal: zgw: zakenapi: zaak-documenten: vertrouwelijkheidsaanduiding-whitelist: - openbaar - beperkt_openbaar - intern - vertrouwelijk - zaakvertrouwelijk - confidentieel - geheim - zeer_geheim status-whitelist: - ter_vaststelling - in_bewerking - definitief - gearchiveerd ``` # Open source ### Uitgangspunten ontwikkeling NL Portal * Open standaarden, open source licentie EUPL 1.2; * Compatible met diverse formulierapplicaties; * Frontend UI gebaseerd op [NL Design System](https://nldesignsystem.nl/); * Voldoet aan alle web toegankelijkheidsrichtlijnen (WCAG); * Onafhankelijk van proces- of zaak management systemen; * Horizontal schaalbaar. ### Bijdrage leveren Alle code is publiek beschikbaar op onze [github](https://github.com/nl-portal/). We zijn trots op ons werk, tonen je graag meer en staan klaar om je op gang te helpen. ### Feature of bugfixes toevoegen 1. Maak een issue aan in de [Frontend](https://github.com/nl-portal/nl-portal-frontend-libraries) of [Backend](https://github.com/nl-portal/nl-portal-backend-libraries) repository. Hiermee willen we zorgen dat alle bugfixes en features afgestemd zijn op elkaar zodat we geen dubbel werk doen 2. Implementeer de feature of bugfix, test deze en maak een PullRequest naar de development branch 3. Schrijf de release notes en documentatie 4. Merge de branch als je een akkoord hebt van het Portal team We streven naar een maandelijkse release, mocht je sneller een fix of feature nodig hebben laat het ons weten. ### Deelnemers ![deelnemers](/files/DOzYiTPp83wKgy2cLwKr) # Opzetten NL Portal ### Wat heb je nodig Om de NL Portal lokaal op te zetten is enige basiskennis van de CLI (command-line interface) vereist. Daarnaast heb je de volgende software nodig: * [Docker Desktop](https://www.docker.com/products/docker-desktop/) — de enige harde vereiste om de NL Portal demo te draaien. * Voor het maken van een eigen portaal: [Git](https://git-scm.com/) en een [GitHub](https://github.com/) account. Het bouwen van de applicatie gebeurt via Docker, een lokale JDK- of Node-installatie is niet nodig. #### Waar kan ik de code vinden Alle code en informatie is opensource en kan gevonden worden op [github.com](https://github.com/nl-portal). De NL Portal is opgesplitst in meerdere repositories. Hieronder een korte beschrijving van elk. | Repository | Beschrijving | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [Documentatie](https://github.com/nl-portal/documentation) | Documentatie over de NL Portal | | [NL Portal App](https://github.com/nl-portal/nl-portal-app) | Referentie-implementatie van de NL Portal backend en frontend apps, inclusief een docker-compose demo-omgeving. Het startpunt voor een eigen portaal. | | [Frontend Libraries](https://github.com/nl-portal/nl-portal-frontend-libraries) | Libraries voor de frontend die gebruikt worden in de NL Portal App | | [Backend Libraries](https://github.com/nl-portal/nl-portal-backend-libraries) | Libraries voor de backend die gebruikt worden in de NL Portal App | | [Docker Compose](https://github.com/nl-portal/nl-portal-docker-compose) | Een docker compose setup om het ZGW landschap op te zetten | | [Helm Charts](https://github.com/nl-portal/helm-charts) | Kubernetes Helm charts voor het deployen van een NL Portal omgeving | **Let op:** de eerdere frontend en backend template repositories zijn vervangen door de [NL Portal App](https://github.com/nl-portal/nl-portal-app) repository. Gebruik deze als startpunt voor een eigen portaal. ### Route 1: De prebuilt images draaien De snelste manier om de NL Portal te bekijken is via de kant-en-klare demo-omgeving in de [NL Portal App](https://github.com/nl-portal/nl-portal-app) repository. De docker-compose file in deze repository bevat alles wat nodig is: * De prebuilt NL Portal backend en frontend images (`ghcr.io/nl-portal/nl-portal-app-backend` en `ghcr.io/nl-portal/nl-portal-app-frontend`). * De benodigde ZGW componenten (Open Zaak, Objecten API, OpenKlant, OpenProduct) en Haal Centraal mocks, opgedeeld in docker-compose profielen zodat je zelf kiest welke onderdelen je start. * Een voorgeconfigureerde Keycloak met token exchange v1 (zie ook de [Keycloak configuratie](/configuratie/keycloak) pagina). Clone de repository en start de demo-omgeving met: ```shell docker compose --profile remote --profile zgw --profile haalcentraal up -d ``` De NL Portal is daarna bereikbaar op `http://localhost:3000`. Je kunt inloggen met de volgende testgebruikers: | Gebruikersnaam | Wachtwoord | Identificatie (BSN/KVK) | | -------------- | ---------- | ----------------------- | | burger | burger | 999993847 | | bedrijf | bedrijf | 14127293 | **Let op:** het opstarten van alle ZGW componenten kan enkele minuten duren. De profielen `remote` en `local` kunnen niet tegelijk draaien omdat ze dezelfde poorten gebruiken. De volledige tabel met services, poorten en profielen vind je in de README.md van de NL Portal App repository. ### Route 2: Configureren via het Configuration Panel De aanbevolen manier om de NL Portal aan te passen is via het [Configuration Panel](/configuratie/configuration-panel). Hiermee kun je zonder code aan te passen: * Alle backend modules configureren (ZGW APIs, HaalCentraal, OpenKlant, etc.) * Een eigen logo uploaden * De huisstijl aanpassen via design tokens Start het Configuration Panel mee in de demo-omgeving: ```shell docker compose --profile remote --profile zgw --profile haalcentraal --profile config up -d ``` Het Configuration Panel is bereikbaar op `http://localhost:3001` met gebruikersnaam **admin** en wachtwoord **admin**. Zie de [Configuration Panel](/configuratie/configuration-panel) pagina voor uitgebreide documentatie over het aansluiten van een bestaande NL Portal instantie. ### Route 3: Fork de repository (geavanceerd) Wil je de NL Portal uitbreiden met eigen componenten of functionaliteit die niet via configuratie mogelijk is? Fork dan de [NL Portal App](https://github.com/nl-portal/nl-portal-app) repository en bouw je eigen images: 1. Fork de repository op GitHub en clone je fork lokaal. 2. Pas de frontend en/of backend aan naar wens. 3. Bouw en start je eigen images met: ```shell docker compose --profile local --profile zgw --profile haalcentraal up -d --build ``` Ook nu is de NL Portal bereikbaar op `http://localhost:3000` met dezelfde testgebruikers als hierboven. **Wanneer forken?** Alleen nodig voor: * Eigen frontend componenten of pagina's * Eigen backend plugins of modules * Aanpassingen aan de authenticatiemethoden (zie [Keycloak configuratie](/configuratie/keycloak)) Voor configuratie van API-koppelingen en huisstijl is forken niet nodig — gebruik hiervoor het [Configuration Panel](/configuratie/configuration-panel). ### Configuratie via environment variabelen De NL Portal app images kunnen ook volledig geconfigureerd worden via environment variabelen. De volledige referentie met inline documentatie vind je in de NL Portal App repository, in de bestanden `imports/backend.env` en `imports/frontend.env`. Zie de [Deployment guide](/configuratie/deployment-guide) voor de naamconventie, de module-configuratie en het deployen met Helm. ### Vervolgstappen Nu je eerste NL Portal draait kun je verder met: * [Configuration Panel](/configuratie/configuration-panel) — configureer API-koppelingen en theming via een UI. * [Eigen vormgeving](/configuratie/eigen-vormgeving) — meer informatie over design tokens en huisstijl. * [Deployment guide](/configuratie/deployment-guide) — deploy de NL Portal naar je eigen omgeving (Azure, AWS of Kubernetes). * [Keycloak configuratie](/configuratie/keycloak) — sluit de NL Portal aan op je eigen Keycloak. # Module Dependency Guide Overzicht van welke NL Portal modules geconfigureerd moeten zijn per feature. > **Let op:** Dit overzicht is gebaseerd op de laatst beschikbare major/minor release en geldt voor de standaard nl-portal-app configuratie. Eigen implementaties kunnen andere frontend-vereisten hebben, maar backend module-afhankelijkheden (zoals taak → objectenapi) blijven van toepassing. ## Afhankelijkheidsgrafiek ```mermaid flowchart TB subgraph features["Features"] zaken["Zaken"] taken["Taken"] berichten["Berichten"] account["Account"] end subgraph modules["Modules"] zakenapi["zakenapi"] catalogiapi["catalogiapi"] documentenapis["documentenapis"] objectenapi["objectenapi"] taak["taak"] berichtenmod["berichten"] openklant2["openklant2"] haalcentraal2["haalcentraal2"] end zaken --> zakenapi zaken --> catalogiapi zaken --> documentenapis zaken --> objectenapi zaken --> taak zaken -.->|"showContactTimeline"| openklant2 taken --> objectenapi taken --> taak taken --> documentenapis berichten --> objectenapi berichten --> berichtenmod berichten --> documentenapis account --> haalcentraal2 account --> openklant2 ``` ## Afhankelijkheidsmatrix | Feature | zakenapi | catalogiapi | documentenapis | objectenapi | taak | berichten | openklant2 | haalcentraal2 | | --------- | :------: | :---------: | :------------: | :---------: | :--: | :-------: | :--------: | :-----------: | | Zaken | ✓ | ✓ | ✓ | ✓ | ✓ | | ¹ | | | Taken | | | ✓ | ✓ | ✓ | | | | | Berichten | | | ✓ | ✓ | | ✓ | | | | Account | | | | | | | ✓ | ✓ | ¹ Alleen vereist als `showContactTimeline` aan staat # Configuration Panel Het Configuration Panel is een beheerapplicatie waarmee je de NL Portal backend en theming kunt configureren via een gebruiksvriendelijke interface — zonder code aan te passen of eigen images te bouwen. Zie de [nl-portal-configuration-panel repository](https://github.com/nl-portal/nl-portal-configuration-panel) voor installatie-instructies, environment variabelen en versiecompatibiliteit. ## Wat kun je configureren ### Backend modules Via het Configuration Panel kun je alle backend modules in- en uitschakelen en configureren: | Module | Beschrijving | | ---------------------- | ------------------------------------------------ | | Zaken API | Koppeling met Open Zaak voor zaken | | Catalogi API | Zaaktypen en informatieobjecttypen | | Documenten APIs | Documentopslag (meerdere configuraties mogelijk) | | Besluiten API | Besluiten bij zaken | | Objecten API | Objectregistratie voor taken en berichten | | OpenKlant 2 | Klantgegevens en contactmomenten | | HaalCentraal BRP v2 | Persoonsgegevens uit de BRP | | HaalCentraal HR | Bedrijfsgegevens uit het Handelsregister | | Taak | Externe taken via Objecten API | | Berichten | Berichtenfunctionaliteit | | Product | Productweergave | | OpenProduct | Koppeling met OpenProduct API | | DMN | Decision Model and Notation | | Prefill | Voorinvullen van formulieren | | Payment (Ogone/Direct) | Betalingsintegraties | | ClamAV | Virusscanning van uploads | ### Theming Het Configuration Panel biedt ook theming-opties: * **Logo** — upload een eigen logo voor de header * **Design tokens** — pas kleuren, typografie en andere stijlen aan via een CSS-editor Zie [Eigen vormgeving](/configuratie/eigen-vormgeving) voor meer informatie over design tokens. ## Uitproberen via de demo-omgeving De eenvoudigste manier om het Configuration Panel te gebruiken is via de [NL Portal App](https://github.com/nl-portal/nl-portal-app) demo-omgeving. Start het `config` profiel mee: ```shell docker compose --profile remote --profile zgw --profile haalcentraal --profile config up -d ``` Het Configuration Panel is daarna bereikbaar op `http://localhost:3001` met gebruikersnaam **admin** en wachtwoord **admin**. ## NL Portal aansluiten op het Configuration Panel De NL Portal backend libraries hebben ingebouwde ondersteuning voor het Configuration Panel. **Beveiliging:** het Configuration Panel bevat gevoelige configuratie zoals API-tokens en secrets. Maak het Configuration Panel nooit publiek toegankelijk. Zowel de webapp als de config server endpoints mogen alleen bereikbaar zijn via interne netwerken (bijv. Kubernetes cluster-netwerk, localhost) of via een beveiligde gateway met authenticatie. Configureer de volgende environment variabelen op de **NL Portal backend**: | Variabele | Beschrijving | | -------------------------------------- | ------------------------------------------------------------------------------------------------- | | `CONFIGURATION_PANEL_ENABLED` | Zet op `true` om de integratie te activeren (default: `false`) | | `CONFIGURATION_PANEL_URI` | URL van het Configuration Panel, bijv. `http://config-panel:8090/configuration` | | `CONFIGURATION_PANEL_TOKEN` | Token voor authenticatie (moet overeenkomen met `CONFIG_SERVER_TOKEN` op het Configuration Panel) | | `CONFIGURATION_PANEL_APPLICATION_NAME` | Naam van de applicatie, bijv. `nl-portal-app` | Voorbeeld: ```shell CONFIGURATION_PANEL_ENABLED=true CONFIGURATION_PANEL_URI=http://host.docker.internal:8090/configuration CONFIGURATION_PANEL_TOKEN=VerySecretToken CONFIGURATION_PANEL_APPLICATION_NAME=nl-portal-app ``` De NL Portal backend haalt bij opstarten de configuratie op uit het Configuration Panel. Waarden uit het Configuration Panel hebben voorrang op environment variabelen. Als notify is ingeschakeld op het Configuration Panel, kan de backend automatisch herstarten bij wijzigingen via Spring Actuator endpoints. ## Helm charts Voor Kubernetes-omgevingen zijn er Helm charts beschikbaar (`nl-portal-configpanel-backend` en `nl-portal-configpanel-frontend`). Zie de [helm-charts repository](https://github.com/nl-portal/helm-charts) voor installatie-instructies. # Eigen vormgeving NL Portal is opgebouwd met componenten gebaseerd op het [NL design system](https://nldesignsystem.nl/). Om je eigen NL Portal vorm te geven volgens de huisstijl kun je designtokens gebruiken. Designtokens zijn kleine stukjes van het designsysteem die ontwerpbeslissingen vertegenwoordigen zoals kleuren en lettertypes. ![eigen-vormgeving](/files/lqWhhEI2jEv4DW5WHDW6)*Drie verschillende klantportalen met verschillende vormgeving door middel van design tokens* ## Via het Configuration Panel De eenvoudigste manier om de huisstijl aan te passen is via het [Configuration Panel](/configuratie/configuration-panel). Hiermee kun je zonder code aan te passen: * **Logo uploaden** — vervang het standaard logo door je eigen organisatielogo * **Design tokens aanpassen** — pas kleuren, typografie en andere stijlen aan via de ingebouwde CSS-editor In het Configuration Panel ga je naar de **Theme** sectie. Onder **Logo** kun je een afbeelding uploaden. Onder **Style** vind je een CSS-editor waarin je design tokens kunt toevoegen of overschrijven. Een voorbeeld van een design token: ```css --nlportal-header-bar-background-color: #03801f; ``` Hiermee wordt de kleur van de header bar ingesteld op #03801f. Zie de [Configuration Panel](/configuratie/configuration-panel) pagina voor het opzetten van het Configuration Panel. ## Design tokens vinden De makkelijkste manier om te achterhalen met welk design token je een bepaald component kunt instellen is door in de [developer toolbar](https://developer.chrome.com/docs/devtools/overview) met de inspector te kijken. ![design-token-voorbeeld](/files/I9QcarMN1XPVw1Czlsd7)*Een voorbeeld van het designtoken nlportal-current-page-indicator-background-color* In het voorbeeld hierboven is een knop geselecteerd. In het omcirkelde deel is zichtbaar dat de achtergrondkleur van de knop wordt ingesteld met het designtoken `nlportal-current-page-indicator-background-color`. ## Geavanceerd: eigen vormgeving via code Als je de vormgeving wilt beheren in versiebeheer of meer controle nodig hebt, kun je de design tokens ook aanpassen in een fork van de [NL Portal App](https://github.com/nl-portal/nl-portal-app) repository. Ga naar het bestand `frontend/src/styles/nl-portal-design-tokens.css` en voeg je eigen designtokens toe die de standaard waardes overschrijven. Bouw vervolgens je eigen images met `docker compose --profile local up -d --build`. Zie [Opzetten NL Portal](/configuratie/opzetten-nl-portal) voor meer informatie over het forken en bouwen van eigen images. # Connectiviteit NL Portal koppelt met alle common ground systemen op laag 1 zoals OpenZaak en de Objecten API. Het koppelen van deze systemen verloopt altijd op ongeveer dezelfde manier: 1. In het aan te sluiten systeem moet een api account aangemaakt worden voor NL Portal 2. In NL Portal configureer je de url van het aan te sluiten systeem en de gegevens van het bij stap 1 aangemaakte account #### Voorbeeld Stel dat we een NL Portal instantie willen koppelen aan Open Zaak. Als eerste loggen we dan in in Open Zaak en gaan we naar Applicaties.![openzaak-beheer](/files/moNVQK1idVg0tDi4c0Zj) Vervolgens kun je daar een nieuwe applicatie toevoegen. ![openzaak-applicatie](/files/zK4cAmZw10wMl9cfUMmm) Vul de client id van de nieuwe applicatie in en een secret key. Het vinkje "heeft alle autorisaties" mag alleen gebruikt worden op development omgevingen. ![openzaak-applicatie-clientid](/files/rWn4FbLPOdLpRYz3X6os) Ga vervolgens naar het scherm beheer autorisatiegegevens en selecteer daar welke machtigingen NL Portal moet krijgen. ![openzaak-autorisaties](/files/lv8vHTpPpim2QQ8s15lX) Vervolgens moet NL Portal geconfigureerd worden om gebruik te maken van de aangemaakte autorisatiegevens. Dit kan met behulp van [environment variabelen](https://en.wikipedia.org/wiki/Environment_variable), of oplossing zoals de [azure key vault](https://azure.microsoft.com/en-us/products/key-vault), of de [aws key management service](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html). # Deployment guide Met deze stappen moet het mogelijk worden om de NL Portal app images te deployen naar je gewenste omgeving, mocht dat Azure, AWS of een Kubernetes cluster zijn. De NL Portal app images (`ghcr.io/nl-portal/nl-portal-app-backend` en `ghcr.io/nl-portal/nl-portal-app-frontend`) worden volledig geconfigureerd via environment variabelen. De complete, versie-specifieke referentie met inline documentatie vind je in de NL Portal App repository, in de bestanden `imports/backend.env` en `imports/frontend.env`. Raadpleeg altijd het bestand dat hoort bij de release die je deployt. De backend variabelen volgen de Spring Boot relaxed binding naamconventie: de property `nl-portal.config.zakenapi.properties.url` wordt de environment variabele `NLPORTAL_CONFIG_ZAKENAPI_PROPERTIES_URL`. ### Deployen met Helm (Kubernetes) Voor Kubernetes-omgevingen zijn er officiële Helm charts beschikbaar in de [helm-charts repository](https://github.com/nl-portal/helm-charts). Deze repository bevat charts voor de NL Portal backend, frontend en het Configuratiepaneel (backend en frontend). De beschikbare configuratiewaarden per chart, installatie-instructies en de changelogs met migratie-instructies per versie staan in de README van die repository. ```shell helm repo add nl-portal https://nl-portal.github.io/helm-charts helm repo update ``` ### Backend: module-configuratie De functionele modules van de backend (onder andere Zaken API, Catalogi API, Documenten APIs, Objecten API, OpenKlant 2, HaalCentraal, Berichten, Taak, Prefill, DMN, OpenProduct, betalingen en virusscan) worden per module aangezet met een enable-vlag. Alle modules staan standaard uit. Elke module heeft daarnaast eigen properties die met hetzelfde patroon worden gezet: `NLPORTAL_CONFIG__PROPERTIES_`. Bijvoorbeeld voor de Zaken API: ```shell NLPORTAL_CONFIG_ZAKENAPI_ENABLED=true NLPORTAL_CONFIG_ZAKENAPI_PROPERTIES_URL=https://openzaak.example.com NLPORTAL_CONFIG_ZAKENAPI_PROPERTIES_CLIENTID=nl-portal NLPORTAL_CONFIG_ZAKENAPI_PROPERTIES_SECRET= ``` **Let op:** de zaken-functionaliteit vereist dat de Zaken API, Catalogi API én Objecten API modules alle drie enabled zijn. Alle module properties, inclusief de optionele, zijn met inline documentatie te vinden in `imports/backend.env` in de NL Portal App repository. Zie de [Keycloak configuratie](/configuratie/keycloak) pagina voor het instellen van de bijbehorende clients in Keycloak. # Keycloak configuratie NL Portal gebruikt Keycloak voor de authenticatie van gebruikers. Deze pagina beschrijft alle vereisten om een Keycloak in te richten voor gebruik met de NL Portal: de benodigde server features, clients, token exchange, gebruikersattributen en claims. Deze documentatie beschrijft de **burger flow** (gebruiker met BSN, ingelogd via DigiD) en de **generieke gebruikersflow** (Keycloak gebruiker zonder BSN of KVK). Voor overige flows, zoals bedrijven (eHerkenning) en machtigingen, verwijzen we naar de broncode of [support](/support-en-resources/community-en-support). Zie [Overige flows](#overige-flows). ## Vereiste server features NL Portal gebruikt de **legacy (v1) token exchange** van Keycloak in combinatie met fine-grained admin permissions. De standaard (v2) token exchange die Keycloak vanaf versie 26 standaard aanbiedt wordt **niet** ondersteund. Beide features moeten expliciet aangezet worden via de `KC_FEATURES` environment variabele van Keycloak. De juiste waarde verschilt per Keycloak versie: | Keycloak versie | KC\_FEATURES | | --------------- | ----------------------------------------------- | | ≤ 24 | `token-exchange,admin-fine-grained-authz` | | ≥ 26 | `token-exchange:v1,admin-fine-grained-authz:v1` | **Let op:** vanaf Keycloak 26 activeert de vlag `token-exchange` zónder suffix de v2-variant; de `:v1` suffix is daarom verplicht. Zie de [officiële Keycloak documentatie](https://www.keycloak.org/securing-apps/token-exchange) voor de verschillen tussen de v1 (legacy) en v2 (standaard) token exchange. ## Realm en clients In het realm van de NL Portal zijn drie clients nodig: | Client (voorbeeldnaam) | Type | Doel | | -------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------- | | `nl-portal` | public, standard flow | Login van de frontend (SPA). Draagt de `middel` mapper. | | `nl-portal-m2m` | confidential, service accounts, met secret | Voert de token exchange uit namens de backend. | | `nl-portal-token-exchange` | public, geen flows | Doelclient (audience) van de token exchange. Bevat de `aanvrager.bsn`/`aanvrager.kvk` mappers. | De clients koppel je aan de backend via de volgende environment variabelen van de app image (zie ook de [Deployment guide](/configuratie/deployment-guide)): | Variabele | Keycloak client | | ---------------------------------- | -------------------------------------- | | `KEYCLOAK_CLIENT_ID` | Client id van de m2m (backend) client | | `KEYCLOAK_CLIENT_SECRET` | Secret van de m2m (backend) client | | `KEYCLOAK_TOKEN_EXCHANGE_AUDIENCE` | Client id van de token-exchange client | ## Token exchange Als je een api call doet naar de backend wordt de token onderschept en wordt er een call naar Keycloak gedaan en hier wordt een nieuwe token opgehaald waar de bsn/kvk wel in zit. Deze wordt nu gebruikt in de verdere applicatie. ### Hoe moet je Keycloak instellen Maak een nieuwe client aan voor de backend. ![tokenexchange1](/files/IWmdlsGnmMrsRUB1WJpp) ![tokenexchange2](/files/Ce9gYHEWP1j12ex6q88L) Op de credentials tab vind je de secret key die je in de application yaml moet zetten. ![tokenexchange3](/files/QQ6NpfgghHwhoXZf3vp3) ![tokenexchange4](/files/9awiqzVLgSAx0YOf6XgR) LET OP: niet zomaar op regenarate klikken dan veranderd de key en kan je niet de oude meer terug zetten. Hierna creëer je nog een client deze is voor de token exchange. ![generalsettings1](/files/iWPz2o2uWs4ZxokZ5EMh) ![generalsettings2](/files/3N9URwJ0gqd4fyOZvsLE) Navigeer naar de ‘Client scopes’ tab. Hier klik je op de 1e client scope. ![clientscopes](/files/5M0yFCIg8APTaA7bkRwo) In ons geval met de naam ‘gzac-portal-token-exchange-dedicated’. Hierin komen de mappers van de bsn en kvk. ![mappers](/files/gwrXzj2unducK3wEMqx9) Ga terug naar client details en navigeer nu naar de tab ‘Permissions’. Zorg dat de ‘permissions enabled’ op ‘on’ staat. Je krijgt een permissions list te zien. Navigeer naar ‘token exchange’. ![permission-list](/files/Uh3EI92Y7rBMg1nEUBGB) Hierin moet je een nieuwe polici maken om de backend client toegang te geven tot een token exchange. ![policy-config](/files/p6b4DBDi75rGW7sSLi6N) De policy. ![policy](/files/Jr4UXPmbrCiML2chg0hc) Hierna moet je nog naar de ‘oude’ al bestaande client om de mappers(kvk en bsn) weg te gooien bij de al bestaande client die nu alleen nog gebruikt zal worden door de frontend. In de backend moet je nu per omgeving een parameter zetten die de secret en de resource heeft om de token exchange succesvol te kunnen runnen. ## Gebruikersattributen: burger flow De backend bepaalt het type gebruiker op basis van claims in de **geëxchangede** token: 1. Claim `aanvrager.bsn` aanwezig → de gebruiker is een **burger**. 2. Claim `aanvrager.kvk` aanwezig → de gebruiker is een **bedrijf** (zie [Overige flows](#overige-flows)). 3. Geen van beide → de gebruiker is een **generieke gebruiker** (zie [Generieke gebruikers](#generieke-gebruikers-sub-flow)). Voor de burger flow betekent dit: * De gebruiker in het portal realm heeft een **user attribute** `bsn` (bijvoorbeeld `999993847`). * Op de **token-exchange client** staat een protocol mapper (type *User Attribute*) die het user attribute `bsn` mapt naar de claim `aanvrager.bsn` in het access token. * Daarnaast heeft de gebruiker het user attribute `authenticationMethod` met waarde `digid`, dat via de `middel` claim de frontend features bepaalt (zie [De middel claim](#de-middel-claim)). Een burger heeft daarmee toegang tot onder andere de Mijn Gegevens pagina (BRP gegevens via Haal Centraal) en ziet zaken waarop hij of zij als initiator met dat BSN geregistreerd staat. ## Generieke gebruikers (sub flow) Een gebruiker zonder `aanvrager.bsn` of `aanvrager.kvk` claim wordt behandeld als generieke Keycloak gebruiker. De backend identificeert deze gebruiker met de eerste 13 karakters van de `sub` claim, met identificatietype `uid`. Voor generieke gebruikers werkt een deel van de portal functionaliteit: | Functionaliteit | Werkt voor generieke gebruiker? | Toelichting | | ---------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Zaken | Ja | Zaken moeten een rol hebben met `betrokkeneIdentificatie.natuurlijkPersoon.anpIdentificatie` gelijk aan de uid (eerste 13 karakters van `sub`). | | Taken | Ja | Taakobjecten met `identificatie.type` = `uid` en `identificatie.value` = de uid. | | Berichten | Ja | Berichtobjecten met dezelfde uid-identificatie. | | Mijn Gegevens (BRP) | Nee | Vereist een burger (BSN); de pagina toont geen gegevens. | | OpenKlant 2 (partijen) | Nee | Vereist een burger of bedrijf; queries geven een foutmelding. | ## De middel claim De frontend leest de claim `middel` uit het access token van de **frontend client** en bepaalt daarmee welke features actief zijn. De standaard app image is geconfigureerd met de volgende authenticatiemethoden (aanpasbaar in een fork, zie `frontend/src/App.tsx` in de NL Portal App repository): | Categorie | Waarden van `middel` | Gedrag | | --------- | ------------------------------ | ------------------------------------------------------- | | person | `digid`, `machtigen` | Persoonsweergave: Mijn Gegevens toont BRP gegevens. | | company | `eherkenning`, `bewindvoering` | Bedrijfsweergave (zie [Overige flows](#overige-flows)). | | proxy | `machtigen`, `bewindvoering` | Machtigingsflow (zie [Overige flows](#overige-flows)). | Voor de burger flow stel je dit in met: * Het user attribute `authenticationMethod` met waarde `digid` op de gebruiker. * Een protocol mapper (type *User Attribute*) op de **frontend client** die het user attribute `authenticationMethod` mapt naar de claim `middel` in het access token. **Let op:** als de `middel` claim ontbreekt valt de frontend terug op de persoonsweergave. De Mijn Gegevens pagina toont dan alleen gegevens als de gebruiker ook daadwerkelijk een burger is (BSN attribuut én mapper correct ingesteld). Is dat niet het geval, dan toont de pagina een foutmelding. ## Externe identity providers De attributen `bsn` en `authenticationMethod` zijn **user attributes op de Keycloak gebruiker** in het portal realm. Wanneer gebruikers via een externe identity provider inloggen (bijvoorbeeld Azure AD of DigiD via identity brokering), bestaan deze attributen niet vanzelf. Configureer in dat geval **identity provider mappers** in Keycloak die de attributen bij het inloggen op de gebruiker zetten. De protocol mappers op de clients (zie hierboven) mappen de attributen vervolgens naar de claims. ## Referentieconfiguratie De docker-compose demo-omgeving in de NL Portal App repository bevat een volledig werkend voorbeeld van alle bovenstaande configuratie. Gebruik deze als referentie bij het inrichten van een eigen Keycloak: * `docker-compose.yaml` — de Keycloak service met de juiste `KC_FEATURES` waarde. * `imports/keycloak/nlportal-realm.json` — een volledig realm met de drie clients, de token exchange permission, de protocol mappers voor `aanvrager.bsn`, `aanvrager.kvk` en `middel`, en testgebruikers (`burger` met BSN attribuut en `authenticationMethod` `digid`, `bedrijf` met KVK attribuut en `authenticationMethod` `eherkenning`). ## Overige flows Naast de burger flow en de generieke gebruikersflow ondersteunt de NL Portal ook bedrijven (KVK / eHerkenning) en machtigingsflows (`machtigen`, `bewindvoering`). Deze flows zijn niet in deze documentatie uitgewerkt. Raadpleeg hiervoor de broncode (de module `zgw/common-ground-authentication` in de Backend Libraries repository en de frontend van de NL Portal App repository) of neem contact op via [Community en support](/support-en-resources/community-en-support). # Best practices In het veelvuldig toepassen van NL Portal zijn een aantal best practices ontdekt. Wanneer deze gevolgd worden maakt dit ontwikkeling en onderhoud van een NL Portal instantie zo makkelijk mogelijk 1. Hou qua vormgeving de standaard aan en style deze met tokens. Pas niet de volledige frontend implementatie aan. Hoewel de standaard implementatie beperkingen kent zijn deze goed te stylen. Een volledig losse frontend implementatie maakt toekomstig onderhoud zeer complex. 2. NL Portal gebruikt Open Standaarden voor het ophalen van informatie. Door het gebruik van deze Open Standaarden en componenten is alles herbruikbaar. 3. Als je nieuwe onderdelen gaat toevoegen wordt het enorm gewaardeerd als je deze ook teruggeeft aan de community. Zo maken we samen NL Portal steeds beter. # Community en support ### Samen maken we NL Portal beter Door samen te werken, combineren we verschillende perspectieven om tot nieuwe ideeën te komen.\ Dit resulteert in betere en flexibelere oplossingen die voor iedereen effectief zijn. Een ander voordeel is het delen van kosten. We ontwikkelen een oplossing slechts één keer en\ doen dit grondig. Alle verbeteringen en nieuwe functionaliteiten worden vervolgens standaard\ beschikbaar voor alle gebruikers. Hoe meer partijen deelnemen aan de ontwikkeling, hoe lager\ de kosten voor iedereen. Wil jij ook iets bijdragen? Op de [governance ](/product-management/governance)pagina wordt meer verteld over hoe je\ nieuwe features en bugfixes kan toevoegen. Wil je ook meepraten? We nodigen je graag uit om mee te kijken tijdens een sprintreview of\ je uit te nodigen voor de NL Portal community op Slack. Stuur hiervoor een mailtje naar . # Repositories | Repository | Beschrijving | | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [Documentatie](https://github.com/nl-portal/documentation) | Documentatie over de NL Portal | | [NL Portal App](https://github.com/nl-portal/nl-portal-app) | Referentie-implementatie van de NL Portal backend en frontend apps, inclusief een docker-compose demo-omgeving. Het startpunt voor een eigen portaal. | | [Frontend Libraries](https://github.com/nl-portal/nl-portal-frontend-libraries) | Libraries voor de frontend die gebruikt worden in de NL Portal App | | [Backend Libraries](https://github.com/nl-portal/nl-portal-backend-libraries) | Libraries voor de backend die gebruikt worden in de NL Portal App | | [Docker Compose](https://github.com/nl-portal/nl-portal-docker-compose) | Een docker compose setup om het ZGW landschap op te zetten | | [Helm Charts](https://github.com/nl-portal/helm-charts) | Kubernetes Helm charts voor het deployen van een NL Portal omgeving | # Impressies Het UX Design is ontwikkeld door de gemeente Den Haag, op basis van het [NL Design system](https://nldesignsystem.nl/).\ Den Haag beschikt over eigen UX lab, waarin de UX wordt getest met inwoners. Enkele impressies\ van ontwerpen van NL Portal in de *look & feel* van de gemeente Den Haag. ## Gemeente Den Haag In het onderstaande overzicht scherm staan alle lopende zaken van deze persoon en de openstaande\ taken die uitgevoerd moeten worden. ![overzichts-pagina](/files/RctSjMuBQuAZXgZAUMzm)*Overzichtscherm* Bij de lopende zaken staan de stappen en de status van een specifieke zaak en welke taken hierbij\ open staan. ![lopende-zaken](/files/5fXDWI5PezsrGQywTecF)*Lopende zaken* NL Portal wisselt berichten uit tussen de klant/ burger en de gemeente. Alle openstaande en\ afgehandelde berichten worden verzameld op deze pagina. ![mijn-berichten](/files/bZO72ozbkztnHp0yzEXc)*Mijn berichten* Door op een bericht te klikken worden de details van het bericht zichtbaar. Eventuele taken\ zoals betalingen kunnen direct worden uitgevoerd. ![bericht-detail](/files/SRI6EqbA7ugnnfS65FkX)*Bericht - detailpagina* Bij mijn gegevens staan de profielgegegevens van deze persoon en kunnen persoonsgegevens\ gewijzigd worden. ![mijn-gegevens](/files/2UKihsTbfB8azZ8Y2CoK)*Mijn gegevens* ## Gemeente Amsterdam Op het overzicht scherm staan de openstaande zaken van de betreffende persoon of organisatie ![overzicht-amsterdam](/files/OnRBOfhGhbnrvv6P2Zyt)*Overzicht* Op de 'mijn gegevens' pagina staan de profiel gegevens van de persoon of organisatie en kunnen\ de contactgegevens gewijzigd worden. ![mijn-gegevens-amsterdam](/files/WSy0yzbI2eF0ksbYZx2u)*Mijn gegevens* # Governance Alle code is publiek beschikbaar op GitHub. Voor contact met het ontwikkelteam kan een mailtje gestuurd worden naar [rik.van.amelsvoort@ritense.com](mailto:undefined) ## Feature of bugfixes toevoegen 1. Maak een issue aan in de [Frontend](https://github.com/nl-portal/nl-portal-frontend-libraries) of [Backend](https://github.com/nl-portal/nl-portal-backend-libraries) repository op Github. Hiermee willen we zorgen dat alle bugfixes en features afgestemd zijn op elkaar zodat we geen dubbel werk doen. 2. Implementeer de feature of bugfix, test deze en maak een PullRequest naar de development branch 3. Schrijf de release notes en documentatie 4. Merge de branch als je een akkoord hebt van het Portal team We streven naar een maandelijkse release, mocht je sneller een fix of feature nodig hebben laat het ons weten. # Roadmap De roadmap van het NL Portal wordt regelmatig bijgewerkt op basis van de actuele behoeften. De stuurgroep stelt de roadmap vast. Via de [link](https://ritense.atlassian.net/jira/discovery/share/views/dbb49c01-b8df-4ab3-89b6-0cda78f9df23) is de meest recente versie te bekijken. ## Mijlpalen Onderstaande mijlpalen worden opgepakt in 2025. ### ZGW configuratie via UI ZGW-configuratie via UI maakt het mogelijk om ZGW (Zaken, Documenten en Zaken API) instellingen rechtstreeks via een gebruikersvriendelijke interface te beheren. Beheerders kunnen hiermee eenvoudig API-eindpunten, autorisaties, en overige ZGW-specifieke parameters configureren zonder handmatig config-bestanden aan te passen. Dit vergroot de flexibiliteit en verlaagt de kans op fouten bij integratie met ZGW-voorzieningen. ### Huisstijl configuratie via UI Huisstijlconfiguratie via UI stelt beheerders in staat om de visuele stijl van de applicatie aan te passen via een gebruiksvriendelijke interface. Op basis van design tokens kunnen kleuren, typografie en componentstijlen worden geconfigureerd in lijn met het NL Design System. Hierdoor is het eenvoudig om de applicatie visueel af te stemmen op de huisstijl van een specifieke organisatie, zonder handmatige codewijzigingen. ### Haalcentraal BRP v2 HaalCentraal BRP v2 integreert de applicatie met de vernieuwde versie van de BRP API van HaalCentraal. Hiermee kunnen actuele persoonsgegevens zoals naam, adres en geboortegegevens veilig en gestandaardiseerd worden opgehaald bij de basisregistratie. Versie 2 biedt verbeterde performance, uitgebreidere datastructuren en betere ondersteuning voor moderne API-standaarden, wat zorgt voor een robuuste en toekomstbestendige koppeling met de BRP. ### Open Product en Open Klant De **Open Product**-feature in het NL Portal (zoals Open Inwoner of Open Zaak) is een module waarmee gemeenten centraal hun producten en producttypen kunnen beheren via een gebruiksvriendelijke beheersapplicatie. Denk aan: * **Producttypen** zoals parkeervergunning, paspoortaanvraag of afvalbakplaatsing, inclusief regels, geldigheid en zones. * **Producten** als individuele aanvragen — bijvoorbeeld de parkeervergunning van Jan Jansen met kenteken en adresgegevens. Andere applicaties (zoals Open Inwoner of Open Formulieren) kunnen via een REST‑API: * Lijsten met beschikbare producttypen ophalen; * Nieuwe producten aanmaken; * Actuele metadata tonen, zoals prijzen of geldigheidsduur. Door deze gecentraliseerde aanpak ontstaat één bron van waarheid voor producten binnen het NL Portal-ecosysteem, wat onderhoud en integratie eenvoudiger en consistenter maakt. # Release notes Deze sectie bevat de release-opmerkingen voor de verschillende versies van NL-Portal. Deze release-opmerkingen bevatten informatie over wat er nieuw is, welke bugs zijn opgelost, breaking changes, gedepriciëerde code en bekende problemen in die releaseversie. Daarnaast zijn er migratie-instructies beschikbaar wanneer een nieuwe versie niet direct out-of-the-box werkt. Deze sectie is bedoeld voor iedereen die wil weten wat er is gewijzigd in een versie van NL-Portal. De migratie-instructies zijn bedoeld voor meer technische gebruikers, zoals een systeembeheerder die zijn NL-Portal-installatie up-to-date wil houden. # 1.x.x # 1.1.0 Releasedatum november 2023 Dit is de eerste gedocumenteerde release van NL Portal. Deze bevat de volgende verbeteringen. * Ondersteuning meerdere document API's; * Diverse verbeteringen op het gebied van naamgeving in code; * Ondersteuning voor klantcontactmomenten; * Refactoring van taken patroon. # 1.4.0 Releasedatum april 2024 * Diverse kleine verbeteringen en bug fixes; * Verbeteringen in de authenticatieflow en de omgang van data in de JWT. Deze release is breaking; en vereist aanpassingen in de frontend, backend en Keycloak configuratie. # 1.4.1 Releasedatum mei 2024 * [Token exchange](https://github.com/nl-portal/nl-portal/tree/release/3.x/configuratie/tokenexchange.md) toegevoegd om de KVK/BSN uit de frontend token te halen. # 1.5.0 ## Nieuwe Functionaliteit De volgende functionaliteiten zijn nieuw toegevoegd: * **Externe-klanttaak support** Deze wijziging heeft geresulteerd in deprecated classes.\ Zie Deprecations voor meer informatie * **Vestigingsnummer bepaald lijst van zaken** Voor organisaties waarbij medewerkers van\ een vestiging geen zaken van andere vestigingen mogen zien * **Zaak informatieobject filtering** * **Betalingen ondersteuning** Het is nu mogelijk om aanslagen te betalen en automatische\ incasso's in te stellen * **Notificaties worden nu weergegeven** * **Berichten** Bied de mogelijkheid om informatieve berichten of meldingen in te zien ## Bugfixes De volgende bugs zijn opgelost: * **Zaken worden gepagineerd weergegeven** ## Breaking changes Er zijn geen breaking changes ## Deprecations De volgende classes zijn deprecated: * Taak - Gebruik in plaats daarvan TaakV2 * TaakFormulier - Gebruik in plaats daarvan TaakFormulierV2 * TaakObject - Gebruik in plaats daarvan TaakObjectV2 * TaakMutation - Gebruik in plaats daarvan TaakMutationV2 * TaakPage - Gebruik in plaats daarvan TaakPageV2 * TaakQuery - Gebruik in plaats daarvan TaakQueryV2 ## Bekende problemen De volgende problemen zijn bekend: * **Vestigingsnummer bepaald lijst van zaken** This feature does not work as intended yet.\ A hotfix (version 1.5.1) will be released when it is confirmed to work properly # 1.5.1 ## Bugfixes The following has been fixed: * **Limiting returned zaken by vestigingsnummer**\ ZakenAPI Client now correctly searches for cases based on a vestigingsnummer and kvk, when the authentication used\ is of type `BedrijfAuthentication` and the token claims contain a `vestigingsnummer`. ## Breaking changes Er zijn geen breaking changes ## Deprecations Er zijn geen deprecations ## Bekende problemen Er zijn geen bekende problemen # 1.6.0 ## Features * Diverse dependencies geüpgraded * Initieel ondersteuning toegevoegd voor het laden van configuratie vanuit het configuratiepaneel. * Nieuw module toegevoegd: payment-direct * OpenKlant2 uitgebreid om rekening te houden met vestigingsnummer * Gedeeltelijke zoekfunctionaliteit toegevoegd voor Zaken (nieuwe frontend env var: CASES\_PARTIAL\_SEARCH) * Gebruikerservaring tijdens laden verbeterd * Paginering toegevoegd aan de Zaken-pagina ## Bugfixes * Probleem verholpen waarbij de OpenZaak-code het vestigingsnummer niet gebruikte in queries wanneer dit wel was geconfigureerd * Fout verholpen waarbij een enkelvoudiginformatieobject zonder vertrouwelijkheidsaanduiding ervoor zorgde dat queries mislukten ## Breaking changes Er zijn geen breaking changes ## Deprecations Er zijn geen deprecations ## Bekende problemen Er zijn geen bekende problemen # 2.x.x # 2.0.0 ## Features * Diverse dependencies geüpgraded * Nieuwe module `haalcentraal2` geïmplementeerd — biedt ondersteuning voor interactie met HaalCentraal BRP 2.0 en Bewoningen API’s * Volledige ondersteuning toegevoegd voor NL Portal Configuration Panel 1.0 * Nieuwe feature toggle toegevoegd in de frontend om te schakelen tussen OpenKlant 1 en OpenKlant 2 `(OPEN_KLANT_VERSION)` * OpenKlant2 uitgebreid met extra functionaliteiten: * Zoeken op een specifiek `DigitaleAdres` * Zoeken naar alle `KlantContactmomenten` van een `Partij` * Mogelijkheid om een notitie toe te voegen aan een `DigitaleAdres` * Een `Partij` wordt automatisch aangemaakt als deze nog niet bestaat bij het aanmaken van een `DigitaleAdres` * OpenZaak uitgebreid: * Zaken kunnen nu worden uitgesloten op basis van ZaakType. Nieuwe configuratie-optie: `zaakTypesIdsExcluded` (lijst van UUID’s om uit te sluiten in de getZaken-query) * Idle timer en logout-waarschuwing toegevoegd aan de frontend * UI-verbeteringen: * De gebruikersinformatiepagina is herontworpen om gegevens te tonen uit OpenKlant 2.0, HaalCentraal BRP 2.0 en HaalCentraal Bewoningen * Verschillende componenten zijn verbeterd in vormgeving en gebruiksvriendelijkheid ## Bugfixes Er zijn geen bugfixes ## Breaking changes * Configuratie-eigenschappen voor NL Portal zijn gewijzigd. De configuratie is nu gegroepeerd per feature en bevat een toggle. Zie [#393](https://github.com/nl-portal/nl-portal-backend-libraries/pull/393/files) voor een voorbeeld. * Authenticatie is overgezet van de Keycloak JS-adapter naar react-oidc-context [#276](https://github.com/nl-portal/nl-portal-frontend-libraries/pull/276). Hierdoor kan NL Portal nu gebruikt worden met elke OIDC-compatibele identity provider. ## Deprecations Er zijn geen deprecations ## Bekende problemen Er zijn geen bekende problemen # 3.0.x # Backend Libraries # 3.0.0 ## Functionaliteiten * Verschillende afhankelijkheden zijn geüpgraded. * Verbeteringen aan bestaande functionaliteiten: * OpenKlant 2: * Nieuwe zoekfilters toegevoegd voor Klantcontactmomenten om te kunnen zoeken op Onderwerpobject-criteria. * OpenZaak: * Ondersteuning toegevoegd voor het opvragen van ZaakResultaten. * Nieuwe feature toggle-configuratie-eigenschap toegevoegd: `nl-portal.config.zakenapi.useNnpKvkQueryIdentificators` om de nieuwe `kvkNummer`-eigenschap van een `Rol` (beschikbaar sinds OpenZaak 1.20.0) te gebruiken bij het opvragen van Zaken als een Bedrijf. * Mogelijkheid toegevoegd om de SubStatussen van een Zaak op te vragen. Alleen SubStatussen met doelgroep betrokkenen of geen doelgroep worden aan de gebruiker getoond. * Direct * Nieuwe eigenschap `customTemplateUrl` toegevoegd voor het instellen van de [variant](https://docs.direct.worldline-solutions.com/en/integration/basic-integration-methods/hosted-checkout-page#createhostedcheckoutrequest:~:text=Method%202%3A%20Customise%20the%20Template%20in%20the%20Merchant%20Portal) van een HostedCheckout. * Berichten * De `getBericht`-query retourneert nu ook het Bericht-ID voor eenvoudiger verwerking in de frontend. * Mogelijkheid toegevoegd om de bijlagen van een Bericht te downloaden. Hiervoor moet de Documenten API geconfigureerd zijn. * Ondersteuning geïntroduceerd voor [Open Product](https://github.com/maykinmedia/open-product) via de `openproduct` NL Portal Backend-module. Dit is bedoeld om de op Objecten API gebaseerde `product`-module te vervangen. ## Bugfixes Er zijn geen bugfixes. ## Breaking changes * OpenKlant 2: * Een typefout gecorrigeerd door de query `getUserDigitaleAdresen` te hernoemen naar `getUserDigitaleAdressen`. * `graphql-kotlin` vervangen door [Spring for GraphQL](https://spring.io/projects/spring-graphql) voor een meer uniforme manier van werken en fijnmazige controle over querydefinities. ## Verwijderingen en afschrijvingen * De volgende backend-modules zijn verwijderd: * `haalcentraal-all` - De HaalCentraal BRP 1.0 API is verlaten en al geruime tijd niet meer in gebruik. Alle functionaliteit is vervangen door de `haalcentraal2`-module, die BRP 2.0 en Bewoningen API-functionaliteit biedt. De HaalCentraal HR-functionaliteit is verplaatst naar een eigen module, omdat deze nog in gebruik is. * `klant`, `klant-generiek` en `klantcontactmomenten` - De Klantinteracties API-specificatie wordt al lange tijd niet meer ondersteund door de VNG. Deze module is vervangen door de `openklant`-module, die [Open Klant](https://github.com/maykinmedia/open-klant) implementeert. * Taak V1-functionaliteit verwijderd ten gunste van Taak V2, die het [Externe Klanttaak](https://dienstverleningsplatform.gitbook.io/platform-generieke-dienstverlening-public/patronen/taken/externe-klanttaak) patroon implementeert. ## Bekende problemen Er zijn geen bekende problemen. # 3.0.1 ## Nieuwe Functionaliteit Er is geen nieuwe functionaliteit. ## Bugfixes De volgende bugs zijn opgelost: * Beveiliging verbeterd naar aanleiding van een penetratietest: * GraphiQL staat nu standaard uitgeschakeld. * Autorisatiecontrole toegevoegd bij het bijwerken en afronden van taken: gebruikers kunnen alleen hun eigen taken bijwerken. * Autorisatiecontrole toegevoegd op de query voor het ophalen van documentinhoud. ## Breaking changes * De Besluiten API-module is verwijderd vanwege een beveiligingsbevinding (ongeautoriseerde toegang tot besluiten-queries). Implementaties die van deze module gebruikmaken, dienen hiervoor eigen queries te implementeren. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # 3.0.2 ## Nieuwe Functionaliteit Er is geen nieuwe functionaliteit. ## Bugfixes De volgende bugs zijn opgelost: * Configuratiefout opgelost waarbij de eigenschap `brp-fields` van de HaalCentraal BRP-module niet kon worden ingesteld (foutmelding "No setter found for property: brp-fields"). ## Breaking changes Er zijn geen breaking changes. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # 3.0.3 ## Nieuwe Functionaliteit De volgende functionaliteiten zijn nieuw toegevoegd: * Het uploaden en downloaden van documenten bij Taken en Berichten verloopt nu via specifieke, beveiligde REST-endpoints in plaats van een generieke query. ## Bugfixes Er zijn geen bugfixes. ## Breaking changes * De GraphQL-query `getDocumentContent` is verwijderd vanwege een beveiligingsbevinding: de query voerde geen eigendomscontrole uit, waardoor elke geauthenticeerde gebruiker willekeurige documenten kon downloaden. Implementaties die van deze query gebruikmaken, dienen over te stappen op de nieuwe documenten-endpoints of hiervoor eigen queries te implementeren. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # 3.0.4 ## Nieuwe Functionaliteit De volgende functionaliteiten zijn nieuw toegevoegd: * Nieuwe, beveiligde GraphQL-query `getFormDefinitionByTaskId` voor het ophalen van een formulierdefinitie bij een taak. De query controleert of de ingelogde gebruiker eigenaar is van de taak en valideert dat het opgehaalde object daadwerkelijk een formulierdefinitie is, voordat de inhoud wordt teruggegeven. * Nieuwe configuratie-eigenschap `nl-portal.config.form.properties.form-definition-object-type-url`. Hiermee wordt de objecttype-URL van formulierdefinities in de Objecten API ingesteld. De backend gebruikt deze URL om te valideren dat een opgehaald object daadwerkelijk een formulierdefinitie is. Zonder deze instelling wordt de objecttype-validatie overgeslagen. ## Bugfixes Er zijn geen bugfixes. ## Breaking changes * De GraphQL-queries `getFormDefinitionByObjectenApiUrl` en `getFormDefinitionById` zijn verwijderd vanwege een beveiligingsbevinding (SSRF): de aanroeper kon een willekeurige URL of object-ID meegeven, waardoor elke geauthenticeerde gebruiker willekeurige objecten uit de Objecten API kon ophalen (waaronder gegevens met persoonsgegevens). Er werd bovendien niet gecontroleerd of het opgehaalde object wel een formulierdefinitie was. Implementaties die van deze queries gebruikmaken, dienen over te stappen op `getFormDefinitionByTaskId`. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # Frontend Libraries # 3.0.0 ## Functionaliteiten * Verschillende afhankelijkheden zijn geüpgraded. * Mogelijkheid toegevoegd om een applicatielogo en stijlen te definiëren via configuratie-eigenschappen of het NL Portal Configuratiepaneel. * Mogelijkheid toegevoegd om extra OIDC-parameters te definiëren in de NL Portal Frontend ([#426](https://github.com/nl-portal/nl-portal-frontend-libraries/pull/426)). * Formio-componenten zijn vervangen door maatwerkcomponenten die de stijlen van de applicatie volgen, waardoor Formio-formulieren prettiger zijn om mee te werken. ## Bugfixes Er zijn geen bugfixes. ## Breaking changes Er zijn geen breaking changes. ## Deprecations Er zijn geen deprecations. ## Bekende problemen * Vooraf invullen van select- en radiocomponenten in Externe Klanttaak-formulieren werkt niet; dit is opgelost in de 3.0.1 patch. # 3.0.1 ## Nieuwe Functionaliteit Er is geen nieuwe functionaliteit. ## Bugfixes De volgende bugs zijn opgelost: * Het vooraf invullen en versturen van select- en radiocomponenten in Formio-formulieren werkt weer (bekend probleem uit release 3.0.0). ## Breaking changes Er zijn geen breaking changes. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # 3.0.2 ## Nieuwe Functionaliteit De volgende functionaliteiten zijn nieuw toegevoegd: * Het uploaden en downloaden van documenten bij Zaken, Berichten en Taken verloopt nu via de nieuwe beveiligde REST-endpoints van de backend (vereist NL-Portal Backend Libraries 3.0.3). ## Bugfixes Er zijn geen bugfixes. ## Breaking changes * Een onveilige GraphQL-query voor het ophalen van documentinhoud is verwijderd, in lijn met de verwijdering in de backend libraries. Implementaties die van deze query gebruikmaken, dienen over te stappen op de nieuwe documenten-endpoints. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # 3.0.3 ## Nieuwe Functionaliteit De volgende functionaliteiten zijn nieuw toegevoegd: * De taakdetailpagina haalt de formulierdefinitie nu op via de nieuwe beveiligde query `getFormDefinitionByTaskId` van de backend (vereist NL-Portal Backend Libraries 3.0.4). De frontend geeft alleen nog het taak-ID door; de backend bepaalt zelf welke formulierdefinitie daarbij hoort. ## Bugfixes Er zijn geen bugfixes. ## Breaking changes * De onveilige GraphQL-queries voor het ophalen van een formulierdefinitie op basis van een URL of object-ID zijn verwijderd, in lijn met de verwijdering in de backend libraries. Implementaties die van deze queries gebruikmaken, dienen over te stappen op `getFormDefinitionByTaskId`. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # App # 3.0.0 ## Functionaliteiten * NL-Portal libraries bijgewerkt naar Backend Libraries 3.0.0 en Frontend Libraries 3.0.0. Zie de release notes van de betreffende libraries voor de inhoudelijke wijzigingen. ## Bugfixes Er zijn geen bugfixes. ## Breaking changes Er zijn geen breaking changes. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # 3.0.3\_3.0.2-1 Vanaf deze release bundelt een release van de NL-Portal App twee onafhankelijk geversioneerde onderdelen. De releasetag volgt het formaat `{backend}_{frontend}-{revisie}`; deze release bevat NL-Portal Backend Libraries 3.0.3 en NL-Portal Frontend Libraries 3.0.2. ## Nieuwe Functionaliteit De volgende functionaliteiten zijn nieuw toegevoegd: * NL-Portal libraries bijgewerkt naar Backend Libraries 3.0.3 en Frontend Libraries 3.0.2. * Nieuwe versionerings- en releaseaanpak voor container-images: elke release publiceert een onveranderlijke tag (`{versie}-{revisie}`) en meebewegende tags (`{versie}`, `{major}.{minor}` en `{major}`). * De voorbeeldconfiguratie ondersteunt nu het uploaden van documenten bij gebruikerstaken. * Ontbrekende configuratie-opties voor de backend en frontend toegevoegd en verouderde configuratievariabelen opgeschoond. * Vertaling toegevoegd voor de onderhoudsmelding. * Beveiliging verbeterd: * De Docker-images draaien nu onder een niet-geprivilegieerde gebruiker (non-root). * Afhankelijkheden bijgewerkt naar aanleiding van security-meldingen. * CI/CD-workflows aangescherpt met vastgepinde action-versies en minimale permissies. ## Bugfixes De volgende bugs zijn opgelost: * Typefouten in de volgende omgevingsvariabelen gecorrigeerd: * `ZAAKDOCUMENTEN_STATUSWHITELIST` * `ZAAKDOCUMENTEN_VERTROUWELIJKHEIDSAANDUIDINGWHITELIST` * `DIGITALADRESSENREFERENTIE` * De standaard sessie-time-out is teruggezet naar 15 minuten. ## Breaking changes * Deployments die de oude (foutieve) namen van de hierboven genoemde omgevingsvariabelen gebruiken, moeten worden aangepast naar de gecorrigeerde namen. * De container-images worden niet langer gepubliceerd met een `latest`-tag. Gebruik in plaats daarvan een van de versie-tags. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # 3.0.4\_3.0.3-1 Een release van de NL-Portal App bundelt twee onafhankelijk geversioneerde onderdelen. De releasetag volgt het formaat `{backend}_{frontend}-{revisie}`; deze release bevat NL-Portal Backend Libraries 3.0.4 en NL-Portal Frontend Libraries 3.0.3. ## Nieuwe Functionaliteit De volgende functionaliteiten zijn nieuw toegevoegd: * NL-Portal libraries bijgewerkt naar Backend Libraries 3.0.4 en Frontend Libraries 3.0.3. * Nieuwe omgevingsvariabele `NLPORTAL_CONFIG_FORM_PROPERTIES_FORMDEFINITIONOBJECTTYPEURL` toegevoegd voor het instellen van de objecttype-URL van formulierdefinities in de Objecten API. De backend gebruikt deze URL om te valideren dat een opgehaald object daadwerkelijk een formulierdefinitie is. ## Bugfixes Er zijn geen bugfixes. ## Breaking changes Er zijn geen breaking changes. ## Deprecations Er zijn geen deprecations. ## Bekende problemen Er zijn geen bekende problemen. # Contributing to NL portal Dankjewel voor het tonen van interesse in de ontwikkeling van de NL Portal. Per repository hebben wij een CONTRIBUTING.md bestand toegevoegd waarin beschreven staat\ hoe je kan bijdragen aan het project. Hieronder is een link naar dit bestand voor elk van de\ repositories: * [nl-portal-backend-libraries](https://github.com/nl-portal/nl-portal-backend-libraries/blob/next-minor/CONTRIBUTING.md) * [nl-portal-frontend-libraries](https://github.com/nl-portal/nl-portal-frontend-libraries/blob/next-minor/CONTRIBUTING.md) # Welkom bij NL Portal NL Portal is een open source burgerpersoonlijke omgeving voor Nederlandse gemeenten. NL Portal is een open source "Mijn Omgeving" voor Nederlandse gemeenten en overheden. Het stelt burgers en ondernemers in staat om via één vertrouwd loket zaken in te zien, taken uit te voeren, berichten te ontvangen en hun profiel te beheren. NL Portal is een erkende implementatie van **VNG MijnServices**, gebouwd op **Common Ground**-principes en volledig gestyled via het **NL Design System**. *** ## Documentatie * [Waarom NL Portal?](/nl-portal-docs-revision/waarom-nl-portal/waarom-nl-portal) — Beleidscontext: NDS, Wmebv en Common Ground * [NL Portal als MijnServices-implementatie](/nl-portal-docs-revision/waarom-nl-portal/waarom-nl-portal/mijnservices-implementatie) — Positie als erkende VNG-leverancier * [Wat kan NL Portal?](/nl-portal-docs-revision/wat-kan-nl-portal/wat-kan-nl-portal) — Overzicht van ondersteunde bouwstenen * [Hoe werkt NL Portal?](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal) — Architectuuroverzicht, vijflagenmodel en componenten * [Integraties](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/integraties) — Welke API-standaarden en referentie-implementaties * [Platform Generieke Dienstverlening](/nl-portal-docs-revision/platform-generieke-dienstverlening/platform-generieke-dienstverlening) — Technische patronen achter MijnServices * [Koppelingen](/nl-portal-docs-revision/koppelingen/koppelingen) — Systemen koppelen aan NL Portal * [NL Design System en huisstijl](/nl-portal-docs-revision/nl-design-system-en-huisstijl/nl-design-system) — Eigen huisstijl toepassen via design tokens * [Community en bijdragen](/nl-portal-docs-revision/community-en-bijdragen/community-en-support) — Ondersteuning en contact *** ## Over NL Portal NL Portal is open source (EUPL 1.2), community-gedreven en onderhouden door Ritense. Het is één van de erkende leveranciers in het VNG MijnServices-programma en wordt ingezet door tientallen Nederlandse gemeenten. → [Open source en governance](/nl-portal-docs-revision/waarom-nl-portal/waarom-nl-portal/open-source-en-governance) → [Repositories](/nl-portal-docs-revision/community-en-bijdragen/repositories) → [Release notes](/nl-portal-docs-revision/release-notes/release-notes) *** ## Gemeenten en partners NL Portal wordt gebruikt en mede-ontwikkeld door Nederlandse gemeenten en leveranciers. | | | | | | :-----------------------------------------------: | :----------------------------------------------: | :------------------------------------------------: | :-----------------------------------------: | | ![Gemeente Den Haag](/files/hrgFRgllx7BqpPTrfVEt) | ![Gemeente Utrecht](/files/2mX0aDDCUUjyJRsE8K6h) | ![Gemeente Amsterdam](/files/4N4rh3c2rOTA7UqwiMq9) | ![PinkRoccade](/files/JMUE6PJmt14aG7aONoTF) | # Waarom NL Portal? Gemeenten staan voor een concrete opgave: burgers en ondernemers moeten digitaal zaken kunnen doen met de overheid. Dat is geen interne IT-keuze maar een politiek en wettelijk mandaat, vastgelegd in de **Nationale Digitaliseringsstrategie (NDS)** en de **Wet modernisering elektronisch bestuurlijk verkeer (Wmebv)**. NL Portal is de open source invulling van die opgave — als erkende **VNG MijnServices**-leverancier die aansluit op Common Ground-standaarden en de wettelijke deadline van 1 januari 2026 ondersteunt. *** ## In deze sectie * [Digitale dienstverlening als opgave](/nl-portal-docs-revision/waarom-nl-portal/waarom-nl-portal/digitale-dienstverlening) — NDS, Wmebv en Common Ground uitgelegd * [NL Portal als MijnServices-implementatie](/nl-portal-docs-revision/waarom-nl-portal/waarom-nl-portal/mijnservices-implementatie) — Wat MijnServices is en hoe NL Portal daarin past * [Open source en governance](/nl-portal-docs-revision/waarom-nl-portal/waarom-nl-portal/open-source-en-governance) — Licentie, community en de rol van Ritense # Digitale dienstverlening als opgave Digitale dienstverlening voor gemeenten is geen optie meer — het is een wettelijke en beleidsmatige verplichting. Drie kaders bepalen de urgentie. ![Drie kaders voor digitale dienstverlening](/files/ARqme1EjilrfaJEQ6KFN) *** ## Nationale Digitaliseringsstrategie (NDS) De **Nationale Digitaliseringsstrategie** is de eerste gezamenlijke digitaliseringsstrategie van alle overheidslagen in Nederland, gelanceerd op 4 juli 2025. Ze is ontwikkeld door en voor nationale ministeries, provincies, gemeenten (VNG), waterschappen en publieke dienstverleners. Kernboodschap: *vrijblijvendheid is voorbij*. Standaarden worden bindend, en gemeenten worden aangesproken op resultaat. ### Prioriteit 4 — Burgers en ondernemers centraal > "De overheid stelt burgers en ondernemers centraal in digitale dienstverlening." Burgers ervaren één overheid: proactieve, toegankelijke en op maat gemaakte dienstverlening via het juiste kanaal. Dit beschrijft direct het doel van een burgerpersoonlijke omgeving: één plek waar de burger zijn zaken, taken, berichten en profiel beheert. ### Prioriteit 5 — Digitale weerbaarheid Verminder afhankelijkheid van een klein aantal leveranciers; versterk digitale autonomie. De NDS motiveert open source en leveranciersneutrale oplossingen. NL Portal is open source onder EUPL 1.2 en niet gebonden aan één backofficesysteem. ### Van vrijwillig naar bindend De NDS introduceert vier interventies: 1. **Versterkt gebruik van standaarden** — Forum Standaardisatie krijgt uitgebreide bevoegdheden; adoptie van open standaarden (zoals ZGW APIs) is niet meer vrijwillig 2. **Verplichte collectieve oplossingen** — Bepaalde bouwstenen worden verplicht voor alle overheidsorganisaties 3. **Collectieve inkoopstrategie** — Overheid organiseert zich als collectieve opdrachtgever voor IT 4. **Governance en accountability** — NDS-raad stuurt en bewaakt voortgang over alle overheidslagen **Implicatie**: voldoen aan open standaarden en gebruik van gedeelde bouwstenen wordt steeds meer een wettelijke en beleidsmatige verplichting. *** ## Wmebv — Wet modernisering elektronisch bestuurlijk verkeer De **Wet modernisering elektronisch bestuurlijk verkeer (Wmebv)** trad volledig in werking op **1 januari 2026**. Gemeenten zijn sindsdien verplicht digitale kanalen aan te bieden voor formele correspondentie met burgers en ondernemers. Concreet houdt dit in: * Burgers moeten berichten van de gemeente digitaal kunnen ontvangen en beantwoorden * Gemeenten moeten een betrouwbaar digitaal berichtenkanaal aanbieden VNG beveelt twee bouwstenen aan voor Wmebv-compliance: **MijnBerichten** (digitale berichtenuitwisseling) en **OMC Notify** (notificaties bij statuswijzigingen en nieuwe berichten). NL Portal implementeert MijnBerichten en draagt daarmee bij aan de invulling van een deel van de Wmebv-vereisten. → Zie ook: [Wmebv | VNG](https://vng.nl/wmebv) *** ## Common Ground **Common Ground** is het informatiearchitectuurprogramma van VNG Realisatie voor Nederlandse gemeenten. Het is volledig in lijn met de NDS en vormt de technische fundering van NL Portal. Kernprincipes: | Principe | Betekenis | | -------------------- | ----------------------------------------------------------------------------------------------- | | **Data bij de bron** | Gegevens worden bevraagd bij de gezaghebbende bronregistratie; niet gekopieerd naar het portaal | | **Vijflagenmodel** | Strikte scheiding van interactie, orkestratie, integratie, services en data | | **API-first** | Alle gegevensuitwisseling via gestandaardiseerde REST APIs (ZGW-suite) | | **Open source** | Software gepubliceerd onder EUPL 1.2 | | **Samen bouwen** | Gemeenten stellen gezamenlijk standaarden op en zijn collectieve opdrachtgever | NL Portal bevindt zich op **laag 5** (interactielaag) van het vijflagenmodel. Het bevraagt data bij de bron — Open Zaak, Open Klant, Haalcentraal BRP — en presenteert die aan de burger zonder lokale kopieën op te slaan. De **Realisatiekoers Common Ground** (goedgekeurd door VNG ALV mei 2025) stelt digitale dienstverlening als eerste focusdomein. *** ## Wat dit betekent voor uw gemeente | Kader | Wat het vraagt | NL Portal-invulling | | -------------------- | ---------------------------------- | -------------------------------------------------- | | NDS Prioriteit 4 | Één digitale omgeving voor burgers | MijnZaken, MijnTaken, MijnBerichten, MijnProfiel | | NDS Prioriteit 5 | Open source, geen vendor lock-in | EUPL 1.2, community-gedreven, leveranciersneutraal | | Wmebv (1 jan 2026) | Digitaal berichtenkanaal verplicht | MijnBerichten (deel van de vereisten) | | Common Ground | API-first, data bij de bron | GraphQL-aggregatielaag op ZGW REST APIs | | Bindende standaarden | ZGW-suite, REST API Design Rules | Volledig geïmplementeerd | **Kernboodschap**: NL Portal kiezen is geen productbeslissing — het is een compliancekeuze die aansluit bij NDS-prioriteiten en Common Ground-verplichtingen. # NL Portal als MijnServices-implementatie ## Wat is VNG MijnServices? **VNG MijnServices** is een programma van de VNG dat herbruikbare open source bouwstenen oplevert voor een persoonlijke digitale omgeving van burgers. Het is de operationele invulling van NDS Prioriteit 4 en het door VNG aanbevolen pad voor Wmebv-compliance. MijnServices is **geen enkelvoudige API-standaard**, maar een verzameling van bouwstenen — elk ondersteund door één of meer bestaande of in ontwikkeling zijnde VNG API-standaarden. De bouwstenen zijn gebruikersgetest, verwerkt in software van erkende leveranciers, compliant met wetgeving en afgestemd op Common Ground. *** ## De elf bouwstenen MijnServices bestaat uit elf bouwstenen. Elke bouwsteen heeft een rijpheidsstatus die het proces van standaardisatie weergeeft: **Help Wanted → Community → Candidate → Standaard**. | Bouwsteen | Omschrijving | Rijpheidsstatus | | ----------------------- | ------------------------------------------------------------------ | ------------------------------------ | | **MijnZaken** | Track-and-trace voor status van aangevraagde producten en diensten | Standaard (meest volwassen) | | **MijnTaken** | Acties die de burger moet uitvoeren via het portaal | Candidate | | **MijnProfiel** | Persoonlijke voorkeuren voor organisatiecontact | Candidate | | **Notificatieservice** | Alerts bij binnenkomende berichten, taken of statuswijzigingen | Candidate | | **MijnBerichten** | Digitale berichten en notificaties van de gemeente (Wmebv) | Candidate — in standaardisatieproces | | **MijnContactmomenten** | Overzicht van contactmomenten tussen gemeente en burger | Candidate | | **MijnProducten** | Overzicht van aangevraagde of verleende producten en diensten | Community | | **MijnActies** | Proactieve acties die de burger kan ondernemen | Community | | **MijnPlan** | Persoonlijk plan van de burger met de gemeente | Community (nieuw) | | **MijnGesprek** | Overzicht van geplande of gevoerde gesprekken met de gemeente | Community (nieuw) | | **MijnAgenda** | Persoonlijke agenda-integratie voor afspraken en deadlines | Community (nieuw) | > MijnPlan, MijnGesprek en MijnAgenda zijn recent toegevoegd aan de MijnServices-roadmap. De technische standaarden hiervoor zijn nog in ontwikkeling. *** ## Welke bouwstenen NL Portal implementeert ### Out-of-the-box (zonder maatwerk) | Bouwsteen | Toelichting | | ----------------------- | ---------------------------------------------------------------- | | **MijnZaken** | Volledig ondersteund via ZGW Zaken API en Catalogi API | | **MijnTaken** | Via het Externe Klanttaak V2-patroon (PGD) | | **MijnBerichten** | Via Klantinteracties API; ondersteunt Wmebv-verplichting | | **MijnProfiel** | Persoonlijk profiel en contactvoorkeuren via Contactgegevens API | | **MijnContactmomenten** | Overzicht van contactmomenten via Klantinteracties API | ### Met maatwerk | Bouwsteen | Toelichting | | ----------------- | ---------------------------------------------------------------------- | | **MijnProducten** | Mogelijk via Producttypecatalogus / Objecten API; vereist configuratie | | **MijnActies** | Mogelijk via notificatiesysteem; vereist maatwerk | ### Nog niet geïmplementeerd MijnPlan, MijnGesprek en MijnAgenda zijn nieuw in de VNG-roadmap. De onderliggende standaarden zijn nog niet vastgesteld. NL Portal volgt de ontwikkeling en implementeert zodra standaarden beschikbaar zijn. *** ## Ritense als erkende MijnServices-leverancier VNG houdt een officieel register bij van leveranciers wier software voldoet aan MijnServices. **Ritense — en daarmee NL Portal — staat op deze erkende leverancierslijst.** Andere erkende leveranciers zijn onder meer: OpenZaak, Shift2, Decos, ICATT, 2AT, Eviden, Visma-Roxit, Yard, EnableU, XXLLNC, Salesforce, Innovadis, Maykin, Brightfox, WoWeb, Pinkroccade, Acato, Worth, Genetics, WeAreFrank, Conduction en Visma Circle. *** ## Wat VNG aanbiedt aan gemeenten VNG ondersteunt gemeenten bij de adoptie van MijnServices met: * Een gratis **stappenplan** (PDF, december 2024) * Maandelijkse online introductiesessies met drie verdiepingssporen: implementatieadvies, service blueprints en architectuur * **Subsidiemogelijkheden** * Referentiearchitectuur (bedrijfs- en informatieperspectief) * NL Design System-richtlijnen en Storybook-ontwerpen Implementatie-inspanning: **300–850 uur** voor een team van 4–21 medewerkers (VNG-schatting). Aanbevolen volgorde: 1. Start met **MijnZaken** — implementeer ZGW APIs in het backofficesysteem 2. Voeg **MijnTaken, MijnBerichten, MijnContactmomenten** toe — vereist Klantinteracties API 3. Implementeer een **Notificatieservice** voor proactieve updates 4. Stel een **burgerfacing portal** in (zoals NL Portal) dat de APIs ontsluit → [MijnServices stappenplan (PDF)](https://vng.nl/sites/default/files/2024-12/mijnservices-stappenplan.pdf) → [VNG MijnServices](https://vng.nl/MijnServices) *** ## Huidige gebruikers NL Portal wordt al ingezet door tientallen gemeenten, waaronder Rotterdam, Den Haag, Nijmegen, Deventer, Tilburg, Groningen, Leeuwarden, Zwolle, Enschede, Arnhem en vele anderen. Sommige gemeenten werken samen via Dimpact of OpenWebconcept. # Open source en governance ## Licentie NL Portal is gepubliceerd onder de **EUPL 1.2** (European Union Public Licence). Dit is dezelfde licentie als gebruikt door Common Ground, Open Zaak, het NL Design System en andere overheidsinitiatieven in Nederland. De EUPL 1.2: * Is goedgekeurd door de Europese Commissie * Verplicht openbaarmaking van wijzigingen bij distributie (copyleft) * Is compatibel met GPL, LGPL en andere open source licenties * Geeft gemeenten het recht de software vrij te gebruiken, te wijzigen en te distribueren *** ## Community-gedreven ontwikkeling NL Portal wordt ontwikkeld in samenwerking met gemeenten en andere overheden. De code staat volledig publiek beschikbaar op GitHub onder de [nl-portal](https://github.com/nl-portal/) organisatie. **Bijdragen**: * Issues en feature requests via de GitHub repositories * Pull requests zijn welkom; zie [Bijdragen aan NL Portal](/nl-portal-docs-revision/community-en-bijdragen/contributing) voor de werkwijze * Maandelijkse releases; urgente fixes op aanvraag *** ## Rol van Ritense **Ritense** is de maintainer van NL Portal. Ritense: * Beheert de centrale repositories en doet de releases * Is officieel erkend als **VNG MijnServices-leverancier** * Is een bijdragende partij aan het **Platform Generieke Dienstverlening (PGD)**, specifiek aan de Zaakgericht Werken- en Objecten-standaarden * Biedt commerciële ondersteuning, hosting en maatwerkontwikkeling voor gemeenten NL Portal is onderdeel van de bredere **Ritense**-suite voor zaakgericht werken, maar functioneert als zelfstandig component en is bruikbaar naast andere backofficesystemen. *** ## Repositories | Repository | Inhoud | | ----------------------------------------------------------------------------------------- | -------------------------------------------- | | [nl-portal-frontend-libraries](https://github.com/nl-portal/nl-portal-frontend-libraries) | React-componentenbibliotheek (npm-pakketten) | | [nl-portal-backend-libraries](https://github.com/nl-portal/nl-portal-backend-libraries) | Spring Boot-bibliotheekmodules | | [nl-portal-app](https://github.com/nl-portal/nl-portal-app) | Referentie-implementatie | | [helm-charts](https://github.com/nl-portal/helm-charts) | Helm Chart voor Kubernetes-deployment | → Zie [Repositories](/nl-portal-docs-revision/community-en-bijdragen/repositories) voor een volledig overzicht. # Wat kan NL Portal? NL Portal implementeert een selectie van de **VNG MijnServices**-bouwstenen. Dit overzicht beschrijft wat de burger ziet, welke backoffice-koppeling vereist is, en wat beschikbaar is zonder en met maatwerk. *** ## In deze sectie * [Functionaliteiten per MijnServices-bouwsteen](/nl-portal-docs-revision/wat-kan-nl-portal/wat-kan-nl-portal/functionaliteiten) — Gedetailleerd overzicht per bouwsteen * [Authenticatie en toegang](/nl-portal-docs-revision/wat-kan-nl-portal/wat-kan-nl-portal/authenticatie) — DigiD, eHerkenning en de relatie met Wmebv *** ## Snel overzicht ### Out-of-the-box (zonder maatwerk) | Bouwsteen | Wat ziet de burger | | ----------------------- | ------------------------------------------------------ | | **MijnZaken** | Status en voortgang van ingediende aanvragen | | **MijnTaken** | Openstaande acties die de burger moet uitvoeren | | **MijnBerichten** | Officiële berichten en notificaties van de gemeente | | **MijnProfiel** | Persoonlijke contactgegevens en communicatievoorkeuren | | **MijnContactmomenten** | Overzicht van eerder contact met de gemeente | ### Met maatwerk | Bouwsteen | Toelichting | | ----------------- | ------------------------------------------------------------------------------ | | **MijnProducten** | Verleende producten en diensten; vereist configuratie via Producttypecatalogus | | **MijnActies** | Proactieve acties; vereist maatwerk op notificatielogica | ### Nog niet geïmplementeerd MijnPlan, MijnGesprek en MijnAgenda zijn nieuwe bouwstenen in de VNG-roadmap. De technische standaarden zijn nog in ontwikkeling. # Functionaliteiten per MijnServices-bouwsteen Per bouwsteen een beschrijving van wat de burger ziet, welke backoffice-koppeling vereist is, en de rijpheidsstatus van de onderliggende standaard. ![MijnServices-bouwstenen overzicht](/files/PC3a7eEMZsLLrT0QNuu2) *** ## Out-of-the-box (zonder maatwerk) ### MijnZaken **Wat ziet de burger?** Een overzicht van alle ingediende aanvragen, met de huidige status en voortgang. De burger kan documenten bekijken die aan een zaak gekoppeld zijn. **Vereiste backoffice-koppeling** * ZGW Zaken API — zaakregistratie en statussen * ZGW Catalogi API — zaaktypecatalogus (ZTC) voor omschrijvingen * ZGW Documenten API — zaakgerelateerde documenten **Referentie-implementatie backoffice**: [Open Zaak](https://openzaak.org/) **Rijpheid standaard**: Standaard (formeel vastgesteld, meest volwassen van alle MijnServices-bouwstenen) *** ### MijnTaken **Wat ziet de burger?** Een lijst van openstaande acties die de burger moet uitvoeren om een zaak voort te zetten — zoals het invullen van een formulier, doen van een betaling of bevestigen van een afspraak. **Vereiste backoffice-koppeling** * Objecten API — taken worden als objecten opgeslagen * Objecttypen API — voor de typedefinitie van taken NL Portal implementeert het **Externe Klanttaak V2-patroon** (Platform Generieke Dienstverlening). Taken worden aangemaakt door het zaakafhandelingssysteem (bijv. ZAC) en door NL Portal opgehaald en gepresenteerd. **Rijpheid standaard**: Candidate *** ### MijnBerichten **Wat ziet de burger?** Officiële berichten van de gemeente, zoals beschikkingen, bevestigingen en beslissingen. De burger kan berichten inzien en beantwoorden. **Vereiste backoffice-koppeling** * Klantinteracties API — berichten en klantcontact * Contactgegevens API — koppeling aan burgergegevens **Referentie-implementatie**: [Open Klant](https://github.com/maykinmedia/open-klant) (implementatie van de Klantinteracties API en Contactgegevens API door Maykin Media) **Wettelijke context**: MijnBerichten is een van de bouwstenen die VNG aanbeveelt voor **Wmebv**-compliance (in werking per 1 januari 2026), naast OMC Notify. NL Portal draagt met MijnBerichten bij aan de invulling van een deel van de Wmebv-vereisten. **Rijpheid standaard**: Candidate — actief in standaardisatieproces bij VNG; Rijksoverheid betrokken *** ### MijnProfiel **Wat ziet de burger?** Persoonlijke contactgegevens en communicatievoorkeuren: via welk kanaal de burger benaderd wil worden en welke contactgegevens de gemeente heeft. **Vereiste backoffice-koppeling** * Contactgegevens API — opslaan en opvragen van contactgegevens en voorkeuren **Referentie-implementatie**: Open Klant (versie 2) **Rijpheid standaard**: Candidate *** ### MijnContactmomenten **Wat ziet de burger?** Een overzicht van eerder contact tussen de burger en de gemeente — telefoongesprekken, e-mails, bezoeken aan de balie — gekoppeld aan zaken. **Vereiste backoffice-koppeling** * Klantinteracties API — registratie en opvragen van contactmomenten **Referentie-implementatie**: Open Klant (versie 2) **Rijpheid standaard**: Candidate *** ## Met maatwerk ### MijnProducten **Wat ziet de burger?** Een overzicht van verleende producten en diensten — zoals een goedgekeurde vergunning, toegekende subsidie of actief abonnement. **Vereiste backoffice-koppeling** * Producttypecatalogus / Objecten API — productregistraties **Referentie-implementatie**: [Open Product](https://github.com/maykinmedia/open-product) **Toelichting**: NL Portal biedt ondersteuning voor MijnProducten, maar de configuratie vereist afstemming op het specifieke productregister van de gemeente. **Rijpheid standaard**: Community *** ### MijnActies **Wat ziet de burger?** Proactieve acties die de gemeente aanbiedt — bijvoorbeeld een herinnering dat een parkeervergunning verlengd kan worden. **Toelichting**: De onderliggende standaard is nog in ontwikkeling bij VNG. NL Portal biedt basisondersteuning, maar volledige implementatie vereist maatwerk op de notificatielogica. **Rijpheid standaard**: Community *** ## Nog niet geïmplementeerd | Bouwsteen | Status | | --------------- | ---------------------------------------------------- | | **MijnPlan** | Nieuw in VNG-roadmap; standaard nog niet vastgesteld | | **MijnGesprek** | Nieuw in VNG-roadmap; standaard nog niet vastgesteld | | **MijnAgenda** | Nieuw in VNG-roadmap; standaard nog niet vastgesteld | NL Portal volgt de ontwikkeling van deze bouwstenen. Zodra VNG de standaarden heeft vastgesteld, wordt implementatie in de roadmap opgenomen. → Zie [Roadmap](/nl-portal-docs-revision/product-management/roadmap) voor de huidige planningen. # Authenticatie en toegang NL Portal biedt ondersteuning voor de twee standaard authenticatiemiddelen van de Nederlandse overheid: **DigiD** voor burgers en **eHerkenning** voor ondernemers. *** ## DigiD DigiD is het digitale identiteitsmiddel waarmee Nederlandse burgers zich identificeren bij overheidsinstanties. NL Portal gebruikt DigiD voor de authenticatie van burgers. Na een succesvolle DigiD-login ontvangt NL Portal het BSN (Burgerservicenummer) van de burger. Dit BSN wordt gebruikt om: * Persoonsgegevens op te halen bij de BRP (Basisregistratie Personen, via Haalcentraal) * Zaken, taken, berichten en contactmomenten op te halen die aan de burger gekoppeld zijn **Wmebv-relatie**: DigiD is het authenticatiemiddel dat Wmebv vereist voor formele berichtgeving aan burgers. MijnBerichten in NL Portal is uitsluitend beschikbaar voor ingelogde DigiD-gebruikers. *** ## eHerkenning eHerkenning is het authenticatiemiddel voor ondernemers en rechtspersonen. NL Portal biedt ondersteuning voor eHerkenning zodat ondernemers namens een bedrijf kunnen inloggen en zakelijke zaken kunnen inzien. Na een succesvolle eHerkenning-login ontvangt NL Portal het KVK-nummer. Dit wordt gebruikt om: * Bedrijfsgegevens op te halen bij het Handelsregister (via Haalcentraal HR) * Zaken en taken op te halen die aan het bedrijf gekoppeld zijn *** ## Technische uitwerking De authenticatie verloopt via **OpenID Connect (OIDC)**. NL Portal fungeert als OIDC-client; DigiD en eHerkenning zijn de identity providers, doorgaans via een intermediaire identity broker (zoals Keycloak). Het BSN of KVK-nummer belandt via een **token exchange** in het authenticatietoken waarmee NL Portal de backoffice-APIs benadert. Dit mechanisme zorgt dat de gebruikersidentiteit veilig meegegeven wordt aan de ZGW-services, zonder dat het portaal zelf gevoelige gegevens hoeft op te slaan. → Zie [Authenticatie en token exchange](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/authenticatie-en-tokenexchange) voor de conceptuele werking. # Hoe werkt NL Portal? NL Portal is een component in het **Common Ground vijflagenmodel** — specifiek laag 5, de interactielaag. Het portaal beheert zelf geen data, maar aggregeert informatie uit bestaande bronregistraties en presenteert die aan de burger via een uniforme interface. *** ## Componenten NL Portal bestaat uit drie lagen: | Laag | Technologie | Doel | | --------------- | -------------------------------------- | --------------------------------------------------------------------- | | **Frontend** | React 19, TypeScript, NL Design System | Burgerfacing interface; thematiseerbaar per gemeente | | **Backend** | Kotlin, Spring Boot | GraphQL-aggregatielaag; vertaalt burgervragen naar ZGW REST API-calls | | **GraphQL API** | GraphQL | Enkelvoudig API-oppervlak tussen frontend en backend | De backend fungeert als **vertaallaag**: de frontend stelt één GraphQL-query in, de backend vertaalt dat naar meerdere REST API-aanroepen op de backoffice-systemen (zaaksysteem, klantregistratie, BRP, etc.) en combineert de resultaten. *** ## Positie in het Common Ground vijflagenmodel ``` Laag 5 — Interactie ← NL Portal (burgerpersoonlijke omgeving) Laag 4 — Proces ← Zaakafhandelingscomponent (bijv. GZAC, ZAC) Laag 3 — Integratie ← API-gateway, authenticatieservices Laag 2 — Services ← Open Zaak, Open Klant, Haalcentraal Laag 1 — Data ← Bronregistraties (ZRC, DRC, BRC, KIC, BRP) ``` NL Portal bevindt zich bovenaan de stack. Het bevraagt de services in laag 2 via gestandaardiseerde APIs en slaat zelf geen zaak- of persoonsgegevens op. Dit is het "data bij de bron"-principe van Common Ground. *** ## Scope van NL Portal **In scope:** * Communicatie met de burger (MijnZaken, MijnTaken, MijnBerichten, MijnProfiel, MijnContactmomenten) * Aggregatie van gegevens uit meerdere bronregistraties * Huisstijlinpassing via NL Design System tokens **Buiten scope:** * Zaakafhandeling (dat is het domein van ZAC/GZAC) * Formulieren (dat is het domein van een formuliercomponent) * Content management (dat is het domein van een CMS) * Notificaties via e-mail/sms (dat is het domein van NL Notify of vergelijkbaar) * Authenticatie (dat is het domein van DigiD-aansluiting + Keycloak) *** ## In deze sectie * [Integraties](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/integraties) — Welke API-standaarden en referentie-implementaties * [Patronen](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/patronen) — Externe Klanttaak, Berichten en Verzoeken * [Authenticatie en token exchange](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/authenticatie-en-tokenexchange) — Hoe BSN/KVK veilig meegegeven wordt aan backoffice-APIs # Integraties NL Portal communiceert met externe systemen via gestandaardiseerde VNG API-standaarden. De onderstaande tabel geeft een overzicht van alle integraties: welke standaard gebruikt wordt, waarvoor, en welke referentie-implementatie er bestaat. ![Architectuur en integraties](/files/0x8lLcxkuahojxEfgX7S) *** ## Overzicht | Integratie | Standaard | Referentie-implementatie | MijnServices-bouwsteen | | ----------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------- | | Zaken, documenten, besluiten | ZGW-suite: Zaken API, Catalogi API, Documenten API, Besluiten API | [Open Zaak](https://openzaak.org/) | MijnZaken | | Klantinteracties en berichten | Klantinteracties API + Contactgegevens API | [Open Klant](https://github.com/maykinmedia/open-klant) (v2) | MijnBerichten, MijnContactmomenten, MijnProfiel | | Taken | Objecten API + Objecttypen API | [Open Zaak Objecten](https://github.com/open-zaak/open-zaak) | MijnTaken | | Persoonsgegevens | Haalcentraal BRP Personen API v2 | — (via gemeentelijke BRP-aansluiting) | MijnProfiel | | Bedrijfsgegevens | Haalcentraal Handelsregister API | — (via gemeentelijke HR-aansluiting) | Ondernemer-login | | Producten en diensten | Producttypecatalogus / Objecten API | [Open Product](https://github.com/maykinmedia/open-product) | MijnProducten | | Notificaties | Notificaties API (ZGW-suite) | [Open Notificaties](https://github.com/open-zaak/open-notificaties) | Notificatieservice | | Autorisatie | ZGW Autorisaties API | Open Zaak | — | *** ## ZGW API-suite De **ZGW API-suite** is een formeel vastgestelde VNG-standaard (versie 1.5) gebaseerd op het RGBZ 2.1-informatiemodel. Het is de meest volwassen standaard in het MijnServices-ecosysteem. De suite bestaat uit: * **Zaken API** — zaakregistratie en -opvraging; statussen en rollen * **Catalogi API** — zaaktypecatalogus (ZTC); bepaalt welke zaaktypen en statussen bestaan * **Documenten API** — documenten gekoppeld aan zaken (zaakinformatieobjecten) * **Besluiten API** — besluiten gekoppeld aan zaken * **Notificaties API** — event-routing tussen componenten (informatie-arm principe) * **Autorisaties API** — autorisatiebeheer voor ZGW API-consumers Specificaties: [vng-realisatie.github.io/gemma-zaken](https://vng-realisatie.github.io/gemma-zaken/standaard/) **Referentie-implementatie**: [Open Zaak](https://openzaak.org/) (Maykin Media, in gebruik bij \~40 gemeenten) *** ## Klantinteracties API en Contactgegevens API Deze standaarden vervangen de verouderde Klanten API en Contactmomenten API. Ze worden gebruikt voor MijnBerichten, MijnContactmomenten en MijnProfiel. > **Let op**: *Open Klant* is de **referentie-implementatie** van deze standaarden — geen standaard zelf. Versie 2 van Open Klant implementeert de Klantinteracties API en de Contactgegevens API. Specificaties: [vng-realisatie.github.io/klantinteracties](https://vng-realisatie.github.io/klantinteracties/) **Status**: De standaard is bij VNG Realisatie gepubliceerd "as is, where is" onder EUPL. Actieve doorontwikkeling is momenteel gepauzeerd. Open Klant is ontwikkeld door Maykin Media, samen met VNG Realisatie en gemeenten Amsterdam, Den Haag en Utrecht. *** ## Haalcentraal BRP Personen API NL Portal haalt persoonsgegevens op via de **Haalcentraal BRP Personen API v2**. Hiermee worden naam, adres en andere BRP-gegevens getoond in het profiel van de burger — direct uit de bronregistratie, zonder lokale opslag. **Vereiste**: een gemeentelijke aansluiting op de BRP via een betrouwbare tussenschakel. *** ## Haalcentraal Handelsregister Voor ondernemers die inloggen via eHerkenning worden bedrijfsgegevens opgehaald via de **Haalcentraal HR API** (Handelsregister). *** ## Objecten API en Objecttypen API De Objecten API is een flexibele VNG-standaard voor het opslaan van generieke objecten. NL Portal gebruikt deze API voor het ophalen van taken (MijnTaken). De taken worden aangemaakt door het zaakafhandelingssysteem en als objecten opgeslagen. De Objecten API is aangewezen als "community standard" door VNG en wordt ook gebruikt voor productregistraties (MijnProducten). *** ## Autorisatie via ZGW Autorisaties API Elke consumer van de ZGW API-suite heeft een autorisatieprofiel nodig. De ZGW Autorisaties API regelt welke zaaktypen, informatieobjecttypen en besluittypen een consumer mag opvragen. NL Portal heeft een autorisatieprofiel nodig dat overeenkomt met de zaaktypen die burgers mogen inzien. → Zie [Koppelingen](/nl-portal-docs-revision/koppelingen/koppelingen) voor hoe dit in de praktijk wordt ingesteld. # Patronen NL Portal implementeert technische interactiepatronen die zijn vastgelegd door het **Platform Generieke Dienstverlening (PGD)**. Deze patronen beschrijven hoe componenten met elkaar communiceren en vormen de technische blauwdruk achter de MijnServices-bouwstenen. → Zie [Platform Generieke Dienstverlening](/nl-portal-docs-revision/platform-generieke-dienstverlening/platform-generieke-dienstverlening) voor de bredere context van PGD. *** ## Externe Klanttaak (Taak V2) Het **Externe Klanttaak**-patroon beschrijft hoe taken worden aangemaakt door het zaakafhandelingssysteem en beschikbaar worden gesteld aan de burger via het portaal. ![Externe Klanttaak flow](/files/f2L3llJTlGikyVf5XYCA) NL Portal implementeert dit patroon als **Taak V2**. Taken worden opgeslagen als objecten in de Objecten API en opgehaald door het portaal. ### Workflow ``` 1. Zaakafhandelingscomponent maakt taak aan in Objecten API 2. Notificatieservice brengt NL Portal op de hoogte 3. Burger logt in → ziet taak in MijnTaken 4. Burger voert taak uit (formulier, betaling, of URL-taak) 5. NL Portal werkt de taakstatus bij in de Objecten API 6. Zaakafhandelingscomponent wordt genotificeerd → taak verdwijnt uit de wachtrij ``` ### Taaktypen | Type | Beschrijving | | ----------------- | ------------------------------------------------------ | | **URL-taak** | Link naar een externe bron; burger wordt doorgestuurd | | **Formuliertaak** | FormIO-formulier dat binnen het portaal wordt ingevuld | | **Betaaltaak** | Geïntegreerd betalingsverzoek | **Belangrijk**: Taken zijn archiefobjecten met een permanente bewaarplicht. NL Portal mag taken tonen maar niet verwijderen — dat is de verantwoordelijkheid van het zaakafhandelingscomponent. *** ## Berichten Het **Berichten**-patroon beschrijft hoe officiële berichten van de gemeente aan burgers worden afgeleverd. Berichten zijn altijd gekoppeld aan een document en optioneel aan een zaak. NL Portal ondersteunt drie kanalen: * **Digitale notificatie** in het portaal (MijnBerichten) * Doorstuur naar **MijnOverheid BerichtenBox** (voor DigiD-gebruikers) * **Fysieke post** als terugvaloptie **Wmebv-relatie**: Het Berichten-patroon draagt bij aan de invulling van de wettelijke berichtenplicht (Wmebv, 1 januari 2026). MijnBerichten is één van de aanbevolen bouwstenen — volledige Wmebv-compliance vereist ook OMC Notify voor notificaties. **Technische beperking**: Per Logius-standaarden mag de berichttekst alleen platte tekst bevatten (URLs en regeleindes; geen HTML-opmaak). *** ## Verzoeken Het **Verzoeken**-patroon beschrijft hoe burgers aanvragen indienen bij de gemeente. Dit is een asynchroon patroon: ``` 1. Burger dient verzoek in via NL Portal → verzoek wordt als object opgeslagen in Objecten API 2. Objecten API notificeert het notificatiecomponent 3. Zaakafhandelingscomponent is geabonneerd op notificaties van dit type → wordt op de hoogte gesteld 4. Zaakafhandelingscomponent haalt het verzoek op uit de Objecten API en start de zaakafhandeling ``` Het verzoek bevat geen gevoelige data in de notificatie zelf (informatie-arm principe van Common Ground) — alleen een verwijzing naar het object. *** ## Synchrone en asynchrone communicatie NL Portal gebruikt beide communicatiestijlen: | Stijl | Gebruik | Voorbeeld | | ----------------------- | -------------------------------------- | --------------------------------- | | **Synchroon** (REST) | Direct opvragen van data voor weergave | Zaken ophalen bij Open Zaak | | **Asynchroon** (events) | Verwerking van inkomende acties | Verzoek indienen via Objecten API | Synchrone communicatie is eenvoudig maar maakt NL Portal afhankelijk van de beschikbaarheid en snelheid van de backoffice-service. Asynchrone communicatie via de Notificaties API maakt de koppeling losser: de services kennen elkaar niet direct. # Authenticatie en token exchange ## Overzicht NL Portal gebruikt **OpenID Connect (OIDC)** als authenticatieprotocol. De burger logt in via DigiD of eHerkenning — de identity provider stuurt een OIDC-token terug naar NL Portal. Dit token bevat echter nog géén BSN of KVK-nummer: die gevoelige identifiers worden pas later toegevoegd via een **token exchange**. *** ## Waarom token exchange? De backoffice-systemen (ZGW APIs, Klantinteracties API) moeten weten namens welke burger een aanvraag wordt gedaan. Ze verwachten het BSN of KVK-nummer in het authenticatietoken. Het BSN mag niet in het initiële inlogtoken staan — dat token wordt ook door de frontend gebruikt en mag geen gevoelige persoonsgegevens bevatten. De oplossing is een **token exchange**: ``` 1. Burger logt in via DigiD/eHerkenning → OIDC-token (zonder BSN) 2. Frontend stuurt API-aanvraag naar NL Portal backend 3. Backend onderschept het token en doet een token exchange call 4. Identity broker (Keycloak) geeft een nieuw token terug met BSN/KVK 5. Backend gebruikt dit verrijkte token voor calls naar ZGW-services ``` Het BSN/KVK-nummer verlaat de backend nooit naar de frontend. De burger ziet zijn eigen gegevens, maar de identifier is nooit zichtbaar in de browser. *** ## Betrokken componenten | Component | Rol | | -------------------------------------- | -------------------------------------------------------------------------------- | | **DigiD / eHerkenning** | Identity provider; voert de daadwerkelijke authenticatie uit | | **Keycloak** (of vergelijkbare broker) | OIDC-broker; voert de token exchange uit en voegt BSN/KVK toe | | **NL Portal backend** | OIDC-client; onderschept tokens en gebruikt verrijkt token voor backoffice-calls | | **ZGW-services** | Ontvangt verrijkt token en autoriseer op BSN/KVK | *** ## Relatie met eHerkenning (ondernemers) Voor ondernemers verloopt het proces identiek, maar met KVK-nummer in plaats van BSN. eHerkenning is het authenticatiemiddel; de Keycloak-broker voegt het KVK-nummer toe tijdens de token exchange. *** > **Technische configuratie**: De concrete configuratie van Keycloak (clients, mappers, policies) valt buiten de scope van deze documentatie. Raadpleeg de [Helm Chart](https://github.com/nl-portal/helm-charts) voor deployment-specifieke configuratie. # Configuration Panel Het Configuration Panel is de beheerapplicatie van NL Portal. Beheerders kunnen hiermee de portal configureren via een gebruikersinterface — zonder omgevingsvariabelen of configuratiebestanden handmatig aan te passen. *** ## Wat kan je ermee? Het panel biedt toegang tot drie onderdelen: * **Features** — Integraties met externe systemen in- of uitschakelen en de bijbehorende instellingen beheren * **Logo** — Het logo van de portal uploaden, bekijken of verwijderen * **Stijl** — CSS-aanpassingen instellen voor de portal *** ## Features per MijnServices-bouwsteen De features in het panel komen overeen met de koppelingen die nodig zijn voor de MijnServices-bouwstenen. Welke features je inschakelt, bepaalt welke functionaliteit beschikbaar is voor de burger. ### MijnZaken Zakoverzicht en documentinzage voor de burger. | Feature | Omschrijving | | -------------- | ----------------------------------------------- | | Zaken API | Zaakregistratie en statussen | | Catalogi API | Zaaktypecatalogus (omschrijvingen en statussen) | | Documenten API | Documenten gekoppeld aan zaken | | Besluiten API | Besluiten en beschikkingen | → Zie [Integraties](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/integraties) voor meer over de ZGW API-suite. *** ### MijnTaken Openstaande acties die de burger moet uitvoeren. | Feature | Omschrijving | | --------------- | ----------------------------------- | | Objects API | Ophalen van taken als objecten | | Objecttypes API | Typedefinities van taken | | Taak | Takenbeheer en formulierkoppelingen | *** ### MijnBerichten, MijnContactmomenten en MijnProfiel Officiële berichten, contactgeschiedenis en contactgegevens — allemaal via Open Klant 2. | Feature | Omschrijving | | ----------- | ---------------------------------------------------- | | OpenKlant 2 | Klantinteracties API en Contactgegevens API | | Berichten | Berichtenservice voor Wmebv-conforme correspondentie | *** ### MijnProfiel — persoonsgegevens | Feature | Omschrijving | | ---------------- | ---------------------------------------------------------------- | | HaalCentraal BRP | Persoonsgegevens van burgers (BRP Personen API v2) | | HaalCentraal HR | Bedrijfsgegevens via het Handelsregister (voor ondernemer-login) | | HaalCentraal 2 | Gecombineerde HaalCentraal-interface | *** ### MijnProducten Overzicht van verleende producten en diensten. | Feature | Omschrijving | | --------------- | --------------------------------- | | OpenProduct(en) | Productcatalogus via Open Product | > MijnProducten vereist afstemming op het productregister van de gemeente. Zie [Functionaliteiten](/nl-portal-docs-revision/wat-kan-nl-portal/wat-kan-nl-portal/functionaliteiten). *** ## Overige features De volgende features zijn niet direct gekoppeld aan één MijnServices-bouwsteen, maar ondersteunen de portal als geheel. | Feature | Omschrijving | | ---------------- | ------------------------------------------------- | | Ogone betaling | Betaalgateway Ogone (voor betaaltaken) | | Directe betaling | Directe betalingsintegratie (voor betaaltaken) | | ClamAV | Virusscan bij bestandsuploads | | DMN | Bedrijfsregels (Decision Model & Notation) | | Prefill | Voorinvullen van formulieren met bekende gegevens | *** ## Toegang en beveiliging Het Configuration Panel is een aparte applicatie die naast NL Portal draait. Toegang vereist inloggen via Keycloak — dezelfde authenticatieinfrastructuur als de portal zelf. Het panel is bereikbaar op **poort 3001**. *** ## Opstarten Het panel wordt meegeleverd als Docker Compose-profiel: ```bash docker compose --profile config up ``` *** ## Versiecompatibiliteit | Configuration Panel | NL Portal | | ------------------- | --------- | | 2.0.0 | 3.0.0 | | 1.0.0 | 2.0.2 | # NL Design System **NL Design System (NLDS)** is het gedeelde design system voor Nederlandse overheidsdigitale diensten, beheerd door **ICTU** namens het **Ministerie van Binnenlandse Zaken en Koninkrijksrelaties (BZK)**. NL Portal is gebouwd op NLDS-componenten. Dit betekent dat elke gemeente de eigen huisstijl kan toepassen **zonder ontwikkelwerk** — puur via een CSS-tokenbestand. *** ## In deze sectie * [Hoe NLDS werkt](/nl-portal-docs-revision/nl-design-system-en-huisstijl/nl-design-system) — Het drielaags tokenmodel en het Estafettemodel (deze pagina) * [Huisstijl toepassen](/nl-portal-docs-revision/nl-design-system-en-huisstijl/nl-design-system/huisstijl) — Stap-voor-stap: eigen huisstijl configureren *** ## Wat is NLDS? NLDS is **geen monolithisch design system** maar een architectuur en een community: een set van standaarden, processen en gedeelde bouwstenen die elke overheidsorganisatie kan adopteren en thematiëren naar de eigen huisstijl. Licentie: EUPL 1.2 — gelijk aan NL Portal en Common Ground. *** ## Het drielaags design token-model NLDS werkt met een hiërarchie van **design tokens** — CSS-variabelen die ontwerpbeslissingen vastleggen zoals kleuren, lettertypes en afstanden. Er zijn drie lagen: ### Laag 1 — Brand tokens De ruwe visuele waarden van de organisatie: specifieke kleuren, lettertypes, border radii. Organisaties hebben hier volledige vrijheid in naamgeving. Deze tokens representeren het merkpalet zonder semantische betekenis. ```css --gemeente-den-haag-color-cyan: #00A6D6; ``` ### Laag 2 — Common tokens Semantische tokens die relevant zijn voor veel componenten: feedbackkleuren (fout, waarschuwing, succes), focusstates, spacingschalen. Zorgen voor consistente UX-patronen ongeacht het merk. ```css --nl-color-primary: var(--gemeente-den-haag-color-cyan); ``` ### Laag 3 — Component tokens Tokens voor een specifiek component, die waarden overnemen van Common tokens. Elk NLDS-component gebruikt standaard component tokens om herbruikbaar te zijn. ```css --button-background-color: var(--nl-color-primary); ``` **Naamgevingsconventie**: `{organisatie}.{component}.{element}.{modifier}.{css-eigenschap}` Door organisatiespecifieke Brand tokens aan Common tokens te koppelen, past de volledige interface automatisch aan de huisstijl — van knoppen tot formulieren tot navigatie. *** ## Het Estafettemodel NLDS hanteert het **Estafettemodel** om de rijpheid van componenten bij te houden: | Status | Beschrijving | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Help Wanted** | Component geïdentificeerd als nodig; community wordt uitgenodigd te starten | | **Community** | Organisaties bouwen en delen implementaties; meerdere varianten mogelijk | | **Candidate** | Component is gegeneraliseerd, breed ingezet en open voor eindreview | | **Hall of Fame** | Definitieve stabiele versie; gegarandeerd toegankelijk en herbruikbaar; in productie bij minimaal 2 organisaties met verschillende huisstijlen | NL Portal-componenten streven naar **Candidate** of **Hall of Fame** status. *** ## Welke organisaties gebruiken NLDS? | Groep | Omvang | | ------------------------------------------------ | -------------- | | **OpenWebconcept** — community van gemeenten | \~40 gemeenten | | **Dimpact** — associatie van gemeenten | \~40 gemeenten | | **G4** — Amsterdam, Rotterdam, Den Haag, Utrecht | 4 steden | **Individuele gemeenten met eigen NLDS-gebaseerd design system:** * Den Haag (`nl-design-system/denhaag`) — referentie-implementatie voor NL Portal * Utrecht (`nl-design-system/utrecht`) — meest complete referentie * Rotterdam (`nl-design-system/rotterdam`) **Rijksoverheid:** * Logius / DigiD / MijnOverheid — via "Lux: Logius Design System" * RVO — ROOS (RVO Open Ontwerp Systeem) *** ## NLDS en Common Ground NLDS en Common Ground zijn complementaire initiatieven: * Beide zijn open source onder EUPL 1.2 * Beide zijn VNG-gelieerd en richten zich op dezelfde doelgroep * Common Ground adresseert de **data/API-architectuurlaag**; NLDS adresseert de **interactie/presentatielaag** * NL Portal is waar ze direct samenkomen → [Doorontwikkeling NL Design System — Digitale Overheid](https://www.digitaleoverheid.nl/innovatieproject/doorontwikkeling-nl-design-system/) → [nldesignsystem.nl](https://nldesignsystem.nl/) # Huisstijl toepassen NL Portal is volledig thematiseerbaar via **NL Design System design tokens**. Eigen huisstijl toepassen is een configuratietaak — geen ontwikkelwerk. *** ## Hoe het werkt NL Portal-componenten zijn opgebouwd met NLDS-componenttokens. Door de Brand- en Common tokens van uw gemeente te definiëren, past de volledige interface automatisch aan: ``` Brand tokens (uw kleuren, lettertypes) ↓ koppelen aan Common tokens (primaire kleur, achtergrond, tekst) ↓ worden overgenomen door Component tokens (knopkleur, koptekstkleur, linkkleur) ↓ sturen Alle NL Portal-componenten ``` *** ## Stap-voor-stap ### Stap 1 — Maak een tokenbestand aan In de frontend-template repository staat het bestand: `/src/styles/nl-portal-design-tokens.css` Dit bestand bevat de design tokens die de standaardwaarden overschrijven. Begin met de Brand tokens van uw gemeente: ```css /* Brand tokens — uw gemeentekleuren */ --gemeente-naam-color-primary: #1234AB; --gemeente-naam-color-secondary: #ABCDEF; --gemeente-naam-font-family: 'Uw Gemeentelettertype', sans-serif; ``` ### Stap 2 — Koppel Brand tokens aan Common tokens Wijs uw Brand tokens toe aan de NLDS-semantische laag: ```css /* Common tokens — semantische betekenis */ --nl-color-primary: var(--gemeente-naam-color-primary); --nl-color-secondary: var(--gemeente-naam-color-secondary); ``` ### Stap 3 — Controleer het resultaat Gebruik de browser-developer tools om te zien welk token een specifiek component aanstuurt. Selecteer een element → inspecteer de CSS-variabele in het rechterpaneel. De naam van het token is direct zichtbaar. Voorbeeld: een knop toont `--button-background-color: var(--nl-color-primary)`. Door `--nl-color-primary` te overschrijven met uw Brand token past de knopkleur automatisch aan. ### Stap 4 — Refereer aan de Den Haag-implementatie Gemeente Den Haag heeft een volledige NLDS-gebaseerde NL Portal-implementatie: * Repository: [Gemeente-DenHaag/nl-portal-libraries](https://github.com/Gemeente-DenHaag/nl-portal-libraries) * Tokenbestand als referentie: [nl-portal-design-tokens.css](https://github.com/nl-portal/nl-portal-frontend-template/blob/master/src/styles/nl-portal-design-tokens.css) *** ## Welke tokens NL Portal gebruikt NL Portal-componenten gebruiken de volgende NLDS-tokenlagen: | Token-categorie | Voorbeelden | | --------------- | ---------------------------------------------------------------- | | Kleuren | `--nl-color-primary`, `--nl-color-background`, `--nl-color-text` | | Typografie | `--nl-font-family`, `--nl-font-size-body` | | Spacing | `--nl-spacing-small`, `--nl-spacing-medium` | | Componenten | `--button-background-color`, `--header-bar-background-color` | Het meest volledige overzicht staat in het tokenbestand van de frontend-template: → [nl-portal-design-tokens.css op GitHub](https://github.com/nl-portal/nl-portal-frontend-template/blob/master/src/styles/nl-portal-design-tokens.css) *** ## Toegankelijkheid NLDS-componenten zijn ontworpen om te voldoen aan **WCAG 2.1 niveau AA** — de minimale toegankelijkheidseis voor overheidswebsites (Besluit digitale toegankelijkheid overheid). Door huisstijltokens toe te passen op NLDS-componenten, behoudt u deze toegankelijkheidsgarantie zolang u voldoende kleurcontrast handhaaft. > Controleer altijd het kleurcontrast van uw Brand tokens met een tool zoals de [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/). *** ## Figma NLDS publiceert een Figma Community Library voor ontwerpers: → [NL Design System Bibliotheek — Figma](https://www.figma.com/community/file/1508831915902670059/nl-design-system-bibliotheek) Ontwerpers kunnen hiermee op basis van de NLDS-componenten een gemeentespecifiek prototype bouwen dat 1-op-1 overeenkomt met de implementatie in NL Portal. # Koppelingen NL Portal sluit aan op backoffice-systemen via gestandaardiseerde VNG API-standaarden. Op deze pagina staat beschreven welke systemen gekoppeld kunnen worden, wat er aan beide kanten nodig is, en hoe autorisatie werkt. *** ## Welke systemen kan NL Portal koppelen? | Systeem | Doel | Vereiste API | | ------------------------------------------------ | ------------------------------------- | ------------------------------------------- | | **Zaaksysteem** (bijv. Open Zaak) | Zaken, documenten en besluiten tonen | ZGW Zaken API, Catalogi API, Documenten API | | **Klantregistratie** (bijv. Open Klant v2) | Berichten, contactmomenten en profiel | Klantinteracties API, Contactgegevens API | | **Objectenregister** (bijv. Open Zaak Objecten) | Taken ophalen | Objecten API, Objecttypen API | | **BRP-aansluiting** | Persoonsgegevens opvragen | Haalcentraal BRP Personen API v2 | | **Handelsregister-aansluiting** | Bedrijfsgegevens opvragen | Haalcentraal HR API | | **Productencatalogus** (bijv. Open Product) | Producten en diensten tonen | Producttypecatalogus / Objecten API | | **Notificatieservice** (bijv. Open Notificaties) | Events ontvangen bij wijzigingen | Notificaties API (ZGW-suite) | *** ## Wat is er aan beide kanten nodig? ### Aan de kant van het externe systeem Voor elk aan te sluiten systeem moet een **API-account** worden aangemaakt voor NL Portal: 1. Maak in het backoffice-systeem een nieuwe applicatie (of client) aan 2. Ken de applicatie een **client ID** en een **secret** toe 3. Stel autorisaties in: welke zaaktypen, informatieobjecttypen of resources NL Portal mag opvragen ### Aan de kant van NL Portal NL Portal moet geconfigureerd worden met: * De **URL** van het externe systeem * Het **client ID** en **secret** van de aangemaakt applicatie > **Technische configuratie** (environment variables, Helm values) valt buiten de scope van deze documentatie. Raadpleeg de [NL Portal Helm Chart](https://github.com/nl-portal/helm-charts) voor deployment-specifieke configuratie. *** ## Autorisatie via de ZGW Autorisaties API Verbinding met een ZGW-systeem is niet voldoende — NL Portal heeft ook **autorisatie** nodig om zaakgegevens te mogen opvragen. Dit wordt geregeld via de **ZGW Autorisaties API**. In de Open Zaak-beheeromgeving stelt u in: * Welke **zaaktypen** NL Portal mag inzien * Welke **informatieobjecttypen** (documenttypen) zichtbaar zijn voor burgers * Welke **besluittypen** worden getoond **Aanbevolen instelling**: maak een autorisatieprofiel dat précies die zaaktypen toestaat die burgers mogen inzien. Het vinkje "heeft alle autorisaties" is uitsluitend bedoeld voor ontwikkelomgevingen. *** ## Sleutelbeheer De client ID en secret van elke koppeling zijn gevoelige gegevens. Gebruik voor opslag en beheer een secrets-management oplossing zoals: * [Azure Key Vault](https://azure.microsoft.com/en-us/products/key-vault) * [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) * HashiCorp Vault * Kubernetes Secrets (met versleuteling at rest) Sla secrets nooit op in versiebeheer. *** ## Meerdere omgevingen NL Portal ondersteunt aparte koppelingen per omgeving (development, acceptatie, productie). Elke omgeving krijgt eigen credentials. Raadpleeg de Helm Chart-documentatie voor de exacte configuratieopties. → [NL Portal Helm Charts](https://github.com/nl-portal/helm-charts) # Platform Generieke Dienstverlening ## Wat is PGD? Het **Platform Generieke Dienstverlening (PGD)** is de technische architectuurlaag onder **VNG MijnServices**. Waar MijnServices de burgerfacing bouwstenen beschrijft (wat de burger ziet), beschrijft PGD hoe die bouwstenen technisch werken: welke patronen, welke standaarden, welke referentiecomponenten. PGD is een Common Ground-initiatief, ontwikkeld in samenwerking tussen gemeenten, leveranciers en Dimpact. Het biedt één gezamenlijke plek voor architectuurafspraken, zodat conflicterende implementaties tussen gemeenten worden voorkomen. **Authoritative bron**: [Platform Generieke Dienstverlening — GitBook](https://dienstverleningsplatform.gitbook.io/platform-generieke-dienstverlening-public) *** ## Relatie met MijnServices PGD en MijnServices zijn complementair: | | MijnServices (VNG) | PGD | | --------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | **Perspectief** | Burger en gemeente | Architect en ontwikkelaar | | **Inhoud** | Bouwstenen en gebruikerswensen | Patronen, standaarden, referentiecomponenten | | **Rijpheid** | Politiek mandaat (NDS, Wmebv) | Technische uitwerking | | **Referentie** | [vng.nl/MijnServices](https://vng.nl/MijnServices) | [PGD GitBook](https://dienstverleningsplatform.gitbook.io/platform-generieke-dienstverlening-public) | MijnServices verwijst gemeenten naar PGD voor de technische uitwerking van de bouwstenen. *** ## Patronen in PGD PGD definieert technische interactiepatronen die beschrijven hoe componenten met elkaar communiceren. NL Portal implementeert drie van deze patronen: ### Externe Klanttaak Het patroon voor taken die burgers moeten uitvoeren. NL Portal implementeert dit als **Taak V2**: taken worden aangemaakt door het zaakafhandelingscomponent, opgeslagen in de Objecten API, en opgehaald en gepresenteerd door NL Portal. → Zie [Patronen — Externe Klanttaak](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/patronen#externe-klanttaak-taak-v2) ### Berichten Het patroon voor officiële berichtgeving aan burgers. Berichten zijn altijd gekoppeld aan documenten en optioneel aan zaken. Drie kanalen: digitaal portaal, MijnOverheid BerichtenBox, fysieke post. → Zie [Patronen — Berichten](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/patronen#berichten) ### Verzoeken Het patroon voor aanvragen die burgers indienen. Asynchroon: het verzoek wordt als object opgeslagen, waarna het zaakafhandelingscomponent via notificaties op de hoogte wordt gebracht. → Zie [Patronen — Verzoeken](/nl-portal-docs-revision/hoe-werkt-nl-portal/hoe-werkt-nl-portal/patronen#verzoeken) *** ## Standaarden in PGD PGD werkt met drie categorieën standaarden: | Standaard | Status | NL Portal | | -------------------------------------- | ------------------ | --------------------------------------------------- | | **Zaakgericht Werken** (ZGW API-suite) | In gebruik | Volledig geïmplementeerd | | **Objecten API** | In gebruik | Gebruikt voor taken en producten | | **Klantinteracties API** | Beproeving / pilot | Gebruikt voor berichten, contactmomenten en profiel | | **Producten** (Producttypecatalogus) | Concept | Basis aanwezig; vereist configuratie | De **ZGW API-suite** is de meest volwassen standaard in het ecosysteem — formeel vastgesteld door VNG (versie 1.5). De Klantinteracties API is gepubliceerd "as is, where is" bij VNG Realisatie; actieve doorontwikkeling is momenteel gepauzeerd. *** ## Ritense als bijdragende partij Ritense is **expliciet genoemde bijdragende leverancier** aan twee PGD-standaarden: * **Zaakgericht Werken** — bijdrage aan de ZGW API-standaard * **Objecten** — bijdrage aan de Objecten API-standaard Andere bijdragende gemeenten en leveranciers: Amsterdam, Den Haag, Dimpact, Rotterdam, Utrecht, Maykin, Atos. *** ## Governance en roadmap PGD heeft een tweewekelijkse overlegcyclus: * Dinsdagmiddag — architecten en ontwikkelaars * Vrijdagochtend — programmamanagers, leveranciers en projectbeheer Roadmap: [PGD Roadmap — Notion](https://www.notion.so/platformvoordienstverlening/Roadmap-e1ebdc0c60904c1a9c34b45388bc4ccd) Authoritative technische documentatie: [PGD GitBook](https://dienstverleningsplatform.gitbook.io/platform-generieke-dienstverlening-public) # Community en support ### Samen maken we NL Portal beter Door samen te werken, combineren we verschillende perspectieven om tot nieuwe ideeën te komen.\ Dit resulteert in betere en flexibelere oplossingen die voor iedereen effectief zijn. Een ander voordeel is het delen van kosten. We ontwikkelen een oplossing slechts één keer en\ doen dit grondig. Alle verbeteringen en nieuwe functionaliteiten worden vervolgens standaard\ beschikbaar voor alle gebruikers. Hoe meer partijen deelnemen aan de ontwikkeling, hoe lager\ de kosten voor iedereen. Wil jij ook iets bijdragen? Op de [governance ](/nl-portal-docs-revision/product-management/governance)pagina wordt meer verteld over hoe je\ nieuwe features en bugfixes kan toevoegen. Wil je ook meepraten? We nodigen je graag uit om mee te kijken tijdens een sprintreview of\ je uit te nodigen voor de NL Portal community op Slack. Stuur hiervoor een mailtje naar . # Repositories | Repository | Beschrijving | | ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | [Documentatie](https://github.com/nl-portal/documentation) | Documentatie over de NL Portal | | [Frontend Template](https://github.com/nl-portal/nl-portal-frontend-template) | Template om een nieuwe NL Portal app frontend te starten, de perfecte basis om mee beginnen | | [Backend Template](https://github.com/nl-portal/nl-portal-backend-template) | Template om een nieuwe NL Portal app backend te starten | | [Frontend Libraries](https://github.com/nl-portal/nl-portal-frontend-libraries) | Libraries voor de frontend die gebruikt worden in de frontend template | | [Backend Libraries](https://github.com/nl-portal/nl-portal-backend-libraries) | Libraries voor de backend die gebruikt worden in de backend template | | [Docker Compose](https://github.com/nl-portal/nl-portal-docker-compose) | Een docker compose setup om het ZGW landschap op te zetten die gebruikt kunnen worden door de NL Portal | | [Helm Charts](https://github.com/nl-portal/helm-charts) | Kubernetes Helm charts die het makkelijker maakt om een NL Portal omgeving op te zetten op de kubernetes cluster | # Bijdragen aan NL Portal Dankjewel voor het tonen van interesse in de ontwikkeling van de NL Portal. Per repository hebben wij een CONTRIBUTING.md bestand toegevoegd waarin beschreven staat\ hoe je kan bijdragen aan het project. Hieronder is een link naar dit bestand voor elk van de\ repositories: * [nl-portal-backend-libraries](https://github.com/nl-portal/nl-portal-backend-libraries/blob/next-minor/CONTRIBUTING.md) * [nl-portal-frontend-libraries](https://github.com/nl-portal/nl-portal-frontend-libraries/blob/next-minor/CONTRIBUTING.md) # Governance Alle code is publiek beschikbaar op GitHub. Voor contact met het ontwikkelteam kan een mailtje gestuurd worden naar [rik.van.amelsvoort@ritense.com](mailto:undefined) ## Feature of bugfixes toevoegen 1. Maak een issue aan in de [Frontend](https://github.com/nl-portal/nl-portal-frontend-libraries) of [Backend](https://github.com/nl-portal/nl-portal-backend-libraries) repository op Github. Hiermee willen we zorgen dat alle bugfixes en features afgestemd zijn op elkaar zodat we geen dubbel werk doen. 2. Implementeer de feature of bugfix, test deze en maak een PullRequest naar de development branch 3. Schrijf de release notes en documentatie 4. Merge de branch als je een akkoord hebt van het Portal team We streven naar een maandelijkse release, mocht je sneller een fix of feature nodig hebben laat het ons weten. # Roadmap De roadmap van het NL Portal wordt regelmatig bijgewerkt op basis van de actuele behoeften. De stuurgroep stelt de roadmap vast. Via de [link](https://ritense.atlassian.net/jira/discovery/share/views/dbb49c01-b8df-4ab3-89b6-0cda78f9df23) is de meest recente versie te bekijken. ## Mijlpalen Onderstaande mijlpalen worden opgepakt in 2025. ### ZGW configuratie via UI ZGW-configuratie via UI maakt het mogelijk om ZGW (Zaken, Documenten en Zaken API) instellingen rechtstreeks via een gebruikersvriendelijke interface te beheren. Beheerders kunnen hiermee eenvoudig API-eindpunten, autorisaties, en overige ZGW-specifieke parameters configureren zonder handmatig config-bestanden aan te passen. Dit vergroot de flexibiliteit en verlaagt de kans op fouten bij integratie met ZGW-voorzieningen. ### Huisstijl configuratie via UI Huisstijlconfiguratie via UI stelt beheerders in staat om de visuele stijl van de applicatie aan te passen via een gebruiksvriendelijke interface. Op basis van design tokens kunnen kleuren, typografie en componentstijlen worden geconfigureerd in lijn met het NL Design System. Hierdoor is het eenvoudig om de applicatie visueel af te stemmen op de huisstijl van een specifieke organisatie, zonder handmatige codewijzigingen. ### Haalcentraal BRP v2 HaalCentraal BRP v2 integreert de applicatie met de vernieuwde versie van de BRP API van HaalCentraal. Hiermee kunnen actuele persoonsgegevens zoals naam, adres en geboortegegevens veilig en gestandaardiseerd worden opgehaald bij de basisregistratie. Versie 2 biedt verbeterde performance, uitgebreidere datastructuren en betere ondersteuning voor moderne API-standaarden, wat zorgt voor een robuuste en toekomstbestendige koppeling met de BRP. ### Open Product en Open Klant De **Open Product**-feature in het NL Portal (zoals Open Inwoner of Open Zaak) is een module waarmee gemeenten centraal hun producten en producttypen kunnen beheren via een gebruiksvriendelijke beheersapplicatie. Denk aan: * **Producttypen** zoals parkeervergunning, paspoortaanvraag of afvalbakplaatsing, inclusief regels, geldigheid en zones. * **Producten** als individuele aanvragen — bijvoorbeeld de parkeervergunning van Jan Jansen met kenteken en adresgegevens. Andere applicaties (zoals Open Inwoner of Open Formulieren) kunnen via een REST‑API: * Lijsten met beschikbare producttypen ophalen; * Nieuwe producten aanmaken; * Actuele metadata tonen, zoals prijzen of geldigheidsduur. Door deze gecentraliseerde aanpak ontstaat één bron van waarheid voor producten binnen het NL Portal-ecosysteem, wat onderhoud en integratie eenvoudiger en consistenter maakt. # Release notes Deze sectie bevat de release-opmerkingen voor de verschillende versies van NL-Portal. Deze release-opmerkingen bevatten informatie over wat er nieuw is, welke bugs zijn opgelost, breaking changes, gedepriciëerde code en bekende problemen in die releaseversie. Daarnaast zijn er migratie-instructies beschikbaar wanneer een nieuwe versie niet direct out-of-the-box werkt. Deze sectie is bedoeld voor iedereen die wil weten wat er is gewijzigd in een versie van NL-Portal. De migratie-instructies zijn bedoeld voor meer technische gebruikers, zoals een systeembeheerder die zijn NL-Portal-installatie up-to-date wil houden. # 1.x.x # 1.1.0 Releasedatum november 2023 Dit is de eerste gedocumenteerde release van NL Portal. Deze bevat de volgende verbeteringen. * Ondersteuning meerdere document API's; * Diverse verbeteringen op het gebied van naamgeving in code; * Ondersteuning voor klantcontactmomenten; * Refactoring van taken patroon. # 1.4.0 Releasedatum april 2024 * Diverse kleine verbeteringen en bug fixes; * Verbeteringen in de authenticatieflow en de omgang van data in de JWT. Deze release is breaking; en vereist aanpassingen in de frontend, backend en Keycloak configuratie. # 1.4.1 Releasedatum mei 2024 * [Token exchange](https://github.com/nl-portal/documentation/blob/feature/docs-revision/configuratie/tokenexchange.md) toegevoegd om de KVK/BSN uit de frontend token te halen. # 1.5.0 ## Nieuwe Functionaliteit De volgende functionaliteiten zijn nieuw toegevoegd: * **Externe-klanttaak support** Deze wijziging heeft geresulteerd in deprecated classes.\ Zie Deprecations voor meer informatie * **Vestigingsnummer bepaald lijst van zaken** Voor organisaties waarbij medewerkers van\ een vestiging geen zaken van andere vestigingen mogen zien * **Zaak informatieobject filtering** * **Betalingen ondersteuning** Het is nu mogelijk om aanslagen te betalen en automatische\ incasso's in te stellen * **Notificaties worden nu weergegeven** * **Berichten** Bied de mogelijkheid om informatieve berichten of meldingen in te zien ## Bugfixes De volgende bugs zijn opgelost: * **Zaken worden gepagineerd weergegeven** ## Breaking changes Er zijn geen breaking changes ## Deprecations De volgende classes zijn deprecated: * Taak - Gebruik in plaats daarvan TaakV2 * TaakFormulier - Gebruik in plaats daarvan TaakFormulierV2 * TaakObject - Gebruik in plaats daarvan TaakObjectV2 * TaakMutation - Gebruik in plaats daarvan TaakMutationV2 * TaakPage - Gebruik in plaats daarvan TaakPageV2 * TaakQuery - Gebruik in plaats daarvan TaakQueryV2 ## Bekende problemen De volgende problemen zijn bekend: * **Vestigingsnummer bepaald lijst van zaken** This feature does not work as intended yet.\ A hotfix (version 1.5.1) will be released when it is confirmed to work properly # 1.5.1 ## Bugfixes The following has been fixed: * **Limiting returned zaken by vestigingsnummer**\ ZakenAPI Client now correctly searches for cases based on a vestigingsnummer and kvk, when the authentication used\ is of type `BedrijfAuthentication` and the token claims contain a `vestigingsnummer`. ## Breaking changes Er zijn geen breaking changes ## Deprecations Er zijn geen deprecations ## Bekende problemen Er zijn geen bekende problemen # 1.6.0 ## Features * Diverse dependencies geüpgraded * Initieel ondersteuning toegevoegd voor het laden van configuratie vanuit het configuratiepaneel. * Nieuw module toegevoegd: payment-direct * OpenKlant2 uitgebreid om rekening te houden met vestigingsnummer * Gedeeltelijke zoekfunctionaliteit toegevoegd voor Zaken (nieuwe frontend env var: CASES\_PARTIAL\_SEARCH) * Gebruikerservaring tijdens laden verbeterd * Paginering toegevoegd aan de Zaken-pagina ## Bugfixes * Probleem verholpen waarbij de OpenZaak-code het vestigingsnummer niet gebruikte in queries wanneer dit wel was geconfigureerd * Fout verholpen waarbij een enkelvoudiginformatieobject zonder vertrouwelijkheidsaanduiding ervoor zorgde dat queries mislukten ## Breaking changes Er zijn geen breaking changes ## Deprecations Er zijn geen deprecations ## Bekende problemen Er zijn geen bekende problemen # 2.x.x # 2.0.0 ## Features * Diverse dependencies geüpgraded * Nieuwe module `haalcentraal2` geïmplementeerd — biedt ondersteuning voor interactie met HaalCentraal BRP 2.0 en Bewoningen API’s * Volledige ondersteuning toegevoegd voor NL Portal Configuration Panel 1.0 * Nieuwe feature toggle toegevoegd in de frontend om te schakelen tussen OpenKlant 1 en OpenKlant 2 `(OPEN_KLANT_VERSION)` * OpenKlant2 uitgebreid met extra functionaliteiten: * Zoeken op een specifiek `DigitaleAdres` * Zoeken naar alle `KlantContactmomenten` van een `Partij` * Mogelijkheid om een notitie toe te voegen aan een `DigitaleAdres` * Een `Partij` wordt automatisch aangemaakt als deze nog niet bestaat bij het aanmaken van een `DigitaleAdres` * OpenZaak uitgebreid: * Zaken kunnen nu worden uitgesloten op basis van ZaakType. Nieuwe configuratie-optie: `zaakTypesIdsExcluded` (lijst van UUID’s om uit te sluiten in de getZaken-query) * Idle timer en logout-waarschuwing toegevoegd aan de frontend * UI-verbeteringen: * De gebruikersinformatiepagina is herontworpen om gegevens te tonen uit OpenKlant 2.0, HaalCentraal BRP 2.0 en HaalCentraal Bewoningen * Verschillende componenten zijn verbeterd in vormgeving en gebruiksvriendelijkheid ## Bugfixes Er zijn geen bugfixes ## Breaking changes * Configuratie-eigenschappen voor NL Portal zijn gewijzigd. De configuratie is nu gegroepeerd per feature en bevat een toggle. Zie [#393](https://github.com/nl-portal/nl-portal-backend-libraries/pull/393/files) voor een voorbeeld. * Authenticatie is overgezet van de Keycloak JS-adapter naar react-oidc-context [#276](https://github.com/nl-portal/nl-portal-frontend-libraries/pull/276). Hierdoor kan NL Portal nu gebruikt worden met elke OIDC-compatibele identity provider. ## Deprecations Er zijn geen deprecations ## Bekende problemen Er zijn geen bekende problemen # 3.x.x # 3.0.0 ## Functionaliteiten * Verschillende afhankelijkheden zijn geüpgraded. * Verbeteringen aan bestaande functionaliteiten: * OpenKlant 2: * Nieuwe zoekfilters toegevoegd voor Klantcontactmomenten om te kunnen zoeken op Onderwerpobject-criteria. * OpenZaak: * Ondersteuning toegevoegd voor het opvragen van ZaakResultaten. * Nieuwe feature toggle-configuratie-eigenschap toegevoegd: `nl-portal.config.zakenapi.useNnpKvkQueryIdentificators` om de nieuwe `kvkNummer`-eigenschap van een `Rol` (beschikbaar sinds OpenZaak 1.20.0) te gebruiken bij het opvragen van Zaken als een Bedrijf. * Mogelijkheid toegevoegd om de SubStatussen van een Zaak op te vragen. Alleen SubStatussen met doelgroep betrokkenen of geen doelgroep worden aan de gebruiker getoond. * Direct * Nieuwe eigenschap `customTemplateUrl` toegevoegd voor het instellen van de [variant](https://docs.direct.worldline-solutions.com/en/integration/basic-integration-methods/hosted-checkout-page#createhostedcheckoutrequest:~:text=Method%202%3A%20Customise%20the%20Template%20in%20the%20Merchant%20Portal) van een HostedCheckout. * Berichten * De `getBericht`-query retourneert nu ook het Bericht-ID voor eenvoudiger verwerking in de frontend. * Mogelijkheid toegevoegd om de bijlagen van een Bericht te downloaden. Hiervoor moet de Documenten API geconfigureerd zijn. * Mogelijkheid toegevoegd om een applicatielogo en stijlen te definiëren via configuratie-eigenschappen of het NL Portal Configuratiepaneel. * Mogelijkheid toegevoegd om extra OIDC-parameters te definiëren in de NL Portal Frontend ([#426](https://github.com/nl-portal/nl-portal-frontend-libraries/pull/426)). * Ondersteuning geïntroduceerd voor [Open Product](https://github.com/maykinmedia/open-product) via de `openproduct` NL Portal Backend-module. Dit is bedoeld om de op Objecten API gebaseerde `product`-module te vervangen. * Formio-componenten zijn vervangen door maatwerkcomponenten die de stijlen van de applicatie volgen, waardoor Formio-formulieren prettiger zijn om mee te werken. ## Bugfixes Er zijn geen bugfixes. ## Breaking changes * OpenKlant 2: * Een typefout gecorrigeerd door de query `getUserDigitaleAdresen` te hernoemen naar `getUserDigitaleAdressen`. * `graphql-kotlin` vervangen door [Spring for GraphQL](https://spring.io/projects/spring-graphql) voor een meer uniforme manier van werken en fijnmazige controle over querydefinities. ## Verwijderingen en afschrijvingen * De volgende backend-modules zijn verwijderd: * `haalcentraal-all` - De HaalCentraal BRP 1.0 API is verlaten en al geruime tijd niet meer in gebruik. Alle functionaliteit is vervangen door de `haalcentraal2`-module, die BRP 2.0 en Bewoningen API-functionaliteit biedt. De HaalCentraal HR-functionaliteit is verplaatst naar een eigen module, omdat deze nog in gebruik is. * `klant`, `klant-generiek` en `klantcontactmomenten` - De Klantinteracties API-specificatie wordt al lange tijd niet meer ondersteund door de VNG. Deze module is vervangen door de `openklant`-module, die [Open Klant](https://github.com/maykinmedia/open-klant) implementeert. * Taak V1-functionaliteit verwijderd ten gunste van Taak V2, die het [Externe Klanttaak](https://dienstverleningsplatform.gitbook.io/platform-generieke-dienstverlening-public/patronen/taken/externe-klanttaak) patroon implementeert. ## Bekende problemen * Vooraf invullen van select- en radio-componenten in Externe Klanttaak-formulieren werkt niet; dit wordt opgelost in de aankomende 3.0.1 patch.