Koppelmij Implementation Guide - Local Development build (v0.1.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

Gegevensdienst Verzamelen Aanbiedertaken

Changelog

Inleiding

In KoppelMij fungeert het PGO als het centrale overzicht voor de cliënt. De cliënt wil in één oogopslag alle taken van verschillende zorgaanbieders zien — zonder eerst in afzonderlijke modules te moeten kijken. Dit vereist dat individuele taken binnen een module zichtbaar en launchbaar zijn vanuit het PGO.

Deze pagina beschrijft de FHIR-gegevensdienst Verzamelen Aanbiedertaken: welke FHIR-resources beschikbaar zijn bij de DVA, en wat de gegevensafspraken zijn tussen de betrokken partijen. De gegevensdienst is de eerste MedMij-gegevensdienst die uitvoerbare (launchbare) data bevat.

Scope

De gegevensdienst definieert twee gegevensafspraken:

1. PGO - DVA: welke data het PGO ophaalt bij de DVA (taken, opdrachten, moduledefinities, endpoints).
2. Module - DVA: welke data de module leest en schrijft in de context van een SMART on FHIR launch (taakcontext, statusupdates).

Buiten scope van deze gegevensdienst

De gegevensdienst legt vast wat er uitgewisseld wordt, niet hoe de data tot stand komt. De volgende onderwerpen vallen buiten scope:

• Catalogusbeheer van ActivityDefinitions — hoe de zorgaanbieder (niet noodzakelijk de DVA) de catalogus van moduledefinities opbouwt en uitwisselt met module-aanbieders.
• FHIR Workflow / Zorgplanning — hoe in een zorginformatiesysteem (XIS/ECD) het proces verloopt waarmee een behandelaar tot een Task of ServiceRequest komt.
• Subscription-mechanisme — hoe de module-aanbieder genotificeerd wordt over nieuwe ServiceRequests (orkestratie tussen module en CKT/zorgaanbieder).
• ActivityDefinition.kind als discriminator — de keuze tussen Task- en ServiceRequest-flow is een workflow-beslissing, geen onderdeel van de gegevensuitwisseling. Zie Harmonisatie met Koppeltaal voor context.

Betrokken partijen

FHIR Resources

Resource-relaties

De kern van het model:

• De ActivityDefinition verwijst via de extensie endpoint naar het Endpoint met het launch-adres.
• De Task verwijst via de extensie instantiates naar de ActivityDefinition die beschrijft welke module gelauncht wordt.
• Elke Task heeft twee referentiepaden naar ServiceRequest, elk met een eigen semantiek:

Twee rollen van ServiceRequest

Een Task verwijst naar twee verschillende ServiceRequest-instances:

Dit onderscheid is nodig omdat een individuele taak ("vul vandaag de vragenlijst in", "doe nu een meting") een eigen lifecycle heeft (requested → in-progress → completed), maar gebonden kan zijn aan een bredere en/of herhalende instructie. De basedOn ServiceRequest groepeert alle taken van een interventie; de focus ServiceRequest legt de specifieke opdracht vast die tot deze taak heeft geleid.

Beide zijn altijd verschillende resource-instances: de groeperings-SR opereert op interventieniveau, de instructie-SR op opdrachtniveau.

Gegevensafspraak PGO - DVA

Het PGO haalt taken op via de DVA FHIR-server. De zoekvraag is:

GET /Task?owner=Patient/{patient-id}

Het PGO groepeert de ontvangen taken op basis van Task.basedOn (verwijzing naar de groeperings-ServiceRequest). De display-naam van de groep komt uit ServiceRequest.code.text van de betreffende DigitalGroupPlan. Zo kan het PGO per interventie een overzicht tonen van individuele taken, met status per taak.

Het PGO resolvet het launch-adres via de keten Task → ActivityDefinition → Endpoint.address (zie Technical Walkthrough: Uitvoeren launch als PGO).

DVA is leidend voor Task.status. Na terugkeer van een module-launch MOET het PGO de taak opnieuw ophalen bij de DVA en uitsluitend de daar verzamelde status overnemen. Eventuele status- of error-query-parameters op de return_url zijn slechts een UX-hint waarmee het PGO direct een gebruikersvriendelijke melding kan tonen, zonder te wachten op de her-synchronisatie.

Gegevensafspraak Module - DVA (SMART on FHIR context)

De module ontvangt bij de SMART on FHIR launch de taakcontext (patient, task-id, fhirUser) en communiceert via het access_token met de DVA FHIR-server.

Lezen:

• GET /Task/{id} — opvragen van de taak waarvoor de module is gelauncht, inclusief de referenties naar basedOn en focus ServiceRequests.

Schrijven:

• PATCH /Task/{id} — bijwerken van Task.status via FHIRPath Patch (zie Technical Walkthrough: Wijzigen Task-status).

De volledige SMART on FHIR launch-flow (van launch-voorbereiding tot terugkeer naar PGO) is beschreven in de Technical Walkthroughs.

Link naar ActivityDefinition: extensie instantiates

In Koppeltaal wordt op de Task een custom extensie instantiates gebruikt om te verwijzen naar de ActivityDefinition. Het voorstel is om dezelfde extensie symmetrisch op de ServiceRequest toe te passen:

• De verwijzing van ServiceRequest naar ActivityDefinition wordt op dezelfde manier geïmplementeerd als bij Task.
• Een vergelijkbare SearchParameter kan worden gedefinieerd voor ServiceRequest.
• Het zoek- en Subscription-criterium wordt gebaseerd op een bewezen mechanisme.

Harmonisatie met Koppeltaal (informatief)

De gegevensdienst is ontworpen in samenhang met Koppeltaal. Een belangrijk harmonisatiepunt is het gebruik van ActivityDefinition.kind als discriminator voor het type workflow:

Dit is een workflow-beslissing die buiten de gegevensdienst zelf valt — de DVA bevat het resultaat (de Tasks en ServiceRequests), ongeacht welk patroon tot hun creatie heeft geleid. Het PGO en de module hoeven het onderscheid niet te kennen; zij werken altijd met dezelfde FHIR-resources.

Ter vergelijking de huidige Koppeltaal-flow:

Zie de Memo: ServiceRequest als orkestratiemiddel voor de volledige analyse en de SMART Task-based Launch overwegingen voor vergelijking met het experimentele SMART Task-based Launch mechanisme.

Open vragen

Wie wordt de requester van de taken?

Wanneer de module taken aanmaakt binnen een ServiceRequest:

• De behandelaar — logisch vanuit zorgperspectief, maar de module kent de behandelaar mogelijk niet direct.
• Overgenomen van de ServiceRequest — Task.requester = ServiceRequest.requester. Dit lijkt het meest consistent: de behandelaar is en blijft de opdrachtgever.

Kan een ServiceRequest taken van meerdere module-aanbieders bevatten?

Het huidige voorstel gaat uit van één module-aanbieder per ServiceRequest. Een samengestelde opdracht (meerdere modules) verhoogt de complexiteit aanzienlijk en vereist nadere uitwerking.

Lifecycle-relatie ServiceRequest en Tasks

De bestaande Task lifecycle (requested → accepted → in-progress → completed) blijft van toepassing op individuele taken. De ServiceRequest introduceert een bovenliggende lifecycle:

• active: er kunnen nog taken worden toegevoegd.
• completed: alle taken zijn afgerond.
• revoked: de opdracht is ingetrokken.

De relatie tussen de Task-lifecycles en de ServiceRequest-lifecycle moet eenduidig worden gedefinieerd.

Referenties

• FHIR Workflow
• Clinical Order Workflow (COW) IG
• FHIR ActivityDefinition
• FHIR ServiceRequest
• FHIR Task
• MedMij R4 Provider Module IG - Technical Design
• Memo: ServiceRequest als orkestratiemiddel in KoppelMij