DVPA-s API

Inleiding

Deze specificatie beschrijft het koppelvlak tussen een zorginformatiesysteem (XIS) en de Dienstverlener Push Autorisatie "source", de DVPA-s. De DVPA-s heeft de rol van een autorisatie server. Het in de DVPA-s geïmplementeerde push autorisatie concept ervoor zorgt dat alleen zorgverleners die een voor deze zorgverlener uitgegeven en aan deze zorgverlener gebonden push autorisatie URL (pa-URL) hebben, via deze URL patiëntendossiers kunnen opvragen bij of gegevens kunnen opsturen naar de bron.

Het XIS kan specifieke brondocumenten (records) van patiënten aanmelden bij de DVPA-s, waarbij het XIS metadata van de patiënt en een aantal parameters waaronder een security policy registreert. Het resultaat is dat een specifieke pa-URL wordt aangemaakt die naar een beoogde 'target' (bijv. een huisartsenpost) wordt gestuurd. Alternatief is dat deze URL (of een autorisatiecode die is afgeleid van de URL) wordt teruggegeven aan het XIS, zodat het XIS deze kan opsturen naar de beoogd ontvanger. Hiermee ontstaat een vorm van gerichte lokalisatie en autorisatie.

Met de pa-URL kan de ontvanger actuele patiëntgegevens direct bij de bron ophalen. Afhankelijk van de policy kan de geautoriseerde partij ook een nieuwe URL opvragen, die kan worden doorgegeven aan een andere partij - als dit is toegestaan door de security policy.

Semantiek van pa-URLs

De DVPA-s bepaalt het formaat van een pa-URL. Deze URL bevat voor de ontvanger leesbare informatie over:

• rechten zoals lees/schrijf/kopieerbaar zijn van een URL
• of de URL met een eenmalige (binding) PIN beschermd is
• de geldigheid (expiration date)
• het via de pa-URL bevraagbare type informatie (het doctype).

Voorbeeld: https://vrbld-amsterdam.md-net.nl/abcdef123456789/MEDEUR-WNH.

De ontvanger mag een pa-URL niet wijzigen. Wijziging van een pa-URL maakt deze ongeldig.

De syntax of semantiek van pa-URLs is geen onderdeel van deze specificatie.

Algemene workflow koppeling en gebruik DVPA-r

• Het XIS moet bij de DVPA-r aangemeld worden zodat de DVPA-s het XIS herkent, zie DVPA-s specificatie.
• Het XIS meldt een protocol aan via welke gegevens opvraagbaar zijn. De DVPA-s moet dit protocol kennen en krijgt een endpoint en credentials van het XIS om het protocol te kunnen gebruiken.
• Het XIS registreert de naam van het via dit protocol opvraagbare document, bijvoorbeeld MEDEUR-WNH, HL7v3-PS of HL7v3-AMO. Dit wordt een doctype genoemd.
• Na registratie van één of meerdere doctypes/protcollen kunnen via de API referenties -- pa-URLs -- aangemaakt worden. Per patient én per document kunnen meerdere referenties aangemaakt worden, elk met eigen metadata, target,
  doctype en policy.
• pa-URLs en autorisatiecodes kunnen door het XIS verstuurd worden, of via de DVPA-s. In dat geval worden policy en adressering gekoppeld in een door de DVPA-s aangeboden target module. Zo'n module is policy- en target-specifiek en zorgt ervoor dat adressering (verzending) van een pa-URL en metadata op een hoog niveau van betrouwbaarheid plaatsvindt. Dit onder meer door te controleren dat de geaddresseerde (de 'target') van het type is waar de policy voor bedoeld is.

Opmerking: bij het bevragen van een pa-URL kan in plaats van een document ook een redirect worden teruggegeven naar een endpoint waar de gegevens kunnen worden opgehaald. Voor deze specificatie wordt uitgegaan van direct opvragen van gegevens via de DVPA-s maar via een OAuth-achtige flow kan bijvoorbeeld naar een FHIR server worden doorverwezen die gegevens oplevert, waarbij de DVPA-s als authorisatie server fungeert. Zo'n flow is ïmplementeerbaar en functioneel equivalent aan het direct teruggeven van informatie.

Koppeling XIS - DVPA-r (enroll)

Zie enroll.

1. Introductie

De kern van de DVPA-s is het aanmaken (en waar nodig versturen) van push autorisatie URLs (pa-URLs), en het op een later moment kunnen opvragen van patiëntgegevens wanneer een pa-URL bevraagd wordt.

Het aanmelden van de voor deze functionaliteit benodigde informatie omvat een algemeen voorbereidende deel en een per-patiënt/per-autorisatie deel. Deze delen worden hieronder op hoofdlijnen uitgelegd. Vervolgens beschrijft deze specificatie elk API onderdeel in detail.

1.1 Algemene (voorbereidende) API calls

Een DVPA-s ondersteunt één of meer protocollen die door het XIS geïnstantieerd kunnen worden zodat de DVPA-r gegevens bij het XIS kan opvragen. Voor het instantiëren van een protocol registreert het XIS:

• een endpoint (URL) en credentials waarmee de DVPA-r een geauthhenticeerde verbinding kan leggen met het XIS;
• de naam - een well-known doctype - van het via dit endpoint op te vragen gestandaardiseerd document, in combinatie met een details veld waarin de voor dit doctype parameters gespecificeerd kunnen worden waarmee het protocol dit specifieke doctype kan opvragen (als het endpoint meerdere doctypes beschikbaar stelt);
• optionele aanvullende protocol-specifieke parameters die gebruikt kunnen om bijvoorbeeld gefilterde gegevens te kunnen opvragen bij het XIS.

De bedoeling van het op deze manier inregelen van een protocol is dat een protocol instance eenduidig gekoppeld wordt aan een doctype dat betekenis heeft voor de buitenwereld. Bij het aanmaken van een pa-URL (zie verderop in deze API) wordt een protocol-instance meegegeven, zodat de DVPA-r weet welk doctype moet worden opgenomen in de te genereren pa-URL. Op deze manier wordt het doctype dat via de pa-URL opvraagbaar is kenbaar gemaakt aan de partij die de pa-URL ontvangt.

Bij het maken van een protocol instance kan het XIS zelf een naam opgeven die gebruikt wordt om te refereren naar het geïnstantieerde (doctype-specifieke) protocol. De naam heeft geen semantische betekenis maar meestal wordt de doctype string gebruikt voor consistentie en helderheid van de broncode. Als het XIS geen naam opgeeft, genereert de DVPA-s een naam.

De protocol-instantie wordt later in het proces gebruikt bij het maken van een push autorisatie, zodat de informatie via het juiste protocol kan worden opgehaald.

Verschillende scenario's voor het instantiëren van een protocol zijn denkbaar. Zo kan het XIS op één endpoint meerdere protocol-instanties voor verschillende doctypes registreren, waarbij de details verschillen zodat uiteindelijk het bij doctype horende document wordt opgehaald. Ook is het toegestaan dat er meerdere protocol-instances met verschillende endpoints zijn voor eenzelfde doctype, bijvoorbeeld als een ^[?] voor meerdere organisatie-onderdelen van eenzelfde zorgaanbieder wordt ingezet met verschillende groepen patiënten in elk een eigen subsysteem.

1.2 Per-patient/autorisatie API calls

Om voor een specifieke patiënt een push autorisatie (pa-URL) aan te maken, wordt de protocol-instantie aangevuld met informatie specifiek voor de patiënt en de autorisatie. Een deel van deze informatie wordt extern zichtbaar als onderdeel van de aangemaakte pa-URL

Een pa-URL heeft een URL schema waarin belangrijke informatie verplicht of optioneel gecodeerd kan worden, zodat de ontvanger van de pa-URL weet wat hij/zij met deze URL kan. Een externe specificatie beschrijft dit schema in detail.

De eigenschappen kunnen per patiënt en per autorisatie verschillen.

De calls om een PA aan te maken hebben deze informatie nodig:

• protocol: de naam die refereert naar een specifiek protocol voor het ophalen van gegevens
• policy: een referentie naar een autorisatiepolicy voor een bepaald type toepassing, bijvoorbeeld "Waarneming-Huisarts" of "Apotheek-Medicatieoverdracht"
• doctype geeft aan ^[?] via de pa-URL opvraagbaar is.
• patient: een resource die de patiënt beschrijft, bestaande uit een metadata record en een interne patientID die nodig is om het specifieke dossier van deze patiënt op te vragen.
• sync is een structuur met een sync flag (boolean) die aangeeft welke patiënt metadata mag worden ^[?] met de ontvangende partij. Een mask geeft aan welke metadata gedeeld mag worden (bijv. BSN of adresgegevens moeten soms onderdrukt worden).
• gpdata bevat informatie over de eigen huisarts en de eigen apotheek (KvK naam), die belang kan zijn voor partijen die een pa-URL ontvangen. Dit vult de patiënt metadata aan. Het XIS moet de metadata en de gpdata regelmatig
• expiration-date(optioneel): de maximale termijn waarop het document beschikbaar is, ongeacht de policy. Deze expiry kan eventuele policy defaults overrulen.
• externalID: een identifier waarmee de patiënt wordt aangeduid. Deze identifier wordt door het XIS bepaalt en wordt in de pa-URL geplaatst, alsmede in alle pa-URLs die aangemaakt worden bij een doorautorisatie en zijn afgeleid van de oorspronkelijke pa-URL. Dit geeft controle over welke ID in welke situatie meegegeven wordt als deel van de pa-URL: BSN, een permanent of one-time (^[?], of niets.

Mogelijk kan in de toekomst ook een patiënt-specifiek filter gespecificeerd worden dat aangeeft welke informatie - ongeacht de policy of omstandigheid - maximaal mag worden opgevraagd voor een specifieke patiënt.

Het registreren van bovengenoemde gegevens en het aanmaken van autorisaties wordt in het navolgende beschreven.

1.3 Doctypes

Een kernconcept in push autorisatie - en in elk ander systeem voor het uitwisselen van medische gegevens - is het doctype. Een doctype is de naam die gegeven wordt aan een gestructuurd document met een specifieke inhoud in een specifiek technisch formaat.

Een doctype is beschreven als een string en is opgenomen in elke pa-URL die door de DVPA-s wordt uitgegeven. Hierdoor weet de ontvanger van de URL welke gegevens via de URL kunnen worden opgevraagd (of teruggestuurd), in welk formaat.

Een aanname is dat er een externe codelijst met doctypes komt die iedereen kent. Tot dat moment definiëren we doctypes zelf. Er kunnen ook 'custom' doctypes gebruikt worden.

Voorbeelden van bekende doctypes zijn:

• HL7v3-PS: een professionele samenvatting voor huisartswaarneming (WNH)
• MEDEUR-AMO: een actueel medicatieoverzicht van de apotheek (verstrekkingshistorie).
• MEDEUR-AMP+: een actueel medicatieoverzicht van de huisarts (voorschrijfhistorie) inclusief ICA gegevens.

Een doctype beschrijft zowel de 'drager', dwz het technische format waarin de gegevens uit het brondossier gecodeerd zijn, als de inhoud van het document, bijv. 'professionele samenvatting conform het NHG model (PS)' of 'Actueel Medicatie Overzicht (AMO)'.

De string doctype omvat beide aspecten in de vorm drager-inhoud. Idealiter worden doctype-strings landelijk toegekend en in lijst met doctypes op basis van de informatiestandaarden die Nictiz bijhoudt.

De beschrijving van de inhoud van een doctype ("PS", "AMO") is geen garantie dat bepaalde informatie ook daadwerkelijk aanwezig is in de opgevraagde gegevens. Zo kunnen specifieke gegevens worden onderdrukt door het toepassen van een policy of op verzoek van de patiënt.

Voor niet-gestandaardiseerde of aangepaste doctypen wordt de prefix CUSTOM_ gebruikt, bijv. "CUSTOM_HL7v10-PS".

---

- Voorbereidende calls -

---

2. Protocol registratie

Een XIS heeft één of meerdere protocollen waarmee de Whitebox medische gegevens kan opvragen bij een dienst die deel uitmaakt van het XIS.

Method	Out	Beschrijving
protocol_list	protocol [ ]	Bij DVPA-s bekende protocollen

protocol_list geeft een lijst van de protocollen die de DVPA-r ondersteunt.

Naam	Protocol
http-mvwi-0.1	Medeur-flow over https (DEPRICATED)
http-medeur-0.1	Get MEDMWC direct over http
http-HL7v3-PS	Get HL7v3 huisartsen-PS over http
todo-vidivici	How to get data?

• http-medeur-0.1 is eenvoudig protocol welke simpelweg een MEDEUR (MEDMWC) resource teruggeeft als resultaat van een GET met een patient id op een http(s) endpoint (en POST voor pushback/terugsturen naar de bron).

Elk protocol heeft een endpoint, gespecificeerd via een URL. Daarnaast kunnen afhankelijk van het protocol diverse parameters worden ingeregeld, om een specifiek doctype op te kunnen vragen bij het XIS, al dan niet met een toe te passen filter.

De volgende API wordt gebruikt voor het instantiëren van door de DVPA-s ondersteunde protocollen:

Method	In	Out	Beschrijving
protinstance_add	protocol, doctype, details, name, rw	name	Instantieer protocol
protinstance_get	name	details	Vraag protocol informatie op
protinstance_set	name, details	details	Stel protocol details in
protinstance_remove	name	(geen)	Verwijder protocol

protinstance_add wordt gebruikt door het XIS om het protocol te instantiëren voor het ophalen van een specifiek soort document.

name kan gekozen worden door het XIS, bijvoorbeeld doctype. Er kan ook een null-value worden meegegeven, dan genereert en retourneert de DVPA-r een naam.

doctype is een string die het document type (bijv. "HL7v3-PS") beschrijft.

details bevat protocol-specifieke parameters die vanuit de DVPA-r moeten worden meegegeven voor het opvragen van een document.

rw geeft aan of het protocol voor ophalen (r) of wegschrijven / pushback bedoeld is. Aangezien doctype(s) verschillen voor lezen en schrijven zal een protocol óf 'r' óf 'w' specificeren. Waarvoor in het vervolg ophalen geschreven wordt kan ook schrijven gelezen worden.

Bij akkoord geeft de DVPA-s de naam terug.

Via `protinstance_get' is de 'details' structuur op te vragen. Deze bevat de eerder opgegeven informatie aangevuld met eventuele defaults wanneer waarden niet gespecificeerd waren.

protinstance_set kan gebruikt worden om details te wijzingen, bijvoorbeeld bij migratie van een endpoint of bij roll-over van authenticatie credentials (bijv een bearer token).

When migrating a credential (key), the DVPA-s keeps the old key usable until the first time that the new key is used. When before that a new credential is set, the intermediate (unused) key will be replaced by the new one. Thus at most one forward-credential is kept in the DVPA-s.

protoinstance_remove semantiek: als een protocol instance verwijderd wordt, zijn alle URLs die dit protocol gebruiken per direct ongeldig. De DVPA-s onthoudt de van de protoinstance naam wel. Bij heraanmelding van een nieuw protocol onder dezelfde naam en met eenzelfde doctype en filtername strings, maar voor het overige mogelijk volledig andere details, worden de daarop gebaseerde URLs weer geldig.

2.1 Protocol details

Hieronder staat de structuur details:

Key	type	Description
url	string	Protocol instance base-URL
auth	object	Details waarmee de DVPA-s het XIS kan authenticeren
cred	object	Details waarmee het XIS endpoint de DVPA authenticeert
protospecs	object	Optioneel: protocol specific extensions
filterspecs [ ]	object	Optioneel: rules to request a specific filtered doc

url is mandatory. URL bevat een http of https endpoint inclusief port, waarop gegevens opvraagbaar zijn. Protocol URLs wijzen nooit naar een specifiek bestand, maar naar het basispad./Dynam

URL protocol	Beschrijving
https	HTTPS (e.g. https://server.example.com:port/prefix/)
http	HTTP (e.g. http://server.example.com:port/prefix/ of HTTP over local IP: http://1.2.3.4:port/prefix)

auth wordt gebruikt wanneer het XIS géén https-endpoint met een geldig domeincertificaat aanbiedt. Via auth kan het XIS informatie aan de DVPA-s meegeven waarmee de DVPA-s het endpoint kan authenticeren.

Hieronder staat de structuur auth:

Key	Type	Beschrijving
type	string	Currently, only "spki" (key pinning format) allowed
key	opaque	the encoded SPKI

cred specificeert een authenticatie methode specificeren voor het aanroepen van de API (URL), inclusief een credential waarmee de DVPA-r het XIS kan bevragen voor (aangemelde) documenten. Dit wordt per protocol ingesteld.

Hieronder staat de structuur creds:

Key	Type	Beschrijving
type	string	"spki" (key fingerprint format) or "token" bearer token
key	opaque	the encoded SPKI or Bearer token for HTTP authorization header

protospecs is bedoeld voor protocols-specifieke informatie. Zo werd een AGB code vereist bij het (depricated) https-mvwi-v0.1 protocol omdat een AGB moest worden ingevuld in het MVWI verzoek. Een ander voorbeeld is een parameter die aangeeft welk type dossier moet worden opgeleverd als bericht conform een informatiestandaard. protospecs kan ook een volledige specificatie bevatten van de op te leveren gegevens (bijv. in FHIR). De inhoud is protocol-specifiek, daarom kan hier geen precieze inhoud beschreven worden.

filterspecs kan een lijst met een of meerdere filterbeschrijvingen (tenminste een filternaam) bevatten die aangeven hoe het XIS specifiek gefilterde informatie kan opleveren conform extern vastgelegde afspraken. Een voorbeeld is waarbij het basis doctype een MEDEUR representatie van de NHG professionele samenvatting is, met daarin een volledige episodelijst en 4 maanden werkblad (journaalregels). Een filter "MinimalPS+" kan zorgen dat het bericht zo wordt gefilterd dat het alleen plus-episodes en één week journaal bevat. De filter-specs kunnen naast de verplichte naam ook protocol-specifieke parameters en een filterspecificatie bevatten.

Hieronder staat de structuur filterspecs:

Key	type	Description
filtername	string	Filter string (may differ per doctype, see list below)
filter-desc	string	Optioneel: mens-leesbare beschrijving
filterparms	string	Protocol-implementation specific parameters for filer
filterspec-type	string	if filterspec: a type indicating the filterspec DSL
filterspec	object	Full filter rule description (language tbd)
delegate-to-dvpa	bool	Hiermee geeft het XIS aan dat het wil dat de DVPA-s (ook) filtert

2.2 Doctypes en filter namen

Een doctype bestaat uit een string "inhoud-structuur" die inhoud en technische representatie van een bericht beschrijft. Een doctype is over het algemeen voor een specifiek zorgdomein ontwikkeld. De (medische) inhoud wordt meestal beschreven in een informatiestandaard. De technische structuur van het bericht ligt ook vast. De medische inhoud wordt over het algemeen wordt op basis van een beroepsrichtlijn vastgelegd. Dit bepaalt de gegevensset die (maximaal) voor een doctype wordt opgeleverd.

Per doctype kan in aanvulling op de basisgegevensset ook een lijst met zogeheten filters worden gespecificeert, die de inhoud van een bericht kan inperken. Deze filters worden voor een gegeven doctype gespecificeerd, bijvoorbeeld op basis van autorisatieafspraken. Elk filter heeft een extern vastgestelde filtername. Dit is de filtername die in bovenstaande filterspecs structuur is opgenomen.

Een filter wordt door het XIS gespecificeerd bij het aanmaken van een pa-URL. De keuze kan afhankelijk zijn van het toepassingsgebied of de voorkeur van de arts of de patiënt. Uiteraard kan alleen een filter gekozen worden dat daadwerkelijk geïmplementeerd is door, en door het XIS is aangemeld bij het betreffende protocol.

Doctype filtering kan op meerdere plekken geïmplementeerd worden: in het XIS, in de DVPA-s, of (zekerheidshalve) op beide plekken. Als filtering in het XIS moet gebeuren, geeft het XIS de gekozen filter string mee als argument bij het opvragen van de gegevens. Als de DVPA-s de filtering implementeert, kan het XIS de flag delegate-to-dvpa zetten in de filterspec structuur.

Alleen filternamen van door het ^[?] geïmplementeerde filters mogen worden geregistreerd. Poging om filtering naar de DVPA-s te delegeren voor een filtername die de DVPA-s niet implementeert, retourneert een error.

Een voorbeeld van door Whitebox/Decozo gestandaardiseerde filternamen bestaat voor de huisarts(waarneem) samenvatting (PS):

• NHG-PS Actueel medicatieoverzicht + ICA, actieve eposides en journaalregels tot 4 mnd terug (Standaard NHG PS)
• Minimal-PS+ Actueel medicatieoverzicht + ICA, episodes met attentiewaarde en journaalregels laatste week
• Minimal-PS Als Minimal-PS+ maar zonder journaalregels
• Extended-PS Alle episodes + 1 jaar journaalregels
• AMO [NEW] Alleen medicatieoverzicht (apotheek als bron)
• AMO+ [NEW] Medicatieoverzicht + ICA (huisarts als bron)
• Lab [NEW] Alleen labresultaten
• Kidney [NEW] Alleen nierfunctie
• Notes-Only Alleen notitie voor waarnemer
• CUSTOM [NEW] Indicates that a custom filter is specified in filter

Wanneer een filter wordt toegepast, is het van belang dat de ontvanger van een pa-URL dit weet. Door de doctype en filter strings te concateneren en deze in de pa-URL te plaatsten, heeft een ontvanger altijd een consistent beeld van welk filter is toegepast.

Voorbeelden van "doctypes" uitgebreid met een filter string in een pa-URL zijn:

• HL7v3-PS:AMO
• HL7v3-PS:Mini-PS
• HL7v3-PS:NHG-PS
• MEDEUR-MWC:AMO
• MEDEUR-MWC:Mini-PS
• MEDEUR-MWC:Mini-PS+
• MEDEUR-MWC:Dynamic-PS
• MEDEUR-MWC:NHG-PS

Merk op dat de set van ondersteunde filters per doctype kan veranderen. Als toegepast, moeten deze filters binnen een toepassingsdomein qua naam en semantiek wel hetzelfde zijn.

3. Policies

Policies bepalen wie bij welke stap in een push autorisatie keten, gegevens mogen inzien, en welke gegevens dat zijn (mogelijk afhankelijk van rol). Policies kunnen ook beperkingen op doorautorisatie vastleggen. De policy wordt toegepast door de DVPA-r.

Policies zijn niet XIS-configureerbaar. De DVPA-r bevat enkele standaard policies. Zodra een of meer policy definitie talen zijn vastgesteld, kunnen kan de administrator van de DVPA-r mogelijk ook handmatig policies invoeren in de DVPA-r.

Er zijn heden een aantal ingebouwde policies, specifiek met de namen:

• "HAP", voor autorisaties bedoeld voor de huisartsenpost)
• "APO", voor autorisaties die door de huisarts naar een apotheker worden gestuurd,
• "HA" voor autorisaties die door de apotheker naar de huisarts worden gestuurd.

De DVPA-r API bevat methods voor het ophalen (listen) van policies die in de DVPA-r gebruikt kunnen worden.

Method	In	Out	Description
policy_list		name [ ]	Vraag lijst met policy namen op
policy_get	name	policy	Get policy

policy_get is nog niet geïmplementeerd. Deze call is bedoeld voor het ophalen van de policy definitie in een DSL, waarbij het type DSL wordt aangegeven in type. Gebruik van policy_get zal heden een lege policy retourneren.

Hieronder staat de structuur policy:

Key	Type	Beschrijving
name	string	Naam van de policy
type	string	Policy definitie taal (DSL)
policy	byte [ ]	policy definition

---

- Push autorisaties aanmaken -

---

4. Patient structuur

Een record met patient informatie is van belang om een koppeling te kunnen leggen tussen de metadata en andere informatie die relevant is voor de DVPA-s.

Dit zijn de calls voor het managen van de patiënt structuur die voor de DVPA-s relevante patiëntgegevens koppelt:

Method	In	Out	Description
patient_add	patientID, metadata, gpinfo, pt	pt	Set (meta)data and set/get ID pt
patient_get	pt	patient	Get the patient struct
patient_set	patientID, metadata, gpinfo	patient	(over)write patient
patient_delete	pt		Forbidden call

patientID is de patientID die de DVPA-s moet gebruiken om een document op te vragen bij het XIS.

metadata is informatie die de DVPA-s intern gebruikt om patiënt informatie te koppelen en om de patiënt voor de eigenaar te presenteren in, bijvoorbeeld, een user interface en in logging regels.

gpinfo bevat (actuele) informatie over de eigen apotheek en de huisarts; deze informatie mag alleen worden ingevoerd door de eigen huisarts.

pt is de identifier die het XIS wil gebruiken om de patient te identificeren bij patient-specifieke calls. Normaliter zal het XIS een eigen, XIS-interne patientID willen gebruiken. Het XIS kan pt ook leeglaten, dan zal de DVPA-r een ID toewijzen en teruggeven.

Hieronder staat de structuur patient:

Key	Type	Beschrijving
pt	string	De patientID die gebruikt wordt in API calls
metadata	object	Het metadata struct van de patiënt met o.a. bsn
patientID	string	Internal patientID used by XIS to identify patient
gpinfo	object	Informatie over de huisarts en eigen apotheek van de patiënt

Het XIS moet metadata en gpinfo regelmatig actualiseren, via een continu proces, of door patient_set aan te roepen bij een aanpassing van de metadata en gpinfo.

Als synchronisatie van metadata van toepassing is (zie pa-url management API) wordt gpinfo tegelijkertijd met de patiënt metadata geüpdatet (gesynchroniseerd) richting de betreffende target.

4.1 Patient metadata

The XIS can pass a general set of metadata about the patient to the DVPA-s. There is only one instance of this metadata per patient, since this information must be consistent in the DVPA-r and over all uses of this metadata.

The metadata is important for the DVPA-s to be able to group information of a specific patient in the management interface (UI) and when searching and displaying (logging) information.

datestamp carries the time the information is last set or updated. If metadata is passed to another party (e.g., the DVPA-r of the GP post of a pharmacist), the timestamp must be carried over to allow the recipient to check what is the most recent information of a patient (if it trusts the source).

Hieronder staat de structuur metadata:

Key	Type	maskname	Beschrijving
datetime	string	!maskable	Read-only: timestamp when data was set
bsn	string	b	Verplicht als beschikbaar: geldig BSN
name	string	f	Optioneel: volledige naam
birthdate	string	d	Optioneel: 1999-12-31
street	string	a	Optioneel: address
house_number	string	h	Optioneel
postal_code	string	z	Optioneel: 1234AA
city	string	p	Optioneel: place
gender	string	g	Optioneel: M, F, of UN

Er moeten altijd minimaal twee gegevens worden ingevuld: volledige naam en BSN of volledige naam en geboortedatum.

Voor een uitgebreide versie van de patiënt metadata see ^[?]

Aanvullend op de metadata kan het XIS ook gegevens over de eigen huisarts en de eigen apotheker invullen.

Hieronder staat de structuur gpinfo:

Key	Type	Beschrijving
datetime	string	Read-only: timestamp when data was set
gp	string	Qualified name of patient's GP
gp-uid	string	Qualified ID of patient's GP
pharmacist	string	Qualified name 'assigned'Ph
pharmacist-uid	string	Qualified Dezi/UZI id van eigen apotheek

LET OP: Deze structuur mag alleen gevuld worden door een huisarts(systeem); in andere systemen blijft de structuur leeg.

4.2 Syncing en masking metadata

De API om een pa-URL aan te maken en op te sturen (zie verderop) bevat ook een sync argument. Dit is een datastructuur die een flag (Boolean) sync bevat die bepaalt of de patiënt metadata voor de specifieke "target" waar de pa-URL naar wordt opgestuurd, de metadata mag ontvangen en zo ja, welke. Als syncen is toegestaan bepaalt een mask string welke velden gedeeld mogen worden (whitelist semantiek).

Deze call vult de policy aan en maakt het mogelijk deze te customizen op het punt van meesturen van metadata in aanvulling op de pa-URL. Merk op: dit is alleen relevant als de DVPA-s controle heeft over het opsturen van de pa-URL en de metadata.

Hieronder staat de structuur sync:

Key	Type	Beschrijving
sync	Bool	True als syncen/delen toegestaan, False als niet.
mask	string	A positive mask of shareable metadata elements, e.g., "f,g,d,a,h,p,z,c"
interval	int	An indicative value containing the number of seconds between syncs"

mask geeft aan welke metadata gedeeld mag worden. Dit kan verschillen per target, zie pa-URL management calls.

Let op: een policy kan ook een mask beschrijven voor een bepaalde target, op dezelfde wijze als de mask in bovenstaande structuur. Deze policy kan de sync mask overrulen. De effectieve mask is de logische AND van de twee masks,d.w.z. als één van de twee masks een bepaalde eigenschap niet aanmerkt als synchroniseerbaar, wordt deze niet gedeeld.

interval is geen garanties mbt het synchronisatie interval omdat praktische omstandigheden synchronisatie kunnen belemmeren. Het is bedoeld als een indicatieve upper-limit voor de DVPA-s binnen hoeveel tijd na een update informatie geüpdated moet worden bij de ontvanger. Het geeft ook een redelijke upper bound indicatie voor de ontvanger, van de maximale periode dat een metadata veld "out of sync" (inconsistent) kan zijn - uiteraard afhankelijk van omstandigheden én van hoe snel na een update het XIS de informatie richting de DVPA-r update.

5 Creating a pa-URL

Er zijn verschillende manieren van gebruik van een PA (pa-URL of autorisatiecode), die door de API ondersteund worden. Dit zijn de varianten:

Method	in:	out:
mkpa-return-pa-URL	pt, policy, prot_w[], prot_r, filter, binding, extid, expiry	pa
mkpa-return-code	pt, policy, prot_w[], prot_r, filter, binding, extid, expiry	pa
mkpa-and-send-to-target	pt, target, filter, expiry	pa-id

mkpa-return-pa-URL

De 'mkpa-return-pa-URL' geeft - afhankelijk van de opgegeven binding flags - een gebonden of een ongebonden pa-URL terug, die het XIS zelf kan opsturen (bijvoorbeeld, via een verwijsbrief). Bij een latebound pa-URL zal normalter ook een code (een PIN) worden geretourneerd, afhankelijk van de binding flags.

In argumenten van de calls:

pt is de identifier die de patiënt identificeert en die verwijst naar de patiënt structuur (sectie 4), inclusief de patiënt metadata en gpinfo structuren.

prot_w [ ] is de set protocollen, en daarmee de set van doctypen die via de pa-URL naar de bron kan worden gestuurd. Dit kunnen meerdere protocollen en dus doctypes zijn, waaruit de ontvanger van de pa-URL kan kiezen (bijv. een HAP systeem kan kiezen voor een gestructureerd journaal of een platte tekst notitie.) Beschikbare pushback doctypes worden niet in de pa-URL geplaatst maar zijn beschikbaar via https content negotiation.

prot_r is de naam van het protocol (en daarmee impliciet het doctype) voor het ophalen van gegevens via de te creëeren pa-URL.

filter is de naam van het (base) filter dat moet worden toegepast over het op te halen document, zie sectie 2. De mkpa call faalt als het filter niet geregistreerd was bij protocol instantiatie (sectie 1).

Merk op dat filters alleen bij ophalen (prot_r) gebruikt worden, aangezien bij pushback berichten de verzender explicet kiest wat er in dit bericht staat (push).

policy is de naam van een policy die moet worden toegepast op de aangemaakte pa-URL. De policy moet zorgvuldig gekozen worden zodat deze past de policy bij de target. Bijvoorbeeld, als de target een Huisartsenopst is hoort hier een policy "Waarneming-HAP" bij.

Voorbeelden van policy namen van de huidige Whitebox zijn:

• Waarneming-HAP (ANW waarneming huisartsen - hoort bij 'target' Huisartsenpost)
• Dagwaarneming (dag- en vakantiewaarneming)
• Apotheek (autoriseren van de apotheek)
• Visite (hoe kan autorisatie lopen via de digitale visitelijst)

extid is een identifier van de patiënt die in de pa-URL wordt opgenomen, naar keuze van het XIS.

expiry is een datetime string (of UNIX time?) die de expiration van de pa-URL aangeeft.

binding is een mechanisme waarmee verschillende eigenschappen van de uit te geven pa-URL kunnen worden geconfigureerd. Zie uitleg na mkpa-return-code.

pa: Voor de geretourneerde pa structuur, zie mkpa-return-pa-code.

mkpa-return-code

De 'mkpa-return-code' call geeft een autorisatiecode terug, in combinatie met de URL van de server waar de pa-URL onder het bijbehorende pseudoniem in geregistreerd, bijvoorbeeld "verwijscode.nl".

Deze call heeft dezelfde set argumenten als mkpa-return-pa-URL.

Beide calls retourneren een pa structuur.

Hieronder staat de PA-structuur pa:

Key	Type	Beschrijving
patient		PatientID struct incl. metadata
sync	object	sync / mask settings
policy	object	As specified when creating the PA
expiry	datetime	Verloopdatum referentie
filter	string	Filter settings
pa-url	string	Externe pa-URL
binding	object	Binding parameters incl. address, autcode etc.
logdata	logging	Logging data related to PA (todo)

Binding properties

Onderstaande binding structuur wordt zowel gebruikt voor het opgeven van binding properties (eigenschappen en constraints) bij het aanmaken van een pa-URL, als voor het opslaan van binding gegevens nadat een pa-URL is gebonden.

Hieronder staat de structuur binding:

Key	Type	Beschrijving
binding-type	object	Late-bound, pre-bound, late-bound-PIN
bind-to-type	object	person-bound, system-bound
bind-address	string	URL of target (if system-bound)
bind-id	string	UZInummer, URA, organization name ..
bind-constraints	object	Constraints like may only bind to BIG role
bind-role	string	Role (must match bind-constraints)
bindcode-type	object	(regular) PIN, authcode
bindcode	string	Actual PIN or autorization code
authcodeserver	string	if authcode: server e.g., "emergencycode.eu", ..

binding-type geeft aan of de pa-URL pre-bound of late-bound is. late-bound-PIN is een variant van late-bound pa-URL waarbij een PIN nodig is om te kunnen binden (dit is het geval wanneer een autorisatiecode wordt gebruikt).

bind-constraints is a set of strings with the form "attribute=value".

bind-constraints:

Key	Type	Beschrijving
BIG-rolcode [ ]	string	Lijst toegestane rolcodes die mogen binden

Heden worden alleen "BIG-rolecode=" strings ondersteund, voorbeelden:

• "BIG-rolcode=17.075" (openbaar apotheker).
• "BIG-rolcode=83.000" (apothekersassistent)
• "BIG-rolcode=01.015" (huisarts)
• "BIG-rolcode=01.004" (apotheekhoudend huisarts)

Codelijst: https://decor.nictiz.nl/pub/medicatieproces/mp-html-20200122T161947/voc-2.16.840.1.113883.2.4.3.11.60.1.11.2-2018-09-10T000000.html

Verdere binding parameters zullen elders worden toegelicht.

Opmerking: voor de ontvanger relevante bind eigenschappen zoals binding-PIN=y worden in de pa-URL gecodeerd.

mkpa-and-send-to-target

mkpa-and-send-to-target is bedoeld als manier om een pa-URL via een vertrouwde (betrouwbare) route af te leveren bij een target van een bepaald type, bijvoorbeeld HAP, Huisarts of Apotheek. Hierbij wordt een pa-URL (en metadata) naar een andere partij verstuurd via een vertrouwde target modules die door de DVPA-s wordt geïmplementeerd.

Target-modules zijn gekoppeld aan een vaste policy, en hebben een vastgesteld protocol (doctype) en policy type. Daarom is het bij deze call alleen nodig om de volgende gegevens te specificeren:

• pt is de patiënt informatie
• target is de naam van de target module of van een specifieke target binnen de target module (dit is een reguliere naam string, geen url).
• fiter is het filter dat op deze specifieke aanmelding moet worden toegepast
• expiry is de specifieke expiration van de te genereren pa-URL

De functie retourneert een pa-id. Met deze pa-id zijn via de call pa-get de precieze gegevens die via de target module zijn aangemaakt, inclusief pa-URL, op te vragen. Zie 5.2 "Listing pa-URLs".

Voor meer informatie, zie het hoofdstuk "Target modules"

6 Target modules

The DVPA-s can contain one or more preconfigured modules that provide a trusted path to one or more authenticated targets of a particular type, associated with a policy. Sending a PA to a target module provides the sending XIS with a high degree of confidence that the PA is send only to a specific (type of) target. Also, it provides for convenience in that the caller does not need to specify specific binding properties or policies as these are built-in into the target module as needed for a specific "target".

Voorbeelden van targets:

• Waarneming-HAP (ANW waarneming huisartsen - hoort bij 'target' Huisartsenpost)
• Dagwaarneming (dag- en vakantiewaarneming)
• Apotheek (autoriseren van de apotheek)
• Visite (hoe kan autorisatie lopen via de digitale visitelijst)

De voorbeeldnamen van deze targets komen niet toevallig overeen met voorbeeld policy namen. De idee van een target module is namelijk dat deze zorgt dat policy en geadresseerde (en tevens, doctype als onderdeel van het protocol) bij elkaar passen; dit voorkomt fouten bij het gebruik van push autorisatie.

Target-modules zijn voorgeconfigureerd en kunnen niet worden aangemaakt of aangepast door het XIS. Ze zijn vindbaar via de target-modules call:

Method	in:	out:	Beschrijving
target-modules		target-module [ ]	Set of strings (names)

Voordat een protocol gebruikt kan worden, zal het protocol van een target-module eerst door het XIS geïnitialiseerd moeten worden. Dit kan via onderstaande call, waarmee o.a. eerder geinitialiseerde protocollen (zie 2) met een bij de target passend doctype worden meegegeven aan de target-module:

Method	In:	Out:	Beschrijving
initialize-target-module	target-module, wprot[], rprot, policy, sync	(todo)	(todo)

Geïnitialiseerde modules krijgen een symbolische naam (eenvoudige strings, geen URLs). Deze wordt toegekend door de target module (DVPA-s).

Dit is de call om geinitialiseerde modules te kunnen vinden/listen:

Method	in:	out:	Beschrijving
target-module-list	[query todo]	name [ ]	Set of strings (names)

De eigenschappen van geïnitialiseerde target-modules kunnen worden opgevraagd via module-property-get.

Method	in:	out:	Beschrijving
module-property-get	name	module-properties	Object containing properties

De geretourneerde gegevens worden geretourneerd in module-properties:

Key	Type	Beschrijving
binding	object	System-bound, pre-bound always?
prot_r	object	protocol and thus doctype for reading
prot_w [ ]	object	protocols and doctypes for writing
policy	object	policy relevant for the target (built-in)
address [ ]	object	addresses linked - policy-module checks type matches policy
sync	object	sync policy, mask, frequency

Adressen zijn gecodeerd via de structuur address:

Key	Type	Beschrijving
name	string	symbolic address name modulename.addressname
url	string	real system address (URL) matching the target

Binding properties worden niet door het XIS gespecificeerd omdat die door de target module / policy worden bepaald.

Logische target namen

Targets zijn logische endpoints met een symbolische naam, zoals HAP (Huisartsenpost) of Apotheek, die wordt aangeboden via een target module. Een target module kan alleen werken als deze via een adres gekoppeld is aan een andere partij.

Voorbeelden van symbolische target namen zijn (case-insensitive):

• "apotheek" voor de (lokale/eigen) apotheek van de patiënt (zoals bekend in het HIS)
• "huisarts" voor de eigen huisarts van de patiënt (zoals bekend bij de apotheek)
• "hap" voor de huisartsenpost waarmee een waarneemcontract bestaat

Meestal wordt een adres ingeregeld door de administrator van de DVPA-s en door de administrator en/of de module gevalideerd. Dit kan door middel van controle van eigenschappen op het systeem certificaat van de geaddresseerde partij (waar bijv. de organisatie naam of een UZI nummer in kan staan), of door middel van f2f controle tussen de eigenaar van de DVPA-s en de andere partij - denk aan de apotheek en een huisarts die elkaar een brief met een koppelcode kunnen overhandigen.

Een module is pas zichtbaar voor het XIS is minimaal aan één endpoint (adres) gekoppeld.

In een aantal gevallen is het mogelijk om als XIS een extra adres (endpoint) toe te voegen aan een target module. Deze zal alleen worden goedgekeurd als de target module de eigenschappen van de 'target' heeft gevalideerd. Bijvoorbeeld door te controleren dat het adres verwijst naar een specifiek type zorgaanbieder (bijv. huisartsenpost, apotheker, huisarts).

Toevoegen (associeren) van een adres aan een module gaat via deze call:

Method	In:	Out:	Beschrijving
attach-addr-to-target-module	adress, target-module	(todo)	(todo)

Adressen van targets (doelbestemmingen) die aan een module gekoppeld zijn krijgen ook een symbolische ^[?]. Deze naam is geconstrueerd via een hierarchische conventie modulename.addressname. Voorbeeld: "hap.hap-maastricht" .

OPMERKING voor Jaap: bovenstaande call is nog niet geïmplementeerd.

7 Finding and listing pa-URLs

To manage PAs that were created before, this API can be used:

Method	In	Out	Beschrijving
pa-list	query parameters	pa-id [ ]	Zoek (root) PAs
subpa-list	pa-id	pa-id [ ]	Get child PAs
pa-get	pa-id	pa	Get PA record
pa-remove	pa-id		Remove PA (incl. children)

pa-getreturns a structured record pa of all data directly related to a push authorization.

Other methods take or return a pa-id, which is a DVPA-s assigned identifier for a pa-URL.

pa-list is a broad search call, for finding pa-URLs matching the query.

Possible query parameters are:

• target (URL or symbolicy target name)
• policy (possibly in combination with target name)
• doctype

Een belangrijke combinatie voor zoeken vanuit het XIS gezien is de combinatie target en policy. Bijvoorbeeld, de combinatie "HAP" "HAP" biedt snel inzicht in alle (root) PA's die zijn 'aangemeld' bij de huisartsenpost. Dit kan bijvoorbeeld zinvol zijn om geautomatiseerd nieuw aangemelde patiënten aan te melden.

Zoeken geeft alleen "root pa-URLs" terug, dat wil zeggen, pa-URLs die direct het resultaat waren van een mkpa- call. Child pa-URLs die het resultaat zijn van doorautoriseren worden niet direct geretourneerd. Deze zijn echter wel eenvoudig terug te vinden, via de call subpa_list.

subpa_list geeft een lijst met pa-id's van de directe kinderen van deze pa terug. Hier ook weer subpa_list op aanroepen, maakt het mogelijk recursief alle kind pa-URLs te vinden.

Verder heeft elke pa-URL een bijbehorende datastructuur met informatie over de PA:

• the full pa-URL
• associated data such as policy, protocol, pa-flags and other initialization information
• the patient structure including metadata
• when it was created, by whom
• an authorizationcode or a PIN associated to it, if any
• when it was bound, to whom, in what way
• when it was used (and by whom)
• child pa-URLs
• parent pa-URLs (if any)
• logregels?

Hieronder staat de structuur pa-struct:

Key	Type	Beschrijving
pa-url	doc_params	Externe pa-URL
policy		As originally specified
metadata	metadata	Patient metadata
expiry	datetime	Verloopdatum referentie
filter	filter	Filter settings
binding
logdata	logging	Logging data related to PA (todo)

Using this information, the caller can traverse the full tree of pa-URLs below a pa-URL, and find relevant information associated with any pa-URL.

Some or all of this information may overlap with logging data.