#232: Move "user" from the request to each individual hook (#425)

* #232: Removed "user" from the request and added it to each of the defined hooks as "userId". Updated relevant examples, yaml, and removed the "user" prefetch token defined by the spec.

* Incorporated changes from #220 

Fixes #232
Fixes #307

Author: brynrhodes

docs/hooks/medication-prescribe.md

@@ -15,6 +15,7 @@ The set of medications proposed or in progress of being prescribed. All FHIR res
 
 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
+`userId` | REQUIRED | Yes | *string* | The id of the current user.<br />For this hook, the user is expected to be of type [Practitioner](https://www.hl7.org/fhir/practitioner.html).<br />For example, `Practitioner/123`
 `patientId` | REQUIRED | Yes | *string* |  The FHIR `Patient.id` of the current patient in context
 `encounterId` | OPTIONAL | Yes | *string* |  The FHIR `Encounter.id` of the current encounter in context
 `medications` | REQUIRED | No | *object* | DSTU2 - FHIR Bundle of _draft_ MedicationOrder resources <br/> STU3 - FHIR Bundle of _draft_ MedicationRequest resources
@@ -24,6 +25,7 @@ Field | Optionality | Prefetch Token | Type | Description
 ```json
 {
   "context":{
+    "userId":"Practitioner/123",
     "patientId":"1288992",
     "encounterId":"89284",
     "medications":{
@@ -168,6 +170,7 @@ Field | Optionality | Prefetch Token | Type | Description
 ```json 
 {
   "context":{
+    "userId":"Practitioner/123",
     "patientId":"1288992",
     "encounterId":"89284",
     "medications":{

docs/hooks/order-review.md

@@ -15,6 +15,7 @@ The set of orders being reviewed for signature on-screen. All FHIR resources in
 
 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
+`userId` | REQUIRED | Yes | *string* | The id of the current user.<br />For this hook, the user is expected to be of type [Practitioner](https://www.hl7.org/fhir/practitioner.html).<br />For example, `Practitioner/123`
 `patientId` | REQUIRED | Yes | *string* | The FHIR `Patient.id` of the current patient in context
 `encounterId` | OPTIONAL | Yes | *string* | The FHIR `Encounter.id` of the current encounter in context
 `orders` | REQUIRED | No | *object* | DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with _draft_ status <br/> STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with _draft_ status
@@ -24,6 +25,7 @@ Field | Optionality | Prefetch Token | Type | Description
 ```json
 {
    "context":{
+      "userId":"Practitioner/123",
       "patientId":"1288992",
       "encounterId":"89284",
       "orders":{
@@ -202,6 +204,7 @@ Field | Optionality | Prefetch Token | Type | Description
 
 ```json
 "context":{
+  "userId":"Practitioner/123",
   "patientId":"1288992",
   "encounterId":"89284",
   "orders":{

docs/hooks/patient-view.md

@@ -15,19 +15,22 @@ The patient whose record was opened, including their encounter, if applicable.
 
 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
+`userId` | REQUIRED | Yes | *string* | The id of the current user.<br />For example, if the user represents a FHIR resource on the given FHIR server, the resource type would be one of [Practitioner](https://www.hl7.org/fhir/practitioner.html), [Patient](https://www.hl7.org/fhir/patient.html), or [RelatedPerson](https://www.hl7.org/fhir/relatedperson.html).<br />If the user was a Practitioner, this value would be `Practitioner/123`
 `patientId` | REQUIRED | Yes | *string* | The FHIR `Patient.id` of the current patient in context
 `encounterId` | OPTIONAL | Yes | *string* | The FHIR `Encounter.id` of the current encounter in context
 
 ### Examples
 
 ```json
 "context":{
+  "userId" : "Practitioner/123",
   "patientId" : "1288992"
 }
 ```
 
 ```json
 "context":{
+  "userId" : "Practitioner/123",
   "patientId" : "1288992",
   "encounterId" : "456"
 }

docs/specification/1.0-api.yaml

@@ -106,18 +106,10 @@ definitions:
       fhirServer:
         type: string
         format: url
-      oauth:
+      fhirAuthorization:
         type: object
-      user:
-        type: string
-      patient:
-        type: string
-      encounter:
-        type: string
       context:
-        type: array
-        items:
-          type: object
+        type: object
       prefetch:
         type: object
 

docs/specification/1.0.md

@@ -111,7 +111,6 @@ Field | Optionality | Type | Description
 <nobr>`hookInstance`</nobr> | REQUIRED | *string* | A UUID for this particular hook call (see more information below).
 `fhirServer` | OPTIONAL | *URL* | The base URL EHR's [FHIR](https://www.hl7.org/fhir/) server. If fhirAuthorization is provided, this field is REQUIRED.  The scheme should be `https`
 `fhirAuthorization` | OPTIONAL | *object* | A structure holding an [OAuth 2.0][OAuth 2.0] bearer access token granting the CDS Service access to FHIR resources, along with supplemental information relating to the token. See the [FHIR Resource Access](#fhir-resource-access) section for more information.
-`user` | REQUIRED | *string* | The id of the current user.<br />For example, if the user represents a FHIR resource on the given FHIR server, the resource type would be one of [Practitioner](https://www.hl7.org/fhir/practitioner.html), [Patient](https://www.hl7.org/fhir/patient.html), or [RelatedPerson](https://www.hl7.org/fhir/relatedperson.html).<br />If the user was a Practitioner, this value would be `Practitioner/123`
 `context` | REQUIRED | *object* | Hook-specific contextual data that the CDS service will need.<br />For example, with the `patient-view` hook this will include the FHIR identifier of the [Patient](https://www.hl7.org/fhir/patient.html) being viewed.  For details, see the Hooks specification page.
 `prefetch` | OPTIONAL | *object* | The FHIR data that was prefetched by the EHR (see more information below).
 
@@ -143,8 +142,8 @@ curl
      "scope" : "patient/Patient.read patient/Observation.read",
      "subject" : "cds-service4"
    },
-   "user" : "Practitioner/example",
    "context" : {
+       "userId" : "Practitioner/example",
        "patientId" : "1288992",
        "encounterId" : "89284"
    },
@@ -178,12 +177,6 @@ relevant data. In order to allow for prefetch templates that are dependent upon
 
 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|
----------|--------
-|`{{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:
@@ -224,7 +217,7 @@ The CDS Service MUST NOT receive any prefetch template key that the EHR chooses
   "prefetch": {
     "p": "Patient/{{context.patientId}}",
     "a1c": "Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date",
-    "u": "Practitioner/{{user}}"
+    "u": "Practitioner/{{context.userId}}"
   }
 }
 ```
@@ -588,7 +581,9 @@ For example, an extension on a request could look like this:
    "hookInstance" : "d1577c69-dfbe-44ad-ba6d-3e05e953b2ea",
    "fhirServer" : "http://fhir.example.org:9080",
    "hook" : "patient-view",
-   "user" : "Practitioner/example",
+   "context" : {
+       "userId" : "Practitioner/example"
+   },
    "extension" : {
       "com.example.timestamp": "2017-11-27T22:13:25Z",
       "myextension-practitionerspecialty" : "gastroenterology"