Notified Pull

Achtergrond

Het Notified Pull (NP) communicatiepatroon stelt een initiatiefnemer in staat gegevens gericht aan te bieden aan een raadpleger. De raadpleger wordt hiervan op de hoogte gebracht via een notificatie. De Pull operatie kan meedere keren worden uitgevoerd over de periode waar de gegevens gedeeld mogen worden. Hierdoor kan een raadpleger gedurende deze periode een actueel overzicht houden van de beschikbaar gestelde informatie. Dit in tegensstelling tot een PUSH, waarbij de er eenmalig een gegevensset wordt verstuurd.

Notified Pull binnen Nuts

Binnen Nuts is de Notified Pull als eerste beschreven en getoetst binnen de use-case eOverdracht. We schrijven dit patroon hier uit zodat het ook los te gebruiken en door te ontwikkelen is. Het patroon is in de basis een implementatie van de FHIR Subscription REST Hook aangevult met Nuts-specifieke methoden om endpoints te vinden en access tokens te maken.

Status van dit document

Dit document beschrijft een generieke versie van de notified pull binnen het Nuts ecosysteem. Sinds het schrijven van de eOverdracht specificatie zijn de FHIR en Nuts standaarden verder ontwikkeld. Deze plek wordt gebruikt om deze nieuwe inzichten te verwerken in een zelfstandige versie van de specificatie.

Interacties

De notificatie

Een notificatie gaat over een specifieke FHIR Resource. Bijvoorbeeld een notificatie Task met id 123.

Notificatie endpoint

Een notificatie moet worden verstuurd naar een endpoint. Dit wordt als volgt samengesteld: Het base endpoint bevindt zich in het notification veld van de relevante use-case service-veld in het DID-Document van de ontvangende organisatie. Het endpoint waar de notificatie heen moet is een combinatie van het base endpoint en de Resource identifier, bijv: https://example.org/fhir/notifications/123.

Authenticatie

Om een bericht te mogen sturen naar dit notificatie endpoint, moet de bronhouder een accesstoken verkrijgen.

Het opvragen van een access token gebeurt via RFC003 bij de autorisatie server van het notificatie endpoint.

Het endpoint van de autorisatie server bevindt zich in het auth veld van de relevante use-case service in het DID-Document van de ontvangende organisatie.

Versturen van de notificatie

Er wordt een notificatie gestuurd middels een lege POST naar het endpoint. Het access token autorisatie header meegestuurd. De Accept header moet gezet worden conform de eisen van een FHIR API call.

Ontvangen van de notificatie

Het doelsysteem valideert het access token door het uitvoeren van een introspectie op het token bij de autorisatie server.

Indien het access token correct is zal de notificatie worden verwerkt.

Het wordt aangeraden de informatie uit het access-token op te slaan met samen met het pad, zodat op een later moment de FHIR Resource kan worden opgehaald.

Bij een correct verwerking zal de ontvangende partij het antwoord 202 Accepted met een lege body geven. Bij een incorrecte verwerking kan de ontvangende partij een 40x of 50x HTTP status code teruggeven. Bij een 400 status code mag de ontvangende partij een body meegeven, indien dit gedaan wordt dan moet dit een FHIR STU3 OperationOutcome zijn.

Opvragen van de resource (Pull)

Indien de ontvangende partij interessse heeft in de gegevens kan deze er voor kiezen de gegvens op te halen.

Resource endpoint

Het doelsysteem is nu op de hoogte van een nieuwe of gewijzigde FHIR resource. Het access token dat in stap bij het versturen van de notificatie gebruikt is, bevat het de identifier van de bronhouder.

Het notificatie request bevatte een autorisatie header met daarin het access token. Dit access-token gaf via een introspectie stap toegang tot oa de identifiers van de bronhouder en de ontvangende partij. Het doelsysteem kan hiermee bepalen waar de FHIR Resource opgehaald moet worden. Het endpoint van de FHIR resource is te vinden in het fhir veld van de relevante service van het DID Document van de bronhouder. Dit is de base URL van de FHIR service. Daar moet nog het relatieve pad van de FHIR Resource (bijv. Task) en de specifieke identifier (bijv. 123) aan toegevoegd worden.

Authenticatie van het FHIR Endpoint

Voordat het doelsysteem de FHIR Resource bij het endpoint kan ophalen, moet er een access-token worden aangemaakt. Dit kan een persoonlijk of systeem token zijn. Met systeemtokens kunnen er alleen resources worden opgehaald waar geen persoonsgegvens in zitten. Het access token gaat (net zoals bij het versturen van de notificatie) mee in een header.

Verwerken van een FHIR Resource request

Het bronsysteem controleert het access token en bepaalt aan de hand daarvan de bronhouder en de opvragende partij. Samen met de gegeven path en query parameters bevat dit voldoende informatie om de juiste FHIR resource te vinden. Er wordt gecontroleerd of de opvragende partij toegang heeft tot de resource. Indien dit het geval is wordt de resource teruggestuurd.