Technisch ontwerp (v0.5)
Door middel van prototyping en interactie met de deelnemers in Expertsessies is vastgesteld dat de uitwisselmethode endpoint-endpoint en de uitwisselgegevens PDF/a het meest geschikt zijn. Deze methoden zijn hieronder uitgewerkt tot een volledig technisch ontwerp ter implementatie in de aankomende fasen van ontwikkeling.
Proces
Het gekozen proces wordt als volgt globaal weergegeven:
Pre-proces met kwalificatie gegevensdienst 51 en acceptatie authenticatie.
Lokalisatie met opvragen MedMij-register en ADP uit zorgaanbiederslijst.
Autorisatie met inloggen, toestemming en tokenuitwisseling.
Gegevens verzamelen met documentlijst en genereren PDF/A.
Beveiligd bewaren en logging.
Pre-proces
De aanbiedende PGO komt als een nieuw type aanbieder op de ZAL, waar we nu nog enkel zorgaanbieders (ZA
) een aanbieders zonder behandelrelaties (BAZB
) kennen. Op de ZAL wordt dan ook geregistreerd voor welke gegevensdiensten de PGO is gekwalificeerd als aanbieder.
Voor nu is gekozen voor de typeaanduiding APD
(aanbieder in het persoonsdomein). Deze aanduiding wordt aan het ZAL-schema toegevoegd. Dit heeft verder geen overige impact op de ZAL, behalve het uitbreiden van de enum
/mogelijke typen van het veld Aanbiedertype
(https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/metamodel#id-(MedMijAfsprakenstelsel2.2.5B)Metamodel-Basisklassen).
Nog te onderzoeken in fase 'Ontwikkelen en geïsoleerd testen'
Is deze impactinschatting correct?
Daarnaast kwalificeert zowel de aanbiedende PGO als de opvragende PGO zich voor het (respectief) aanbieden of ontvangen van gegevensdienst 51, Verzamelen Documenten 3.0 (MM-PLR-FHIR) uit 2020.
Dit komt neer op het ophalen van een FHIR STU3 DocumentReference-bundel in JSON of XML.
Lokalisatie
Lokalisatie voor welk PGO moet worden geraadpleegd (bij welke APD je de use case “Verzamelen” gaat uitvoeren) gaat altijd handmatig. Dit blijft ook het geval in een situatie van het gebruik van de generieke voorzieningen Toestemmingen en Lokalisatie (Mitz), omdat deze enkel het aanbiedertype ZA
kan lokaliseren. De aanbiedertypes APD
en BAZB
blijven hiermee altijd handmatig.
Uitwerking lokalisatie flow
Initiatief voor uitwisseling van een medisch levensloopdossier ligt bij de patiëntgebruiker. Deze logt in op een PGO en kiest een beschikbaarstellend PGO om gegevens op te halen.
De PGO (raadplegend PGO) toont een selectie van MedMij-Zorgaanbiederslijst.xml uit de XML-lijsten van MedMij Beheer. Specifiek gaat het om zorgaanbieders met aanbiedertype APD die uitwisseling langs gegevensdienst 51 ondersteunen.

Weergaverichtlijn
Voor dit lokalisatiescherm wordt een minimale weergave richtlijn voorzien, maar is over het algemeen de PGO aan zet voor het ontwerpen van de UX. Lokalisatie vindt volledig plaats binnen de raadplegende PGO.
Testcases
Hier zijn minimaal de volgende testcases/flows van toepassing:
Happy flow: gebruiker selecteert bron PGO
Unhappy flow: gebruiker breekt interactie af
Authenticatie & Autorisatie
Nadat een APD (beschikbaarstellend PGO) is gekozen uit de lijst, vindt een redirect plaats naar de APD Autorisatie server plaats, net als bij een normale Verzamelen flow: https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/verzamelen#id-(MedMijAfsprakenstelsel2.2.5B)Verzamelen-Businesslaag

De normale Verzamelen flow zoals opgenomen in het Afsprakenstelsel
De PGO stuurt de gebruiker door naar het <AuthorizationEndpointUri> van APD. Na inloggen en toestemming van de gebruiker (zie hieronder), stuurt APD de gebruiker terug naar de PGO met een code. PGO wisselt deze code in op het <TokenEndpoint> van APD voor gegevensuitwisseling.

De autorisatieflow is uitgeschreven in de volgende pagina’s van Afsprakenstelsel. Deelnemers voldoen aan het normenkader informatiebeveiliging. Uitwisseling van gegevens tussen bron-PGO en doel-PGO en APD vindt expliciet plaats zonder langdurige toestemming, dus zonder refresh-tokens. Gebruiker logt in met 2FA, zoals beschreven in https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/a-9-4-1-beperking-toegang-tot-informatie.
MedMij-functies Autoriseren en Authenticeren zonder langdurige toestemming.
MedMij Authorization-interface op OpenID Connect.
MedMij Token-interface conform OAuth 2.0 zonder refresh-tokens.
NB: Doel-PGO mag er voor kiezen om tijdens de autorisatieflow gebruikers op een ander redirect_uri-endpoint terug te laten komen in de reguliere autorisatie met een bron-PGO dan in autorisatie bij een DVA. Laat daarvoor een extra RedirectURI vastleggen in de OAuthclientlist, waarop autorisatieserver controleert. Uiteraard kan doel-PGO ook kiezen voor een ander AuthorizationEndpointuri dan het adres waarop de PGO doorgaans gebruikers laat inloggen.
Randvoorwaarden
Testcases
Hier zijn minimaal de volgende testcases/flows van toepassing:
Happy flow: gebruiker logt correct in en geeft toestemming
Unhappy flow: gebruiker logt niet in, error terug naar ontvangend PGO
Unhappy flow: gebruiker logt in maar geeft geen toestemming, error terug naar ontvangend PGO
Error flow(s): er gaat iets fout tijdens de uitwisselingen (internal server error)
Logging
De normale logging voor de use case Verzamelen, zoals op https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/logging-interface uiteengezet dient ook geïmplementeerd te worden voor de APD Auth Server & Resource bevragingen.
Nog te onderzoeken in fase ‘Ontwikkelen en geïsoleerd testen’
Moet de logging interface of software worden aangepast om logs van dit 'nieuwe type DVA’ te ontvangen?
Voorbeelden
Voorbeeld autorisatie-interface
Doel-PGO stuurt gebruiker door naar AuthorizationEndpointUri van bron-PGO met een redirect_uri.
Bron-PGO geeft een code terug of een error. Geeft de gebruiker geen autorisatie, dan toont doel-PGO een boodschap dat importeren mislukt omdat geen toestemming verleend is.
Voorbeeld token-interface
Doel-PGO stuurt een verzoek naar TokenEndpoint van APD en ontvangt een access_token-respons.
Bron-PGO stuurt een HTTP-4xx-statuscode en JSON-bericht bij geweigerde tokenverzoeken.
Toestemmingen

Na het inloggen, maar voor het verstrekken van een auth code voor de tokenuitwisseling, moet een gebruiker ook toestemming geven voor de overdracht van de data voor bepaalde tijd. Gedetailleerde uitleg over de opmaak van Toestemmingsverklaring in Afsprakenstelsel Core.
Hierbij geldt het volgende:
Voor bron-PGO’s is er nog geen langdurige toestemming, dit vinkje mist dus tegenover een normale DVA-uitwisseling.
Er is geen optie om te kiezen voor het uitwisselen van een deel van de data.
Gegevens verzamelen (PDF/A-lijst en document)
Uitvragen van de gegevens volgt Gegevensdienst 51: Verzamelen Documenten 3.0.
Het ontwerp MM-3.0-PLR-FHIR beschrijft een use-case ‘Raadplegen gezondheidsinformatie
in PDF/A door een patient’. Deelnemers ondersteunen deze standaard uit 2020. Specifiek voor PGO-Koppelvlak vragen wij deelnemers te kwalificeren op het raadplegen en sturen van documenten
met een typecodering MedMijPortabiliteitCodelijst.Export
(zie bijlage) onder code EXPORT
.
Op dit verzoek geeft APD een bundel FHIR STU3 terug dat geen of meer DocumentReference-entries bevat met verwijzingen naar PDF-documenten. Daarnaast voegt bron-PGO een portabiliteitsrapport in zoals beschreven in XML-schema’s.
De specificatie van entries is beschreven in DocumentReference. Het is aan bron-PGO om te bepalen hoeveel documenten uitgewisseld worden. Ze zijn steeds van het type application/pdf
, of bij een portabiliteitsrapport van het type application/xml
.
Nog te beantwoorden in fase 'Ontwikkelen en geïsoleerd testen’
Is het mogelijk om ook andere dingen dan PDF (zoals application/xml) uit te wisselen binnen gegevensdienst 51 of een revisie daarvan? Voorstel kort besproken met Nictiz, vervolg.
In een bundel met entries gaat de aandacht uit naar DocumentReference.content.attachment
. Bron-PGO heeft de keuze om documenten op twee manieren mee te sturen: als base64-encoded data, of als een verwijzing naar een url.
In bijlage voorbeeldtestdata vind je een bundel met beide varianten:
In veel gevallen zal een APD het document buiten een FHIR-server willen genereren.
Het kan dan nuttig zijn met attachment.url
te werken zoals in het voorbeeld hieronder.
Nog te onderzoeken in fase 'Ontwikkelen en geïsoleerd testen’
Laten we met deelnemers een keuze maken of attachment.url
niet de enige optie zou moeten zijn. Misschien FHIR profiel vaststellen waarbij attachment.data
helemaal niet meer mogelijk is (restrictive)?
Wel als mogelijkheid houden leidt tot extra testcases en mogelijk falen van een uitwisseling.
Graag de variant die we niet kiezen ook weghalen uit deze tekst.
In dit voorbeeld verwijst DocumentReference.content.attachment
naar een endpoint waar
een PDF-document met samenvatting op aanvraag gegenereerd wordt.
Tenslotte vind je in de testdata een voorbeeld van een eenvoudig portabiliteitsrapport in XML
met content-type application/xml. Bron-PGO verplicht zich dit mee te sturen en doel-PGO mag het rapport gebruiken als bedoeld in core.portabiliteit.100, buiten de scope van dit ontwerp.
Referenties in DocumentReference
PGO kan deze patiëntverwijzing uitvragen bij APD zoals dat mag gebeuren met verwijzingen in resources op elk FHIR-bericht. (Clients doen dit soms zelfs automatisch.) Tijdens kwalificatie is daarom toegestaan:
Zie ook: https://simplifier.net/nictiz-r4-zib2020/nlcorepatient
Let er bij een implementatie op dat een FHIR DocumentReference-bericht altijd een subject
-veld bevat. De velden status, type, subject en content zijn verplicht in STU3. Voegt Doel-PGO referenties in voor bijvoorbeeld subject
, author
en relatesTo
, dan moet doel-PGO ook het ophalen van de verwijzingen mogelijk maken.
Ophalen document
Wanneer gebruikers in een PGO het dossier met persoonlijke medische gegevens bekijken, dan is dit uiteraard netjes opgemaakt met kopjes en tabellen. Doorgaans in HTML+CSS of een opmaaktaal die
daar op lijkt. Deze opmaak is gekwalificeerd voor gegevensdiensten bij MedMij.
In de uitwisseling van een levensloopdossier tussen PGO’s willen we dat deze informatie op een gelijke wijze gepresenteerd wordt in PDF/A-documenten. PDF/A is een documenttype dat op lange termijn eenzelfde weergave van het document kan garanderen. Het is aan de sturende APD om een juiste vorm te vinden en aan het PGO om te bewaren onder bronvermelding.
De informatie van een medisch dossier mag in één of meerdere PDF-documenten.
Tijdlimiet access-token: 15 minuten
Het maken van een document met volledig overzicht van medische gegevens neemt tijd. Conform verantwoordelijkheid core.autorisatie.211 is een uitgegeven access-token 900 seconden geldig bij kortdurende toestemming voor gegevensuitwisseling (zie token-interface). Daaruit volgt dat doel-PGO in staat moet zijn om gegevens als een gegenereerd PDF-document binnen dit kwartier op te halen. Als een access-token verlopen is stuurt bron-PGO een 401 Unauthorized
conform core.authint.203. Het staat doel-PGO vrij de autorisatieflow en uitwisselen opnieuw te starten.
Tijdlimiet server-proxies en clients: 60 seconden
Afsprakenstelsel legt geen specifieke tijdlimieten voor verzoeken vast, maar aangenomen wordt dat verzoeken die langer dan een minuut nemen om response te genereren vaker tot time-outs leiden in server-proxies en clients. Resource interface schrijft daarom een response voor na maximaal 60 seconden. Time-outs buiten deze minuut zijn te voorkomen met uitgesteld ophalen (async-pattern).
Ondersteunen van uitgesteld ophalen met FHIR Async-pattern
Het ophalen van een documentverwijzing in DocumentReference.content.attachment.url
dient
FHIR Asynchronous Interaction Request Pattern te ondersteunen. Bron-PGO kan er voor kiezen een
HTTP-statuscode 202 Accepted
terug te sturen in plaats van een respons met het gangbare 200 OK
. Doel-PGO haalt het document dan later op van aangegeven locatie, tot 15 minuten na verzoek.
De gebruiker hoeft overigens niet te wachten tot het document is opgehaald: Doel-PGO kan hiervoor een melding tonen in de website of e-mail versturen naar de gebruiker zodra de gegevens zijn overgenomen.
In nieuwere versies van de FHIR-specificatie is asynchrone verwerking toegestaan wanneer een server de aanvraag heeft ontvangen, maar de verwerking nog niet is afgerond. De manier van werken is al tientallen jaren oud en krijgt de laatste jaren ook ingang in FHIR met ondermeer afspraken over status-polling. Omdat uitgestelde overdracht nieuw is en er binnen FHIR nog geen vaste afspraken zijn gemaakt waarin PGO kan aangeven dat er compatibiliteit bestaat, voegt MedMij een extra header toe. Bron-PGO past Async-pattern alleen toe als doel-PGO een header Prefer: respond-async
meestuurt in de aanvraag. Gegevensdienst Verzamelen Documenten 3.0 legt in volgende versie het verschil uit tussen beide headers. Bron-PGO stuurt header Preference-Applied: prefer-async
mee als deze Async toepast.
Praktisch alle webservers en applicatieservers ondersteunen deze vorm van uitgesteld ophalen. Gegevensdienst 51 is echter gebaseerd op FHIR STU3 waar dit patroon niet aanwezig is, deze backporten we daarom naar die gegevensdienst. Omdat het genereren van een PDF vrijwel altijd buiten de FHIR-server plaatsvindt kan een Bron-PGO die hier gebruik van wil maken het eenvoudig aanbieden. Doel-PGO moet er er rekening mee houden dat een 202 Accepted
respons met header Content-Location
kan terugkomen bij het uitvragen van een document. In dat geval moet Doel-PGO op een later moment opnieuw binnenhalen.

Doel-PGO toont een melding voor uitgestelde overdracht
na het ontvangen van een HTTP 202 Accepted-respons.
Voorbeeldaanpak async ophalen
Kiest Bron-PGO voor uitgestelde verwerking, dan stuurt de webserver een 202 Accepted
terug met een status-endpoint in header Content-Location
om het bestand op te halen. In dit voorbeeld laten we twee endpoints genereer_pdf en status zien. Deze mag je ook samenvoegen tot één endpoint.
Het status-endpoint kan elk adres hebben en geeft een statusrepons of het bestand terug. Een minimale implementatie volgt onderstaand voorbeeld, maar Bron-PGO mag er voor kiezen een OperationOutcome in de body mee te sturen als extra informatie. Header Retry-After
geeft aan hoeveel seconden te wachten voor het opnieuw pollen van de statuspagina.
Een foutmelding als 429 Too Many Requests
leidt tot langzamer statuspollen, andere foutmeldingen leiden in Doel-PGO tot een bericht aan de gebruiker dat het ophalen mislukt is. Is het PDF-document gereed, dan geeft het status-endpoint bij Bron-PGO dit meteen terug.
Voorbeeldaanpak endpoints samenvoegen
In dit voorbeeld laten we twee endpoints genereer_pdf en status zien. Merk op dat in async-pattern de twee ook samengevoegd mogen in één endpoint waarop de status 202 Accepted
terug blijft komen met headers Retry-After
en Content-Location
naar het eigen endpoint. Dat maakt de implementatie vaak eenvoudiger. Bij een implementatie kunnen extra query-parameters ook nuttig zijn, zoals een document-id:
Voorbeeldaanpak converteren webpagina’s
PGO’s verzamelen steeds nieuwe informatie. Documenten zoals deze PDF’s met samenvatting mogen al beschikbaar zijn in bijvoorbeeld een FHIR-resourceserver, maar omdat de informatie ververst zullen de documenten vaker nog beschikbaar gemaakt op moment dat een aanvraag van PGO bij APD loopt. Het is mogelijk om conversiesoftware de inhoud van webpagina’s snel om te laten zetten naar PDF/A.
Een voorbeeld met de software van Gotenberg is:
Uiteraard is iets dergelijks ook mogelijk met een PDF-template of een template in markdown, zolang de inhoud gelijkwaardig is aan de inhoud zoals dat te zien in op de website van het PGO. Het resultaat in voldoet aan minimale vereisten voor PDF/A, bijvoorbeeld PDF/A-1 en daarbinnen is PDF/A-b ook toegestaan.

Voorbeeld volledig_overzicht_patiënt.pdf
Gebruik lettertypen en grafisch werk geschikt voor onbeperkt delen
Patiëntgebruikers houden de beschikking over PDF-documenten die een PGO voor hen maakt. Het doel is om de documenten ook in de toekomst te downloaden en mee te nemen naar een ander PGO. Gebruik daarom bij het ontwikkelen alleen materialen die ingesloten mogen en onbeperkt gedeeld.
Alle in de PDF/A-documenten gebruikte lettertypen dienen over een ‘permissive licence’ te beschikken met minimale restricties die het insluiten (embedding), reproduceren en verspreiden van het lettertype toestaat, in overeenstemming met de vereisten van de PDF/A-standaard (ISO 19005). We gebruiken geen lettertypen of beeldmateriaal waarvan de licentie dergelijke toepassingen beperkt of uitsluit. Houd daar rekening mee wanneer je bijvoorbeeld het logo of de huisstijl van een PGO toepast op het document. Soms liggen hierop beperkingen in verveelvuldiging, bijvoorbeeld van een ontwerpbureau.
Gegevens plaatsen in document op basis van beschikbaarheid
Het doel van uitwisselen documenten langs koppelvlak is om meerwaarde te bieden aan
een patiëntgebruiker die verzamelde informatie in levensloopdossier wil meenemen naar
een ander PGO. Het is aan APD om daar namens gebruiker een afweging in te maken.
Zo bewaren PGO’s sommige medische gegevens deels in het dossier. Goed voorbeeld daarvan zijn (radiologische) beelden die op aanvraag opgehaald worden bij zorgaanbieders en een reeks met veel beelden opleveren. Als gegevens niet beschikbaar zijn of de presentatie ervan in een samenvatting overweldigend veel inhoud oplevert, dan laat de APD deze buiten het document.
Testscenario’s en testcases
Op het flows in het ontwerp zijn minimaal de volgende scenario’s van toepassing.
Zie Bijlage testscenario's (Q125-PGOK v0.4.1) voor een volledig overzicht van testscases.
Scenario met testcases ‘happy flow’: de gebruiker vraagt de lijst met bundel van DocumentReference op. De lijst bevat een verwijzing naar drie documenten, waarvan twee in de bundel en één buiten de bundel. De drie documenten worden correct ontvangen. Het document buiten de bundel is aangeboden met een async-respons (202 Accepted en Location-header) waarbij de status eens opgevraagd (200 OK).
Scenario met testcases ‘unhappy flow’: de gebruiker vraagt de lijst op, er komt een lege bundel terug zonder document, een document of de status kan niet opgehaald worden (HTTP 4xx, 5xx). Het PGO toont een foutmelding naar gebruiker met de optie opnieuw te proberen.
Scenario met testcases ‘error flow’: de gebruiker vraagt de lijst op, de lijst bevat het gevraagde document maar het ontvangen neemt te lang. Ontvangend PGO toont een timeout-melding na 5 minuten met de optie opnieuw te proberen.
Te implementeren veranderingen
Doel-PGO (APD) biedt services aan om een FHIR-request te beantwoorden, afgeschermd met een autorisatietoken. Het volgt de dezelfde flow waarlangs PGO-gebruikers inloggen bij DVA’s voor gegevensoverdracht. Bij implementatie kan een documentservice nuttig zijn om PDF-documenten te genereren op verzoek, praktisch op eenzelfde wijze als gebruikers HTML-pagina’s op verzoek bekijken.
Dat betekent dat een doel-PGO de volgende veranderingen moet doorvoeren:
OIDC-autorisatieservice met ondersteuning voor OIDC-flow (OAuth 2.0).
FHIR-resourceserver met endpoint voor een bundel van DocumentReference resource.
Optioneel PDF-documentservice met endpoint voor uitlezen van gegenereerde PDF/A.
Een minimale implementatie van resourceserver voldoet, beperkt tot Verzamelen Documenten. Het is niet nodig een volledige FHIR-server neer te zetten. Een doel-PGO mag er voor kiezen uit een webserver een relatief eenvoudig HTTP-response terug te sturen met een JSON-bericht op dezelfde manier als FHIR-servers doen.
Vereiste aanpassingen in doel-PGO:
Implementeren autorisatieservice langs OpenID Connect met ondersteuning voor simpele consent-vraag met short-lived tokens. Patiëntgebruiker krijgt dit gepresenteerd als als een toestemmingsverklaring zonder opties voor langdurige toegang, dat wil zeggen zonder refresh-tokens.
Implementeren Resource Server met minimaal FHIR-endpoints voor opvragen
Patient
-resource waarnaar verwezen wordt in DocumentReferenceBundel met
DocumentReference
-resourceOndersteuning ophalen van een document in
DocumentReference.content.attachment.url
.
Vereiste aanpassingen in bron-PGO:
Lokaliseren beschikbaarstellende doel-PGO’s in zorgaanbiederslijst MedMij Register.
Tonen van schermen voor het selecteren van een PGO en statusmeldingen importeren.
Ondersteuning voor het ophalen van documenten met uitgestelde Async-verwerking,
dat wil zeggen: kunnen omgaan met een202 Accepted
-respons en status-polling.