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. Sosiaalihuollon asiakastietovarannossa yhdessä Bundle-resurssissa voidaan siirtää myös yksi (1) samoihin henkilöihin liittyvä Observation ja Provenance-pari, jos toimintakykytieto liittyy sosiaalihuollon yhteiseen asiaan. 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 osiosta 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.