Stream: cds hooks
Topic: Search param names in prefetch
Lloyd McKenzie (Aug 13 2018 at 01:52):
Prefetch templates define queries that a particular service would like to be performed with the results passed as part of the service specification. However, there are a few things that aren't currently addressed in the CDS Hooks specification:
- The search parameter names aren't nailed down by FHIR. Preferred ones are defined, but servers are allowed to define alternate names - and in the case of collisions, will have to define alternate names. The true meaning of a given search parameter is determined by looking up the search name in the CapabilityStatement for that server and finding what SearchParameter canonical URL it's tied to. This is a particular issue when the searches may need to use SearchParameters that aren't defined in the core specification. What is the intention for how this will work?
- The standard behavior in FHIR when performing queries is to query with what parameters they support and echo what parameters they actually paid attention to in the 'self' link - and the client system then deals with the discrepancy by filtering or issuing narrower queries. However, in the hook invocation, there's no mechanism to include the 'self' link. Is the presumption therefore that if a system doesn't support the fully query exactly as specified, it won't execute that prefetch query? If not, how is the server to know that what it has isn't exectly what it asked for (and that it might have more data or less data than hoped for)?
- Some queries might result in more data than is reasonable to include in the hook call. Is the expectation that if the result set is too large, that that particular prefetch result will be excluded?
Isaac Vetter (Aug 13 2018 at 16:00):
Some queries might result in more data than is reasonable to include in the hook call. Is the expectation that if the result set is too large, that that particular prefetch result will be excluded?
Yes. I'm pretty sure that we even talked about this (somewhere on github) as one of the scenario's for why it's reasonable for an EHR to not satisfy a pre-fetch request.
Lloyd McKenzie (Aug 13 2018 at 16:13):
Should the specification make that explicit that systems SHALL NOT return pre-fetch if they don't support the fully query as requested?
Isaac Vetter (Aug 13 2018 at 17:10):
Should the specification make that explicit that systems SHALL NOT return pre-fetch if they don't support the fully query as requested?
Lloyd, are you still talking about a search response's size? If so, we do have this in the spec now:
The resulting response, which MUST BE rendered in a single page — no "next page" links allowed — is passed along to the CDS Service using the prefetch parameter (see below for a complete example).
and
the prefetched data given to the CDS Service MUST BE equivalent to the data the CDS Service would receive if it were making its own call to the EHR FHIR server
There's also language around how to handle error'd searches.
Isaac Vetter (Aug 13 2018 at 17:13):
The Prefetch query restrictions is the section of the spec that is related. (It's been a while since I read this section of the spec).
The primary goal here is for the CDS service to use search paramters that are supported by the EHR's FHIR server. In practice and for the short-term, this means using US Core's CCDS profiled search terms. Optimally, the search parameters used/useable in CDS Hooks wouldn't be defined in the CDS Hooks specification, but rather would fall back to FHIR while also remaining true to production FHIR servers.
Lloyd McKenzie (Aug 13 2018 at 19:30):
It's not normally an error if someone says "please filter on x" and you don't support that filter - typically you just return the search results without the filter applied and declare that's what you've done. If we need that to be treated as an error from a prefetch perspective, we should make that explicit.
Lloyd McKenzie (Aug 13 2018 at 19:32):
Where's the language on limiting max number of rows? (Beyond supporting the _count parameter)
Bryn Rhodes (Aug 13 2018 at 20:12):
I would think that the case when the server returned results without an expected filter applied should definitely be considered an error condition; if that's the expectation from the FHIR server side we should make a note about in the CDS Hooks prefetch discussion.
Bryn Rhodes (Aug 13 2018 at 20:12):
As far as limiting the max number of rows, we don't have language beyond just supporting the _count parameter. Should we?
Lloyd McKenzie (Aug 14 2018 at 02:23):
Also, any thoughts on dealing with non-standard search parameter names?
Isaac Vetter (Aug 14 2018 at 02:49):
this is a copout, but do we really need to?
Lloyd McKenzie (Aug 14 2018 at 02:51):
I've had to introduce 3 in DaVinci already.
Lloyd McKenzie (Aug 14 2018 at 02:51):
Now hopefully those will become part of the core spec for R4, but they won't for R3.
Lloyd McKenzie (Aug 14 2018 at 02:52):
(And one of them was the ability to search on Patient for SupplyRequest...)
Lloyd McKenzie (Aug 14 2018 at 02:52):
so not exactly esoteric.
Isaac Vetter (Aug 14 2018 at 02:55):
For R3, can we say that the service consults the FHIR server / implementing health system as part of implementation to determine supported search params?
Lloyd McKenzie (Aug 14 2018 at 02:57):
We can do that for regular queries, but not for prefetch.
Lloyd McKenzie (Aug 14 2018 at 02:57):
In that case, the client would need to consult the server - and the server might not have a FHIR endpoint
Isaac Vetter (Aug 14 2018 at 03:00):
Lloyd McKenzie: We can do that for regular queries, but not for prefetch.
hence, the words "implementing" and "implementation" :octopus:
Lloyd McKenzie (Aug 14 2018 at 03:01):
My expectation was that a service gets defined and then exposes itself to a wide variety of clients running a variety of software. And I wasn't necessarily expecting what those servers supported to be homogeneous or static.
Lloyd McKenzie (Aug 14 2018 at 03:02):
Are services expected to be tuned to a single client or small set of clients?
Isaac Vetter (Aug 14 2018 at 03:06):
No. Services should be tuned to widely and commonly implemented API features ...
In the absence of widely implemented APIs, stuff gets harder and either services or clients do need to be tuned. A single client should be configured to meet the query needs of the service.
Lloyd McKenzie (Aug 14 2018 at 03:09):
Right. But is that tuning expected to be handled out-of-band? My preference is that the discovery mechanism would expose enough information that a client could determine what it needs to do without human-to-human interaction. Is that unrealistic/not part of intended scope?
Isaac Vetter (Aug 14 2018 at 03:10):
I understand and empathize. There isn't a configuration mechanism available.
Lloyd McKenzie (Aug 14 2018 at 03:15):
We could make the prefetch declaration unambiguous by providing a list of search-term - SearchParameter canonical URL pairs.
Isaac Vetter (Aug 14 2018 at 04:49):
Hey Lloyd, what you're suggesting is, I think, well outside of the 80+% case. The more reasonable alternative would be for the client to specify it's FHIR server when calling the discovery endpoint -- thereby enabling the CDS service to adjust it's prefetch queries to the FHIR server's capabilities. An HTTP GET _iss_ parameter would be reasonable. If the client authenticated (using the same jwt mechanism currently specified for the request), the CDS service would be able to keep track of which client had which capabilities.
This is pretty advanced stuff, but the above would solve a generic problem.
Bryn Rhodes (Aug 14 2018 at 04:52):
We could make the prefetch declaration unambiguous by providing a list of search-term - SearchParameter canonical URL pairs.
Another option would be DataRequirements in a CapabilityStatement. (would need to be an extension at this point, but we already defined an extension to support a CDS Hooks service endpoint declaration).
Isaac Vetter (Aug 14 2018 at 04:57):
Hey Bryn, DataRequirements would interoperably define what the service expects, but not what the client's FHIR server supports -- which is the specific problem Lloyd is trying to solve (I think).
Bryn Rhodes (Aug 14 2018 at 04:59):
Oh I see, yes.
Lloyd McKenzie (Aug 14 2018 at 14:07):
Listing what each search parameter means is in the 80% for CapabilityStatement and allows the statements to be passive. The expectation is that whenever clients do a query, they always check the CapabilityStatement before evaluating a query because that's the only way to know what the search parameters mean. Exposing the linkage in CDSService.prefetch would be consistent with that.
Active, client-centric declarations of capability would be pretty cool, but seem super-advanced and push a lot of complexity into the server. Some FHIR servers support that to show user permissions, but it's not common.
Last updated: Apr 12 2022 at 19:14 UTC
