vng-realisatie / notificatieservices Goto Github PK

Informatie over het in 2021/2022 uitgevoerde project Notificatieservices

project

notificatieservices's Introduction

Inleiding

Het project Notificatieservices is in 2021 uitgevoerd door VNG Realisatie in opdracht van het Ministerie van Binnenlandse Zaken. Doel van het project was om geautomatiseerd notificeren van applicaties binnen de Nederlandse overheid te standaardiseren. Meer algemeen was het doel om als overheid beter en vaker gebeurtenisgedreven ('event driven') te kunnen werken.

Een aanleiding voor het project was de wens om als overheid effectiever gebruik te gaan maken van bronregistraties en daarmee lokale datakopieen overbodig te maken. Naast het opvragen van gegevens via gestandaardiseerde API's zijn daarvoor notificaties nodig als er gebeurtenissen hebben plaatsgevonden die wijzigingen in bronregistraties als gevolg hebben.

Bij de uitvoering hebben verschillende soorten overheidsorganisaties, uitvoeringsorganisaties en marktpartijen in communityverband samengewerkt. Het project is uitgevoerd van junuari 2021 tot juli 2022.

Scope

Gebeurtenissen vinden continu en in allelei vormen plaats. Bij de start van het project Notificaties heeft een noodzakelijke afbakening plaatsgevonden. Het project richtte zich bijv. uitsluitend op geautomatiseerd notifceren van applicaties (en dus niet op notificeren van mensen). Wat overigens niet wil zeggen dat projectresultaten niet bruikbaar zijn voor zaken die buiten de projectscope vallen. U vindt een toelichting in de notitie 'projectscope'.

Producten

NL GOV profile for CloudEvents

Het NL GOV profile for CloudEvents is een specificatie voor het gestandaardiseerd beschrijven en uitwisselen van gegevens over plaatsgevonden gebeurtenissen. Het profiel bouwt voort op de CloudEvents specificatie die is ontwikkeld door de Serverless Working Group van de Cloud Native Computing Foundation.

De basis van CloudEvents is een specificatie voor het gestandaardiseerd beschrijven van gebeurtenisgegevens. Aanvullend daarop zijn (en worden) standaarden ontwikkeld die beschrijven hoe de specificatie is toe te passen bij gebruik van specifieke gegevensformaten en transportprotocollen. Doelstelling is om wereldwijd de interoperabiliteit van services, platforms en voorzieningen te vergroten.

Het NL GOV profile for CloudEvents bevat afspraken over het gebruik van de CloudEvents-specificatie binnen de Nederlandse overheid. Bijvoorbeeld door af te spreken hoe overheidsorganisaties bepaalde attributen gebruiken. Zo maken we als overheid gebruik van internationale standaardisatie en vullen we die aan met afspraken die binnen de Nederlandse context nodig of wenselijk zijn.

Handreikingen

Binnen project Notificatieservices zijn naar aanleiding van de opgedane ervaringen een aantal handreikingen ontwikkeld als hulpmiddel voor organisaties die hun informatievoorziening meer event-driven willen inrichten.

Technisch

Onderstaande handreikingen beschrijven hoe het NL GOV profiel gestandaardiseerd is te gebruiken in combinatie met een aantal, ook binnen de overheid, gangbare gegevensformaten, transportprotocollen en patronen. Ze zijn te zien als een logisch verlengstuk van het NL GOV profiel bij het ontwerpen en realiseren van oplossingen.

Functioneel

Onderstaande handreikingen beschrijven op een toegankelijke manier een aantal belangrijke aspecten van gebeurtenisgedreven werken in het algemeen en notificeren in het bijzonder:

Architectuur

De uitgebreide handreiking Notificatieservices Architectuur beschrijft een breed scala aan architectuuraspecten met betrekking tot gebeurtenisgedreven werken. De handreiking is bedoeld om kennis die tijdens het project Notificatieservices is opgedaan beschikbaar te stellen voor toekomstig gebruik. Er is hierbij dankbaar gebruik gemaakt van wat wereldwijd aan kennis en ervaring op dit vlak bestaat.

Diversen

Community presentaties: alle presentaties die gebruikt zijn tijdens communitybijeenkomsten
Werkgroep Berichtenstandaard presentaties: alle presentaties die gebruikt zijn tijdens de werkgroep waarmee de berichtenstandaard is ontwikkeld.
Samenwerkingsruimte voor project Notificatieservices: de plaats waar in 2021 binnen het project met een commmunity van overheids- en uitvoeringsorganisaties en leveranciers is samengewerkt.
Concept API-specificatie voor geautomatiseerd abonneren: een API die als onderdeel van een beproeving met VNG Realisatie is ontwikkeld in lijn met de concept CloudEvents-standaard voor geautomatiseerd abonneren op ontvangst van notificaties.

Informatie en vervolg

Het project Notificatieservices is beeindigd per 30 juni 2022. Naar alle waarschijnlijkheid wordt het beheer van het NL GOV profiel en de ontwikkelde handreikingen binnenkort belegd bij een uitvoeringsorganisatie.

Wilt u feedback geven of vragen stellen dan kunt u daarvoor gebruik maken van Github-issues. Omdat er nog geen strucureel beheer is geregeld kan het zijn dat er niet direct een reactie op volgt:

Issues m.b.t. project Notificiatieservices: https://github.com/VNG-Realisatie/notificatieservices/issues
Issues m.b.t. het NL GOV profile for CloudEvents: https://github.com/VNG-Realisatie/NL-GOV-profile-for-CloudEvents/issues/

notificatieservices's People

Contributors

Stargazers

Watchers

Forkers

henrikorver

notificatieservices's Issues

RefImpl: Domain verplicht

Beschrijvingen OAS controleren.

In ieder geval beschrijving subscription.

OAS non-empty construct beoordelen en consequent doorvoeren

Waarschijnlijk zit dit construct ofwel alleen in subscriptions van CE of in ZGW en is dat gekopieerd naar events en mogelijk domains.

Documentatielink Notificaties van Zaken API omzetten naar CE-versie

Dus deze documentatiepagina van de filters en events van de Zaken API omzetten naar een CE-versie. Dit voorbeeld kunnen we gebruiken om de nieuwe Notificatie API te valideren en te gebruiken als demonstratie tijdens het API Lab.

OAS aanpassen: filterAttributes moet array of strings zijn.

Content-type type `application/cloudevents+json` toevoegen als fixed value in header

Hosted (test) version opzetten van de referentie-implementatie

zodat de teamleden (Jeanot, Ad, ik, etc.) de Notificatie API alvast mee kunnen testen voordat deze op het API Lab gelanceerd wordt.

Aparte indicator voor correcties?

Wil je iets van een aparte indicator voor correcties. (Maar dan volgt al snel de vraag wat voor soort correctie het is. Correctie van actuele waarde of aanpassing in eerdere historische voorkomens? De eerste kunnen afnemers mogelijk nog geautomatiseerd verwerken, tweede vaak niet).

RefImpl: filterAttributes array toevoegen aan domains

RefImpl: Validatie datacontenttype schrappen

RefImpl: Filters uit subscription implementeren (minimaal AND/OR en Equals ivm ZGW)

Om backwards compatible te zijn met ZGW notificatie API zouden we minimaal de AND, OR en Equals moeten implementeren.

(
  domain = "nl.vng.zaken" 
  and 
  (
    type = "nl.vng.zaken.status_gewijzigd" 
    or 
    type = "nl.vng.zaken.zaak_gesloten"
  )
)

or 

(
  domain = "nl.vng.documenten" 
  and 
  vertrouwelijkheid = "normaal"
)

- - -

Any
  All
    Equals
      Attribute = "domain"
      Value = "nl.vng.zaken"
    Any
      Equals
        Attribute = "type" 
        Value = "nl.vng.zaken.status_gewijzigd"
      Equals
        Attribute = "type"
        Value = "nl.vng.zaken.zaak_gesloten"
  All
    Equals
      Attribute = "domain"
      Value = "nl.vng.documenten"
    Equals
      Attribute = "vertrouwelijkheid"
      Value = "normaal"

Is filters attribuut in de subscriptions resource goed gedeclareerd?

Dit attribuut is recursief. In de oorspronkelijke spec van CE stond bij ieder subtype van filter steeds: $ref: "#/components/schemas/Filter". Dit is weggehaald omdat deze constructie onduidelijk was. De vraag is wat de bedoeling is van deze constructie en of we deze weer moeten herstellen?

Correcte implementatie event.data attribute

Zie spec:
https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/formats/cloudevents.json

In de huidige OAS is data een object, volgende officiele spec zijn diverse typen toegestaan.

Datatype van event.time

Time kan scherper door te verwijzen naar ISO 8601

OAS: Subscription resource weer gelijkmaken aan CE spec (let op details)

Subscription id staat nu vooraan in plaats van achteraan zoals in de oospronkelijke OAS van CE

Dit is verwarrend en het zou wenselijk zijn zoveel mogelijk de originele OAS te volgen. Mijn voorstel is dat de originele OAS van CE als basis wordt genomen en daarop alleen verbijzonderingen mogen worden doorgevoerd die backwards compatible zijn. Dit doen we dan met uitcommentariëren zodat de verschillen expliciet zichtbaar zijn.

Media type in header: uitzoeken of charset=UTF-8 in http header opgenomen kan worden.

Zie Referentie CE spec

Ondersteunen van expiration of accesstokens

OAS aanpassen: Resource domains, delete en update weg

Bespreken:
Stel iemand maakt een domein aan in het API-lab met de verkeerde filterAttributes. Hoe corrigeren we die dan?
Lijkt me dat we dus minimaal of een put of een delete moeten hebben (zodat je daarna opnieuw een create kan doen).

Tutorial

Uitleggen hoe je username/password via subscriptions.protocolSettings.headers... alsnog kunt doen
Keuze: niet expliciet via SinkCredentials (plain access token)

OAS: Domain verplicht

Events resource data_base64 : underscore toevoegen in gegenereerde OAS en foutmeldingen

Je kunt gewoon data_base64 doorgeven. Alleen de OAS generator en foutmeldingen gebruiken camelcase.

RefImpl: Check tegen OAS

Subscription: Sink en Protocol verplicht
Protocol: mag en kan alleen HTTP zijn
Domain niet verplicht op subscriptions
Sink van subscription aanpassen naar url
Scopes aanpassen naar Engels

Gedrag: SubscriberReference toevoegen

Aan Events resource het attribuut subscriberReference toevoegen en dit attribuut vullen indien een referentie is opgegeven in subscriptions.config array met de naam subscriverReference

`/domains` en `/subscription` resources hebben geen PATCH-operatie. Waarom?

In ZGW heeft /abonnementen namelijk wel een PATCH-operatie.

RefImpl: Custom attributes hoeven niet te beginnen met domain.

Controle of extra attributen in een event gedefinieerd zijn (als filterAttributes) bij het domein.

Voorbeeld:
/domains POST
name:nl.vng.zaken
documentationLink:http:
filterAttributes: bronorganisatie, vertrouwelijkheid

/events POST
domain = nl.vng.zaken
vertrouwelijkheid = ...
gezelligheid = ...
mag niet, want gezelligheid is geen filterattribuut
minder attributen mag wel, meer niet

Gedrag afhandelen Event

Voor mij is onduidelijk welk gedrag er verwacht wordt wanneer een Event wordt ontvangen in de volgende scenario's:

Event heeft geen domain en subscription velden gespecificeerd
Event heeft geen domain maar wel een subscription veld gespecificeerd
Event heeft wel een domain veld gespecificeerd maar geen subscription
Event heeft zowel een domain als een subscription veld gespecificeerd

Uiteindelijk zullen er meer scenario's zijn (omdat filtering niet in een eerste versie geimplenteerd zal worden) maar volgens mij zijn dit de scenario's die dan overblijven. Het lijkt mij dat in het laatste scenario dat er alleen een Event wordt gestuurd wanneer het opgegeven domain gekoppeld is aan de opgegeven subscription.

Communicatie naar betrokkenen

AccessToken communiceren
Docker is er wel, maar beperkt ondersteuning om deze draaiend te krijgen. Voorkeur heeft aansluiten op hosted version, zeker de dag.

RefImpl: subject atttribuut opnemen in event.

`/domains` resource heeft PUT en DELETE operaties, `/kanaal` in ZGW API heeft dat niet. Waarom dit verschil?

OAS: SubscriberReference toevoegen

Aan Events resource het attribuut subscriberReference toevoegen

Toevoegen ontbrekende status en error codes aan OAS

Openstaande vragen specificatie

Tijdens het implementeren van de specificatie zijn er een aantal vragen bij me ontstaan:

In het gedrag.md document van de specificatie wordt aangegeven (in stap 2) dat het subscription veld ingevuld moet worden met "het id van de subscription van de afnemer", waar zou deze waarde vandaan gehaald moeten worden?
Dezelfde vraag komt op bij het subscriberReference, de waarde waarmee dit veld gevuld zou moeten worden, waar zou deze te vinden moeten zijn?
In de Redoc zie ik daarnaast camelcase attributen en attributen met underscores voorbij komen (bijvoorbeeld data_base64 bij Event en protocolSettings bij Subscription), het lijkt mij dat we hier consistent in willen zijn en willen gaan voor camelcase?

OAS: id string en geen uuid

RefImpl: Omschrijvingen gelijktrekken aan OAS.

Postman scripts maken

zodat gebruikers en testers snel met de Notificatie API kunnen spelen.

RefImpl: SubscriberReference toevoegen

Aan Events resource het attribuut subscriberReference toevoegen en dit attribuut vullen indien een referentie is opgegeven in subscriptions.subscriberReference.

n.b. Eerst zouden we dit attribuut opnemen in subscription.config maar dat is wel heel inconsequent.

Autorisatie verfijnen

Bijvoorbeeld domains POST apart kunnen autoriseren

OAS: weghalen <domain> prefix bij de custom attributes. Wordt dus alleen "<key1>..."

OAS: subject attribuut opnemen in event.