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.
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 | FHIR-resurssi ja elementti | Huomioita |
|---|---|---|---|---|
| patient:identifier | reference | P (1..1) | 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) | 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) | 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ä. |
| code | token | O | Observation.code - toimintakykyhavainnon ICF-aihekoodi | |
| method | token | O | Observation.method - toimintakykyhavainnon havainnointimenetelmä | |
| functional-limitation-stability | token | O | Observation.extension.functionalLimitation.LimitationStability- havaittu toimintakykyrajoite on pysyvä | Käytetään hakuparametrina merkinnän toimintakyvystä haussa. |
| issued | date | O (0..2) | Observation.issued - toimintakykymerkinnän tai toimintakykyarvion laatimispäivämäärä | Päivämäärän voi antaa aikavälinä. |
| practitioner-qualification | token | O (0..1) | Observation.Practitioner.qualification - merkinnän toimintakyvystä tai toimintakykyarvion laatijan ammattioikeus | |
| practitioner-service-center | token | O (0..1) | organization.identifier - merkinnän toimintakyvystä tai toimintakykyarvion laatijan palveluyksikkö | |
| custodian-organization | token | eP (0..*) | Provenance.agent.who.organization - asiakastietojen rekisterinpitäjän yksilöintitunnus | Hakuparametri on pakollinen palveluntuottajan rekisterinkäyttöoikeuteen perustuvassa haussa, jossa on sallittua antaa yhden rekisterinpitäjän yksilöintitunnuksen. Hakuparametri on optionaalinen sosiaalihuollon toisen rekisterinpitäjän tietojen haussa, jossa on sallittua antaa 0 - n rekisterinpitäjän yksilöintitunnusta. |
| service-producer | token | O (0..1) | Provenance.agent.who.organization.ServiceProducer - toimintakykytiedon tallentaneen palveluntuottajan yksilöintitunnus | |
| service-center | token | O (0..1) | Provenance.agent.who.organization.ServiceCenter - toimintakykytiedon tallentaneen palveluyksikön yksilöintitunnus | |
| service-event | token | O (0..1) | Provenance.extension.serviceEvent - sosiaalihuollon asian asiatunnus | |
| service-process | token | O | Provenance.extension.serviceProcess - sosiaalihuollon palveluprosessi | |
| function-code | token | O | Provenance.extension.functionCode - sosiaalihuollon palvelutehtävä | |
| social-service | token | O | Provenance.extension.socialService - sosiaalipalvelu | |
| document-type | token | O (0..2) | Provenance.extension.DocumentType - yleinen asiakirjatyyppi | |
| specific-document-type | token | O (0..2) | 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
| Parametri | Tyyppi | Pakollisuus | Kuvaus |
|---|---|---|---|
| _count | Number | Vapaaehtoinen 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. |
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-producer={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
Asiakkaan toimintakykytietojen jatkohaku
Kanta-palvelujen palauttamassa vastaussanomassa sivutetun hakuvastauksen jatkohaussa käytettävissä olevat linkit (esimerkissä palautettu hakutuloksen ensimmäisen sivun tiedot):
"resourceType": "Bundle", "type": "searchset", "link": [ { "relation": "self", "url": "http://example.org/baseR4/Observation/_search?patient:identifier=urn:oid:1.2.246.21|300111A9001&_offset=10&_count=10" }, { "relation": "next", "url": "http://example.org/baseR4/Observation/_search?patient:identifier=urn:oid:1.2.246.21|300111A9001&_offset=20&_count=10" }, { "relation": "previous", "url": "http://example.org/baseR4/Observation/_search?patient:identifier=urn:oid:1.2.246.21|300111A9001&_offset=0&_count=10" } ]
Jatkohaussa käytetään Kanta-palvelujen vastaussanomassa palauttamia hakuparametreja, jotka hakeva järjestelmä poimii halutun sivun url-arvosta. Esimerkki, kun halutaan hakea edellä esitetyn hakutuloksen seuraavan sivun tiedot:
POST [base]/Observation/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier=urn:oid:1.2.246.21|300111A9001&_offset=20&_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 |