Expand

title	Versiegeschiedenis...

Versie	Datum	Status	Wijzigingen
1.04	09 Oct 2024	concept	De search parameter Activity Definition participant is toegevoegd.
1.0.3	06 Nov 2023	definitief	Aanpassing i.v.m. Task.instantiates
1.0.2	11 Jul 2023	definitief	Deadlinks opgelost
1.0.1	05 Jul 2023	definitief	Bij samen voegen van eisen was een fout gemaakt. Deze is hersteld.
1.0.0	29 Mar 2023	definitief

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 gebruik 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
`_id`	`_sort`	`_include`	`_offset`
`_lastUpdated`	`_count`	`_revinclude`
`_tag`	`_summary`	`_contained`
`_profile`	`_total`	`_containedType`
`_security`	`_elements`
`_text`
`_content`
`_list`
`_has`
`_type`

Info
Let op: Een aantal van de bovenstaande search result parameters worden NIET ondersteund. Dit vanwege extra complexiteit i.c.m. het autorisatiemodel.

Paging

...

. 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 RFC 5005 - Feed Paging and Archiving (rfc5005) voor 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. 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):

Code Block

language	js

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

...

Custom `_offset` search result parameter.

...

de

...

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] 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.De volgende SearchParameters MOETEN door Koppeltaal worden toegevoegd. 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

instantiatesCanonicalinstantiates instantiates
-canonical reference ActivityDefinition
publisher-identifierpublisherId
2 ActivityDefinition extension('http://koppeltaal.nl/fhir/StructureDefinition/
KT2PublisherIdentifierKT2PublisherId')
publisher-identifierpublisherId token ActivityDefinition 
3 ActivityDefinition Koppeltaal v2.0 | KT2_SearchParticipant - SIMPLIFIER.NET participant reference RelatedPerson|Patient|Practitioner 
4 ActivityDefinition, CareTeam, Device, Organization, Patient, Practitioner, RelatedPerson, Task, AuditEvent, Endpoint, Subscription
, OperationOutcome, Bundle extension('
httpshttp://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

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 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}

SearchParameter #2

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

SearchParameter #3

Deze SearchParameter maakt het mogelijk Activity Definitions te kunnen zoeken voor een Participant-Type.

https://koppeltaal.nl/ActivityDefinition?participant=RelatedPerson

SearchParameter #4

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.

`Eisen`

...

Voorbeeld:

https://koppeltaal.nl/Patient?resource-origin=Device/4507fa63-7cfd-4d1e-8389-7598b8e24de0

SearchParameter #5

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

SearchParameter #6

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

SearchParameter #7

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	https://www.hl7.org/fhir/r4/search.html
FHIR paginatie	https://www.hl7.org/fhir/r4/http.html#paging
FHIR `SearchParameter`	https://www.hl7.org/fhir/r4/searchparameter.html

{}

Versions Compared

Old Version 4

New Version Current

Key

Beschrijving

Overwegingen

FHIR API

Paginering

Toepassing en restricties

Ondersteunde search parameters overzicht

Paging

.Paginering

_summary

Veelgebruikte functionaliteit uit de standaard

Sorteren

Limiting

Functionaliteit toegevoegd op

Custom `_offset` search result parameter.

de

standaard

`Search Narrowing`

`Custom SearchParameters`

`Eisen`

`Links naar gerelateerde onderwerpen`

publisherId
2	ActivityDefinition	extension('http://koppeltaal.nl/fhir/StructureDefinition/

publisherId	token	ActivityDefinition
3	ActivityDefinition	Koppeltaal v2.0 \| KT2_SearchParticipant - SIMPLIFIER.NET	participant	reference	RelatedPerson\|Patient\|Practitioner
4	ActivityDefinition, CareTeam, Device, Organization, Patient, Practitioner, RelatedPerson, Task, AuditEvent, Endpoint, Subscription

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

Page Comparison

Versions Compared

Old Version 4

New Version Current

Key

Beschrijving

Overwegingen

FHIR API

Paginering

Toepassing en restricties

Ondersteunde search parameters overzicht

Paging

.Paginering

_summary

Veelgebruikte functionaliteit uit de standaard

Sorteren

Limiting

Functionaliteit toegevoegd op

Custom _offset search result parameter.

de

standaard

Search Narrowing

Custom SearchParameters

Eisen

Links naar gerelateerde onderwerpen

Custom `_offset` search result parameter.

`Search Narrowing`

`Custom SearchParameters`

`Eisen`

`Links naar gerelateerde onderwerpen`