Merge branch 'master' into add-desc-for-orders-element-clarify-what-f…

…hir-resources

docs/hooks/appointment-book.md

@@ -10,7 +10,7 @@
 | ---- | ----
 | specificationVersion | 1.0
 | hookVersion | 1.0
-| hookMaturity | [3 - Considered](../../specification/current/#hook-maturity-model)
+| hookMaturity | [1 - Submitted](../../specification/current/#hook-maturity-model)
 
 ## Workflow
 

docs/hooks/encounter-discharge.md

@@ -4,7 +4,7 @@
 | ---- | ----
 | specificationVersion | 1.0
 | hookVersion | 1.0
-| hookMaturity | [3 - Considered](../../specification/current/#hook-maturity-model)
+| hookMaturity | [1 - Submitted](../../specification/current/#hook-maturity-model)
 
 ## Workflow
 

docs/hooks/order-dispatch.md

@@ -3,12 +3,12 @@
 | Metadata | Value
 | ---- | ----
 | specificationVersion | 2.0
-| hookVersion | 1.0
+| hookVersion | 1.1
 | hookMaturity | [0 - Draft](../../specification/current/#hook-maturity-model)
 
 ## Workflow
 
-The `order-dispatch` hook fires when a practitioner is selecting a candidate performer for a pre-existing order that was not tied to a specific performer.  For example, selecting an imaging center to satisfy a radiology order, selecting a cardiologist to satisfy a referral, etc.  This hook only occurs in situations where the order is agnostic as to who the performer should be and a separate process (which might be performed by back-office staff, a central dispatch service, or even the ordering clincian themselves at a later time) is used to select and seek action by a specific performer.  It is possible that the same order might be dispatched multiple times, either because initial selected targets refuse or are otherwise unable to satisfy the order, or because the performer is only asked to perform a 'portion' of what's authorized (the first monthly lab test of a year-long set, the first dispense of a 6 month order, etc.)
+The `order-dispatch` hook fires when a practitioner is selecting a candidate performer for a pre-existing order or (set of orders) that was not assigned to a specific performer.  For example, selecting an imaging center to satisfy a radiology order, selecting a cardiologist to satisfy a referral, etc.  This hook only occurs in situations where the order is agnostic as to who the performer should be and a separate process (which might be performed by back-office staff, a central dispatch service, or even the ordering clincian themselves at a later time) is used to select and seek action by a specific performer.  It is possible that the same order might be dispatched multiple times, either because initial selected targets refuse or are otherwise unable to satisfy the order, or because the performer is only asked to perform a 'portion' of what's authorized (the first monthly lab test of a year-long set, the first dispense of a 6 month order, etc.).  Note that the order isn't updated to include the performer in this situation, as the authorization of who could theoretically perform the order isn't changed by seeking fulfillment by a specific provider.
 
 This "request for fulfillment" process is typically represented in FHIR using [Task](http://hl7.org/fhir/task.html).  This resource allows identifying the order to be acted upon, who is being asked to act on it, the time-period in which they're expected to act, and any limitations/qualifications to 'how much' of the order should be acted on.
 
@@ -19,26 +19,26 @@ Decision support that may be relevant for this hook might include information re
 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
 `patientId` | REQUIRED | Yes | *string* |  The FHIR `Patient.id` of the current patient in context
-`order` | REQUIRED | Yes | *string* |  The FHIR local reference for the Request resource for which fulfillment is sought  E.g. `ServiceRequest/123`
+`dispatchedOrders` | REQUIRED | Yes | *array* |  Collection of the FHIR local references for the Request resource(s) for which fulfillment is sought  E.g. `ServiceRequest/123`
 `performer` | REQUIRED | Yes | *string* |  The FHIR local reference for the Practitioner, PractitionerRole, Organization, CareTeam, etc. who is being asked to execute the order.  E.g. `Practitioner/456`
-`task` | OPTIONAL | No | *object* | DSTU2/STU3/R4 - Task instance that provides a full description of the fulfillment request - including the timing and any constraints on fulfillment
+`fulfillmentTasks` | OPTIONAL | No | *array* | DSTU2/STU3/R4/R5 - Collection of the Task instances (as objects) that provides a full description of the fulfillment request - including the timing and any constraints on fulfillment.  If Tasks are provided, each will be for a separate order and SHALL reference one of the dispatched-orders.
 
 ## Examples
 ### Example (R4)
 
 ```json
 "context":{
   "patientId" : "1288992",
-  "order" : "ServiceRequest/proc002",
+  "dispatched-orders" : ["ServiceRequest/proc002"],
   "performer" : "Organization/some-performer",
-  "task" : {
+  "fulfillment-tasks" : [{
     "resourceType" : "Task",
     "status" : "draft",
     "intent" : "order",
     "code" : {
       "coding" : [{
-        "system" : "",
-        "code" : ""
+        "system" : "http://hl7.org/fhir/CodeSystem/task-code",
+        "code" : "fulfill"
       }]
     },
     "focus" : {
@@ -55,7 +55,7 @@ Field | Optionality | Prefetch Token | Type | Description
     "owner" : {
       "reference" : "Organziation/some-performer"
     }
-  }
+  }]
 }
 ```
 
@@ -64,3 +64,4 @@ Field | Optionality | Prefetch Token | Type | Description
 Version | Description
 ---- | ----
 1.0 | Initial Release
+1.1 | Adjusted context names and cardinalities based on feedback

docs/hooks/order-select.md

@@ -8,14 +8,13 @@
 
 ## Workflow
 
-The `order-select` hook fires when a clinician selects one or more orders to place for a patient, (including orders for medications, procedures, labs and other orders). If supported by the CDS Client, this hook may also be invoked each time the clinician selects a detail regarding the order.
-This hook is among the first workflow events for an order entering a draft status. 
-The context of this hook may include defaulted order details 
-as it first occurs immediately upon the clinician selecting the order from the order catalogue of the CPOE, or upon her manual selection of order details (e.g. dose, quantity, route, etc). CDS services should expect some of the order information to not yet be specified. 
-Additionally, the context may include previously selected orders that are not yet signed from the same ordering session. 
-The `order-select` hook occurs after the clinician selects the order and before signing. 
+The order-select hook occurs after the clinician selects the order and before signing.
 
-This hook is intended to replace (deprecate) the `medication-prescribe` hook. 
+This hook occurs when a clinician initially selects one or more new orders from a list of potential orders for a specific patient (including orders for medications, procedures, labs and other orders). The newly selected order defines that medication, procedure, lab, etc, but may or may not define the additional details necessary to finalize the order.
+
+`order-select` is among the first workflow events for an order entering a draft status. The context of this hook may include defaulted order details upon the clinician selecting the order from the order catalogue of the CPOE, or upon her manual selection of order details (e.g. dose, quantity, route, etc). CDS services should expect some of the order information to not yet be specified. Additionally, the context may include previously selected orders that are not yet signed from the same ordering session. 
+
+This hook is intended to replace (deprecate) the medication-prescribe hook.
 
 ![CDS Hooks Overview](../../images/orderingflow.png)
 

docs/hooks/order-sign.md

@@ -12,7 +12,7 @@ The `order-sign` hook fires when a clinician is ready to sign one or more orders
 This hook is among the last workflow events before an order is promoted out of a draft status. 
 The context contains all order details, such as dose, quantity, route, etc, 
 although the order has not yet been signed and therefore still exists in a draft status. 
-Use this hook when your service requires all order details, and the clinician will accept recommended changes.
+Use this hook when your service requires all order details.
 
 This hook can also be used when an order or set of orders is being 're-signed' after revision (e.g. change
 to status, extending dates, or other changes allowed to signed orders within the system's workflow).  In this

mkdocs.yml

@@ -24,9 +24,9 @@ nav:
     - 'order-review 🚫' : 'hooks/order-review.md'
     - 'order-select 4' : 'hooks/order-select.md'
     - 'order-sign 5' : 'hooks/order-sign.md'
-    - 'appointment-book 3' : 'hooks/appointment-book.md'
+    - 'appointment-book 1' : 'hooks/appointment-book.md'
     - 'encounter-start 1' : 'hooks/encounter-start.md'
-    - 'encounter-discharge 3' : 'hooks/encounter-discharge.md'
+    - 'encounter-discharge 1' : 'hooks/encounter-discharge.md'
     - 'medication-refill 1' : 'hooks/medication-refill.md'
 - Quick Start: 'quickstart.md'
 - Cheat Sheet: 'cheat-sheet/Cheat Sheet - Sept 2019.pdf'