Hakusanomat
Hakusanoma lähetetään Kanta-palveluihin HTTP POST-pyyntönä (request). Merkinnän toimintakyvystä tai toimintakykyarvion uusin versio haetaan search-interaktiolla: POST [base]/[observation]/_search. Merkinnän toimintakyvystä tai toimintakykyarvion kaikki versiot haetaan history-interaktiolla: POST [base]/[observation]/_history.
Potilastietovarannon hauissa käytetään search- ja history-interaktioita. History-interaktiota on sallittua käyttää vain haettaessa toimintakykytietoja rekisterinpitäjän omasta rekisteristä. Sosiaalihuollon asiakastietovarannon hauissa käytetään vain search-interaktiota, sillä asiakastietojärjestelmästä on mahdollista hakea vain resurssin viimeisin, voimassa oleva versio. Sosiaalihuollon asiakastietovaranto ei palauta haussa asiakastietojärjestelmälle resurssin aiempia versioita tai mitätöityjä resursseja. Sosiaalihuollossa asiakastietojen rekisterinpitäjä voi hakea omassa rekisterissään olevat resurssin aiemmat versiot tai mitätöidyn resurssin Sosiaalihuollon asiakastietovarannon arkistonhoitajan käyttöliittymästä.
Pyynnön URL:in muoto noudattaa 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ä soveltamisoppaassa.
Haussa käytettäviä hakuparametreja ei saa lisätä pyynnön URLiin, koska URLin osana hakuparametrien arvot, kuten asiakkaan yksilöivä tunnus, voivat jäädä esimerkiksi verkkolaitteiden lokitietoihin.
Sosiaalihuollon toimintakykytietojen haussa ei tueta toimintakykytietojen käsittelyn alkuvaiheessa hakutuloksen sivutusta. Hakutuloksen sivutus Sosiaalihuollon asiakastietovarannossa tullaan toteuttamaan jatkokehityksenä.
HTTP-pyynnön header
Haun HTTP-pyynnön header-osuus noudattaa Kanta-palveluiden yhteisiä Kanta FHIR HTTP header -dokumentin mukaisen HTTP-headerin ja JSON Web Tokenin määrittelyitä. 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
Toimintakykytiedon haussa käytettävät hakuparametrit lähetetään HTTP-pyynnön body-osuudessa. Sosiaalihuollon asiakastietovarannon tukemat hakuparametrit on kuvattu taulukossa 4. Asiakastietovaranto tukee hakuparametreina sekä toimintakykytiedon tietosisällössä olevia tietoja että Provenance-resurssissa olevia toimintakykytiedon metatietoja. Hakuparametrit ovat pakollisia (P), ehdollisesti pakollisia (eP) tai vapaaehtoisia (O).
Potilastietovarannon tukemat hakuparametrit tarkennetaan vuonna 2026.
Taulukko 4 Sosiaalihuollon asiakastietovarannossa käytettävät hakuparametrit
| FHIR-hakuparametri | Hakuparametrin tyyppi | Pakollisuus | Toistuvuus | Hakuparametrin muoto | FHIR-resurssi ja elementti | Huomioita |
|---|---|---|---|---|---|---|
| patient:identifier | reference | P | 1..1 | patient:identifier={system|value} | patient.identifier - asiakkaan henkilötunnus tai tilapäinen yksilöintitunnus | Haussa toisen rekisterinpitäjän rekisteristä on annettava henkilötunnus. |
| identifier | token | O | 0..1 | identifier:{system|value} | Observation.identifier - merkinnän toimintakyvystä tai toimintakykyarvion yksilöivä tunnus | Hakuparametri on pakollinen, kun haetaan yksi (1) merkintä toimintakyvystä tai toimintakykyarvio. |
| date | date | O | 0..2 | Yksi päivä: date=2023-10-30 |
Observation.effective - toimintakyvyn havainnointipäivämäärä, Observation.effective.Effectiveperiod.start - toimintakykyarvion alkamispäivämäärä, Observation.effective.Effectiveperiod.end - toimintakykyarvion päättymispäivämäärä | Päivämäärän voi antaa aikavälinä. Hakuparametri on FHIR-standardin mukainen Observation-resurssin hakuparametri, jota käytetään FHIR-standardin mukaisesti. |
| code | token | O | 0..*, OR | code={system|value} | Observation.code - toimintakykyhavainnon ICF-aihekoodi | |
| method | token | O | 0..*, OR | method={system|value} | Observation.method - toimintakykyhavainnon havainnointimenetelmä | |
| issued | date | O | 0..2 | Yksi päivä: date=2023-10-30 Aikaväli: date=ge2023-10-30&date=lt2023-11-02 | Observation.issued - toimintakykymerkinnän tai toimintakykyarvion laatimispäivämäärä | Päivämäärän voi antaa aikavälinä. |
| practitioner-qualification | token | O | 0..*, OR | practitioner-qualification={system|value} | Observation.Practitioner.qualification - merkinnän toimintakyvystä tai toimintakykyarvion laatijan ammattioikeus | |
| practitioner-service-center | token | O | 0..*, OR | Practitioner-service-center={system|value} tai |
organization.identifier - merkinnän toimintakyvystä tai toimintakykyarvion laatijan palveluyksikkö | |
| custodian-organization | token | eP | 0..*, OR | custodian-organization={system|value} tai |
Provenance.agent.who.organization - asiakastietojen rekisterinpitäjän yksilöintitunnus | Hakuparametri on pakollinen rekisterinpitäjän omassa haussa (hakutilanne 1) ja palveluntuottajan rekisterinkäyttöoikeuteen perustuvassa haussa (hakutilanteet 2 ja 4), joissa on sallittua antaa yhden rekisterinpitäjän yksilöintitunnus. Hakuparametri on optionaalinen sosiaalihuollon toisen rekisterinpitäjän tietojen haussa (hakutilanne 3), jossa on sallittua antaa 0 - n rekisterinpitäjän yksilöintitunnusta. Hakuparametri on pakollinen hakuparametri palveluntuottajan rekisterinkäyttöoikeuteen perustuvassa luovutushaussa (hakutilanne 6), jossa on sallittua antaa 1 - n rekisterinpitäjän yksilöintitunnusta. Yhden rekisterinpitäjän yksilöintitunnus on oltava sen sosiaalihuollon rekisterinpitäjäjän yksilöintitunnus, jonka rekisterissä palveluntuottajalla on rekisterinkäyttöoikeus. |
| service-provider | token | O | 0..*, OR | service-provider={system|value} tai |
Provenance.agent.who.organization.ServiceProvider - toimintakykytiedon tallentaneen palveluntuottajan yksilöintitunnus | |
| service-center | token | O | 0..*, OR | service-center={system|value} tai |
Provenance.agent.who.organization.ServiceCenter - toimintakykytiedon tallentaneen palveluyksikön yksilöintitunnus | |
| service-event | token | O | 0..*, OR | service-event={system|value} | Provenance.extension.serviceEvent - sosiaalihuollon asian asiatunnus | |
| service-process | token | O | 0..*, OR | service-process={system|value} | Provenance.extension.serviceProcess - sosiaalihuollon palveluprosessi | |
| function-code | token | eP | 0..*, AND, OR | function-code={system|value} | Provenance.extension.functionCode - sosiaalihuollon palvelutehtävä | Hakuparametri on pakollinen haussa toisen sosiaalihuollon rekisterinpitäjän rekisteristä. |
| social-service | token | O | 0..*, OR | social-service={system|value} | Provenance.extension.socialService - sosiaalipalvelu | |
| document-type | token | O | 0..2, OR | document-type={system|value} | Provenance.extension.DocumentType - yleinen asiakirjatyyppi | |
| specific-document-type | token | O | 0..2, OR | specific-document-type={system|value} | Provenance.extension.specificDocumentType - asiakirjan tarkennettu asiakirjatyyppi |
Date-tyyppisissä hakuparametreissa sallitut ajan muodot ovat:
- Päivätarkkuus: yyyy-mm-dd
- Sekuntitarkkuus: yyyy-mm-ddThh:mm:ss tai yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm].
Jos hakeva järjestelmä ei ilmoita sekunnin tarkkuudella ilmoitettavassa hakuparametrissa aikavyöhykettä, Kanta-palvelut käsittelee hakuparametrissa annetua arvoa Helsingin aikavyöhykkeenä. Kanta-palvelut ei rajoita käytettäviä aikavyöhykkeitä. Kanta-palvelujen palauttamassa vastauksessa käytetään Helsingin aikavyöhykettä (+02:00 tai +03:00).
Hakua ohjaavat parametrit, ota tyyppi pois
| Parametri | Pakollisuus | Toistuvuus | Kuvaus |
|---|---|---|---|
| _count | O | 0..1 | Parametri kertoo kuinka monta merkintää toimintakyvystä ja/tai toimintakykyarviota hakeva järjestelmä haluaa palautettavaksi yhdellä sivulla. Jos parametria ei ole annettu, Kanta-palvelut käyttää Kanta-palveluissa asetettua oletussivukokoa. Sosiaalihuollon asiakastietovarannossa oletussivukoko on 300 Observation-Provenance-resurssiparia, joka on myös palautettavien resurssiparien maksimimäärä. |
| _sort | O | 0..1 | Parametri kertoo missä järjestyksessä hakupalvelimen pitää järjestää hakutuloksena saadut resurssit hakuvastauksessa. Sosiaalihuollon asiakastietovarannossa parametria on sallittua käyttää date-hakuparametreissa. Jos_sort-parametria ei ole annettu, Sosiaalihuollon asiakastietovaranto palauttaa hakuvastauksessa resurssit obsevation.id:n mukaan järjestettynä. |
Esimerkkejä hakuparametrien käytöstä
Yhteen hakuun voidaan liittää useita hakuparametreja, alla on esimerkkejä hakulauseista.
Asiakkaan kaikkien merkintöjen toimintakyvystä ja toimintakykyarvioiden haku asiakkaan yksilöivän tunnisteen perusteella
POST [base]/Observation/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001
Yksittäisen merkinnän toimintakyvystä tai toimintakykyarvion haku asiakkaan yksilöivän tunnisteen ja resurssin tunnisteen perusteella
POST [base]/Observation/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&identifier={system|value}
Asiakkaan kaikkien merkintöjen toimintakyvystä ja toimintakykyarvioiden haku asiakkaan yksilöivän tunnisteen perusteella ja rekisterinpitäjän perusteella
POST [base]/Observation/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&custodian-organization={system|value}
Asiakkaan kaikkien merkintöjen toimintakyvystä ja toimintakykyarvioiden haku asiakkaan yksilöivän tunnisteen perusteella ja palveluntuottajan perusteella
POST [base]/Observation/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&service-provider={system|value}
Asiakkaan kaikkien merkintöjen toimintakyvystä ja toimintakykyarvioiden haku asiakkaan yksilöivän tunnisteen perusteella ja sosiaalihuollon asiatunnuksen perusteella
POST [base]/Observation/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&service-event={system|value}
Jos halutaan kerralla palautettavaksi oletussivukokoa vähemmän toimintakykytietoja, käytetään hakua ohjavaa parametria _count
POST [base]/Observation/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&_count=10
Tuetut aikarajaukset
Sosiaalihuollon asiakastietovaranto tukee toimintakykytietojen haussa seuraavia prefixejä:
| Prefix | Selite |
|---|---|
| eq | Resurssissa oleva arvo on samansuuruinen kuin hakuparametrina annettu arvo tai sisältyy kokonaan hakuparametrina annettuun arvoon. Resurssi palautetaan, jos aikaleima on hakuparametrina annetun aikavälin sisällä. |
| gt | Resurssissa oleva arvo on suurempi kuin hakuparametrina annettu. Resurssi palautetaan, jos aikaleima on hakuparametrina annettua aikaleimaa myöhempi. |
| lt | Resurssissa oleva arvo on pienempi kuin hakuparametrina annettu arvo. Resurssi palautetaan, jos aikaleima on annettua hakuparametria aikaisempi. |
| ge | Resurssissa oleva arvo on suurempi tai yhtä suuri kuin hakuparametrina annettu arvo. Resurssi palautetaan, jos hakuparametrina annettu aika on suurempi tai yhtä suuri kuin resurssissa oleva aika. |
| le | Resurssissa oleva arvo on pienempi tai yhtä suuri kuin hakuparametrina annettu arvo. Resurssi palautetaan, jos hakuparametrina annettu aika on pienempi tai yhtä suuri kuin resurssissa oleva aika. |
Potilastietovarannon tukemat prefixit vuonna 2026.
Esimerkki hakuehdosta, jossa asiakkaan palautettavat merkinnät toimintakyvystä rajataan toimintakyvyn havainnointipäivämäärän alkuajan perusteella:
patient:identifier=urn:oid:1.2.246.21|300111A9001&date=ge2023-10-30&date=lt2023-11-02
| Päivämäärä täyttää hakuehdon | Päivämäärä ei täytä hakuehtoa |
|---|---|
| 2023-10-31T01:00:12.000 | 2023-10-29T01:00:00.00 |
| 2023-10-30T00:00:00.000 | 2023-11-02T00:00:00.00 (Ei sisälly tulosjoukkoon, koska lt-prefix haussa) |
patient:identifier=urn:oid:1.2.246.21|300111A9001&date=eq2023-10-30
| Päivämäärä täyttää hakuehdon | Päivämäärä ei täytä hakuehtoa |
|---|---|
| 2023-10-30T10:30:00.000 | 2023-10-29T20:00:00.00 |
| 2023-10-30T15:00:00.000 | 2023-10-31T07:00:00.00 |