Mitätöinti- ja vastaussanomat

Toimintakykytiedon mitätöinnissä käytettävän HTTP-pyynnön tiedot lähetetään HTTP header- ja body-osuuksiin jaettuna. Tällä sivulla kuvataan nämä osuudet tarkemmin mitätöinnin osalta.

Mitätöintisanoma

Mitätöintisanoma lähetetään Kanta-palveluihin HTTP-pyyntönä (request) POST-metodilla FHIR-palvelun endpoint:in juureen. Mitätöinnissä käytetään POST-metodia, sillä HTTP body-osuudessa oleva FHIR-resurssi on Bundle, jonka tyyppi on transaction.

Varsinainen toimintakykytiedon mitätöinti (toimintakykytietoresurssi-instanssin mitätöinti) tehdään FHIR:in DELETE-interaktiolla. Interaktion mukainen DELETE lisätään HTTP-pyynnön transaction Bundleen. Pyyntö lähetetään transaktiona, joka sisältää mitätöinnin tiedot sisältävän Provenance-resurssin tallennuksen ja Observation-resurssin mitätöivän DELETE-interaktion.

HTTP-pyynnön header

Mitätöinnin HTTP-pyynnön header-osuudet sisältävät Kanta FHIR HTTP header -dokumentin mukaisen HTTP-headerin ja JSON Web Tokenin. Potilastietovarantoon lähetettävän HTTP-pyynnön (request) tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta FHIR HTTP-header taulukon 2.1 Kanta-palveluiden HTTP pyynnön header kentät sarakkeessa PTA ja Sosiaalihuollon asiakastietovarantoon lähetettävän HTTP-pyynnön sarakkeessa SHA. JSON Web Tokenin tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta JSON Web Token taulukossa 4.1 Kanta-palveluiden JWT Claimit. Potilastietovarantoon lähetettävän JWT:n tiedot ja tietojen pakollisuudet on määritelty sarakkeessa PTA ja Sosiaalihuollon asiakastietovarantoon lähetettävän JWT:n sarakkeessa SHA.

HTTP-pyynnön body

HTTP-pyynnön body-osuus sisältää pyynnössä välitettävät resurssit. Mitätöitävän merkinnän toimintakyvystä tai toimintakykyarvion tiedot lähetetään Kanta-palveluihin Bundle-resurssilla, jonka tyyppi on transaction. Bundle-resurssi sisältää kaksi entryä (Bundle.entry).

Toinen entryistä sisältää mitätöitävään Observation-resurssiin liittyvän Provenance-resurssin. Provenance-resurssista tallennetaan mitätöinnissä kokonaan uusi instanssi. Mitätöinnin Provenance-resurssi sisältää viittauksen mitätöitävään toimintakykytietoon, mitätöinnin syyn sekä muut mitätöinnissä tarvittavat tiedot. Provenance-resurssista viitataan seuraaviin resursseihin, jotka esitetään contained-rakenteessa:

  • Patient (toimintakykytiedon asiakkaan tai asiakkaiden tiedot)
  • Practitioner (toimintakykytiedon mitätöinnin tehneen ammattilaisen tiedot)
  • Device (tiedot tuottanut tietojärjestelmä)

Provenance-resurssille Bundle.entry.request.method-elementin arvoksi laitetaan POST.

Toinen entry sisältää pelkän viittauksen mitätöitävään toimintakykytietoon eli viittauksen mitätöitävän Observation-resurssi-instanssin loogiseen tunnisteeseen (id). Bundle.entry.request.method-elementin arvoksi laitetaan DELETE.

Bundle-resurssi sisältää sähköisen allekirjoituksen.

HTTP-pyynnön body-osuuden rakentuminen mitätöinnissä on kuvattu kuvassa 5.

  HTTP-body, mitatointi

Kuva 5 Toimintakykytietojen HTTP-pyynnön body-osuus mitätöinnissä

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

Mitätöintiä varten on määritelty Kanta-yhteinen profiili MitatointiProvenance. Mitätöinnissä annettavat Provenance-resurssin tiedot on kuvattu tarkemmin profiilissa. Alla on kuvattu toimintakykytiedon mitätöinnissä huomioitavat tiedot.

  • Provenance.target:
    • Viittaus mitätöitävään toimintakykytiedon resurssi-instanssiin ilmoitetaan Provenance.target.reference-elementissä. Mitätöitävän toimintakykytiedon yksilöivänä tunnuksena tulee käyttää Kanta-palvelujen tuottamaa Observation-resurssi-instanssin loogista tunnistetta (Observation.id).
    • Jos mitätöitävä toimintakykytieto on merkintä toimintakyvystä, Provenance.target.display-elementti saa arvon ”Merkintä toimintakyvystä”.
    • Jos mitätöitävä toimintakykytieto on toimintakykyarvio, Provenance.target.display-elementti saa arvon "Toimintakykyarvio".
  • Provenance.activity
    • Provenance.activity.coding-elementissä ilmoitetaan mitätöinnin syy koodattuna.
      • Potilastietovarannossa mitätöinnin syy ilmoitetaan koodistolla eArkisto-Asiakirjan korvauksen syy (1.2.246.537.5.40178.2008).
      • Sosiaalihuollon asiakastietovarannossa mitätöinnin syy ilmoitetaan koodistolla Sosiaalihuolto - Asiakirjan mitätöinnin syy (1.2.246.537.6.1278.201701).
    • Potilastietovarannossa tulee lisäksi ilmoittaa resurssin mitätöinnin syy vapaamuotoisena tekstinä elementissä Provenance.activity.text.
  • Provenance.entity
    • Provenance.entity.role saa profiilin mukaisesti arvon ”removal”.
    • Provenance.entity.what.reference-elementissä ilmoitetaan viittaus mitätöitävään toimintakykytiedon resurssi-instanssiin, koska tieto on rakenteessa pakollinen.

Esimerkki Sosiaalihuollon asiakastietovarantoon tallennetun merkinnän toimintakyvystä mitätöinnistä

{
    "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": "Merkintä toimintakyvystä"
                },
                ...
                "activity": {
                    "coding": {
                        "system": "1.2.246.537.6.1278.201701",
                        "code": "5",
                        "display": "Virhe asiakasasiakirjan sisällössä"
                    }
                }
                ...
                "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": "Observation/ce5ea340-adfd-40f2-87d4-a25e4f8bf198"
            }
        }
    ],
    {
        "signature": {
            ...
        }
    }
}

Vastaussanoma

Kanta-palvelut palauttaa vastauksena HTTP-vastauksen (response), jossa tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna.

HTTP-vastauksen header

Mitätöinnin HTTP-vastauksen header-osuus noudattaa Kanta-palvelujen yhteistä Kanta FHIR HTTP header määrittelyä. Potilastietovarannon palauttaman HTTP-vastauksen tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta FHIR HTTP-header taulukon 3.1 Kanta-palveluiden HTTP pyynnön header kentät sarakkeessa PTA ja Sosiaalihuollon asiakastietovarannon palauttaman HTTP-vastauksen sarakkeessa SHA.

HTTP-vastauksen body

Kanta-palvelut palauttaa HTTP-vastauksen body-osuudessa Bundle-resurssin, jonka tyyppi on transaction-response. Onnistuneen mitätöinnin tuloksena Kanta-palvelut palauttaa Bundle-resurssin, joka sisältää jokaista lähetettyä entryä vastaavan responsen. Kanta-palvelut palauttaa Response-elementissä seuraavat tiedot:

  • Provenance-resurssin status-elementissä ilmoitetaan resurssin tallennuksen HTTP-statuskoodi 201 CREATED.
  • Observation-resurssin status-elementissä ilmoitetaan HTTP-statuskoodi 204 NO CONTENT.
  • Provenance-resurssille palautetaan lisäksi location-elementissä tallennetun resurssin tyyppi, Kanta-palvelujen tuottama yksilöivä tunnus resurssille ja resurssin versionumero.
  • Provenance-resurssille palautetaan lisäksi etag-elementissä resurssin versionumero.

Esimerkki Kanta-palvelujen palauttamasta vastaussanomasta onnistuneessa mitätöinnissä

{
    "resourceType": "Bundle",
    "id": "bundle-response",
    "type": "transaction-response",
    "entry": [
        {
            "fullUrl": "urn:uuid:2639da1f-e03c-4faf-aec0-6007c4de7288",
            "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

Virhetilanteessa Kanta-palvelut palauttaa Bundle-resurssin entry-elementissä HTTP-virhestatuskoodin ja OperationOutcome-resurssin, jolla ilmoitetaan tarkempi virhe. Kanta-palvelujen virhetilanteessa palauttama vastausssanoma on kuvattu Kanta yhteisten FHIR- ja REST-rajapintamäärittelyjen soveltamisoppaassa sivulla Kanta-rajapinnan virhevastaus.