Haku
Haun HTTP pyyntö (request)
Haku välitetään palvelulle HTTP POST-pyyntönä (request).
Ajanvarausten viimeisimmät versiot haetaan search-interaktiolla: POST: [base]/Appointment/_search
Esim. POST http://example.org/baseR4/Appointment/_search
Ajanvarausten kaikki versiot haetaan history-interaktiolla: POST: [base]/Appointment/_history
Esim. POST http://example.org/baseR4/Appointment/_history
Pyynnön URL:in muoto noudattaa FHIR määrittelyjä (Style Guide). Eri ympäristöjen käytettävät juuret ilmoitetaan erikseen eikä niitä julkisteta tässä implementointioppaassa.
Hakuparametreja ei saa lisätä pyynnön URLiin. Perusteena on, että URLin osana hakuparametrien arvot voivat jäädä esimerkiksi verkkolaitteiden lokitietoihin.
HTTP pyynnön header
Haun HTTP-pyynnön header-osuus noudattaa Kanta-palveluiden yhteisiä Kanta FHIR HTTP header ja Kanta JSON Web Token määrittelyitä ja näissä kuvattuja tietoja ja tietojen pakollisuuksia.
Organisaatiotietojen välittämistä JSON WEB Token -tiedoissa eri tilanteissa on kuvattu tarkemmin Organisaatiotiedot FHIR-sanomien JSON Web Token -tiedoissa.
HTTP pyynnön body
Ajanvarausten haussa käytettävät hakuparametrit välitetään HTTP pyynnön body-osuudessa.
Ajanvarausten viimeisimpien versioiden haussa on käytettävisssä seuraavat hakuparametrit:
| FHIR-hakuparametri | Hakuparametrin tyyppi | Pakollisuus | FHIR-resurssi ja elementti |
|---|---|---|---|
| identifier | token | Vapaaehtoinen 0..1 | appointment.identifier - Ajanvarauksen tunniste |
| patient:identifier | reference | Pakollinen 1..1 | patient.identifier - Asiakkaan tunniste |
| service-organiser | token | Vapaaehtoinen 0..1 | Provenance.agent.who.identifier - Varatun palvelun palvelunjärjestäjä |
| appointment-service-provider | token | Vapaaehtoinen 0..1 | organization.partOf - Varatun palvelun palveluntuottaja |
| appointment-service-provider-unit | token | Vapaaehtoinen 0..1 | organization.identifier - Varatun palvelun toteuttava yksikkö |
| producing-service-provider-unit | token | Vapaaehtoinen 0..1 | Provenance.agent.who.identifier - Resurssin tallentajan palveluyksikkö. Jos hakuparametri annetaan, annettava aina myös Palveluntuottaja-hakuparametri 'appointment-service-provider' (asiakkaan tunnisteen lisäksi). |
| date | date | Vapaaehtoinen 0..2 | appointment.start - Ajanvarauksen alkuaika ** |
| recorded | date | Vapaaehtoinen 0..2 | provenance.recorded - Ajanvaraustoimenpiteen tekoaika eli ajankohta, jolloin ajanvaraus on suoritettu (Appointment-resurssin luontiaika) ** |
| register-type-code | token | Vapaaehtoinen 0..1 | provenance.extension.RegisterType - Potilasrekisteritunnus |
| service-event | token | Vapaaehtoinen 0..1 | provenance.extension.ServiceEvent - Palvelutapahtumatunnus |
| include-own | token | Vapaaehtoinen 0..1 | Palautetaanko hakutuloksessa tiedot kyselyn tekijän rekisteristä vai rajataanko ne pois (oletuksena true) |
** Sallitut ajan muodot:
- Päivätarkkuus: yyyy-mm-dd
- Sekuntitarkkuus: yyyy-mm-ddThh:mm:ss tai yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]. Ilman aikavyöhykettä annettu arvo käsitellään Helsingin aikavyöhykkeenä. LT1
Ajanvarausten kaikkien versioiden haussa on käytettävisssä seuraavat hakuparametrit:
| FHIR-hakuparametri | Hakuparametrin tyyppi | Pakollisuus | FHIR-resurssi ja elementti |
|---|---|---|---|
| identifier | token | Pakollinen 1..1 | appointment.identifier - Ajanvarauksen tunniste |
| patient:identifier | reference | Pakollinen 1..1 | patient.identifier - Asiakkaan tunniste |
Jos ajanvarausten kaikkien versioiden haussa välitetään hakuparametreja, jotka ovat käytössä vain ajanvarausten viimeisimpien versioiden haussa, näitä hakuparametreja ei huomioida haun rajauksessa.
Hakua ohjaavat parametrit
| Parametri | Tyyppi | Pakollisuus | Kuvaus |
|---|---|---|---|
| _count | number | Vapaaehtoinen 0..1 | Parametri kertoo kuinka monta ajanvarausta halutaan palautettavaksi yhdellä sivulla. Historiahaussa yhteen ajanvaraukseen liittyy kaikki ajanvarauksen versiot. Jos parametria ei ole annettu, käytetään Potilastietovarannossa asetettua oletussivukokoa. |
Esimerkkejä hakuparametrien käytöstä
Yhteen hakuun voidaan liittää useita kyselyparametreja, alla esimerkkejä hakulauseista.
Kun system-arvona on vakio urn:ietf:rfc:3986, system-arvo voidaan välittää tai jättää välittämättä.
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001
Yksittäisen ajanvarauksen haku potilaan ja ajanvarauksen tunnisteen perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&identifier={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja palvelunjärjestäjän perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&service-organiser={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja palveluntuottajan perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&appointment-service-provider={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja palvelun toteuttavan yksikön perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&appointment-service-provider-unit={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen, palveluntuottajan ja resurssin tallentajan palveluyksikön perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&appointment-service-provider-unit={system|value}&producing-service-provider-unit={system|value}
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja ajanvarauksen alkamisajan perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&date=&date=
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001&date=ge2024-01-01&date=le2024-12-31
Haku palauttaa ne tiedot, joissa Appointment.start on aikarajauksen sisällä.
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja ajanvarauksen luontiajan perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&provenance:recorded=&provenance:recorded=
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001&provenance:recorded=ge2024-01-01
Haku palauttaa ne tiedot, joissa Provenance.recorded on annetun aikarajauksen mukainen.
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001&provenance:recorded=ge2024-01-01&provenance:recorded=le2024-01-07
Haku palauttaa ne tiedot, joissa Provenance.recorded on aikarajauksen sisällä
Potilaan kaikkien ajanvarausten haku potilaan tunnisteen ja potilasrekisteritunnuksen perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}®ister-type-code={system|code}
Potilaan ajanvarausten haku palvelutapahtumatunnuksen perusteella:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&service-event={system|value}
Potilaan ajanvarausten haku luovutushaku, hakua ei kohdisteta hakijan omaan rekisteriin:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&include-own=boolean
Esim. patient:identifier=urn:oid:1.2.246.21|300111A9001&include-own=false
Jos kerralla halutaan palautettavaksi oletussivukokoa vähemmän ajanvarauksia, käytetään hakua ohjavaa parametria _count
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier={system|value}&_count=10
Potilaan ajanvarausten jatkohaku:
Ajanvaraukseen toteutettu hakutuloksen sivutusratkaisu mahdollistaa eteenpäin navigoinnin.
Ajanvarauksen sivutetun haun vastaussanomassa palautetaan tarvittaessa Bundle.link‑elementissä jatkohakuun käytettävä linkki, jonka relation‑kentän arvo on next.
{
"resourceType": "Bundle",
"type": "searchset",
"link": [
{
"relation": "self",
"url": "http://example.org/baseR4/Appointment?patient:identifier=urn:oid:1.2.246.21|300111A9001&_count=10"
},
{
"relation": "next",
"url": "http://example.org/baseR4/Appointment?patient:identifier=urn:oid:1.2.246.21|300111A9001&_count=10&result_set_key=20230327142915|3c4c5e99-1baa-4531-b1cb-8c5b31dcd6ce&original_x_request_id=6f7lks3n-vpc3-928h-c78v-sk95g27lb954"
}
]
...
}
Jatkohaku voidaan suorittaa POST-pyyntönä käyttäen next-linkissä palautettua URLia vastaavia parametreja. Esim. kun halutaan hakea edellä esitetyn hakutuloksen seuraavan sivun tiedot:
POST [base]/Appointment/_search
Content-Type: application/x-www-form-urlencoded
patient:identifier=urn:oid:1.2.246.21|300111A9001&_count=10&result_set_key=20230327142915|3c4c5e99-1baa-4531-b1cb-8c5b31dcd6ce&original_x_request_id=6f7lks3n-vpc3-928h-c78v-sk95g27lb954
Miten aikarajaus toimii
Tuetut prefixit:
- eq
- gt
- lt
- ge
- le
Esim. Hakuehto, jossa potilaan palautettavat ajanvaraukset rajataan ajanvarauksen 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 |
Lisätiedot
LT1 Aikavyöhyketiedot
Tallennettavan ajanvarauksen instant-tietotyyppiä olevat tiedot sisältävät aina aikavyöhyketiedon. Potilastietovaranto ei rajoita käytettäviä aikavyöhykkeitä.
Vastauksen jsonissa Helsingin aikavyöhykkeeet (+02:00 tai +03:00).