Kanta Potilastietovaranto Ajanvaraukset R4 versio 0.1

Mitätöinti

Ajanvarauksen mitätöinnissä käytettävän HTTP-pyynnön tiedot välittyvät HTTP header- ja body-osuuksiin jaettuna. Tällä sivulla kuvataan nämä osuudet tarkemmin mitätöintipyynnön osalta.

HTTP pyyntö (request)

Mitätöintipyyntö välitetään palvelulle HTTP pyyntönä (request) POST-metodilla FHIR-palvelun endpoint:in juureen. POST: [base]/

Esim. POST http://example.org/baseR4/

HUOM. mitätöinnissä käytetään POST-metodia, sillä HTTP body-osuudessa oleva FHIR-resurssi on Bundle ja tyypiltään transaction!

Varsinainen ajanvarauksen mitätöinti (ajanvarausresurssi-instanssin mitätöinti) tehdään FHIR:in DELETE-interaktiolla. Interaktion mukainen DELETE lisätään HTTP-pyynnön transaction Bundle:een. Pyyntö lähetetään transaktiona, joka sisältää sekä mitätöinnin tiedot sisältävän Provenance-resurssin tallennuksen että Appointment-resurssin mitätöivän DELETE interaktion.

URL:in muoto noudattaa sekä tallennuksessa että korvauksessa FHIR määrittelyjä (Style Guide). Eri ympäristöjen käytettävät juuret ilmoitetaan erikseen eikä niitä julkisteta tässä implementointioppaassa.

HTTP pyynnön header

Mitätöinnin HTTP-pyyntöjen header-osuudet noudattavat Kanta-palveluiden yhteisiä Kanta FHIR HTTP header ja Kanta JSON Web Token määrittelyitä ja näissä kuvattuja tietoja ja tietojen pakollisuuksia.

HTTP pyynnön body

HTTP pyynnön body-osuus sisältää pyynnössä välitettävät resurssit. Alla olevassa kuvassa on kuvattu HTTP body-osuuden rakentuminen:

Mitätöitävän ajanvarauksen tiedot lähetetään Potilastietovarantoon Bundle-resurssilla, joka on tyypiltään transaction.

Bundle-resurssi sisältää kaksi entryä (Bundle.entry):

Toinen entry sisältää mitätöitävään Appointment-resurssiin liittyvän Provenance-resurssin.

Provenance-resurssissa luodaan mitätöintitilanteessa kokonaan uusi instanssi, sitä ei versioida.

Mitätöivä Provenance-resurssi sisältää viittauksen mitätöitävään ajanvaraukseen, mitätöinnin syyn sekä muut mitätöinnissä tarvittavat tiedot.

Provenance-resurssista viitataan seuraaviin resursseihin, jotka esitetään contained-rakenteessa:
- Patient (ajanvarauksen asiakkaan tiedot)
- Practitioner (ajanvarauksen mitätöinnin tehneen ammattilaisen tiedot)
- Device (tiedot tuottanut tietojärjestelmä)
Provenance-resurssin osalta Bundle.entry.request.method-elementin arvoksi laitetaan POST.
Toinen entry sisältää pelkän viittauksen mitätöitävään ajanvaraukseen eli viittauksen mitätöitävään Appointment-resurssi-instanssin loogiseen tunnisteeseen (id).

Bundle.entry.request.method-elementin arvoksi laitetaan DELETE.

Bundle-resurssi allekirjoitetaan sähköisellä allekirjoituksella, jolla varmistetaan vaatimus välitettävien resurssien muuttumattomuudesta pysyväissäilytyksessä. Sähköisen allekirjoitus on määritelty erillisessä määrittelyssä Kanta FHIR sähköinen allekirjoitus.

Mitätöinnissä käytettävän Provenance-resurssin sisältö

Mitätöintiä varten on määritelty erillinen Kanta-yhteiset soveltamisoppaasta löytyvä mitätöinnin Provenance-profiili. Mitätöinnissä annettavat Provenance-resurssin tiedot on kuvattu tarkemmin profiilissa.

Alla listataan erityisesti ajanvarauksessa huomioitavat tiedot.

Provenance.target:
- Viittaus mitätöitävään ajanvarausresurssiin välitetään Provenance.target.rerference-elementissä. Mitätöitävän ajanvarauksen yksilöivänä tunnuksena tulee käyttää Potilastietovarannon ajanvaraukselle tuottamaa Appointment-resurssi-instanssin loogista tunnistetta (id).
- Provenanc.target.display-elementti saa arvon ”Ajanvaraus”
Provenance.activity
- Provenance.activity.coding-elementissä ilmoitetaan mitätöinnin syy koodattuna eArkisto-Asiakirjan korvauksen -luokitusta käyttäen. (Tarkempi kuvaus mitätöinnin syy -koodeista löytyy Tallenna, korvaa, mitätöi ajanvaraus -käyttötapauksesta.)
- Lisäksi tulee ilmoittaa resurssin mitätöinnin syy vapaamuotoisena tekstinä elementissä Provenance.activity.text.
Provenance.entity
- Provenance.entity.role saa arvon ”removal” profiilin mukaisesti
- Myös Provenance.entity.what.reference-elementissä annetaan viittaus mitätöitävään ajanvarausresurssiin (koska tieto on rakenteessa pakollinen).

{
    "resourceType": "Bundle",
    "type": "transaction",
    "entry": [
        {
            "fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf149",
            "resource": {
                "resourceType": "Provenance",
                ...
                "target": {
                    "reference": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
                    "display": "Ajanvaraus"
                },
                ...
                "activity": {
                    "coding": {
                        "system": "urn:oid:1.2.246.537.5.40178.2008",
                        "code": "4",
                        "display": " Mit\u00e4t\u00f6inti siten, ett\u00e4 vanhat versiot merkit\u00e4\u00e4n k\u00e4yt\u00f6st\u00e4 poistetuiksi"
                    },
                    "text": "Mit\u00e4t\u00f6innin syyn kuvaus"
                }
                ...
                "entity": {
                    "role": "removal",
                    "what": {
                        "reference": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198"
                    }
                }
            },
            "request": {
                "method": "POST",
                "url": "Provenance"
            }
        },
        {
            "fullUrl": "ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
            "request": {
                "method": "DELETE",
                "url": "Appointment/ce5ea340-adfd-40f2-87d4-a25e4f8bf198"
            }
        }
    ],
    {
        "signature": {
            ...
        }
    }
}

HTTP vastaus (response)

HTTP vastauksen tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna.

Vastauksen HTTP header

Mitätöinnin HTTP-vastauksen header-osuus noudattaa Kanta-palveluiden yhteistä Kanta FHIR HTTP header määrittelyä ja siinä kuvattuja tietoja ja tietojen pakollisuuksia.

Vastauksen HTTP body

HTTP vastauksen body-osuudessa vastauksena palautuu Bundle-resurssi ja sen tyyppi on transaction-response.

Onnistuneen operaation tuloksena Potilastietovaranto palauttaa Bundle-resurssin, joka sisältää jokaista lähetettyä entryä vastaavan responsen. Response-elementissä on seuraavat tiedot:

molemmille operaatioille palautuu status-elementissä resurssin tallennuksen HTTP-statuskoodi
Provenance-resurssille palautuu lisäksi location-elementissä tallennetun resurssin tyyppi ja Potilastietovarannon tuottama yksilöivä tunnus resurssille ja resurssin versionumero
Provenance-resurssille palautuu lisäksi etag-elementissä ilmoitetaan resurssin versionnumero

Esimerkki Potilastietovarannon palauttamasta vastaussanomasta onnistuneessa mitätöinnissä

{
    "resourceType": "Bundle",
    "id": "bundle-response",
    "type": "transaction-response",
    "entry": [
        {
            "response": {
                "status": "201 Created",
                "location": "Provenance/urn:uuid:2639da1f-e03c-4faf-aec0-6007c4de7288/_history/1",
                "etag": "W/\"1\""
            }
        },
        {
            "response": {
                "status": "204 No content"
            }
        }
    ]
}

Vastaussanoma virhetilanteessa

Virhetilanteissa vastauksena palautuu HTTP virhestatuskoodi sekä HTTP bodyssa OperationOutcome resurssi-instanssi, jolla ilmaistaan tarkempi virhe. Arkistossa käytettävää OperationOutcome-resurssia ei ole profiloitu.

OperationOutcome-sivulla on kuvattu tarkemmin, miten Potilastietovaranto palauttaa virheilmoitukset OperationOutcome-resussilla.