Technisch ontwerp (2025-PGOK)

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: Vaststellen dat PGO en APD gekwalificeerd zijn voor gegevensdienst 51 en authenticatie accepteren.

• Lokalisatie: PGO lokaliseert de juiste APD via het MedMij-register en de Zorgaanbiederslijst.

• Autorisatie: Gebruiker logt in, geeft toestemming en er vindt tokenuitwisseling plaats.

• Gegevens verzamelen: APD voert de functie Verzamelen uit, selecteert relevante gegevens en genereert maximaal één PDF/A-document (levensloop/overstapdocument).

• Beveiligd bewaren en logging: Alle stappen worden beveiligd uitgevoerd en gelogd volgens MedMij-standaarden.

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

In het metamodel van het afsprakenstelsel wordt deze uitbreiding vastgelegd in de basisklasse Aanbiedertype; het logisch model van de lijsten neemt deze aangepaste basisklasse over.

Meer over het Metamodel van Afsprakenstelsel : https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/metamodel
Meer over Logische modellen van Afsprakenstelsel : https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/logische-modellen

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-3.0-PLB-FHIR en MM-3.0-PDB-FHIR) uit 2020. Dit komt neer op het ophalen van een FHIR STU3 IHE.MHD.Minimal.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 lokalisatieflow

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.

    <Zorgaanbiederslijst>
      <Zorgaanbieders>
        <Aanbiedertype>APD</Aanbiedertype>
        <Interfaceversies>
          <Interfaceversie>
            <Gegevensdiensten>
              <Gegevensdienst>
                <GegevensdienstId>51<GegevensdienstId>

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 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.

HTTP 302 GET https://deoudepgo.nl/login/auth
  ?response_type=code
  &client_id=medmij.deenigeechtepgo.nl
  &redirect_uri=https://medmij.deenigeechtepgo.nl/importeren/auth_callback
  &scope=deenigeechtepgo
  &state=xcoivjuywkdkhvusuye3kch
  &MedMij-Request-ID=57510be1-73e6-4a75-9db8-ee005cced48f
  &X-Correlation-ID=c0e7b545-9606-4eef-bea7-75d8addaa54b

  https://medmij.deenigeechtepgo.nl/importeren/auth_callback?code=jhgRtpO12D3qR5tU9
  https://medmij.deenigeechtepgo.nl/importeren/auth_callback?error=access_denied

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.

HTTP POST https://deoudepgo.nl/token
  Content-Type: application/x-www-form-urlencoded
  X-Correlation-ID: c0e7b545-9606-4eef-bea7-75d8addaa54b
  MedMij-Request-ID: 57510be1-73e6-4a75-9db8-ee005cced48f

  grant_type=authorization_code&code=jhgRtpO12D3qR5tU9&
  client_id=medmij.deenigeechtepgo.nl&
  redirect_uri=https://medmij.deenigeechtepgo.nl/importeren/auth_callback

200 OK
  Content-Type: application/json
  {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 900
    "scope": "openid deenigeechtepgo"
  }

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 patiënt’. Deelnemers ondersteunen deze standaard uit 2020. Specifiek voor het overdragen van een levensloopdocument langs PGO-Koppelvlak vragen wij deelnemers te filteren op codes .. en …

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
HTTP GET [base-url]/DocumentReference?status=current

De raadplegende PGO doet hiermee een ‘kale’ 51‑aanroep: er wordt uitsluitend gefilterd op status=current. Verdere inhoudelijke selectie of businesslogica (welke gegevens precies in het dossierdocument komen) vindt volledig aan APD‑kant plaats.

Toepassing functie Verzamelen in deze use case

De functie Verzamelen, zoals beschreven in het MedMij-afsprakenstelsel en nader juridisch uitgewerkt, wordt in deze overstapservice door de APD toegepast op het volledige brondossier van de gebruiker. Op hoofdlijnen betekent dit dat de APD:

• de voor de gebruiker relevante gezondheidsinformatie selecteert uit het brondossier;

• gegevens die juridisch of inhoudelijk buiten scope vallen, weglaat;

• deze gegevens bundelt tot één logisch samenhangend levensloop‑/overstapdocument;

• dit document aanbiedt als PDF/A.

De exacte reikwijdte en weglatingscriteria volgen uit de juridische analyse; dit technisch ontwerp beschrijft de wijze van uitwisseling en de vereiste formaten. Op dit verzoek geeft APD een bundel FHIR STU3 terug dat geen of meer DocumentReference-entries bevat met verwijzingen naar PDF-documenten.

Content-Type: application/fhir+json
  200 OK
  {
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 1,
    "entry": [
      {
        (DocumentReference)
      }
    ]
  }

De specificatie van entries is beschreven in DocumentReference.

Voor de overstapservice stelt de APD op basis van de functie Verzamelen en eigen businesslogica maximaal één PDF/A‑document samen dat het medische levensloop‑ of overstapdossier bevat. Het aantal documenten met medische inhoud is daarmee in deze use case begrensd tot één.

De DocumentReference-resource wordt ingevuld met class (FHIR STU-3, ook wel category in R4) code http://snomed.info/sct|371535009 en type http://snomed.info/sct|408403008:

Bron-PGO heeft de keuze om documenten op twee manieren mee te sturen in DocumentReference.
content.attachment: als base64-encoded data, of als een verwijzing naar een url . In bijlage voorbeeldtestdata vind je een bundel met beide varianten:

   {
      "resource": {
        "resourceType": "DocumentReference",
        "class": {
          "coding": [{
            "system": "http://snomed.info/sct",
            "code": "371535009",
            "display": "Verslag van overdracht"
          }]
        },
        "type": {
          "coding": [{
            "system": "http://snomed.info/sct",
            "code": "408403008",
            "display": "Patient held record"
          }],
          "text": "Document met samenvatting patiëntinformatie"
        },
        "subject": { "reference": "Patient/medmij-bgz-test-patA" },
        "content": [
          {
            "attachment": {
              "contentType": "application/pdf",
              "data": "JVBERi0xLjQKJ... (base64-encode PDF-data)"
            }
          }
        ]
      }
    }

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.

In dit voorbeeld verwijst DocumentReference.content.attachment naar een endpoint waar
een PDF-document met samenvatting op aanvraag gegenereerd wordt.

          {
            "attachment": {
              "contentType": "application/pdf",
              "url": "https://deoudepgo.nl/genereer_pdf?document=voorbeeld123"
            }
          }

Let op: de attachment.url mag ook verwijzen naar een Binary-resource waarin het PDF-document opgenomen is als Base64-content. DocumentReference neemt in attachment.contentType naar application/pdf, ook als de url een Binary bevat. De FHIR-server geeft een respons met header aan dat het gaat om Content-Type: application/pdf of Content-Type: application/fhir+json.

          {
            "attachment": {
              "contentType": "application/pdf",
              "url": "Binary/voorbeeld123"
            }
          }

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:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
HTTP GET [base-url]/Patient/medmij-bgz-patient-ts-01

 Zie ook: https://simplifier.net/nictiz-r4-zib2020/nlcorepatient

Invoegen van een Patient-verwijzing (subject) in DocumentReference is optioneel.
Voegt doel-PGO referenties in voor bijvoorbeeld subject of author, dan moet het ook het ophalen van die verwijzingen mogelijk maken (Patient of Practitioner en Organization).

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.

Algemeen kan de informatie van een medisch dossier in één of meerdere PDF-documenten worden vastgelegd. In deze overstapservice wordt echter maximaal één PDF/A-document gebruikt.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
HTTP GET https://deoudepgo.nl/genereer_pdf?document=voorbeeld123

HTTP/2 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="export_medisch_patientdossier.pdf"

%PDF-1.4
...
stream
<?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>
<rdf:RDF ...>
  <rdf:Description ... pdfaid:part="1" pdfaid:conformance="B"/>
</rdf:RDF>
<?xpacket end='w'?>
endstream
...

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:

HTTP POST [documentservice] /forms/chromium/convert/url

  url= https://deoudepgo.nl/portal/volledig_overzicht_patient.html&
  pdfa=PDF/A-1b

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.

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 voor een volledig overzicht van testscases.

• Scenario met testcases ‘happy flow’: de gebruiker vraagt de lijst DocumentReference?status=current op. Hier zit een verwijziging in naar tenminste één document op overdracht levensloopdossier. Het document wordt correct ontvangen.
  

• 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 bron-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.

• Verkeer met autorisatieserver is net als ander verkeer tussen MedMij-deelnemers gebonden aan https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/verantwoordelijkheden-core#id-(MedMijAfsprakenstelsel2.2.6d)Verantwoordelijkheden,Core-Autorisatie waarin het raadplegen van de whitelist, de clientlist (OCL) en de common name van de in mTLS uitgewisselde PKI-overheidcertificaten tegen MedMij Register. Zie specifiek: core.rollen.207, core.whl.307, core.autorisatie.209.

• Implementeren Resource Server met minimaal FHIR-endpoints voor opvragen

  • Patient-resource waarnaar verwezen wordt in DocumentReference

  • Bundel met DocumentReference-resource

    • Ondersteuning ophalen van een document inDocumentReference.content.attachment.url.

• Op de ZAL PGO kwalificeren als aanbieder, met de typeaanduiding APD (aanbieder in het persoonsdomein). Deze aanduiding wordt in het metamodel vastgelegd in de basisklasse Aanbiedertype en in het ZAL‑schema Zorgaanbiederslijst.xsd (ZAL/XSD) toegevoegd. Dit heeft verder geen overige impact op de ZAL, behalve het uitbreiden van de enum/mogelijke typen van het veld Aanbiedertype : Zie https://afsprakenstelsel.medmij.nl/asverplicht/mmverplicht/metamodel

• Op deze pagina “XML-schema's” vind je in een nieuw voorbeeld schema Zorgaanbiederslijst.xsd (ZAL/XSD) , met dit nieuwe type ADP.

• Voor gegevensdienst 51 met systeemrol code MM-3.0-PLB-FHIR & MM-3.0-PDB-FHIR

Vereiste aanpassingen in Doel-PGO:

• Lokaliseren beschikbaar stellende doel-PGO’s in zorgaanbiederslijst MedMij Register.

• Tonen van schermen voor het selecteren van een PGO en statusmeldingen importeren.