status:VERSIE: 17-01-2025 status:STATUS: definitief

Incrementele implementatie
Het iWlz-netwerkmodel wordt incrementeel geïmplementeerd aan de hand van het afsprakenstelsel iWlz-netwerkmodel. Het eerste deel dat is geïmplementeerd is het Indicatieregister. Vanaf 16-01-2025 is Indicatieregister 2 van toepassing.

De inhoud van dit artikel geeft de actuele situatie weer met Indicatieregister 2. Het uitgangspunt is dat dit artikel ook de eindsituatie weergeeft voor verdere ontwikkelingen van het iWlz-netwerkmodel.

Dit artikel beschrijft de dienst Notificeren. Deze dienst wordt door bronhouders aangeboden aan afnemers. De inhoud van dit artikel is gebaseerd op RFC0008 - Functionele uitwerking notificaties die is vastgesteld in december 2024. Bepaalde onderdelen uit deze RFC zijn verwerkt in andere delen van het afsprakenstelsel zoals het artikel nID netwerkstelsel en de Begrippenlijst.

1 1. Inleiding
2 2. Notificaties
- 2.1 2.1 Doel notificatie
- 2.2 2.2 Typen notificatie
- 2.3 2.3 Overzicht van de Scopes
- 2.4 2.4 Inhoud notificatie
  - 2.4.1 2.4.1 Afzender en Ontvanger lijst
- 2.5 2.5 Notificatie-flow
- 2.6 2.6 Voorbeeld van notificatie
- 2.7 2.7 Notificatie responses vanuit OPA

1. Inleiding

Binnen het iWlz-netwerkmodel werken we met generieke technische oplossingen en contracten om minimaal afhankelijk te zijn van gezamenlijke releases. Daarom werken we bijvoorbeeld met GraphQL, zodat het uitleveren van extra gegevens via een register geen impact heeft op de overige deelnemers aan het netwerk.

Het netwerkmodel moet in zijn geheel ondersteuning bieden aan het gehele iWlz ketenproces. Daarvoor is het in bepaalde situaties nodig om als ketenpartij op de hoogte gebracht te worden van relevante informatie om de voortgang in het proces van zorglevering aan een cliënt te waarborgen. Een deelnemer moet daarom genotificeerd worden dat er relevante informatie beschikbaar is.

Andersom kan een deelnemer ook de bronhouder voorzien van (nieuwe) informatie. In dat geval spreken we over Melden. Deze dienst zal in een apart artikel worden beschrevren zodra RFC0018 vastgesteld is.

Dit artikel beschrijft de werking van notificeren in het iWlz-netwerkmodel.

1.1 Het verschil tussen notificeren en melden

@startuml rfc008-01-notificatie_melding
title notificeren of melden
skinparam handwritten false
skinparam participantpadding 20
skinparam boxpadding 40
autonumber "<b>[00]"
box  #lightblue
participant "bronhouder" as bs
end box

box  #lightyellow
participant "deelnemer" as dbs
end box

Group Notificeren
    bs -> dbs : sturen notificatie
    hnote over bs #GreenYellow :notificatie 
    activate bs
    activate dbs
    return response
    deactivate bs
end

Group Melden
    dbs -> bs: sturen melding
    hnote over dbs #GreenYellow :melding
    activate bs
    activate dbs
    return response
    deactivate dbs
end
@enduml

	Van	Naar	Omschrijving

	Van	Naar	Omschrijving
Notificeren	Bronhouder	Deelnemer	Op de hoogte stellen van een deelnemer over dat er nieuwe (of gewijzigde) informatie in een bron beschikbaar is die directe of afgeleide betrekking heeft op die deelnemer.
Melden	Deelnemer	Bronhouder	Verzoek tot muteren of het beschikbaar stellen van nieuwe informatie naar aanleiding van een gebeurtenis van een deelnemer aan een bron.

Op dit moment is Melden nog niet uitgewerkt. Dit wordt gedaan in RFC0018 - (Fout-)meldingen iWlz Netwerkmodel.

1.2 Uitgangspunten

Notificaties worden gestuurd op basis van wettelijke en vrijwillige abonnementen. Vrijwillige abonnementen worden in deze release nog niet geïmplementeerd.
Een notificatie stelt de ontvanger in staat te bepalen welke informatie opgevraagd kan worden.
Notificaties die randvoorwaardelijk zijn om een wettelijke taak uit te kunnen voeren worden door de bronhouder verstuurd zonder dat daar een apart abonnement per deelnemer voor nodig is.
Er is een lijst beschikbaar met notificatie end-points. Dit is het tijdelijk adresboek wat later wordt vervangen door de generieke functie Adresboek zodra deze beschikbaar komt.

1.3 Code-repository

De in actuele in dit artikel beschreven code staat in https://github.com/iStandaarden/iWlz-generiek/tree/master . Daar staat onder andere het GraphQL-schema voor de benodigde mutations.

2. Notificaties

2.1 Doel notificatie

Het doel van een notificatie is het op de hoogte stellen van een deelnemer door een bron over nieuwe (of gewijzigde) informatie die directe of afgeleide betrekking heeft op die deelnemer en daarmee de deelnemer in staat stellen op basis van die notificatie de nieuwe informatie te raadplegen. Een notificatie verloopt altijd van bronhouder naar deelnemer.

De reden voor notificatie is altijd de registratie of wijziging van gegevens in een bronregister. Dit is de notificatie-trigger en beschrijft welk event op een register leidt tot een notificatie.

2.2 Typen notificatie

Er zijn twee typen notificaties gedefinieerd, waarbij het onderscheid zit in de vrijwilligheid van het ontvangen van de notificatie door een deelnemer of het noodzakelijk ontvangen van de notificatie door de deelnemer. Wanneer het voor de afgesproken werking van de iWlz noodzakelijk is een deelnemer van een event in een register op de hoogte te stellen is er sprake van een verplichte notificatie. Een bronhouder moet deze notificatie versturen en een deelnemer hoeft zich voor de deze notificatie niet te abonneren. Is voor een goede werking van de iWlz gewenst dat een deelnemer op de hoogte wordt gesteld van een event, maar niet noodzakelijk, dan hoeft een bronhouder een notificatie alleen te versturen wanneer de deelnemer zich heeft geabonneerd op deze notificatie (vrijwillige notificatie).

Een voorbeeld van een verplichte notificatie is de registratie van een nieuw indicatiebesluit. Het zorgkantoor dat verantwoordelijk is voor de regio waarin de cliënt van het indicatiebesluit volgens het BRP woont, moet op de hoogte gesteld worden. Het CIZ moet daarom een dergelijke notificatie verzenden aan het zorgkantoor en het zorgkantoor moet de notificatie volgens iWlz-afspraken afhandelen. Het zorgkantoor hoeft zich niet apart op deze notificatie "nieuwe indicatie voor zorgkantoor" te abonneren.

De twee typen iWlz notificaties zijn daarom:

Type notificatie	Verzenden notificatie	Opmerking

Type notificatie	Verzenden notificatie	Opmerking
Verplicht	Altijd, geen keuze deelnemer	Er zijn voor twee registers verplichte notificaties gespecificeerd. Deze zijn te vinden in het informatiemodel iWlz
Vrijwillig	Alleen naar abonnees, keuze ligt bij deelnemer

In de eerste implementatie zal er alleen sprake zijn van iWlz-verplichte notificaties. Er zal geen functionaliteit worden ondersteund voor de iWlz-vrijwillige notificatie en er zal verder in dit artikel niet worden besproken.

2.3 Overzicht van de Scopes

Binnen het iWlz-netwerkmodel zijn er specifieke scopes gedefinieerd voor de dienst Notificeren. Deze scopes bepalen de rechten en acties die gebruikers mogen uitvoeren binnen het systeem. Elke scope is gekoppeld aan een specifieke resource en beschrijft welke acties geautoriseerd zijn.

Resource	Scope	Omschrijving	Gebruiksscenario

Resource	Scope	Omschrijving	Gebruiksscenario
Notificatie	organisaties/zorgkantoor/notificaties/notificatie:create	Deze scope geeft de gebruiker het recht om notificaties te verzenden naar zorgkantoren. Dit wordt bijvoorbeeld gebruikt wanneer een nieuwe indicatie is geregistreerd en het zorgkantoor hiervan op de hoogte moet worden gesteld.	Een bronhouder genereert een notificatie wanneer een cliënt een nieuwe indicatie krijgt. Het zorgkantoor ontvangt deze notificatie om de benodigde acties te ondernemen.
Notificatie	organisaties/zorgaanbieder/notificaties/notificatie:create	Deze scope staat het verzenden van notificaties toe naar zorgaanbieders. Dit kan noodzakelijk zijn wanneer nieuwe of gewijzigde informatie relevant is voor zorgaanbieders.	Een zorgaanbieder ontvangt een notificatie over een gewijzigde indicatie van een cliënt om zorgprocessen aan te passen.

Relatie tussen Scopes en Toepassingen

De gedefinieerde scopes zijn essentieel om een duidelijke scheiding van rechten te waarborgen binnen het iWlz-netwerk. Ze zorgen ervoor dat gebruikers alleen toegang krijgen tot de gegevens en functionaliteiten die relevant zijn voor hun rol en verantwoordelijkheden.

2.4 Inhoud notificatie

Op basis van de inhoud van een notificatie moet de ontvanger van de notificatie onder andere kunnen bepalen:

wat is de trigger, wat is de reden van de notificatie
van welke bronhouder is de notificatie afkomstig
wanneer is de notificatie verzonden
op welke informatie de notificatie betrekking heeft
informatie om een gerichte raadpleging te kunnen doen

Daarnaast moet de autorisatievoorziening voldoende informatie hebben om te kunnen bepalen dat de notificatie (type) door verzender mag worden verstuurd. Bijvoorbeeld: Notificatietype mag verzonden worden door verzender en stuurt naar juiste type ontvanger.

De notificatie is uit de volgende elementen opgebouwd:

Element	Algemene beschrijving	Specifieke beschrijving voor notificeren	V/O^*	Type

Element	Algemene beschrijving	Specifieke beschrijving voor notificeren	V/O^*	Type
timestamp	Tijdstip waarop de notificatie is aangemaakt		V	Datetime^*2
afzenderIDType	Kenmerk van het type ID van de verzendende partij		V	String
afzenderID	Identificatie van de verzender van het bericht		V	String
ontvangerIDType	Kenmerk van het type ID van de ontvangende partij		V	String
ontvangerID	Identifictie van de ontvanger van het bericht		V	String
ontvangerKenmerk	Kenmerk van de ontvanger:	Bij iWlz-vrijwillige notificatie gevuld met abonnementsID. Anders leeg	O	String
eventType	Onderwerp van het bericht; wat is de reden van het bericht	Notificatie ObjectID	V	String
subjectList	Lijst met onderwerpen van het bericht	...	V	Array
../subject	Onderwerp van het bericht	Identificatie van het parent-object waarover de autorisatie loopt.	V	String
../recordID	Identificatie van het record waar het bericht betrekking op heeft	Identificatie van het record waar de notificatie betrekking op heeft.	V	String

^* V = verplicht / O = Optioneel

^*2Datetime volgens ISO-8601 zie ISO 8601 en https://scalars.graphql.org/andimarek/date-time. Formaat is bijvoorbeeld: 2016-07-20T17:30:15Z of 2016-07-20T17:30:15+05:30 of 2016-07-20T17:30:15.234890+05:30.

@startuml rfc0008-06-message-erd.puml

entity Notification {
timestamp : Datetime,
afzenderIDType : string,
afzenderID : string,
ontvangerIDType : string,
ontvangerID : string,
ontvangerKenmerk : string[0..1],
eventType : string,
}
entity SubjectList {
subject : string
recordID : string
}

Notification "1" -- "1.." SubjectList: contains

@enduml

2.4.1 Afzender en Ontvanger lijst

Code	Omschrijving	Referentie	Toepassing

Code	Omschrijving	Referentie	Toepassing
AGB	AGB-code	AGB-register	identificatie Zorgaanbieder
KVK	Kamer van Koophandel	KVK-register	identificatie Ondernemer (CIZ bij eerste implementatie^*)
OIN	Organisatie Identificatienummer	OIN-register	identificatie CIZ (toekomstig^*)
UZOVI	Unieke ZorgVerzekeraarsIdentificatie	UZOVI-register	identificatie Zorgkantoren

^* Op dit moment registreert VECOZO geen OIN bij overheidsorganisaties waardoor er geen claim kan worden afgegeven op basis van OIN. Bij de eerste implementatie van notificaties zal voor de identificatie van het CIZ het KVK-nummer (62253778) worden gebruikt.

2.5 Notificatie-flow

De hier beschreven flow beschrijft alleen het notificeren zelf. Voor het notificeren is autorisatie nodig. Het aanvragen van autorisatie en de bijbehorende flow is beschreven in artikel nID netwerkstelsel.

@startuml rfc008-02-notificatie_sequence
title notificatie sequence-diagram
skinparam handwritten false
skinparam participantpadding 20
skinparam boxpadding 40

box bronhouder #lightblue
  participant "Resource" as Resource
  participant "Register- \ndata" as Register
end box

box "nID"
    participant "autorisatieserver" as AuthzServer
    participant "PEP" as PEP
    participant "PDP" as PDP
end box

box deelnemer #lightyellow
  participant "Resource-\nServer" as ResServer
end box

note over PEP #lightgreen: De volledige validatie en autorisatie flow \nis beschreven in het artikel \nnID netwerkstelsel 

autonumber "<b>[00]"
Resource -> Register : <b>registratie data

activate Resource 
  activate Register
  Register -> Register: <b>event trigger
  Register -> Resource : <b>bepaal notificatietype
  deactivate Register

  Resource -> Resource: <b>genereer GraphQL notificatie
autonumber stop
  Resource -> AuthzServer: Aanvragen van autorisatie\n"scope": "../notificaties/notificatie:create" 
    activate AuthzServer #Darkgrey
        AuthzServer --> Resource --: 200 Response (JWT Access-Token) 
    deactivate AuthzServer
autonumber resume
  Resource -> PEP: **GraphQL Request **\nAuthenticatiemiddel + JWT Access-Token + notificatie

autonumber stop
  activate PEP

    PEP -> PEP: Valideer Authenticatie en \nAccess
    PEP -> PDP: GraphQL met policy valideren
      activate PEP #LightGray
        activate PDP
        PDP -> PDP: Valideer graphql    
        autonumber stop
          PDP -> PEP: Graphql allowed
        deactivate PDP
        PEP -> ResServer: **[05] GraphQL Request**
      deactivate PEP

autonumber resume
    activate ResServer
    ResServer -> ResServer: <b>ontvang \n<b>notificatie
    ResServer --> PEP: <b>GraphQL 200 response
    deactivate ResServer
autonumber stop
    PEP --> Resource: <b>[07] GraphQL 200 response


    deactivate PEP 
    Resource --> Resource: <b>[08] verwerk GraphQL 200 response

  @enduml

#	Beschrijving	Toelichting	Voorbeeld: Indicatie voor zorgkantoor

#	Beschrijving	Toelichting	Voorbeeld: Indicatie voor zorgkantoor
01	registratie data	data vanuit backoffice in register plaatsen	Het CIZ registreert een nieuwe Wlz Indicatie voor een cliënt
02	event trigger	registratie of wijziging data laat een notificatie trigger afgaan	Het zorgkantoor dat verantwoordelijk is voor de regio waar de cliënt volgens het BRP woonachtig is, moet van deze nieuwe indicatie op de hoogte gebracht worden.
03	bepaal notificatietype	bepaal notificatietype en bepaal of het een verplichte of vrijwillige notificatie is	Het is de trigger van de iWlz-verplichte notificatie: NIEUWE_INDICATIE_ZORGKANTOOR
04	genereer GraphQL notificatie	maak de benodigde notificatie aan	Gebruik wlzIndictieID en uzovi-code uit ‘initieelVerantwoordelijkZorgkantoor’ in de notificatie.
05	zend GraphQL notificatie	verstuur de notificatie naar het endpoint van de deelnemer
06	verwerk notificatie	verwerk de ontvangen notificatie
07	GraphQL 200 response	stuur ontvangst bevestiging	De zorgaanbieder bevestigt de ontvangst van de notificatie en kan deze verwerken en gebruiken voor een raadpleging
08	Verwerk GraphQL 200 response	Verwerk de ontvangstbevestiging

Zodra een event zich voordoet waarvoor een notificatie-trigger is gedefinieerd verstuurt de bronhouder de bijbehorende notificatie.

2.6 Voorbeeld van notificatie

Het gaat hier om een notificatie als gevolg van een nieuwe registratie in het Indicatieregister van een nieuwe Indicatie. Met deze registratie ontstaat er een nieuwe Indicatie waarvan het zorgkantoor op de hoogte moet worden gesteld. Hiervoor is er de verplichte notificatie: NIEUWE_INDICATIE_ZORGKANTOOR die naar het zorgkantoor onder initieelVerantwoordelijkZorgkantoor in WlzIndicatie gestuurd moet worden. Op basis van het wlzIndicatieID kan dat zorgkantoor een raadpleging doen.

Voorbeeld Notificatie Query:

mutation zendNotificatie(
  $afzenderID: String!
  $afzenderIDType: IDTypeEnum!
  $eventType: String!
  $ontvangerID: String!
  $ontvangerIDType: IDTypeEnum!
  $timestamp: DateTime!
  $subjectList: [SubjectEntity!]!
) {
  zendNotificatie(
    notificatieInput: {
      afzenderID: $afzenderID
      afzenderIDType: $afzenderIDType
      eventType: $eventType
      ontvangerID: $ontvangerID
      ontvangerIDType: $ontvangerIDType
      timestamp: $timestamp
      subjectList: $subjectList
    }
  ) {
    notificatieID
  }
}

GraphQL Variabelen:

{
  "afzenderID": "62253778",
  "afzenderIDType": "KVK",
  "eventType": "NIEUWE_INDICATIE_ZORGKANTOOR",
  "ontvangerID": "5151",
  "ontvangerIDType": "UZOVI",
  "timestamp": "2024-07-02T00:00:00Z",
  "subjectList": [
    {
      "recordID": "WlzIndicatie/ef88ce35-58fa-4e6d-ac7a-6e298dd211d6",
      "subject": "WlzIndicatie/ef88ce35-58fa-4e6d-ac7a-6e298dd211d6"
    }
  ]
}

Succesvol response:

HTTP/1.1 200
{
  "data": {
    "zendNotificatie": {
      "notificatieID": "e2d8c3c2-7453-4948-95c8-de86688461e5"
    }
  }
}

Validatie fout response:

HTTP/1.1 400 Bad Request
{
  "errors": [
    {
      "message": "ZendNotificatie mutation: afzender_id is not valid",
      "extensions": {
        "code": "GRAPHQL_VALIDATION_FAILED"
      }
    }
  ]
}

2.7 Notificatie responses vanuit OPA

Het notificatiesysteem binnen nID is ontworpen om meldingen en notificaties op een consistente en betrouwbare manier te verzenden naar geautoriseerde partijen binnen de iWlz-keten. Dit proces wordt ondersteund door de GraphQL-operaties zendMelding en zendNotificatie, die verantwoordelijk zijn voor het initiëren van respectievelijk meldingen en notificaties.

De responses van deze GraphQL-operaties bieden een gestandaardiseerde manier om de uitkomst van het verzoek te communiceren. Ze bevatten zowel statusinformatie als foutmeldingen, die essentieel zijn voor het begrijpen en diagnosticeren van het notificatieproces. Dit maakt het mogelijk om problemen in de keten snel te identificeren en te verhelpen.

De response codes zijn gebaseerd op gestandaardiseerde HTTP-statuscodes, uitgebreid met specifieke foutberichten en contextuele informatie om de aard van de uitkomst of fout te verduidelijken. Zowel technische als functionele foutscenario's worden behandeld, zodat ontwikkelaars en beheerders een volledig inzicht krijgen in de verwerking van notificaties.

Hieronder wordt een tabel weergegeven met de mogelijke response codes, foutberichten en oorzaken die kunnen optreden bij de uitvoering van de GraphQL-verzoeken zendMelding en zendNotificatie. Deze tabel dient als leidraad voor een correcte interpretatie van de responses en het oplossen van eventuele problemen.

De hieronder beschreven foutcodes ontstaan bij het valideren van de ingezonden GraphQL in nID, onderdeel PDP (zie artikel nID netwerkstelsel).

@startuml rfc0008-04-error-flow
title notificatie flow incl. nID
skinparam handwritten false
skinparam participantpadding 20
skinparam boxpadding 40


box bronhouder #lightblue
  participant "Resource" as Resource
  participant "Register- \ndata" as Register
end box

box "nID"
    participant "autorisatieserver" as AuthzServer
    participant "PEP" as PEP
    participant "PDP" as PDP
end box


box deelnemer #lightyellow
  participant "Resource-\nServer" as ResServer
end box

note over PEP #lightgreen: De volledige validatie en autorisatie flow \nis beschreven in het onderdeel \nnID netwerkstelsel 

Resource -> Register : registratie data

activate Resource 
  activate Register
  Register -> Register: event trigger
  Register -> Resource : bepaal notificatietype
  deactivate Register

  Resource -> Resource: genereer GraphQL notificatie

  Resource -> AuthzServer: **Aanvragen van autorisatie**\n"scope": "../notificaties/notificatie:create" 
    activate AuthzServer #Darkgrey
        AuthzServer --> Resource --: 200 Response (JWT Access-Token) 
    deactivate AuthzServer

  Resource -> PEP: **GraphQL Request **\nAuthenticatiemiddel + JWT Access-Token + notificatie
  activate PEP

    PEP -> PEP: Valideer Authenticatie en \nAccess
    PEP -> PDP: GraphQL met policy valideren
      activate PEP #LightGray
        activate PDP
        PDP -> PDP: Valideer graphql  
        autonumber "<color:red><b>[00]"
          Resource <-[#red]-X PDP: <color:red> 400 Bad Request
          Resource <-[#red]-X PDP: <color:red> 400 Bad Request: GRAPHQL_VALIDATION_FAILED       
        autonumber stop
          PDP -> PEP: Graphql allowed
        deactivate PDP
        PEP -> ResServer: **GraphQL Request**
      deactivate PEP

    activate ResServer
    ResServer -> ResServer: ontvang notificatie
    ResServer --> PEP: GraphQL 200 response
    deactivate ResServer
    PEP --> Resource: GraphQL 200 response

    deactivate PEP 
    Resource --> Resource: verwerk GraphQL 200 response

  @enduml

Response	Oorzaak

Response	Oorzaak
400 Bad Request	Het notificatieverzoek bevatte ongeldige of ontbrekende parameters.
400 Bad Request GRAPHQL_VALIDATION_FAILED instantie_type claim not found	De JWT token bevat geen instantie_type claim
400 Bad Request GRAPHQL_VALIDATION_FAILED afzender_type is not valid	De afzenderIDType komt niet overeen met de instantie_type claim of is niet toegestaan
400 Bad Request GRAPHQL_VALIDATION_FAILED event_type is not valid	Het opgegeven event type komt niet voor in de lijst met toegestane types
400 Bad Request GRAPHQL_VALIDATION_FAILED ontvanger is not valid	De combinatie van ontvangerIDType en eventType is niet toegestaan

Met deze informatie kunnen deelnemers vaststellen wat er gebeurt binnen het notificatieproces en waar mogelijke knelpunten zich bevinden.

Afsprakenstelsel iWlz (netwerkmodel)

Notificeren