Tallennus ja korvaus
Sote-luovutusluvan tallennuksessa ja korvauksessa käytettävän HTTP-pyynnön tiedot välittyvät HTTP header- ja body-osuuksiin jaettuna. Tällä sivulla kuvataan nämä osuudet tarkemmin tallennus- ja korvauspyyntöjen osalta.
HTTP pyyntö (request)
Tallennuspyyntö välitetään palvelulle HTTP pyyntönä (request) POST-metodilla FHIR-palvelun endpoint:in juureen. POST: [base]/
Esim. POST http://example.org/baseR4/
Korvauspyyntö välitetään palvelulle HTTP pyyntönä (request) POST-metodilla FHIR-palvelun endpoint:in juureen. POST: [base]/
Esim. POST http://example.org/baseR4/
HUOM. Myös korvauksessa käytetään POST-metodia, sillä HTTP body-osuudessa oleva FHIR-resurssi on Bundle ja tyypiltään transaction!
URL:in muoto noudattaa sekä tallennuksessa että korvauksessa FHIR määrittelyjä (Style Guide). Eri ympäristöjen käytettävät juuret ilmoitetaan palveluun liittyville tietojärjestelmätoimittajille erikseen eikä niitä julkisteta tässä implementointioppaassa.
HTTP pyynnön header
Tallennuksen ja korvauksen HTTP-pyyntöjen header-osuudet noudattavat Kanta-palveluiden yhteisiä Kanta FHIR HTTP header ja Kanta JSON Web Token määrittelyitä ja näissä kuvattuja tietoja ja tietojen pakollisuuksia.
HTTP pyynnön body
HTTP pyynnön body-osuus sisältää pyynnössä välitettävät resurssit. Alla olevassa kuvassa on kuvattu HTTP body-osuuden rakentuminen:
Sekä uuden sote-luovutusluvan tallennuksessa Tahdonilmaisupalveluun että Tahdonilmaisupalveluun jo tallennetun sote-luovutusluvan korvauksessa sote-luovutusluvan tiedot lähetetään Tahdonilmaisupalveluun Bundle-resurssilla, joka sisältää yksi tai kaksi Consent- ja Provenance -paria. Jos samalla Bundle-resurssilla tuodaan kaksi paria, tulee sen sisältämien Consent-resurssien sisältää eri luovutusluvat (eli lupa luovuttaa terveydenhuollosta sosiaalihuoltoon ja lupa luovuttaa sosiaalihuollosta terveydenhuoltoon). Consent -resurssi sisältää varsinaisen sote-luovutusluvan sisällön ja Provenance-resurssi siihen liittyvät metatiedot.
Bundlen tyyppi on transaction eli käytännössä molemmat resurssit käsitellään omina operaatioinaan ja molempien operaatioiden on onnistuttava, jotta tallennus tai korvaus on kokonaisuudessa onnistunut.
Bundle-resurssi allekirjoitetaan sähköisellä allekirjoituksella, jolla varmistetaan vaatimus välitettävien resurssien muuttumattomuudesta pysyväissäilytyksessä. Sähköinen allekirjoitus on määritelty erillisessä määrittelyssä Kanta FHIR sähköinen allekirjoitus.
Sote-luovutusluvan tiedot sisältävästä Consent-resurssista viitataan seuraavaan resurssiin, joka esitetään Consent-resurssin sisällä olevassa contained-rakenteessa:
- Patient (asiakkaan tiedot, jonka lupaa käsitellään)
Sote-luovutusluvan metatiedot sisältävästä Provenance-resurssista viitataan tarpeen mukaan seuraaviin resursseihin, jotka esitetään Provenance-resurssin sisällä olevassa contained-rakenteessa:
- Patient (asiakkaan tiedot, jonka lupaa käsitellään)
- Practitioner/Patient/RelatedPerson (sote-luovutusluvan tallentaja: ammattilainen, asiakas tai puolesta-asioija)
- Device (tiedot tuottanut tietojärjestelmä)
Tallennus ja resurssin looginen tunniste (id), käytettävä HTTP metodi
Tahdonilmaisupalvelu hallinnoi Consent-resurssi-instanssin yksilöivää tunnusta eli FHIR resurssi-instanssin loogista tunnistetta (id). Huom. tämä on eri tunniste kuin sote-luovutusluvan tietosisällöstä löytyvä tunniste (Consent.identifier).
Sote-luovutuslupaa tallentavan tahon on luotava uuden sote-luovutusluvan tallennuksen yhteydessä ”väliaikainen” looginen tunniste Consent-resurssi-instanssille ja annettava se Consent-resurssiin liittyvässä Bundle.entry:n fullUrl-elementissä. Tätä loogista tunnistetta fullUrl-elementissä on käytettävä viittauksessa Provenance-resurssista (Provenance.target.reference) Consent-resurssiin.
Tahdonilmaisupalvelu tuottaa tallennuksen yhteydessä Consent-resurssi-instanssille globaalisti yksilöivän tunnuksen ja korvaa tallentavan tahon resurssi-instanssiin fullUrl-elementissä antaman loogisen tunnisteen (id). Tahdonilmaisupalvelun luoma resurssi-instanssin looginen tunniste (id) palautetaan pyynnön vastauksessa onnistuneen tallennuksen yhteydessä (huom. tätä tunnistetta on käytettävä, jos sote-luovutuslupaa päivitetään).
Molempien resurssien Bundle.entry.request.method-elementtien arvoksi laitetaan POST.
Alla esimerkki tallennuksessa käytettävästä Bundle-resurssista ja viittauksesta Provenance-resurssi-instanssista Consent-resurssi-instanssiin.
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:ss4rt321-prlv-33g7-22f1-f55t6g7hh333",
"resource": {
"resourceType": "Consent",
...
},
"request": {
"method": "POST",
"url": "Consent"
}
},
{
...
"resource": {
"resourceType": "Provenance",
...
"target": {
"reference": "urn:uuid:ss4rt321-prlv-33g7-22f1-f55t6g7hh333",
"display": "Sote-luovutuslupa"
},
...
}
"request": {
"method": "POST",
"url": "Provenance"
}
}
],
{
"signature": {
...
}
}
}
Korvaus ja resurssin looginen tunniste (id), käytettävä HTTP metodi
Sote-luovutusluvan korvauksessa Consent-resurssi-instanssin loogisena tunnisteena on käytettävä Tahdonilmaisupalvelun resurssi-instanssille luomaa resurssi-instanssin yksilöivää loogista tunnistetta (id).
Consent-resurssiin liittyvän Bundle.entry.request.ifMatch-elementin arvoksi on annettava resurssi-instanssin viimeisin versionumero eli haun vastaussanomalla resurssin response-elementin etag-kentässä palautettu versionumero (tai tallennuksen vastausanomassa palautunut versionumero jos voi olla varma, että versionumero ei ole ensimmäisen tallennuksen jälkeen muuttunut). Sote-luovutusluvan korvaus onnistuu vain, kun ifMatch-elementissä välitetään versionumero, joka vastaa kyseisen sote-luovutusluvan (eli joko luvan terveydenhuollosta sosiaalihuoltoon tai sosiaalihuollosta terveydenhuoltoon) viimeisintä eli voimassa olevaa versiota Tahdonilmaisupalvelussa. Tahdonilmaisupalvelu huolehtii muuten korvattavan resurssi-instanssin versioinnista.
Consent-resurssiin liittyvän Bundle.entry.request.url-elementin arvoksi on annettava viittaus korvattavan Consent-resurssi-instanssin loogiseen tunnisteeseen (id).
Provenance-resurssista luodaan korvaustilanteessa kokonaan uusi instanssi, sitä ei versioida. Näin Provenance-resurssi-instanssit ovat aina Consent-resurssi-instansseihin liittyen versiokohtaisia.
Consent-resurssin osalta Bundle.entry.request.method-elementtien arvoksi laitetaan PUT ja Provenance-resurssin osalta POST.
Alla esimerkki korvauksessa käytettävästä Bundle-resurssista ja sen sisällä olevista Consent- ja Provenance-resurssi-instansseista sekä korvauksen osalta merkittävistä tiedoista.
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "[base]/Consent/ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"resource": {
"resourceType": "Consent",
"id": "ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
...
},
"request": {
"method": "PUT",
"url": "Consent/ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"ifMatch": "W/\"1\""
}
},
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf145"
"resource": {
"resourceType": "Provenance",
...
"target": {
"reference": "Consent/ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/2",
"display": "Sote-luovutuslupa"
},
...
},
"request": {
"method": "POST",
"url": "Provenance"
}
}
],
{
"signature": {
...
}
}
}
HTTP vastaus (response)
HTTP vastauksen tiedot palautetaan HTTP header- ja body-osuuksiin jaettuna.
Vastauksen HTTP header
Tallennuksen ja korvauksen HTTP-vastauksen header-osuus noudattaa Kanta-palveluiden yhteistä Kanta FHIR HTTP header määrittelyä ja siinä kuvattuja tietoja ja tietojen pakollisuuksia.
Vastauksen HTTP body
HTTP vastauksen body-osuudessa vastauksena palautuu Bundle-resurssi ja sen tyyppi on transaction-response.
Onnistuneen operaation tuloksena Tahdonilmaisupalvelu palauttaa Bundle-resurssin, joka sisältää jokaista lähetettyä entryä vastaavan responsen. Response-elementissä on seuraavat tiedot:
- status-elementissä ilmoitetaan resurssin tallennuksen HTTP-statuskoodi
- location-elementissä ilmoitetaan tallennetun resurssin tyyppi, Tahdonilmaisupalvelun tuottama yksilöivä tunnus resurssille ja resurssin versionumero
- etag-elementissä ilmoitetaan resurssin versionnumero
Esimerkki Tahdonilmaisupalvelun palauttamasta vastaussanomasta onnistuneessa tallennuksessa
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"response": {
"status": "201 Created",
"location": "Consent/ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/1",
"etag": "W/\"1\""
}
},
{
"fullUrl": "urn:uuid:2639da1f-e03c-4faf-aec0-6007c4de7265",
"response": {
"status": "201 Created",
"location": "Provenance/2639da1f-e03c-4faf-aec0-6007c4de7265/_history/1",
"etag": "W/\"1\""
}
}
]
}
Esimerkki Tahdonilmaisupalvelun palauttamasta vastaussanomasta onnistuneessa korvauksessa
{
"resourceType": "Bundle",
"type": "transaction-response",
"entry": [
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"response": {
"status": "200 OK",
"location": "Consent/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\""
}
}
]
}
Vastaussanoma virhetilanteessa
Virhetilanteissa vastauksena palautuu HTTP virhestatuskoodi sekä HTTP bodyssa OperationOutcome resurssi-instanssi, jolla ilmoitetaan tarkempi virhe. Tahdonilmaisupalvelussa käytettävää OperationOutcome-resurssia ei ole profiloitu.
Implementointioppaan OperationOutcome-sivulla on kuvattu tarkemmin, miten Tahdonilmaisupalvelu palauttaa virheilmoitukset OperationOutcome-resussilla.