Skip to main content
Skip table of contents

3.7 Wijzigen Task Status Module

Inleiding

Doel

Aanbiedermodule haalt de FHIR Task op en wijzigt de status (bijv. requested → in-progress → completed) bij de (DVA FHIR-)Resource server.

Randvoorwaarden

  • Module heeft een access_token uit 3.6 Ontvangen launch context.

  • De Task-Id komt uit het token-responseveld resource (bijv. "resource":"Task/350755BC-...").

  • Task-status bevat 1 van de statussen beschreven door: http://hl7.org/fhir/task-status

  • Scopes omvatten o.a. patient/Patient.read, system/Task.* (lezen/schrijven) en juiste aud (audience) van de FHIR-server.

Aanbeveling voor moduleaanbieder

  • Voor tracebility is de logging wel gewenst voor module aanbieders, maar niet verplicht: Correlation-ID in requests (bijv. X-Correlation-ID) en log deze ketenbreed.

Proces sequencediagram

Processtappen

Processtap

Toelichting

  1. Ophalen FHIR Task (GET)

De Aanbiedermodule gebruikt het Task-Id uit de launch context en leest resource uit het Token Response.

Met een GET haalt de Aanbiedermodule de taakgegevens op om de Taak te starten.

  1. Toesturen Taak aan AM

De DVA Resource Server stuurt de Taak aan de AM met een 200 OK response.

  1. Wijzigen van status

De AM stuurt een PATCH message om de status van de taak te wijzigen.

  1. Bevestigen update

De DVA bevestigt de verwerking van de update met een 204 No Content response.

Task state machine

Het volgende Task state machine diagram komt uit FHIR R4 specificatie (Task - FHIR v4.0.1), en is ter kennisgeving opgenomen.

image-20251204-090542.png

Relatie tussen het taakstatusdiagram en FHIR R4 Task.status

Het onderstaande statusdiagram sluit volledig aan op de formele FHIR R4 Task.status-waardes. De overgangen requested → received → accepted → rejected komen overeen met de FHIR-states voor het “claiming & triage”-proces. Ook de uitvoer-staten (in-progress, on-hold, completed, failed, cancelled) zijn 1-op-1 beschikbaar in FHIR.

FHIR R4 definieert de volgende statussen:

  • draft

  • requested

  • received

  • accepted

  • rejected

  • ready

  • cancelled

  • in-progress

  • on-hold

  • failed

  • completed

  • entered-in-error

Om ervoor te zorgen dat de Persoon alleen relevante taken ziet (AM-FE-52 en 53):

  • De DVA MAG NIET een Taak met Task.status gelijk aan Draft versturen.

  • De DVP MOET een Taak met Task.status gelijk aan Draft negeren.

  • De DVA of Resource Server MAG NIET een taak versturen naar de DVP die de gebruiker en/of systeem vanuit status Draft annuleert (d.w.z. deze niet eerst naar de patiënt verstuurt als ‘klaar om uitgevoerd te worden’). Dit kan op diverse manieren worden opgelost, daar is keuzevrijheid. In het geval van een implementatie op een FHIR server, wordt de DVA AANBEVOLEN de Task.statusReason te vullen met de waarde draft2cancel.

  • De DVA MAG NIET een Taak met Task.status gelijk aan Cancelled EN Task.statusReason gelijk aan draft2cancel naar de DVP versturen.

  • De DVP MOET een Taak met Task.status gelijk aan Cancelled EN Task.statusReason gelijk aan draft2cancel negeren.

De andere Task.statussen wil de DVP wel ontvangen, want een Task, die ooit verzameld is, kan van Requested naar Entered-in-Error wijzigen en zou de Persoon voor consistentie wel willen terugzien.

Relatie taakstatus en starten Aanbiedermodule

Niet voor alle statussen hoort de Persoon door te kunnen gaan naar de Aanbiedermodule. De definitieve statussen die bepalen of de Persoon wel of niet naar de Aanbiedermodule gaat, worden in de Beta versie van het T.O. toegevoegd. 3.4 Ophalen Launch code en Authentication cookie heeft de status entered-in-error uitgewerkt.

Gebruik van ready versus requested/received/accepted

FHIR beschrijft twee mogelijke manieren om taken toe te wijzen:

  1. Volledig toewijzingsproces
    (requested → received → accepted/rejected)
    Geschikt wanneer de taak eerst aangeboden, geaccepteerd of afgewezen moet worden.

  2. Vereenvoudigd model
    (ready als startpunt)
    Geschikt wanneer er geen expliciet claim-/acceptatieproces nodig is.
    Een taak kan dan direct vanuit ready door naar in-progress.

Ons diagram gebruikt beide paden:

  • links het eenvoudige pad via ready,

  • rechts het uitgebreide pad met requested/received/accepted/rejected.

Beide zijn toegestaan binnen FHIR. In het Solution Design kan worden aangegeven dat:

  • Wanneer een DVA taken aanbiedt die expliciet geaccepteerd moeten worden, worden de staten requested, received en accepted gebruikt.

  • Wanneer er geen acceptatiestap nodig is, mag de taak direct in ready gezet worden.

Tussentijdse status

Een Aanbiedermodule bijvoorbeeld met een vragenlijst kan tussentijds resultaten bewaren en een (tussentijdese) gereedmelding opslaan bij Zorgaanbieder haar DVA.

Aanvullende richtlijnen voor wijzigen van Task.status

(onderscheid gebruikersgedrag vs. systeemfouten)

Bij het wijzigen van de status van een FHIR Task is het belangrijk om een expliciet onderscheid te maken tussen:

  • bewuste gebruikerskeuzes (annuleren, pauzeren, stoppen), en

  • technische of functionele fouten.

Een foutstatus mag uitsluitend worden gebruikt wanneer sprake is van een systeem- of verwerkingsfout.
Gebruikersgedrag mag niet als error worden geïnterpreteerd, om vervuiling van foutstatistieken en onjuist inzicht in gebruik te voorkomen.

Ontwerpprincipe (leidend)

Een error-status (failed, entered-in-error) duidt altijd op een systeemfout en nooit op een gebruikerskeuze.

Fouten & gedrag

  • 400 (Bad Request): ongeldig/foutief verzoek

  • 401 (Unauthorized)/403 (Forbidden): token ongeldig of scope ontbreekt (system/Task.*).

  • 404 (resource not found): Task niet gevonden (check id uit resource).

  • 412 (Precondition Failed): Test of de versie failed; versie-conflict → ETag/If-Match gebruiken en opnieuw ophalen. Indien dit wordt ondersteunt.

  • 422 (Unprocessable Content): businessregel in FHIR-server (statusovergang ongeldig); vul statusReason of gebruik businessStatus.

De status van de taak wordt bepaald door de voortgang van de gebruiker in de module en de zorgverlener in het behandelportaal /XIS. De module-leverancier en het XIS zijn verantwoordelijk voor de taakstatus en niet de PGO of DVA.

Verantwoordelijkheden

  • Aanbiedermodule & XIS

    • bepalen en zetten de juiste Task.status

    • maken onderscheid tussen gebruikersgedrag en systeemfouten

  • PGO

    • interpreteert taakstatussen

    • toont gebruikersvriendelijke meldingen

    • toont op basis van de error-statussen failed / entered-in-error een gebruikersvriendelijke melding of indicator. Dit MAG in een categorie, zoals ‘Mislukt’ of ‘Gestopt’.

  • DVA

    • faciliteert statuswijzigingen via FHIR

    • is niet verantwoordelijk voor interpretatie van gebruikersgedrag

Procesdialogen

De Procesdialogen zijn ter illustratie. Alleen de essentie is weergegeven. Zo zijn uitgebreide headers van HTTP vrijwel altijd weggelaten. Sommige waarden zijn fixed, andere variable. De variable parameters hebben een voorbeeld waarde gekregen.

CODE 
2. Retrieve FHIR Task

GET {baseUrl}/Task/350755BC-E573-4004-91A3-91321E4BCA2A
Accept: application/fhir+json
Authorization: Bearer {ACCESS_TOKEN}
X-Correlation-ID: {GUID}
CODE 
3. Update FHIR Task (via PATCH)

PATCH [baseUrl]/Task/350755BC-E573-4004-91A3-91321E4BCA2A
Content-Type: application/json-patch+json
Accept: application/fhir+json
Authorization: Bearer {ACCESS_TOKEN}
X-Correlation-ID: {GUID}
If-Match: W/"{versionId}" (als e-tags worden/kunnen ondersteunt)

[
  { "op": "replace", "path": "/status", "value": "in-progress" }
]

//als alles goed gaat
HTTP 204 NO-CONTENT

//als workflow het niet toestaat
HTTP/1.1 422 Unprocessable Content
Content-Type: application/fhir+json
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "conflict",
      "diagnostics": "Task cannot transition from status 'completed' to 'in-progress'."
    }
  ]
}

//bij ETag mismatch, versie die je controleert is verie 5 en is al geupdate naar versie 6
HTTP/1.1 412 Precondition Failed

//bij fout in PATCH zelf
HTTP/1.1 400 Bad Request
Content-Type: application/fhir+json
{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "invalid",
      "details": {
        "text": "Invalid JSON Patch document."
      }
    }
  ]
}

Einde Procesdialoog.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close