Tallennus- ja vastaussanomat

Kanta sosiaalihuolto R4 soveltamisopas kuvaa FHIR-standardin mukaisen tietojen siirron asiakastietoa käsittelevän järjestelmän ja lokirekisterien säilytyspalvelun välillä. Tässä kuvatut toiminnallisuudet ovat FHIR RESTful määritysten mukaisia interaktioita (ks. tarkemmin FHIR RESTful API).

Tallennussanoma

Tallennussanoma välitetään lokirekisterien säilytyspalvelulle 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 tiedot välitetää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. Lokirekisterien säilytyspalveluun 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 SHA. JSON Web Tokenin tiedot ja niiden pakollisuudet on määritelty dokumentin Kanta JSON Web Token taulukossa 4.1 Kanta-palveluiden JWT Claimit sarakkeessa SHA.

HTTP-pyynnön body-osuus sisältää pyynnössä välitettävät resurssit. Luovutusilmoitukset lähetetään lokirekisterien säilytyspalveluun Bundle-resurssilla, jonka sisälle kootaan AuditEvent ja Provenance -parit. AuditEvent-resurssi sisältää varsinaisen luovutusilmoituksen ja Provenance-resurssi AuditEvent-resurssin metatiedot. Yhdessä Bundle-resurssissa voidaan siirtää samaan henkilöön liittyviä AuditEvent ja Provenance -pareja 1 - n kappaletta.

Tallennuksessa Bundlen tyyppi on transaction. Bundle-resurssi sisältää sähköisen allekirjoituksen, jolla varmistetaan välitettävien resurssien muuttumattomuus. Luovutusilmoituksen tallennuksessa tuetaan vain create-interaktiota.

Sosiaalihuollon FHIR-standardin mukaisissa toteutuksissa Kanta-palveluissa tuettu formaatti on JSON. Sosiaalihuollon osalta muita formaatteja ei tueta.

Vastaussanoma

Lokirekisterien säilytyspalvelu palauttaa vastauksena HTTP-vastauksen (response), jossa tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna. HTTP-vastauksen header-osuus noudattaa Kanta-palveluiden yhteistä Kanta FHIR HTTP header määrittelyä. Lokirekisterien säilytyspalvelun 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 SHA.

Lokirekisterien säilytyspalvelu palauttaa lähettäneelle järjestelmälle tallennuksen vastauksena Bundlen, jonka tyyppi on transaction-response. Onnistuneessa tallennuksessa lokirekisterien säilytyspalvelu 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 lokirekisterien säilytyspalvelun palauttamasta vastaussanomasta onnistuneessa tallennuksessa

{
  "resourceType": "Bundle",
  "id": "9f6c7669-2727-4053-bffc-cecc2f3e7039",
  "type": "transaction-response",
  "entry": [ 
     {
        "response":
        {   "status": "201 CREATED",       
            "location": "AuditEvent/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\""     
        }
    }
  ]
}

Lokirekisterien säilytyspalvelun palauttamassa vastaussanomassa palautettavat responset ovat samassa järjestyksessä kuin tallennettavat resurssit olivat lähetetyssä Bundlen-resurssissa.

Virhetilanteessa lokirekisterien säilytyspalvelu palauttaa Bundle-resurssin entry-elementissä HTTP-virhestatuskoodin ja OperationOutcome-resurssin, jolla ilmoitetaan tarkempi virhe. Sosiaalihuollossa käytettävää OperationOutcome-resurssia ei ole profiloitu.

Lokirekisterien säilytyspalvelu 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 sosiaalihuollon luovutusilmoituksen käsittelyssä tai muissa sosiaalihuollon FHIR-toteutuksissa tunnistetaan tälle tarve. Lokirekisterien säilytyspalvelu 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ä lokirekisterien säilytyspalvelun palauttamassa virhevastauksessa.

Resurssien validointivirheistä lokirekisterien säilytyspalvelu palauttaa OperationOutcome-resurssin, johon liitetään lisäksi HAPIn muodostamat issuet sellaisenaan.

Esimerkki lokirekisterien säilytyspalvelun 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"
                    }
                ]
            }
        }
    ]
}