TOP-KT-002b - Search interacties
- Joris Scharp
- Marlotte Pannekoek
- Marcel Schrauwen
Beschrijving
Zoekbewerkingen doorlopen bestaande resources die gefilterd worden op parameters die met een zoekbewerking meegeleverd kunnen worden. De volgende FHIR zoekkaders zijn van belang voor de verschillende Koppeltaal portalen om gegeven op een ordelijke en duidelijke manier aan de gebruikers te kunnen presenteren.
Naast de veelgebruikte FHIR zoekkaders op deze pagina, kan men ook meer complexe zoekbewerkingen uitvoeren. Zie verschillende FHIR voorbeelden op https://www.hl7.org/fhir/search.html.
Overwegingen
FHIR API
FHIR biedt een duidelijke beschrijving van de search API. Koppeltaal gebruikt deze specificaties met enkele aanpassingen in:
wat er ondersteund wordt,
wat er binnen Koppeltaal verplicht is,
toevoegingen op de standaard.
Paginering
De FHIR API maakt gebruik van Feed Paging and Archiving (rfc5005) voor paginering. In deze specificatie wordt een first, last, previous, self en next url in het resultaat meegegeven. De HAPI implementatie maakt naast rfc5005 tevens gebruik van zelf genereerbare URLs door middel van _count en _offset parameters. Het voordeel van het laatste is dat het voor een UX mogelijk wordt om naar specifieke pagina's te springen, omdat de URL van een dergelijke pagina te genereren/berekenen zijn. De rfc5005 werkt echter met enkel de URLs voor vooruit en achteruit spoelen, en niet met specifieke pagina's. Hoewel we mogelijk hier een wens zien ontstaan vanuit de afnemers van de API, besluiten we als Koppeltaal deze af te wachten en vooralsnog geen extra eisen anders dan de door de FHIR API gespecificeerde rfc5005 vast te stellen.
Toepassing en restricties
Ondersteunde search parameters overzicht
Parameters for all resources | Search result parameters | Search result parameters NIET ondersteund | Custom search result parameters |
|---|---|---|---|
|
|
|
|
|
|
| |
|
|
| |
|
|
| |
|
| ||
| |||
| |||
| |||
| |||
|
Let op: Een aantal van de bovenstaande search result parameters worden NIET ondersteund. Dit vanwege extra complexiteit i.c.m. het autorisatiemodel. De niet ondersteunde parameters mogen a) door de FHIR resource service worden genegeerd of b) het request mag afgekeurd worden.
.Paginering
De FHIR API specificeert dat de resultaten van een zoek- of geschiedenis interactie en voldoen aan de methode (gespecificeerd in Feed Paging and Archiving (rfc5005) voor het verzenden van vervolg-links naar de applicatie-instantie bij het retourneren van een Bundle resource (bijv. geschiedenis en zoeken). De FHIR resource service MOET deze specificatie volgen.
De implementatie MAG naast het implementeren van Feed Paging and Archiving (rfc5005) gebruik maken van vaste parameters rond paginering, geadviseerd wordt om gebruik te maken van_offset. Deze in combinatie met de _count paramater die reeds onderdeel is van de search parameters.
Voorbeeld - Het opvragen van Task(s) met als resultaat 25 Tasks die aan een bepaalde criteria voldoen, verdeeld over 3 pagina's die elk 10 Task resources tonen. Zie de _count=10 in link.relation=self (is de huidige pagina):
{
"resourceType": "Bundle",
"id": "3bfbeaf3-8bcf-499b-8cbe-90b3ce3e1b42",
"type": "searchset",
"timestamp": "2022-03-01T12:32:55Z",
"total": 25,
"link": [
{
"relation": "first",
"url": "https://tst-koppeltaal.dvzaservices.nl/api/v1/domein1/fhir/r4/Task?page=1&queryId=15c25015-cae9-4ff2-9d02-38e34ba9d971"
},
{
"relation": "self",
"url": "https://tst-koppeltaal.dvzaservices.nl/api/v1/domein1/fhir/r4/Task?_count=10"
},
{
"relation": "next",
"url": "https://tst-koppeltaal.dvzaservices.nl/api/v1/domein1/fhir/r4/Task?page=2&queryId=15c25015-cae9-4ff2-9d02-38e34ba9d971"
},
{
"relation": "last",
"url": "https://tst-koppeltaal.dvzaservices.nl/api/v1/domein1/fhir/r4/Task?page=3&queryId=15c25015-cae9-4ff2-9d02-38e34ba9d971"
}
],
...
}Je kan vervolgens met gebruik van de aangeboden URL's in de Bundle van first, previous, next en last door de verschillende Task resource instanties heen navigeren.
_summary
Er worden GEEN Koppeltaal-specifieke velden toegevoegd aan de _summary search resultaten. Dit houdt dus in dat _summary enkel een summary geeft van de velden die als zodanig gemarkeerd zijn door FHIR zelf.
Veelgebruikte functionaliteit uit de standaard
Sorteren
FHIR ondersteunt sorteren volgens een specifieke set regels.
Volgens de specificatie wordt het sorteren door de applicatie-instantie gevraagd met behulp van zoekparameters. Bij het doorzoeken van Patient resources kan gesorteerd worden op Patient.name.given door de given zoekparameter mee te geven aan de _sort parameter.
Voorbeeld:
https://koppeltaal.nl/Patient?_sort=given
Limiting
FHIR ondersteunt Page Count. Het aantal te retourneren zoekresultaten kan worden doorgegeven.
Voorbeeld:
https://koppeltaal.nl/Patient?_count=10
Functionaliteit toegevoegd op de standaard
Search Narrowing
Search Narrowing wordt automatisch toegepast door de FHIR resource service en zorgt er voor dat applicatie-instanties enkel resources verkrijgen waartoe deze geautoriseerd is. Zie Rollen en rechten voor applicatie-instanties voor meer informatie
Custom SearchParameters
Een SearchParameter is een FHIR resource zoals andere FHIR resources. Deze resource zorgt er voor dat extra velden in de database geïndexeerd worden, zodat hier op gezocht kan worden. De SearchParameter geeft in een simplistische uitleg aan waar in de Resource(s) op gezocht kan worden en middels welke query parameter dit aangeroepen kan worden. Standaard biedt FHIR een hoop SeachParameters aan die te gebruiken zijn in de FHIR resource provider. In het geval van Koppeltaal, MOETEN de volgende SearchParameters worden toegevoegd door de aanbieder van de FHIR resource provider:
# | Resource (base) | Search Parameter | code (query parameter) | type | target | chain |
|---|---|---|---|---|---|---|
1 | Task | instantiates | instantiates | reference | ActivityDefinition | publisherId |
2 | ActivityDefinition | extension('http://koppeltaal.nl/fhir/StructureDefinition/KT2PublisherId') | publisherId | token | ActivityDefinition | |
3 | ActivityDefinition | participant | reference | RelatedPerson|Patient|Practitioner |
| |
4 | ActivityDefinition, CareTeam, Device, Organization, Patient, Practitioner, RelatedPerson, Task, AuditEvent, Endpoint, Subscription | extension('http://koppeltaal.nl/fhir/StructureDefinition/resource-origin') | resource-origin | reference | Device | |
5 | AuditEvent | extension('https://simplifier.net/koppeltaalv2.0/kt2searchtraceid') | traceId | reference | AuditEvent | |
6 | AuditEvent | extension('https://simplifier.net/koppeltaalv2.0/search-correlation-id') | correlationId | reference | AuditEvent | |
7 | AuditEvent | extension('https://simplifier.net/koppeltaalv2.0/search-request-id') | requestId | reference | AuditEvent |
Deze SearchParameter is nodig om de volgende vraag te beantwoorden:
“Geef mij alle Tasks die gekoppeld zijn aan een ActivityDefinition waarvan de publisherId extensie overeenkomt met X”.
Deze parameter maakt gebruik van een zogenaamde “chain” tussen Task en ActivityDefinition. Dit zorgt ervoor dat er gezocht kan worden op een specifieke eigenschap van een gerefereerd object.
Voorbeeld:
https://koppeltaal.nl/Task?instantiates.publisherId=X
Applicatie-instanties mogen ActivityDefinitions groeperen met de publisherId extensie. Deze groepering kan gebruikt worden om direct op te zoeken en om alle toegekende Tasks aan de groep van ActivityDefinitions te vinden (SearchParameter #1).
Voorbeeld:
https://koppeltaal.nl/ActivityDefinition?publisherId=my-publisher-123
Deze SearchParameter maakt het mogelijk Activity Definitions te kunnen zoeken voor een Participant-Type.
https://koppeltaal.nl/ActivityDefinition?participant=RelatedPerson
Alle resources die aangemaakt worden krijgen automatisch een resource-origin extensie ingevuld met een Reference naar hun unieke Device resource. Middels deze SearchParameter kan gezocht worden op eigenaarschap van de gebruikte Resources in Koppeltaal 2.
Voorbeeld:
https://koppeltaal.nl/Patient?resource-origin=Device/4507fa63-7cfd-4d1e-8389-7598b8e24de0
Deze parameter maakt het mogelijk om op basis van TraceId te zoeken binnen de AuditEvents.
Voorbeeld:
https://koppeltaal.nl/AuditEvent?traceid=a094d05b-7e8e-4c65-aba7-e73c5875849b
Deze parameter maakt het mogelijk om op basis van CorrelationId te zoeken binnen de AuditEvents.
Voorbeeld:
https://koppeltaal.nl/AuditEvent?correlationid=6bc84a32-54e0-4e4b-ab7c-f019c53c3a31
Deze parameter maakt het mogelijk om op basis van RequestId te zoeken binnen de AuditEvents.
Voorbeeld:
https://koppeltaal.nl/AuditEvent?requestid=be1b2026-b953-43a1-8cef-3cbb221a51e0
Links naar gerelateerde onderwerpen
Beschrijving | Link |
|---|---|
FHIR search specificatie | |
FHIR paginatie | |
FHIR |
{}