Notified Pull gebaseerd op FHIR subscriptions

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 meerdere 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 tegenstelling 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 Out of band FHIR Subscription in combinatie met een FHIR Subscription REST Hook aangevuld met Nuts-specifieke methoden om endpoints te vinden en access tokens te maken.

Status van dit document

Dit document beschrijft een nieuwe en 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. De specificatie heeft de status DRAFT en dient nog niet gebruikt te worden in een toepassing.

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, bijvoorbeeld: https://example.org/fhir/notifications/123.

Subscription aanmaken

De notificatie wordt verstuurd op basis van een FHIR subscriptie. Een subscriptie kan op 2 manieren tot stand komen: op inititiatief van de client (raadpleger) of de server (bronbouder). Gezien de raadpleger bij een NP niet weet dat er gegevens klaar staan wordt er gebruik van gemaakt van een zgn. Out-of-band subscription.

Voor de use-case bestaat er een SubscriptionTopic.

De bronhouder maakt een 'Subscription` aan voor de specifieke raadpleger die verwijst naar het topic gefilterd op de patient en de resource waar de notificatie voor is.

Authenticatie

Om een bericht te mogen sturen naar dit notificatie-endpoint, moet de bronhouder een access token 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 notification van het type id-only in een POST naar het notification endpoint gestuurd. Het access token wordt in de autorisatie header meegestuurd. Het id van de notificatie verwijst naar de resource waar de notificatie over gaat.

{
  "resourceType" : "Bundle",
  "id" : "3945182f-d315-4dbf-9259-09d863c7e7da",
  "type" : "subscription-notification",
  "timestamp" : "2024-04-17T10:24:13.1882432-05:00",
  "entry" : [{
    "fullUrl" : "urn:uuid:c144782b-da2f-4125-a9e2-9fa4b9085a40",
    "resource" : {
      "resourceType" : "SubscriptionStatus",
      "id" : "c144782b-da2f-4125-a9e2-9fa4b9085a40",
      "status" : "active",
      "type" : "handshake",
      "notificationEvent" : [{
        "eventNumber" : "1",
        "focus" : {
          "reference" : "http://example.org/FHIR/Task/123"
        }
      }],
      "subscription" : {
        "reference" : "http://example.org/FHIR/R5/Subscription/456"
      },
      "topic" : "http://example.org/FHIR/R5/SubscriptionTopic/eOverdrachtv1"
    }
  }]
}

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 samen met de bundle, zodat op een later moment de FHIR Resource kan worden opgehaald op basis van de informatie uit het access token.

Bij een correcte verwerking zal de ontvangende partij het antwoord 202 Accepted met een lege body geven.

TODO: De volgende responses uitwerken voor het afwijzen van een subscriptie.

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.

Als de ontvangende partij de subscriptie afwijst dient het bronsysteem de Subscription.status te wijzigen naar status off.

Opvragen van de resource (Pull)

Indien de ontvangende partij interessse heeft in de gegevens kan deze ervoor kiezen de gegevens 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 een systeem token zijn. Met systeem tokens kunnen er alleen resources worden opgehaald waar geen persoonsgegevens 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 raadplegende 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.