Added support for enhanced prefetch - and clarified prefetch expectat… #612

lmckenzi · 2022-02-07T00:10:59Z

…ions in general.

Specifically intended to address #377 and provide support for referencing information related to data in "in-memory" orders

…ions in general.

docs/specification/current.md

jmandel · 2022-05-11T19:57:49Z

docs/specification/current.md

@@ -240,45 +240,66 @@ A prefetch token is a placeholder in a prefetch template that is *_replaced by i

 Prefetch tokens MUST be delimited by `{{` and `}}`, and MUST contain only the qualified path to a hook context field *_or one of the following user identifiers: `userPractitionerId`, 'userPractitioneRoleId', `userPatientId`, or `userRelatedPersonId`_*.

-Individual hooks specify which of their `context` fields can be used as prefetch tokens. Only root-level fields with a primitive value within the `context` object are eligible to be used as prefetch tokens. For example, `{{context.medication.id}}` is not a valid prefetch token because it attempts to access the `id` field of the `medication` field.
+Individual hooks specify which of their `context` fields can be used as prefetch tokens. Prefetch templates must start with one of these context elements and can then navigate to information available within the context element using [simple FHIRPath](https://hl7.org/fhir/fhirpath.html#simple).  For example, 


Dangling "For example,"

jmandel · 2022-05-11T20:02:00Z

docs/specification/current.md

  }
 }
 ```
-or though a FHIR search:
+
+`{{context.patient}}` resolves to a simple id.  `{{context.user}}` resolves to a resource type and simple id separated by a '/'.  In both cases, the result of resolving the prefetch template is a single string that matches a relative URL to a single resource instance.  That relative URL could be appended to the CDS Client's server base URL to form the URL for a valid read.


Suggested change

`{{context.patient}}` resolves to a simple id. `{{context.user}}` resolves to a resource type and simple id separated by a '/'. In both cases, the result of resolving the prefetch template is a single string that matches a relative URL to a single resource instance. That relative URL could be appended to the CDS Client's server base URL to form the URL for a valid read.

`{{context.patient}}` resolves to a simple id (e.g., `123` for the Patient with id 123). `{{context.user}}` resolves to a resource type and simple id separated by a '/' (e.g., `Patient/123` or `Practitioner/456`). In both cases, the result of resolving the prefetch template is a single string that matches a relative URL to a single resource instance. That relative URL could be appended to the CDS Client's server base URL to form the URL for a valid read.

Adding examples would help, but I'm still not clear what the assumptions here. Is this paragraph defining a new context.patient variable in context, and a new context.user variable?

jmandel · 2022-05-11T20:12:25Z

docs/specification/current.md

+* If a collection element is a simple type, the value is returned and any extensions or 'id' elements are ignored.  If no value is specified for the element, the element is ignored
+* If a collection element is a Coding or Identifier, the element is converted to [token](http://hl7.org/fhir/search.html#token) syntax with code/value followed by '|' followed by system.
+5. Content expanded from a prefetch token may require HTTP escaping to ensure a valid URL fragment
+6. When dealing with prefetch tokens that resolve to relative references, in some cases, the search needs the resolved token to be an id or collection of ids rather than references. In this circumstance, the FHIRPath can be followed with ":" and the name of the resource whose references should be filtered.  Only relative references for the specified resource type are returned.  For example `{{context.draftOrders.ofType(MedicationRequest).requester.reference:Practitioner}}` would resolve to the a list of ids who are requesters that are also Practitioners.  For legacy reasons, this can also be done with the userId element by inserting the resource name into the context name.  E.g. `{{context.userPatientRoleId}}`, `{{context.userPractionerId}}`, `{{context.userPractitionerRoleId}}`, and `{{context.userRelatedPersonId}}`.


This "extra colon at the end" syntax makes it harder to see what is the "thing that needs to be parsed as FHIRPath". I'd rather see (in order of preference):

Define "simple FHIRpath + replaceMatches" so developers can build a list of IDs by taking final path segments

Define a distinct templating syntax {{expr}:Patient} or somesuch so the fhirpath is unambiguous

Let CDS Clients figure out how to filter based on context (i.e., "please do what I mean" -- if searching for )

Use existing fhirpath comment syntax like /*Patient*/ instead of tacking on :. Aim would be to leverage existing parsers. If you just split on : you hit complications in places where the gramamr (https://github.com/HL7/FHIRPath/blob/master/spec/fhirpath.g4) allows colons.

jmandel · 2022-05-11T20:13:45Z

docs/specification/current.md

+* If a collection element is a simple type, the value is returned and any extensions or 'id' elements are ignored.  If no value is specified for the element, the element is ignored
+* If a collection element is a Coding or Identifier, the element is converted to [token](http://hl7.org/fhir/search.html#token) syntax with code/value followed by '|' followed by system.
+5. Content expanded from a prefetch token may require HTTP escaping to ensure a valid URL fragment
+6. When dealing with prefetch tokens that resolve to relative references, in some cases, the search needs the resolved token to be an id or collection of ids rather than references. In this circumstance, the FHIRPath can be followed with ":" and the name of the resource whose references should be filtered.  Only relative references for the specified resource type are returned.  For example `{{context.draftOrders.ofType(MedicationRequest).requester.reference:Practitioner}}` would resolve to the a list of ids who are requesters that are also Practitioners.  For legacy reasons, this can also be done with the userId element by inserting the resource name into the context name.  E.g. `{{context.userPatientRoleId}}`, `{{context.userPractionerId}}`, `{{context.userPractitionerRoleId}}`, and `{{context.userRelatedPersonId}}`.


For legacy reasons, this can also be done

The "legacy" examples are about "context.user*" but the other equivalent examples are about "context.draftOrders...". I'm unclear on how to translate (say) context.userPatientRoleId in the new syntax.

jmandel · 2022-05-11T20:23:44Z

docs/specification/current.md


-#### Prefetch query restrictions
+###### Prefetch query restrictions

 To reduce the implementation burden on CDS Clients that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. When using this subset, valid prefetch templates MUST only make use of:


What is the name of this subset (so servers can say whether they are limited to it)?

jmandel · 2022-05-11T20:24:42Z

docs/specification/current.md


 To reduce the implementation burden on CDS Clients that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. When using this subset, valid prefetch templates MUST only make use of:

-* _instance_ level [read](https://www.hl7.org/fhir/http.html#read) interactions (for resources with known ids such as `Patient`, `Practitioner`, or `Encounter`)
 * _type_ level [search](https://www.hl7.org/fhir/http.html#search) interactions; e.g. `patient={{context.patientId}}`
 * Resource references (e.g. `patient={{context.patientId}}`)


This prohibits chaining, yes? It'd be good to annotate the examples above to say whether they are "compatible with the restricted subset".

hstrasbe · 2023-09-12T23:11:36Z

As we discussed at today's CDS WG meeting, we need to be able to support a request for something like all BP Observations from the last 10 days.

As currently proposed we could retrieve the last 10 BP Observations using:
"bloodPressures": "Observation?patient={{context.patient}}&code=85354-9|http%xx/loinc.org&_sort=-date&_count=10"

However, there does not seem to be a way to request all BP Observations from the last 10 days using a prefetch template.

lmckenzi · 2023-09-13T16:50:36Z

One option would be to use x-fhir-query, though that's a bigger lift than what's proposed here. We could possibly also subset x-fhir-query?

Added support for enhanced prefetch - and clarified prefetch expectat…

fd18dfe

…ions in general.

jmandel reviewed Feb 7, 2022

View reviewed changes

docs/specification/current.md Show resolved Hide resolved

lmckenzi and others added 2 commits April 20, 2022 12:06

Merge branch 'master' into enhanced-prefetch

d4ca9eb

Merge branch 'master' into enhanced-prefetch

33f92d2

jmandel reviewed May 11, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added support for enhanced prefetch - and clarified prefetch expectat… #612

Added support for enhanced prefetch - and clarified prefetch expectat… #612

lmckenzi commented Feb 7, 2022

jmandel May 11, 2022

jmandel May 11, 2022

jmandel May 11, 2022

jmandel May 11, 2022

jmandel May 11, 2022

jmandel May 11, 2022

hstrasbe commented Sep 12, 2023

lmckenzi commented Sep 13, 2023

Added support for enhanced prefetch - and clarified prefetch expectat… #612

Are you sure you want to change the base?

Added support for enhanced prefetch - and clarified prefetch expectat… #612

Conversation

lmckenzi commented Feb 7, 2022

jmandel May 11, 2022

Choose a reason for hiding this comment

jmandel May 11, 2022

Choose a reason for hiding this comment

jmandel May 11, 2022

Choose a reason for hiding this comment

jmandel May 11, 2022

Choose a reason for hiding this comment

jmandel May 11, 2022

Choose a reason for hiding this comment

jmandel May 11, 2022

Choose a reason for hiding this comment

hstrasbe commented Sep 12, 2023

lmckenzi commented Sep 13, 2023