TOP-KT-015 - Search parameters - [vervallen, samengevoegd met TOP-KT-002]

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 beschreven FHIR zoekkaders op deze pagina, kan men ook meer complexe zoekbewerkingen uitvoeren. Zie verschillende FHIR voorbeelden op https://www.hl7.org/fhir/search.html.

Bepaalde karakters zijn in de search NIET toegestaan. Deze MOETEN door een escape sequence, een procentteken "%" gevolgd door twee hexadecimale cijfers (0-9, A-F) die de waarde voor dat karakter (octet waarde) aangeven, vervangen worden. Zie "De URL opbouw" in https://vzvz.atlassian.net/wiki/x/XhqdAQ. Om de voorbeelden leesbaar te houden, zijn de escape sequence niet gebruikt.

Alle zoekinteracties zullen gelogd worden door de FHIR Resource Provider, zoals beschreven in de "Logging", zie de Event type Search.

Limiting

FHIR ondersteunt Page Count. Tellingspecificatie kan worden doorgegeven.

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

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 vervolglinks naar de afnemer (client applicatie) 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).

Paging

{
    "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.

GEEN FHIR STANDAARD.

De HAPI FHIR (gebruikt in de referentie implementatie) ondersteunt 'paging' m.b.v. een _offset zoekparameter. Deze _offset zoekparameter kan worden doorgegeven aan een procedure met @Offset-annotatie. Ook 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 databaseniveau 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: http://koppeltaal.nl/Patient?identifier=urn:foo|123&_count=10&_offset=0

Voorbeeld opvragen 2e pagina met 10 patiënten: http://koppeltaal.nl/Patient?identifier=urn:foo|123&_count=10&_offset=10

Sorteren

FHIR ondersteunt 'sorteren' volgens een specifieke set regels.

Volgens de specificatie wordt het sorteren door de klant gevraagd met behulp van een zoekparameter als de sorteersleutel. Bij het doorzoeken van Patient resources vraagt een sorteersleutel van "given" bijvoorbeeld de "given" zoekparameter als de sorteersleutel. Die parameter komt overeen met de waarden in het veld "Patient.name.given".

Voorbeeld: http://koppeltaal.nl/Patient?identifier=urn:foo|123&_sort=given

Narrowing (verborgen autorisatie interceptor)

GEEN FHIR STANDAARD.

De HAPI FHIR 3.7.0 ondersteunt een interceptor genaamd de "SearchNarrowingInterceptor"

Deze interceptor is ontworpen om te worden gebruikt in combinatie met de "AuthorizationInterceptor". Het gebruikt een vergelijkbare strategie waarbij voor elk verzoek een dynamische lijst wordt opgebouwd, maar het doel van deze interceptor is het wijzigen van cliënt zoekopdrachten die worden ontvangen (nadat HAPI FHIR het HTTP-verzoek heeft ontvangen, maar voordat de zoekopdracht daadwerkelijk wordt uitgevoerd) om het zoeken zodanig te beperken om alleen specifieke resources te retourneren waartoe een gebruiker toegang heeft.

Dit kan bijvoorbeeld worden gebruikt om de gebruiker in staat te stellen een zoekopdracht uit te voeren naar:
http://koppeltaal.nl/Task

...en ontvang vervolgens de resultaten alsof ze hierom hadden gevraagd:
http://koppeltaal.nl/Task?resource-origin=Device/480

Hiermee krijgt men krijgt dus alleen de taken te zien van Task resource owner Device/480.

Het definiëren en vastleggen van (extended) SearchParameters

Dit hoofdstukje moet nog verder uitgewerkt worden. Ook opgenomen bij Simplifier SearchParameter profielen. Zie Search Parameters.

Referentie: https://www.hl7.org/fhir/searchparameter-examples.html

Een SearchParameter is een (FHIR) resource zoals andere FHIR resources.

Het moeilijkste om uit te vinden is de expressie of uitdrukking waaraan de zoekparameter moet voldoen. Men kan hier de FhirPathTester-tool van Brian Postlewaith (op Github en in de Windows Store) gebruiken om de juiste FHIRPath-expressie te vinden.

Voorbeeld:

xyz

Device.extension.where(url='https://koppeltaal.nl/resource-origin').value

We plaatsen het gedeelte 'Device' in de basis en de rest in de expressie. Aangezien de waarde in de extensie van het type 'string' is, hebben we een zoekparameter van het type 'string' nodig om erop te zoeken. En we moeten een canonieke URL en een string kiezen om deze parameter te identificeren.

Merk op dat we de zoekparameter naar het beheer endpoint van FHIR (Resource) Provider moeten sturen. De resources op het beheer endpoint bepalen hoe de FHIR (Resource) Provider zich gedraagt. Als je het naar het reguliere data-eindpoint zou sturen, zou het lukken, maar je zou de zoekparameter niet kunnen gebruiken om in de FHIR (Resource) Provider te zoeken.

SearchParameter

PUT .../SearchParameter/Resource-Origin
{ 
	"resourceType":"SearchParameter", 
	"id": "Resource-Origin", 
	"url": "http://hl7.org/fhir/SearchParameter/resource-origin-extension", 
	"name": "Search Parameter for extension resource-origin", 
	"status": "active", 
	"experimental": false, 
	"publisher": "Koppeltaal 2.0",
	"code": "resource-origin", 
    "base": [" ", "ActivityDefinition", "Device", " "], // Opsomming van alle FHIR resources
	"target": [ "Device" ], 
	"type": "reference", 
	"description": "Value of the resource-origin", 
    "expression": "..| ActivityDefinition.extension('https://koppeltaal.nl/resource-origin') | Device.extension('https://koppeltaal.nl/resource-origin') | ..",
	"xpath": "normal"
}

Volgende search parameters (SearchParameter) hebben we nu bij Koppeltaal toegevoegd:

Search Parameter Tabel Koppeltaal 2.0

Resource (base)	Search Parameter	XPath	code	type	target	chain
Task	instantiatesCanonical	f:Task/f:instantiatesCanonical	instantiates-canonical	reference	ActivityDefinition	publisher-identifier
ActivityDefinition	extension('https://koppeltaal.nl/publisher-identifier')	f:ActivityDefinition/f:extension[@url='https://koppeltaal.nl/publisher-identifier']	publisher-identifier	token	ActivityDefinition
ActivityDefinition, CareTeam, Device, Organization, Patient, Practitioner, RelatedPerson, Task, AuditEvent, Endpoint, Subscription, OperationOutcome, Bundle	extension('https://koppeltaal.nl/resource-origin')	-	resource-origin	reference	Device

Koppeltaal stelselarchitectuur

TOP-KT-015 - Search parameters - [vervallen, samengevoegd met TOP-KT-002]

Beschrijving

Limiting

Paging

Sorteren

Narrowing (verborgen autorisatie interceptor)

Het definiëren en vastleggen van (extended) SearchParameters

Search Parameter Tabel Koppeltaal 2.0

Rationale

Implicaties

Voorbeelden

Toepassingsgebied

Onderbouwen

Eisen

Referenties