Tallennus- ja vastaussanomat

Toimintakykytiedon 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 ja uuden version tallenus- 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. Merkinnän toimintakyvystä ja toimintakykyarvion tallentamisessa pääresurssi on Observation, josta viitataan contained-rakenteessa muihin tarvittaviin resursseihin, kuten Patient, Organization tai Practitioner. Merkinnän toimintakyvystä ja toimintakykyarvion metatiedot tallennetaan Provenance-resurssilla. Kanta-palveluihin toimintakykytieto 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. Bundle-resurssi sisältää sähköisen allekirjoituksen.

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

Vastaussanoma

Kanta-palvelut palauttaa 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-504faaca481d/_history/1",       
            "etag": "W/\"1\""     
        }
    }
  ]
}

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

• pääresurssin (Observation) status-elementissä ilmoitetaan resurssin tallennuksen HTTP-statuskoodi 200 OK.
• Provenancence-resurssin 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 uuden version onnistuneessa tallennuksessa

{
    "resourceType": "Bundle",
    "type": "transaction-response",
    "entry": [
        {
            "fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
            "response": {
                "status": "200 OK",
                "location": "Observation/ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/2",
                "etag": "W/\"2\""
            }
        }, 
        {
            "fullUrl": "urn:uuid:2639da1f-e03c-4faf-aec0-6007c4de7267",
            "response": {
                "status": "201 Created",
                "location": "Provenance/2639da1f-e03c-4faf-aec0-6007c4de7267/_history/1",
                "etag": "W/\"1\""
            }
        }
    ]
}

Kanta-palvelujen palauttamassa vastaussanomassa palautettavat responset ovat samassa järjestyksessä kuin tallennettavat resurssit olivat lähetetyssä Bundlen-resurssissa.

Vastaussanoma virhetilanteessa

Virhetilanteessa Kanta-palvelut palauttaa Bundle-resurssin entry-elementissä HTTP-virhestatuskoodin ja OperationOutcome-resurssin, jolla ilmoitetaan tarkempi virhe. Kanta-palveluissa käytettävää OperationOutcome-resurssia ei ole profiloitu.

Kanta-palvelut ilmoittaa yksittäisen virheen tiedot OperationOutcome-resurssin issue-elementissä. Severity-elementin arvo on ”error”. Issue-elementin Code-elementin arvo ilmoitetaan FHIR-koodistolla Issue Type. Tällä hetkellä Code-elementissä ilmoitetaan koodiston arvo "processing". Code-elementissä ilmoitettavia arvoja tarkennetaan tarvittaessa myöhemmin, jos toimintakykytiedon käsittelyssä tai muissa Kanta-palvelujen FHIR-toteutuksissa tunnistetaan tälle tarve. Kanta-palvelut ilmoittaa varsinaisen virheen Details-elementissä koodistolla Kanta-palvelut - Prosessivirheet ja huomautukset.

Details-elementin tietotyyppi on CodeableConcept ja se rakentuu Coding-tietotyypistä ja text-elementistä. Coding-tietotyypin elementeissä tiedot annetaan seuraavasti:

• system-elementissä ilmoitetaan virheiden ilmoittamisessa käytettävä koodisto Kanta-palvelut - Prosessivirheet ja huomautukset (1.2.246.537.5.40112.2006).
• code-elementissä ilmoitetaan virhekoodi koodistolla Kanta-palvelut - Prosessivirheet ja huomautukset.
• display-elementissä ilmoitetaan virhekoodia vastaava selite koodistossa Kanta-palvelut - Prosessivirheet ja huomautukset.

CodeableConcept tietotyypin text-elementtiä ei toistaiseksi käytetä Kanta-palvelujen palauttamassa virhevastauksessa.

Resurssien validointivirheistä Kanta-palvelut palauttaa OperationOutcome-resurssin, johon liitetään lisäksi HAPIn muodostamat issuet sellaisenaan.

Esimerkki Kanta-palvelujen palauttamasta OperationOutcome resurssi-instanssista

{
    "resourceType": "OperationOutcome",
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "details": {
                "coding": [
                    {
                        "system": "urn:oid:1.2.246.537.5.40112.2006",
                        "code": "2T02001",
                        "display": "Sisäinen tekninen virhe"
                    }
                ]
            }
        }
    ]
}