Tallennus ja korvaus
Ajanvarauksen 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/
Myös 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 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 ajanvarauksen tallennuksessa Potilastietovarantoon että Potilastietovarannossa olevan ajanvarauksen korvauksessa ajanvarauksen tiedot lähetetään Potilastietovarantoon Bundle-resurssilla, joka sisältää yhden Appointment- ja Provenance -parin. Appointment-resurssi sisältää varsinaisen ajanvarauksen tiedot ja Provenance-resurssi Appointment-resurssiin 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öisen allekirjoitus on määritelty erillisessä määrittelyssä Kanta FHIR sähköinen allekirjoitus.
Ajanvarauksen tiedot sisältävästä Appointment-resurssista viitataan seuraaviin resursseihin, jotka esitetään Appointment-resurssin sisällä olevassa contained-rakenteessa:
- Patient (ajanvarauksen asiakkaan tiedot)
- Condition (ajanvarauksen syy)
- HealthcareService (ajanvarauksen kohde)
- Organization (palvelun toteuttajan tiedot)
- Location (palvelupiste)
Ajanvarauksen metatiedot sisältävästä Provenance-resurssista viitataan seuraaviin resursseihin, jotka esitetään Provenance-resurssin sisällä olevassa contained-rakenteessa:
- Patient (ajanvarauksen asiakkaan tiedot)
- Practitioner/Patient/Device (ajanvarauksen tekijä, joka voi olla ammattilainen, kansalainen tai ohjelmisto)
- Device (tiedot tuottanut tietojärjestelmä)
Tallennus ja resurssin looginen tunniste (id), käytettävä HTTP metodi
Potilastietovaranto hallinnoi Appointment-resurssi-instanssin yksilöivää tunnusta eli FHIR resurssi-instanssin loogista tunnistetta (id). Huom. tämä on eri tunniste kuin ajanvarauksen tietosisällöstä löytyvä ajanvarauksen tunniste (Appointment.identifier).
Ajanvarausta tallentavan tahon on luotava uuden Ajanvarauksen tallennuksen yhteydessä ”väliaikainen” looginen tunniste Appointment-resurssi-instanssille ja annettava se Appoiment-resurssiin liittyvässä Bundle.entry:n fullUrl-elementissä. Tätä loogista tunnistetta fullUrl-elementissä on käytettävä viittauksessa Provenance-resurssista (Provenance.target.reference) Appointment-resurssiin.
Potilastietovaranto tuottaa tallennuksen yhteydessä Appointment-resurssi-instanssille globaalisti yksilöivän tunnuksen ja korvaa tallentavan tahon resurssi-instanssiin fullUrl-elementissä antaman loogisen tunnisteen (id). Potilastietovarannon luoma resurssi-instanssin looginen tunniste (id) palautetaan pyynnön vastauksessa onnistuneen tallennuksen yhteydessä (huom. tätä tunnistetta on käytettävä, kun ajanvarausta 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 Appointment-resurssi-instanssiin.
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143",
"resource": {
"resourceType": "Appointment",
...
},
"request": {
"method": "POST",
"url": "Appointment"
}
},
{
...
"resource": {
"resourceType": "Provenance",
...
"target": {
"reference": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf143",
"display": "Ajanvaraus"
},
...
}
"request": {
"method": "POST",
"url": "Provenance"
}
}
],
{
"signature": {
...
}
}
}
Korvaus ja resurssin looginen tunniste (id), käytettävä HTTP metodi
Ajanvarauksen korvauksessa Appointment-resurssi-instanssin loogisena tunnisteena on käytettävä Potilastietovarannon resurssi-instanssille luomaa resurssi-instanssin yksilöivää loogista tunnistetta (id).
Appointment-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). Ajanvarauksen korvaus onnistuu vain, kun ifMatch-elementissä välitetään versionumero, joka vastaa ajanvarauksen viimeisintä eli voimassa olevaa versiota Potilastietovarannossa. Potilastietovaranto huolehtii muuten korvattavan resurssi-instanssin versioinnista.
Appointment-Bundle.entry.request.url-elementin arvoksi on annettava viittaus korvattavan Appointment-resurssi-instanssin loogiseen tunnisteeseen (id).
Provenance-resurssissa luodaan korvaustilanteessa kokonaan uusi instanssi, sitä ei versioida. Näin Provenance-resurssi-instanssit ovat aina Appointment-resurssi-instansseihin liittyen versiokohtaisia. Korvauksessa pitää ilmoittaa korvauksen syy ja se välitetään Provenance.activity-elementillä.
Appointment-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 Appointment- ja Provenance-resurssi-instansseista sekä korvauksen osalta merkittävistä tiedoista.
{
"resourceType": "Bundle",
"type": "transaction",
"entry": [
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"resource": {
"resourceType": "Appointment",
"id": "ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
...
},
"request": {
"method": "PUT",
"url": "Appointment/ce5ea340-adfd-40f2-87d4-a25e4f8bf198",
"ifMatch": "W/\"1\""
}
},
{
"fullUrl": "urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf145"
"resource": {
"resourceType": "Provenance",
...
"target": {
"reference": "Appointment/ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/2",
"display": "Ajanvaraus"
},
...
"activity": {
"coding": {
"system": "urn:oid:1.2.246.537.5.40178.2008",
"code": "1",
"display": "Korjaus"
}
}
},
"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 Potilastietovaranto 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, Potilastietovarannon tuottama yksilöivä tunnus resurssille ja resurssin versionumero
- etag-elementissä ilmoitetaan resurssin versionnumero
Esimerkki Potilastietovarannon palauttamasta vastaussanomasta onnistuneessa tallennuksessa
{
"resourceType": "Bundle",
"id": "bundle-response",
"type": "transaction-response",
"entry": [
{
"response": {
"status": "201 Created",
"location": "Appointment/ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/1",
"etag": "W/\"1\""
}
},
{
"response": {
"status": "201 Created",
"location": "Provenance/2639da1f-e03c-4faf-aec0-6007c4de7265/_history/1",
"etag": "W/\"1\""
}
}
]
}
Esimerkki Potilastietovarannon palauttamasta vastaussanomasta onnistuneessa korvauksessa
{
"resourceType": "Bundle",
"id": "bundle-response",
"type": "transaction-response",
"entry": [
{
"response": {
"status": "200 OK",
"location": "Appointment/urn:uuid:ce5ea340-adfd-40f2-87d4-a25e4f8bf198/_history/2",
"etag": "W/\"2\""
}
},
{
"response": {
"status": "201 Created",
"location": "Provenance/urn:uuid:2639da1f-e03c-4faf-aec0-6007c4de7267/_history/1",
"etag": "W/\"1\""
}
}
]
}
Vastaussanoma virhetilanteessa
Virhetilanteissa vastauksena palautuu HTTP virhestatuskoodi sekä HTTP bodyssa OperationOutcome resurssi-instanssi, jolla ilmaistaan tarkempi virhe. Potilastietovarannossa käytettävää OperationOutcome-resurssia ei ole profiloitu.
OperationOutcome-sivulla on kuvattu tarkemmin, miten Potilastietovaranto palauttaa virheilmoitukset OperationOutcome-resussilla.