3.7 Wijzigen Task Status Module

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 6. Uitwisselen launch-context.

• De Task-id komt uit het token-responseveld resource (bijv. "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 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.

Processtappen

Procesdiagram

Procesdialoog

2. Retrieve FHIR Task

GET {baseUrl}/Task/350755BC-E573-4004-91A3-91321E4BCA2A
Accept: application/fhir+json
Authorization: Bearer {ACCESS_TOKEN}
X-Correlation-ID: {GUID}

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" }
]

zie ook: FHIR HTTP REST interface: https://hl7.org/fhir/R4/http.html

De task Id komt uit de token response veldnaam resource van 3.6 Ontvangen launch context

3.6: 6. Uitwisselen launch-context

POST https://dvauth.example.org/connect/token
Content-Type: application/x-www-form-urlencoded
  grant_type=authorization_code&
  code=SplxlOBeZQQYbYS6WxSbIA&
  redirect_uri=https://module_redirect_uri.example.org&
  client_id=module_client_id&
  client_secret=module_client_secret

HTTP 200 OK
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 500,
  "scope": "launch fhirUser patient/.read patient/Task.",
  "patient": "Patient/XXX_Patient",
  "fhirUser": "Patient/XXX_Patient",
  "resource": "Task/350755BC-E573-4004-91A3-91321E4BCA2A",
  "intent": "startmodule",
  "return_url": "https://pgo.example.org/launch_callback"
  ...
}

Task-State diagram:

Relatie tussen het taakstatusdiagram en FHIR R4 Task.status

Het onderstaande statusdiagram sluit vrijwel 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

Ons statusmodel bevat al deze statussen, met uitzondering van:

• entered-in-error – bedoeld voor administratieve fouten (“taak had nooit mogen bestaan”).
  Deze status wordt zelden gebruikt, maar hoort formeel wel bij de FHIR-state machine.

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

Fouten & gedrag

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

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

• 409: versie-conflict → ETag/If-Match gebruiken en opnieuw ophalen. Indien dit wordt ondersteunt.

• 422: 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.