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 biedt een duidelijke beschrijving van de search API. Koppeltaal gebruik deze specificaties met enkele aanpassingen in:

1. wat er ondersteund wordt, 
2. wat er binnen Koppeltaal verplicht is,
3. toevoegingen op de standaard.

Toepassing en restricties

Ondersteunde search parameters overzicht

Paging

De FHIR Resource Provider MOET paging ondersteunen voor de resultaten van een zoek- of geschiedenis interactie en voldoen aan de methode (gespecificeerd in RFC 5005 - Feed Paging and Archiving) voor het verzenden van vervolg-links naar de applicatie-instantie bij het retourneren van een Bundle resource (bijv. geschiedenis en zoeken). Als de server dit niet doet, is er geen manier om door te gaan met oproepen.

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.

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

Custom _offset search result parameter.

Koppeltaal ondersteunt paging m.b.v. een _offset zoekparameter. Deze annotatie maakt geen deel uit van de FHIR-standaard.

Er zijn twee mogelijke manieren om paging te gebruiken. Het is mogelijk om de parameter _offset in de aanvraag te definiëren, wat betekent dat in combinatie met _count de paging op database-niveau wordt gedaan. Dit type paging heeft het voordeel dat er bij het paging-items niet zoveel items uit de database hoeven te worden geretourneerd. Het is ook mogelijk om de standaard paginagrootte (d.w.z. standaard _count indien niet opgegeven) en maximale paginagrootte (d.w.z. maximale waarde voor de _count parameter) te definiëren.

Voorbeeld om eerste pagina op te vragen met 10 patiënten:

https://koppeltaal.nl/Patient?identifier=urn:foo|123&_count=10&_offset=0

Voorbeeld opvragen 2e pagina met 10 patiënten:

https://koppeltaal.nl/Patient?identifier=urn:foo|123&_count=10&_offset=10

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 [TODO: Link topic 005] 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:

SearchParameter #1

Deze SearchParameter is nodig om de volgende vraag te beantwoorden:

“Geef mij alle Tasks die gekoppeld zijn aan een ActivityDefinition waarvan de publisher-identifier 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-canonical=my-publisher-123

SearchParameter #2

Applicatie-instanties mogen ActivityDefinitions groeperen met de publisher-identifier 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).

SearchParameter #3

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.

Links naar gerelateerde onderwerpen

{}