...

...

Beschrijving

Voor Koppeltaal maken we gebruik van verschillende resource types. De verschillende resource types gebruiken verschillende elementen om aan te geven of de resource content daadwerkelijk gebruikt en wat de status binnen de levenscyclus is. Dit laatste is extra van belang binnen koppeltaal omdat er gebruik wordt gemaakt van soft-deletes; resources worden in normaal gebruik nooit echt verwijderd, maar door middel van status worden ze op inactief gezet. Hiervoor wordt het element active of het element status gebruikt. Het element active is van het type 'boolean' en het element status heeft een lijstje van kiesbare enumeratie waarden. Elk resource in Koppeltaal heeft een active of status veld, en het veld heeft daadwerkelijk een betekenis. Als aanbieder en afnemer van de FHIR resources is het van belang de status van de resource goed te verwerken.

Overwegingen

Semantiek

De resources binnen FHIR hebben in sommige gevallen een active veld met een boolean waarde, en in andere resources is er een status veld met een lijst aan mogelijkheden. Aangezien Koppeltaal gebruik maakt van soft-deletes worden deze velden gebruikt om de levenscyclus van de FHIR resources aan te geven. We zijn ons ervan bewust dat hier het venijn in de details zit; enige vorm van misinterpretatie van de status tussen systemen binnen en/of tussen domeinen kan tot verwarring, fouten en mogelijk conflicten leiden. De kernvraag die steeds geldt is welk gedrag er bij welke status hoort. Mag een inactieve gebruiker inloggen? Mag een voltooide taak gestart worden? Waar mogelijk proberen we daar antwoord op te geven. Om zoveel mogelijk bij de bestaande standaarden en semantiek aan te sluiten werken we in de volgende volgorde:

1. Wat Koppeltaal specificeert.
2. Wat de ZIBs er over zeggen.
3. Wat de FHIR specificatie zegt.

Hard Delete

In Koppeltaal wordt in normaal gebruik geen gebruik gemaakt van de delete functionaliteit, er wordt door middel van de status of active vlag aangegeven wat de huidige status van de levenscyclus van het FHIR object is. Echter, het gebruik van de delete blijft bestaan binnen koppeltaal in specifieke situaties zoals migraties en beheersscenario's. Hoewel nog niet duidelijk is om welke situaties het exact gaat, voorzien we dat er in de toekomst gebruik gemaakt gaat worden van deze functionaliteit.

Toepassing, restricties en eisen

De FHIR secificatie

Het volgende tabel is een lijstje van situaties per resource en de daarbij behorende element en waarde. Alle onderstaande waardes zijn ook terug te vinden via het profiel van iedere resource.

...

The patients record is not in active use

• Many systems use this property to mark as non-current patients, such as those that have not been seen for a period of time based on an organization's business rules.
• It is often used to filter patient lists to exclude inactive patients
• Deceased patients may also be marked as inactive for the same reasons, but may be active for some time after death.

Requirements

Need to be able to mark a patient record as not to be used because it was created in error.

...

If a record is inactive, and linked to an active record, then future patient/record updates should occur on the other patient.

...

The practitioner's record is not in active use.

Requirements

Need to be able to mark a practitioner record as not to be used because it was created in error.

...

The organization's record is not in active use.

Requirement

Need a flag to indicate a record is no longer to be used and should generally be hidden for the user in the UI.

Comment

This element is labeled as a modifier because it may be used to mark that the resource was created in error.

...

FHIR kent standaard een aantal mogelijke statussen voor een task. In de onderstaande tabel worden die aan Koppeltaal use cases gebonden, waaronder ook de launch.

De onderstaande tabel is overgenomen uit business use case: Toewijzen en volgen taak. De behandelaar kan van iedere statuswijziging een notificatie ontvangen en op die manier de voortgang van uitvoering blijven volgen.

...

Een behandelaar kiest een interventie voor een patient en maakt daarmee een taak voor de patiënt.

...

De behandelaar besluit dat de taak uitgevoerd mag gaan worden door de patiënt en geeft deze vrij.

...

De patiënt start met het uitvoeren van de taak

...

Er kan iets mis gaan tijdens de uitvoering van de taak

...

cancelled

...

De taak is succesvol afgerond

...

Zowel de behandelaar als de patiënt kunnen beide de taak inzien. Ieder vanuit hun eigen portaal.

...

...

Overige statussen van een task

Bovenstaande tabel beschrijft de voornaamste statussen die gebruikt zullen worden binnen Koppeltaal. Een taak kent echter ook een status-flow waarbij een taak-toekenning wordt beoordeel. De status "ready" wordt gebruikt wanneer de taak-toekenning een gegeven is. Binnen de GGZ is dit laatste bijna altijd het geval. Wanneer dit echter wel gebruikt wordt, dient de status als volgt behandeld te worden:

...

Hard Delete

Indien men gebruik maakt van de FHIR DELETE operatie wordt er een “logische” verwijdering uitgevoerd. Dat wil zeggen dat men niet meer bij de inhoud van de resource kan komen, en dus ook niet de status van de resource kan bekijken. Belangrijk hierbij is dat de gegevens niet fysiek uit de FHIR datastore (database) worden verwijderd.

Stel dat er een Patient resource met id 123 wordt aangemaakt (via HTTP POST /Patient) en vervolgens wordt deze Patient id=123 verwijderd (via HTTP DELETE Patient/123). De Patient resource krijgt hiermee een tweede versie van Patient/123 met versie Patient/123/_history/2 die gemarkeerd wordt als ‘deleted’.

Deze patiënt verschijnt niet langer in de zoekresultaten en pogingen om deze resource Patient/123 te lezen (met behulp van een HTTP GET Patient/123) zullen falen met een "HTTP 410 Gone" melding met een Location header die een URL bevat met resource id en versie id:

Location: http://example.org/fhir/Patient/123/_history/2

Het mooie is dat de originele resource inhoud niet wordt verwijderd. Men kan de geschiedenis van de resource nog steeds opvragen op de volgende manieren:

GET Patient/123/_history/1 of met GET Patient/123/_history/.

Voorbeelden

1 - Creëer een Patient Resource

POST http://hapi.fhir.org/baseR4/Patient/

{
  "resourceType": "Patient",
  "active": true,
 "identifier": [{
      "use": "usual",
      "system": "http://hl7.org/fhir/sid/us-ssn",
      "value": "555501234"
    }
  ],
  "name": [
    {
      "text": "Berend Botje",
      "family": "Botje",
      "given": [ "Berend" ]
    }
  ],
  "telecom": [{
    "system": "email",
    "value": "berendbotje01@vzvz.nl",
    "use": "home"
  }],
  "gender": "male",
  "birthDate": "1970-12-20",
  "managingOrganization": {
    "identifier":
    {
      "system": "http://fhir.nl/fhir/NamingSystem/agb-z",
      "value": "12345678"
    },
  "type": "Organization"
  }
}

Response:

{
    "resourceType": "Patient",
    "id": "2043390",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2021-04-19T13:15:53.052+00:00"
    },
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><div class=\"hapiHeaderText\">Berend <b>BOTJE </b></div><table class=\"hapiPropertyTable\"><tbody><tr><td>Identifier</td><td>555501234</td></tr><tr><td>Date of birth</td><td><span>20 December 1970</span></td></tr></tbody></table></div>"
    },
    "identifier": [
        {
            "use": "usual",
            "system": "http://hl7.org/fhir/sid/us-ssn",
            "value": "555501234"
        }
    ],
    "active": true,
    "name": [
        {
            "text": "Berend Botje",
            "family": "Botje",
            "given": [
                "Berend"
            ]
        }
    ],
    "telecom": [
        {
            "system": "email",
            "value": "berendbotje01@vzvz.nl",
            "use": "home"
        }
    ],
    "gender": "male",
    "birthDate": "1970-12-20",
    "managingOrganization": {
        "type": "Organization",
        "identifier": {
            "system": "http://fhir.nl/fhir/NamingSystem/agb-z",
            "value": "12345678"
        }
    }
}

2 - Verwijder (logische) de Patient Resource

DELETE http://hapi.fhir.org/baseR4/Patient/2043390

Response:

{
    "resourceType": "OperationOutcome",
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h1>Operation Outcome</h1><table border=\"0\"><tr><td style=\"font-weight: bold;\">INFORMATION</td><td>[]</td><td><pre>Successfully deleted 1 resource(s) in 12ms</pre></td>\n\t\t\t</tr>\n\t\t</table>\n\t</div>"
    },
    "issue": [
        {
            "severity": "information",
            "code": "informational",
            "diagnostics": "Successfully deleted 1 resource(s) in 12ms"
        }
    ]
}

3 - Bevraag de (verwijderde) Patient Resource a.d.h.v. de id

GET http://hapi.fhir.org/baseR4/Patient/2043390

Statuscode: "410 Gone"

Location: http://hapi.fhir.org/baseR4/Patient/2043390/_history/2

{
    "resourceType": "OperationOutcome",
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><h1>Operation Outcome</h1><table border=\"0\"><tr><td style=\"font-weight: bold;\">ERROR</td><td>[]</td><td><pre>Resource was deleted at 2021-04-19T13:18:00.818+00:00</pre></td>\n\t\t\t</tr>\n\t\t</table>\n\t</div>"
    },
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "diagnostics": "Resource was deleted at 2021-04-19T13:18:00.818+00:00"
        }
    ]
}

4 - Bevraag de historische gegevens van de Patient Resource a.d.h.v. de id en versieId

GET http://hapi.fhir.org/baseR4/Patient/2043390/_history/1

Statuscode: 200 OK

{
    "resourceType": "Patient",
    "id": "2043390",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2021-04-19T13:15:53.052+00:00",
        "source": "#vzvz_1235"
    },
    "text": {
        "status": "generated",
        "div": "<div xmlns=\"http://www.w3.org/1999/xhtml\"><div class=\"hapiHeaderText\">Berend <b>BOTJE </b></div><table class=\"hapiPropertyTable\"><tbody><tr><td>Identifier</td><td>555501234</td></tr><tr><td>Date of birth</td><td><span>20 December 1970</span></td></tr></tbody></table></div>"
    },
    "identifier": [
        {
            "use": "usual",
            "system": "http://hl7.org/fhir/sid/us-ssn",
            "value": "555501234"
        }
    ],
    "active": true,
    "name": [
        {
            "text": "Berend Botje",
            "family": "Botje",
            "given": [
                "Berend"
            ]
        }
    ],
    "telecom": [
        {
            "system": "email",
            "value": "berendbotje01@vzvz.nl",
            "use": "home"
        }
    ],
    "gender": "male",
    "birthDate": "1970-12-20",
    "managingOrganization": {
        "type": "Organization",
        "identifier": {
            "system": "http://fhir.nl/fhir/NamingSystem/agb-z",
            "value": "12345678"
        }
    }
}

{}

Toepassingsgebied

Onderbouwen

Eisen

...

Beschrijving

Voor Koppeltaal maken we gebruik van verschillende resource types. De verschillende resource types gebruiken verschillende elementen om aan te geven of de resource content daadwerkelijk gebruikt en wat de status binnen de levenscyclus is. Dit laatste is extra van belang binnen koppeltaal omdat er gebruik wordt gemaakt van soft-deletes; resources worden in normaal gebruik nooit echt verwijderd, maar door middel van status worden ze op inactief gezet. Hiervoor wordt het element active of het element status gebruikt. Het element active is van het type 'boolean' en het element status heeft een lijstje van kiesbare enumeratie waarden. Elk resource in Koppeltaal heeft een active of status veld, en het veld heeft daadwerkelijk een betekenis. Als aanbieder en afnemer van de FHIR resources is het van belang de status van de resource goed te verwerken.

Overwegingen

Semantiek

De resources binnen FHIR hebben in sommige gevallen een active veld met een boolean waarde, en in andere resources is er een status veld met een lijst aan mogelijkheden. Aangezien Koppeltaal gebruik maakt van soft-deletes worden deze velden gebruikt om de levenscyclus van de FHIR resources aan te geven. We zijn ons ervan bewust dat hier het venijn in de details zit; enige vorm van misinterpretatie van de status tussen systemen binnen en/of tussen domeinen kan tot verwarring, fouten en mogelijk conflicten leiden. De kernvraag die steeds geldt is welk gedrag er bij welke status hoort. Mag een inactieve gebruiker inloggen? Mag een voltooide taak gestart worden? Waar mogelijk proberen we daar antwoord op te geven.

Soft en Hard Delete

In Koppeltaal wordt in normaal gebruik geen gebruik gemaakt van de delete functionaliteit, er wordt door middel van de status of active vlag aangegeven wat de huidige status van de levenscyclus van het FHIR object is. Echter, het gebruik van de delete blijft bestaan binnen koppeltaal in specifieke situaties zoals migraties en beheersscenario's, zoals de use case /wiki/spaces/KTSA/pages/27080725. Hoewel nog niet duidelijk is om welke situaties het exact gaat, voorzien we dat er in de toekomst gebruik gemaakt gaat worden van deze functionaliteit.

Toepassing, restricties en eisen

De FHIR specificatie

Het volgende tabel is een lijstje van situaties per resource en de daarbij behorende element en waarde. Alle onderstaande waardes zijn ook terug te vinden via het profiel van iedere resource in simplifier.

Anchor
statussen_task statussen_task

Statussen van een task

FHIR kent standaard een aantal mogelijke statussen voor een task. In de onderstaande tabel worden die aan Koppeltaal use cases gebonden, waaronder ook de launch.

De onderstaande tabel is overgenomen uit business use case: Het kiezen, toewijzen, uitvoeren, en volgen van interventies . De behandelaar kan van iedere statuswijziging een notificatie ontvangen en op die manier de voortgang van uitvoering blijven volgen.

Overige statussen van een task

Bovenstaande tabel beschrijft de voornaamste statussen die gebruikt zullen worden binnen Koppeltaal. Een taak kent echter ook een status-flow waarbij een taak-toekenning wordt beoordeel. De status "ready" wordt gebruikt wanneer de taak-toekenning een gegeven is. Binnen de GGZ is dit laatste bijna altijd het geval. Wanneer dit echter wel gebruikt wordt, dient de status als volgt behandeld te worden:

Hard Delete

Indien men gebruik maakt van de FHIR DELETE operatie wordt er een “logische” verwijdering uitgevoerd. Dat wil zeggen dat men niet meer bij de inhoud van de resource kan komen, en dus ook niet de status van de resource kan bekijken. Belangrijk hierbij is dat de gegevens niet fysiek uit de FHIR datastore (database) worden verwijderd.

Stel dat er een Patient resource met id 123 wordt aangemaakt (via HTTP POST /Patient) en vervolgens wordt deze Patient id=123 verwijderd (via HTTP DELETE Patient/123). De Patient resource krijgt hiermee een tweede versie van Patient/123 met versie Patient/123/_history/2 die gemarkeerd wordt als ‘deleted’.

Deze patiënt verschijnt niet langer in de zoekresultaten en pogingen om deze resource Patient/123 te lezen (met behulp van een HTTP GET Patient/123) zullen falen met een "HTTP 410 Gone" melding met een Location header die een URL bevat met resource id en versie id:

Location: http://example.org/fhir/Patient/123/_history/2

Het mooie is dat de originele resource inhoud niet wordt verwijderd. Men kan de geschiedenis van de resource nog steeds opvragen op de volgende manieren:

GET Patient/123/_history/1 

Voorbeelden

Zie simplifier.