Tallennus- ja vastaussanomat

Toimintakykytietojen soveltamisopas kuvaa FHIR-standardin mukaisen tietojen siirron tallentavan järjestelmän ja Kanta-palvelujen välillä. Tässä kuvatut toiminnallisuudet ovat FHIR RESTful määritysten mukaisia interaktioita (ks. tarkemmin FHIR RESTful API). Tällä sivulla kuvataan Kanta-palveluihin lähetettävän toimintakykytiedon ensimmäisen version tallennus- ja vastaussanomat.

Tallennussanoma

Tallennussanoma lähetetään Kanta-palveluihin HTTP-pyyntönä (request) POST-metodilla FHIR-palvelun endpoint:in juureen. Eri ympäristöjen käytettävät juuret ilmoitetaan palveluun liittyville tietojärjestelmätoimittajille erikseen eikä niitä julkisteta tässä soveltamisoppaassa.

HTTP-pyynnön header

HTTP-pyynnön tiedot lähetetään HTTP header- ja body-osuuksiin jaettuna. HTTP-pyynnön header-osuus sisältää 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ä lähetettävät resurssit. Observation-resurssi sisältää merkinnän toimintakyvystä tai toimintakykyarvion ja siitä viitataan contained-rakenteessa muihin tarvittaviin resursseihin:

  • Observation (havainto toimintakyvystä tai toimintakyvyn muutoksen arviointi)
  • Patient (asiakas tai potilas, jota toimintakykytieto koskee)
  • Practitioner (merkinnän toimintakyvystä/toimintakykyarvion laatija)
  • PractitionerRole (merkinnän toimintakyvystä/toimintakykyarvion laatijan palveluyksikkö)

Provenance-resurssi sisältää merkintään toimintakyvystä tai toimintakykyarvioon liittyvät metatiedot ja siitä viitataan contained-rakenteessa muihin metatietojen ilmoittamisessa tarvittaviin resursseihin:

  • Device (tietojärjestelmä, josta toimintakykytieto on tallennettu)
  • Organization (toimintakykykytiedon rekisterinpitäjä, palveluntuottaja jne.)
  • Patient (asiakas tai potilas, jota toimintakykytieto koskee)
  • Practitioner (merkinnän toimintakyvystä/toimintakykyarvion tallentanut ammattihenkilö)

Kanta-palveluihin tiedot lähetetään Bundle-resurssilla, jonka sisälle kootaan Observation ja Provenance -pari. Yhdessä Bundle-resurssissa voidaan siirtää yksi (1) samaan henkilöön liittyvä Observation ja Provenance -pari. Tallennuksessa Bundlen tyyppi on transaction. Tämä tarkoittaa, että molemmat Bundlen sisältämät resurssit käsitellään omina operaatioinaan ja molempien operaatioiden on onnistuttava, jotta tallennus onnistuu.

Molempien resurssien Bundle.entry.request.method-elementtien arvoksi laitetaan POST.

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

HTTP-pyynnön body-osuuden rakentuminen 1. version tallentamisessa on kuvattu kuvassa 6.

  HTTP-body

Kuva 6 Toimintakykytietojen tallennuksen HTTP-pyynnön body-osuus 1. version tallennuksessa

Potilastietovarannon ja Sosiaalihuollon asiakastietovarannon FHIR-standardin mukaisissa toteutuksissa Kanta-palveluissa tuettu formaatti on JSON eikä muita formaatteja tueta.

Tallennus ja resurssin looginen tunniste (id)

Kanta-palvelut hallinnoi Observation-resurssi-instanssin yksilöivää tunnusta eli FHIR resurssi-instanssin loogista tunnistetta (Observation.id). Tämä tunniste on eri kuin merkinnän toimintakyvystä tai toimintakykyarvion tietosisällössä oleva tunniste (Observation.identifier). Toimintakykytiedon 1. version tallennuksessa tallentavan järjestelmän on luotava väliaikainen looginen tunniste Observation-resurssi-instanssille ja ilmoitettava se Observation-resurssiin liittyvässä Bundle.entry:n fullUrl-elementissä. fullUrl-elementissä ilmoitettua loogista tunnistetta on käytettävä viittauksessa Provenance-resurssista (Provenance.target.reference) Observation-resurssiin.

Kanta-palvelut tuottaa tallennuksessa Observation-resurssi-instanssille globaalisti yksilöivän tunnuksen ja korvaa tallentavan järjestelmän resurssi-instanssin fullUrl-elementissä ilmoittaman loogisen tunnisteen (id). Kanta-palvelut palauttaa tuottamansa resurssi-instanssin loogisen tunnisteen (id) vastaussanomassa onnistuneessa tallennuksessa. Tallentavan järjestelmän on käytettävä tätä tunnistetta, jos Observation-resurssista tallennetaan uusi versio. Uuden version tallentamisesta voi lukea lisää soveltamisoppaan sivulta Versiointi- ja vastaussanomat.

Kanta-palvelut hallinnoi myös Provenance-resurssi-instanssin yksilöivää tunnusta eli FHIR resurssi-instanssin loogista tunnistetta (Provenance.id). Provenance-resurssin tallennuksessa tallentavan järjestelmän on luotava väliaikainen looginen tunniste Provenance-resurssi-instanssille ja ilmoitettava se Provenancen-resurssiin liittyvässä Bundle.entry:n fullUrl-elementissä. Kanta-palvelut tuottaa tallennuksessa Provenance-resurssi-instanssille globaalisti yksilöivän tunnuksen ja korvaa tallentavan järjestelmän resurssi-instanssin fullUrl-elementissä ilmoittaman loogisen tunnisteen (id). Kanta-palvelut palauttaa tuottamansa resurssi-instanssin loogisen tunnisteen (id) vastaussanomassa onnistuneessa tallennuksessa.

Esimerkki tallennuksessa käytettävästä Bundle-resurssista

{
    "resourceType": "Bundle",
    "type": "transaction",
    "entry": [
        {
            "fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143",
            "resource": {
                "resourceType": "Observation",
                ...
            },
            "request": {
                "method": "POST",
                "url": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143"
            }
        },
        {
            ...
            "resource": {
                "resourceType": "Provenance",
                ...
                "target": {
                    "reference": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143",
                    "display": "Merkintä toimintakyvystä"
                },
                ...
            }
            "request": {
                "method": "POST",
                "url": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf144" 
            }
        }
    ],
    {
        "signature": {
            ...
        }
    }
}

Vastaussanoma

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

HTTP-vastauksen header

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

Merkinnän toimintakyvystä tai toimintakykyarvion ensimmäisen version tallentamisessa Kanta-palvelut palauttaa tallentavalle järjestelmälle vastauksena Bundlen, jonka tyyppi on transaction-response. Ensimmäisen version onnistuneessa tallennuksessa Kanta-palvelut palauttaa Bundle-resurssin entry-elementin response-elementissä seuraavat tiedot:

  • status-elementissä ilmoitetaan resurssin tallennuksen HTTP-statuskoodi 201 CREATED.
  • location-elementissä ilmoitetaan tallennetun resurssin nimi, Kanta-palvelujen tuottama yksilöivä tunnus resurssille ja resurssin versionumero.
  • etag-elementissä ilmoitaan resurssin versionumero.

Esimerkki Kanta-palvelujen palauttamasta vastaussanomasta resurssin 1. version onnistuneessa tallennuksessa

{
  "resourceType": "Bundle",
  "id": "9f6c7669-2727-4053-bffc-cecc2f3e7039",
  "type": "transaction-response",
  "entry": [ 
     {
        "response":
        {   "status": "201 CREATED",       
            "location": "Observation/6aac45d1-6893-4bdf-827b-504faaca481d/_history/1",       
            "etag": "W/\"1\""     
        }
    },
    {
        "response":
        {   "status": "201 CREATED",       
            "location": "Provenance/6aac54d1-6893-4bdf-827b-504faaca481e/_history/1",       
            "etag": "W/\"1\""     
        }
    }
  ]
}

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.