Koppeltaal 2.0 Implementation Guide (Full Documentation)
0.16.3 - ci-build
Koppeltaal 2.0 Implementation Guide (Full Documentation)
0.16.3 - ci-build
Koppeltaal 2.0 Implementation Guide (Full Documentation) - Local Development build (v0.16.3) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
| Page standards status: Draft |
| Versie | Datum | Wijziging |
|---|---|---|
| 0.0.1 | 2026-04-01 | Initiële versie |
| 0.0.2 | 2026-06-10 | AuditEvents voor authenticatie (login: /authorize, IdP-call, IdP-besluit), HTI-introspectie en authenticatie aan applicatiezijde toegevoegd; AuditEvents voor de opschoning-lifecycle toegevoegd, inclusief veldmapping (action, agent.who, entity.what, outcome) per lifecycle-event |
| 0.0.3 | 2026-06-15 | 3.6 vereenvoudigd: alle authenticatie-events gebruiken DCM#110114 / DCM#110122 met de geauthenticeerde gebruiker op entity.what (entity.role 1/6/15) en de handelende systemen (applicatie, IdP) op agent.who; differentiatie via outcome en agent.who(2); 3.7 bijgewerkt: T_authorize en T_introspect_hti zijn query-equivalent, samengevoegd als T_auth; §3.8 mapping verduidelijkt |
| 0.0.4 | 2026-06-17 | 3.6 herzien tot één User Authentication-sectie: vier varianten binnen subtype DCM#110122, onderscheiden via een prefix in outcomeDesc (introspect, authorize, idp call, idp login) die de AuditEvent Viewer als subtype toont; de voormalige aparte introspect-sectie is hierin opgegaan. Authenticatie aan applicatiezijde (nu 3.7) krijgt een eigen subtype DCM#110126 "Node Authentication" (event Application User Authentication). Resterende secties hernummerd (3.8→3.8→ |
Datum: 2 april 2026 Voor: Koppeltaal Technical Community Van: Kees Graveland & Roland Groen Onderwerp: Overzicht wijzigingen in TOPKT011 en impact voor gekwalificeerde applicaties
In voorbereiding op release KTV 2.4.0 van de Koppeltaalvoorziening worden diverse wijzigingen uit de nieuwe versie van TOPKT011 – Logging & Tracing doorgevoerd. Dit memo geeft een overzicht van de relevante wijzigingen en de impact hiervan op applicaties die gebruikmaken van Koppeltaal.
De nieuwe versie van het topic is gepubliceerd op Confluence.
De laatste definitieve versie van het topic die door leveranciers geïmplementeerd moet zijn, is versie 1.3.4.
De wijzigingen die nu worden doorgevoerd in KTV 2.4.0 zijn óók relevant voor applicaties, maar leiden niet tot een aparte kwalificatieronde voor Topic 11.
Leveranciers die zich opnieuw laten kwalificeren kunnen deze wijzigingen direct meenemen in de reguliere kwalificatieprocedure.
Bij het verwerken van de updates uit TOPKT011 ligt de nadruk op die elementen waar de applicatie zelf verantwoordelijk voor is. De aanpassingen worden hieronder per AuditEvent gespecificeerd.
AuditEvents worden in Koppeltaal door twee producenten aangemaakt:
De events van producent 1 zijn voor leveranciers vooral informatief; zij zijn opgenomen omdat ze het bewijsanker vormen voor patiëntbetrokkenheid.
Alle AuditEvents krijgen de volgende generieke aanpassingen:
source.site wordt vastgelegd volgens de nieuwe specificatieoutcomeDesc is aangescherpt en dient door de applicatie correct gevuld te wordenGeen aanvullende aanpassingen naast de wijzigingen die voor alle AuditEvents gelden.
Geen extra wijzigingen buiten de generieke aanpassingen.
Naast de generieke wijzigingen:
type: code gewijzigd naar receive, display naar "Receive/Retain Record Lifecycle Event"agent.who, agent.type en agent.requestor van de verzendende partij zijn verwijderd. Deze informatie wordt vanaf nu alleen voor de ontvangende partij vastgelegd.Geen verdere inhoudelijke wijzigingen naast de generieke aanpassingen.
De authenticatiegebeurtenissen binnen het Koppeltaal-domein worden vastgelegd als User Authentication AuditEvents van het type DCM#110114 / subtype DCM#110122 "Login". De Koppeltaalvoorziening genereert deze events; de applicatie hoeft ze niet zelf aan te maken — ze zijn voor leveranciers relevant als bewijsanker voor patiëntbetrokkenheid (zie §3.8 en opschoning-patient-data.html).
De vier varianten delen dit ene subtype — er zijn dus geen aparte subtypes — en worden onderscheiden via een prefix in outcomeDesc (bijvoorbeeld introspect: Introspect succesvol), die de AuditEvent Viewer als subtype toont. Ze volgen de launch-flow in de tijd:
| Prefix | Wanneer |
|---|---|
introspect |
Launch via HTI: introspectie van het HTI launch token |
authorize |
Launch via SMART app launch: de /authorize-call |
idp call |
Optioneel vanuit /authorize: de gebruiker wordt naar de externe IdP gestuurd |
idp login |
De redirect terug: het IdP-besluit (outcome 0 geslaagd / 8 geweigerd) |
Bij elke variant staat de geauthenticeerde gebruiker (Patient / RelatedPerson / Practitioner) op entity.what en de uitvoerende applicatie als agent.who(1). Bij de IdP-stappen (idp call / idp login) komt de IdP daar als tweede handelende partij bij op agent.who(2). Een mislukte idp login (outcome 8) doet niets af aan de betrokkenheid die introspect of authorize al heeft vastgelegd.
Het introspect-event wordt alleen vastgelegd voor HTI launch tokens; introspectie van access- of id-tokens is een technische validatie en levert géén AuditEvent op. Omdat introspect en authorize dezelfde coding delen (met de gebruiker op entity.what), zijn ze query-equivalent en samengevoegd in T_auth, wat de bewaartermijn-berekening vereenvoudigt tot max(T_auth, T_task_owner) (zie opschoning-patient-data.html).
Naast de authenticatie die de Koppeltaalvoorziening zelf vastlegt (§3.6), kan een applicatie de patiënt of naaste ook buiten de Koppeltaal-authenticatieketen authenticeren (bijvoorbeeld een eigen sessie-login). Voor een volledige toegangslog SHOULD de applicatie hiervoor zelf een AuditEvent aanmaken en vastleggen: een eigenstandig event (Application User Authentication) met een eigen subtype DCM#110126 "Node Authentication" onder type DCM#110114. Anders dan de in-keten events (subtype DCM#110122) markeert dit patiëntactiviteit búiten de keten.
source.site: de domeinnaam van de applicatie; source.observer: de Device-referentie van de applicatie (Device/<id|client_id>).entity.what: de geauthenticeerde Patient / RelatedPerson / Practitioner (entity.role 1 / 6 / 15), conform de mapping van User Authentication; agent.who: de applicatie (Device/client_id, requestor=true).Hiermee is ook patiëntbetrokkenheid die niet via /authorize of de HTI-introspectie loopt aantoonbaar. Samen met DCM#110122 geeft DCM#110126 een volledig beeld van de patiëntactiviteit; beide subtypes tellen mee in de bewaartermijn-afleiding (last-patient-engagement, zie opschoning-patient-data.html).
Voor het opschonen van patiëntdata (zie opschoning-patient-data.html) legt de Koppeltaalvoorziening elke aggregaat-overgang van het opschoon-proces (over de per-app KT2_DeletePendingTasks heen, niet elke losse Task-write) vast in een immutable AuditEvent met ISO 21089 lifecycle-codes op AuditEvent.type (http://terminology.hl7.org/CodeSystem/iso-21089-lifecycle). Deze events overleven de $purge en vormen de aantoonbare audit trail van het verwijderproces.
| Aggregaat-overgang | type |
action |
Doel |
|---|---|---|---|
| Aangekondigd (Task(s) aangemaakt) | archive |
C |
Aantoonbaar: verwijdering aangekondigd, grace period begint |
| Geblokkeerd — eerste handrem | hold |
U |
Aantoonbaar: het proces is geblokkeerd |
| Gedeblokkeerd — laatste handrem eraf | unhold |
U |
Aantoonbaar: de laatste blokkade is losgelaten |
| Grace-reset — holds gewist, grace herstart | archive |
U |
Aantoonbaar: grace period herstart, alle holds gewist |
Afgebroken (cancelled) |
reactivate |
U |
Aantoonbaar: verwijdering afgebroken wegens hernieuwde betrokkenheid |
$purge uitgevoerd (completed) |
destroy |
D |
Aantoonbaar: data definitief vernietigd; draagt tevens het post-delete signaal |
Deze delete-AuditEvents zijn server-owned en geaggregeerd: de Koppeltaalvoorziening logt de geaggregeerde proces-status per Patiënt (één event per overgang), niet elke losse Task.status-write. Een tweede hold of gedeeltelijke release levert dus geen event op; unhold volgt pas op de láátste. Enkele velden zijn voor álle events gelijk en staan daarom niet in de tabel: agent.who = de Koppeltaalvoorziening, agent.type = DCM#110153 "Source Role ID" (requestor = true), outcome = 0, en entity.what = altijd de Patient (entity=Patient/{id}), nooit de Task. De reden van een hold (Task.statusReason) leeft per-applicatie op de Task en verdwijnt met de $purge. Een eigen subtype is niet nodig — de ISO 21089-code op type is al onderscheidend. Ook de generieke velden gelden (request-id/correlation-id/trace-id, source.site, source.observer, recorded). Deze AuditEvents bevatten geen PII — uitsluitend technische referenties — zodat zij de $purge en de langere bewaartermijn overleven.
Impact voor leveranciers. Applicaties reageren via hun eigen Task.status (on-hold/accepted); de Koppeltaalvoorziening logt daaruit de geaggregeerde lifecycle-events — een enkele app-actie leidt niet één-op-één tot een AuditEvent. Voor het moment van definitieve verwijdering subscriben doelapplicaties op het destroy-event (type = …iso-21089-lifecycle|destroy): omdat de Task in het Patient-compartiment mee verdwijnt in de $purge, is dit AuditEvent de enige bron voor het post-delete signaal.
DCM#110114 / DCM#110122 (met variant-differentiatie via de outcomeDesc-prefix), §3.7 gebruikt DCM#110114 / DCM#110126; de tijdlijn voor opname in de reguliere kwalificatie wordt in een vervolgtraject bepaald.De aanpassingen in TOPKT011 die in release KTV 2.4.0 worden meegenomen, zijn beperkt en richten zich vooral op uniformiteit en verduidelijking van de AuditEvents. De impact op leveranciers is overzichtelijk. Leveranciers hoeven geen aparte kwalificatie te doorlopen maar kunnen de wijzigingen meenemen bij een toekomstige reguliere kwalificatie.