diff --git a/docs/specification/1.0.md b/docs/specification/1.0.md index d6a011b4..ea22752c 100644 --- a/docs/specification/1.0.md +++ b/docs/specification/1.0.md @@ -77,7 +77,7 @@ curl "https://example.com/cds-services" "description": "An example of a CDS Service that returns a static set of cards", "id": "static-patient-greeter", "prefetch": { - "patientToGreet": "Patient/{{Patient.id}}" + "patientToGreet": "Patient/{{context.patientId}}" } }, { @@ -86,8 +86,8 @@ curl "https://example.com/cds-services" "description": "An example of a CDS Service that simply echos the medication being prescribed", "id": "medication-echo", "prefetch": { - "patient": "Patient/{{Patient.id}}", - "medications": "MedicationOrder?patient={{Patient.id}}" + "patient": "Patient/{{context.patientId}}", + "medications": "MedicationOrder?patient={{context.patientId}}" } } ] @@ -173,12 +173,34 @@ Similarly, each EHR will decide what FHIR resources to authorize and to prefetch ### Prefetch Template The prefetch template is a dictionary of `read` and `search` requests to supply -relevant data, where the following variables are defined: +relevant data. In order to allow for prefetch templates that are dependent upon the particular CDS Service request, prefetch tokens or variables may be defined. -|variable|meaning| +Prefetch tokens MUST be delimited by `{{` and `}}`, MUST be named based upon the field they correspond to, and MUST have a primitive value. + +The CDS Hooks specification defines just one prefetch token: + +|Variable|Meaning| ---------|-------- -|`{{Patient.id}}`|The id of the patient in context for this activity (e.g. `123`)| -|`{{User.id}}`|The type and id of the user for this session (e.g. `Practitioner/123`)| +|`{{user}}`|The value of the `user` field from this CDS Service request (e.g. `Practitioner/123`)| + +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 instance, given a hook of `example-hook` with the following context in which the `patientId` and `medicationId` fields are both denoted as prefix tokens: + +```json +"context": { + "patientId": "123", + "medicationId": "456", + "medication": { + "id": "456", + "code": { + ... // FHIR CodeableConcept + } + } +} +``` + +The prefetch tokens defined by this `example-hook` would be `{{context.patientId}}` and `{{context.medicationId}}`. Note that the `context.medication.id` field is not eligible to be a prefetch token as it is not a root-level field of the `context` object. An EHR MAY choose to honor some or all of the desired prefetch templates, and is free to choose the most appropriate source for these data. For example: @@ -198,9 +220,9 @@ The CDS Service MUST NOT receive any prefetch template key that the EHR chooses ```json { "prefetch": { - "p": "Patient/{{Patient.id}}", - "a1c": "Observation?patient={{Patient.id}}&code=4548-4&_count=1&sort:desc=date", - "u": "Practitioner/{{User.id}}" + "p": "Patient/{{context.patientId}}", + "a1c": "Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date", + "u": "Practitioner/{{user}}" } } ``` @@ -257,7 +279,7 @@ To reduce the implementation burden on EHRs that support CDS Services, CDS Hooks * _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={{Patient}}`) +* 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 @@ -551,7 +573,7 @@ As another example, an extension defined on the discovery response could look li "hook": "patient-view", "id": "patientview", "prefetch": { - "patient": "Patient/{{Patient.id}}" + "patient": "Patient/{{context.patientId}}" }, "description": "clinical decision support for patient view", "extension": {