Fixes #238: Clarified how prefetch templates are processed

brynrhodes · brynrhodes · commit cad7f75fb0e3 · 2018-12-05T09:29:30.000-07:00
Fixes #239: Clarified prefetch data conformance language Fixes #242: Added definition for prefetch key Fixes #244: Updated conformance language usage in prefetch restrictions Fixes #246: Clarified prefetch limitations are on prefetch templates Fixes #257: Added clarification on responses and notes about multiple services from the same hook Fixes #262: Added examples for each action type Fixes #264: Clarified documentation for actions Fixes #274: Clarified hook context table is an example Fixes #281: Clarified prefetch response resources may be a searchset bundle Fixes #282: Provided rationale for the use of null in the prefetch response Fixes #287: Clarified allowable data types for context fields Fixes #289: Changed prefetch token status change to Major Fixes #298: Added examples to hook/prefetch discussion Fixes #300: Added an overview section discussing CDS Hooks components Fixes #313: Clarified definitions of prefetch template, prefetch token, and prefetch key Fixes #314: Clarified prefetch behavior for multiple services attached to the same hook Fixes #316: Added rationale for not allowing next page links in prefetch data Fixes #344: Clarified distinction between context and prefetch Fixes #343: Updated prefetch example to use full key names Fixes #349: Corrected capitalization of conformance language in prefetch description
diff --git a/docs/specification/1.0.md b/docs/specification/1.0.md
@@ -199,11 +199,7 @@ A _prefetch template_ is a `read` or `search` request that describes relevant da
 Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date
 ```
 
-To allow for prefetch templates that are dependent on the workflow context, prefetch templates may include references to context using _prefetch tokens_. In the above example, `{{context.patientId}}` is a prefetch token. A prefetch token is a placeholder in a prefetch template that is replaced by a value from the hook's context to construct the FHIR URL used to request the prefetch data. 
-
-Prefetch tokens MUST be delimited by `{{` and `}}`, and MUST contain only the qualified path to a hook context field.
-
-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.
+To allow for prefetch templates that are dependent on the workflow context, prefetch templates may include references to context using [_prefetch tokens_](#prefetch-tokens). In the above example, `{{context.patientId}}` is a prefetch token.
 
 The `prefetch` field of a CDS Service description defines the set of prefetch templates for that service, providing a _prefetch key_ for each one that is used to identify the prefetch data in the CDS request. For example:
 
@@ -239,65 +235,27 @@ The EHR MUST NOT send any prefetch template key that it chooses not to satisfy.
 
 It is the CDS Service's responsibility to check prefetched data against its template to determine what requests were satisfied (if any) and to manually retrieve any additional necessary data. If the CDS Service is unable to obtain required data because it cannot access the FHIR server and the request did not contain the necessary prefetch keys, the service SHALL respond with an HTTP 412 Precondition Failed status code.
 
-#### Example prefetch templates
+#### Prefetch tokens
 
-```json
-{
-  "prefetch": {
-    "patient": "Patient/{{context.patientId}}",
-    "hemoglobin-a1c": "Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date",
-    "user": "Practitioner/{{context.userId}}"
-  }
-}
-```
+A prefetch token is a placeholder in a prefetch template that is replaced by a value from the hook's context to construct the FHIR URL used to request the prefetch data. 
 
-Here is an example prefetch field from a CDS Service discovery endpoint. The
-goal is to know, at call time:
-
-| Key | Description |
-| --- | ----------- |
-| `patient` | Patient demographics. |
-| `hemoglobin-a1c` | Most recent Hemoglobin A1c reading for this patient. |
-| `user` | Information on the current user (Practitioner).
+Prefetch tokens MUST be delimited by `{{` and `}}`, and MUST contain only the qualified path to a hook context field.
 
-#### Example prefetch data
+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.
 
-```json
-{
-  "prefetch": {
-    "patient":{
-      "resourceType": "Patient",
-      "gender": "male",
-      "birthDate": "1974-12-25",
-      "...": "<snipped for brevity>"
-    },
-    "hemoglobin-a1c": {
-      "resourceType": "Bundle",
-      "type": "searchset",
-      "entry": [{
-        "resource": {
-        "resourceType": "Observation",
-        "code": {
-          "coding": [{
-            "system": "http://loinc.org",
-            "code": "4548-4",
-            "display": "Hemoglobin A1c"
-            }]
-          },
-          "...": "<snipped for brevity>"
-        }
-      }]
-    }
-  }
-}
-```
+#### Prefetch query restrictions
 
-The CDS Hooks request is augmented to include two prefetch values, where the dictionary
-keys match the request keys (`patient` and `hemoglobin-a1c` in this case).
+To reduce the implementation burden on EHRs that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. Valid prefetch templates SHOULD only make use of:
 
-Note that the missing `user` key indicates that either the EHR has decided not to satisfy this particular prefetch template or it was not able to retrieve this prefetched data. The CDS Service is responsible for retrieving this Practitioner data from the FHIR server (if required).
+* _instance_ level [read](https://www.hl7.org/fhir/http.html#read) interactions (for resources with known ids such as `Patient` and `Practitioner`)
+* _type_ level [search](https://www.hl7.org/fhir/http.html#search) interactions
+* Patient references (e.g. `patient={{context.patientId}}`)
+* _token_ search parameters using equality (e.g. `code=4548-4`) and optionally the `:in` modifier (no other modifiers for token parameters)
+* _date_ search parameters on `date`, `dateTime`, `instant`, or `Period` types only, and using only the prefixes `eq`, `lt`, `gt`, `ge`, `le`
+* the `_count` parameter to limit the number of results returned
+* the `_sort` parameter to allow for _most recent_ and _first_ queries
 
-#### Prefetch tokens
+#### Example prefetch token
 
 Often a prefetch template builds on the contextual data associated with the hook. For example, a particular CDS Service might recommend guidance based on a patient's conditions when the chart is opened. The FHIR query to retrieve these conditions might be `Condition?patient=123`. In order to express this as a prefetch template, the CDS Service must express the FHIR identifier of the patient as a token so that the EHR can replace the token with the appropriate value. When context fields are used as tokens, their token name MUST be `context.name-of-the-field`. For example, given a context like:
 
@@ -360,17 +318,63 @@ Only the `encounterId` field in this example is eligible to be a prefetch token
 }
 ```
 
-#### Prefetch query restrictions
+#### Example prefetch templates
 
-To reduce the implementation burden on EHRs that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. Valid prefetch templates SHOULD only make use of:
+```json
+{
+  "prefetch": {
+    "patient": "Patient/{{context.patientId}}",
+    "hemoglobin-a1c": "Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date",
+    "user": "Practitioner/{{context.userId}}"
+  }
+}
+```
 
-* _instance_ level [read](https://www.hl7.org/fhir/http.html#read) interactions (for resources with known ids such as `Patient` and `Practitioner`)
-* _type_ level [search](https://www.hl7.org/fhir/http.html#search) interactions
-* Patient references (e.g. `patient={{context.patientId}}`)
-* _token_ search parameters using equality (e.g. `code=4548-4`) and optionally the `:in` modifier (no other modifiers for token parameters)
-* _date_ search parameters on `date`, `dateTime`, `instant`, or `Period` types only, and using only the prefixes `eq`, `lt`, `gt`, `ge`, `le`
-* the `_count` parameter to limit the number of results returned
-* the `_sort` parameter to allow for _most recent_ and _first_ queries
+Here is an example prefetch field from a CDS Service discovery endpoint. The
+goal is to know, at call time:
+
+| Key | Description |
+| --- | ----------- |
+| `patient` | Patient demographics. |
+| `hemoglobin-a1c` | Most recent Hemoglobin A1c reading for this patient. |
+| `user` | Information on the current user (Practitioner).
+
+#### Example prefetch data
+
+```json
+{
+  "prefetch": {
+    "patient":{
+      "resourceType": "Patient",
+      "gender": "male",
+      "birthDate": "1974-12-25",
+      "...": "<snipped for brevity>"
+    },
+    "hemoglobin-a1c": {
+      "resourceType": "Bundle",
+      "type": "searchset",
+      "entry": [{
+        "resource": {
+        "resourceType": "Observation",
+        "code": {
+          "coding": [{
+            "system": "http://loinc.org",
+            "code": "4548-4",
+            "display": "Hemoglobin A1c"
+            }]
+          },
+          "...": "<snipped for brevity>"
+        }
+      }]
+    }
+  }
+}
+```
+
+The CDS Hooks request is augmented to include two prefetch values, where the dictionary
+keys match the request keys (`patient` and `hemoglobin-a1c` in this case).
+
+Note that the missing `user` key indicates that either the EHR has decided not to satisfy this particular prefetch template or it was not able to retrieve this prefetched data. The CDS Service is responsible for retrieving this Practitioner data from the FHIR server (if required).
 
 ### FHIR Resource Access
 
