#298: Added examples to hook/prefetch discussion.

Author: brynrhodes

docs/specification/1.0.md

@@ -653,7 +653,24 @@ Note that each hook (e.g. `medication-prescribe`) represents something the user
 
 Any user workflow or action within an EHR will naturally include contextual information such as the current user and patient. CDS Hooks refers to this information as _context_ and allows each hook to define the information that is available in the context. Because CDS Hooks is intended to support usage within any EHR, this context can contain both required and optional data, depending on the capabilities of individual EHRs. However, the context information is intended to be relevant to most CDS Services subscribing to the hook.
 
-Prefetch data, on the other hand, is defined by CDS Services as a way to allow the EHR to provide the data that a CDS Service needs as part of the initial request to the service. When the context data relates to a FHIR resource, it is important not to conflate context and prefetch. For instance, imagine a hook for opening a patient's chart. This hook should include the id of the patient whose chart is being opened, not the full patient FHIR resource. In this case, the FHIR identifier of the patient is appropriate as CDS Services may not be interested in details about the patient resource but instead other data related to this patient. Or, a CDS Service may only need the full patient resource in certain scenarios. Therefore, including the full patient resource in context would be unnecessary. For CDS Services that want the full patient resource, they can request it to be prefetched or fetch it as needed from the FHIR server.
+For example, consider a simple `patient-view` hook that is invoked whenever the user views a patient's information within the EHR. At this point in the workflow, the contextual information would include at least the current user and the patient that is being viewed. The hook declares this as `context`, and passes it to the CDS Service as part of the request in the `context` field:
+
+```json
+"context":{
+  "userId" : "Practitioner/123",
+  "patientId" : "1288992"
+}
+```
+
+Prefetch data, on the other hand, is defined by CDS Services as a way to allow the EHR to provide the data that a CDS Service needs as part of the initial request to the service. When the context data relates to a FHIR resource, it is important not to conflate context and prefetch. For instance, in the hook described above for opening a patient's chart, the hook includes the id of the patient whose chart is being opened, not the full patient FHIR resource. In this case, the FHIR identifier of the patient is appropriate as CDS Services may not be interested in details about the patient resource but instead other data related to this patient. Or, a CDS Service may only need the full patient resource in certain scenarios. Therefore, including the full patient resource in context would be unnecessary. For CDS Services that want the full patient resource, they can request it to be prefetched or fetch it as needed from the FHIR server using a prefetch template in their discovery response, such as:
+
+```json
+"prefetch": {
+  "patientToGreet": "Patient/{{context.patientId}}"
+}
+```
+
+See the section on [prefetch tokens](#prefetch-tokens) below for more information on how contextual information can be used to parameterize prefetch templates.
 
 Consider another hook for when a new patient is being registered. In this case, it would likely be appropriate for the context to contain the full FHIR resource for the patient being registered as the patient may not be yet recorded in the EHR (and thus not available from the FHIR server) and CDS Services using this hook would predominantly be interested in the details of the patient being registered.