Merge branch 'master' into link-to-hooks-correctly

Author: isaacvetter

docs/hooks/index.md

@@ -111,13 +111,7 @@ All fields defined by the hook's context MUST be defined in a table where each f
 - Type: The type of the field in the context JSON object, expressed as the JSON type, or the name of a FHIR Resource type. Valid types are *boolean*, *string*, *number*, *object*, *array*, or the name of a FHIR resource type. When a field can be of multiple types, type names MUST be separated by a *pipe* (`|`)
 - Description: A functional description of the context value. If this value can change according to the FHIR version in use, the description SHOULD describe the value for each supported FHIR version.
 
-### FHIR resources in context
-
-When potentially multiple FHIR resources value a single context field, these resources SHOULD be formatted as a FHIR Bundle. For example, multiple FHIR resources are necessary to describe all of the orders under review in the `order-review` hook's `orders` field. Hook definitions SHOULD prefer the use of FHIR Bundles over other bespoke data structures.
-
-Often, context is populated with in-progress or in-memory data that may not yet be available from the FHIR server. For example, `medication-prescribe` and `order-review` define context fields containing FHIR resources that represent draft resources. In this case,  the EHR should only provide these draft resources and not the full set of orders available from its FHIR server. The CDS service MAY pre-fetch or query for FHIR resources with other statuses.
-
-All FHIR resources in context MUST be based on the same FHIR version.
+The below illustrates a sample table. 
 
 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
@@ -127,6 +121,14 @@ Field | Optionality | Prefetch Token | Type | Description
 `moreObjects` | OPTIONAL | No | *array* | A clear description of the items in this array.
 `allFHIR` | OPTIONAL | No | *object* | A FHIR Bundle of the following FHIR resources using a specific version of FHIR.
 
+### FHIR resources in context
+
+When potentially multiple FHIR resources value a single context field, these resources SHOULD be formatted as a FHIR Bundle. For example, multiple FHIR resources are necessary to describe all of the orders under review in the `order-review` hook's `orders` field. Hook definitions SHOULD prefer the use of FHIR Bundles over other bespoke data structures.
+
+Often, context is populated with in-progress or in-memory data that may not yet be available from the FHIR server. For example, `medication-prescribe` and `order-review` define context fields containing FHIR resources that represent draft resources. In this case,  the EHR should only provide these draft resources and not the full set of orders available from its FHIR server. The CDS service MAY pre-fetch or query for FHIR resources with other statuses. 
+
+All FHIR resources in context MUST be based on the same FHIR version. 
+
 ### Examples
 
 Hook creators SHOULD include examples of the context.
@@ -167,15 +169,16 @@ To help ensure the stability of CDS Hooks implementations, once a hook has been
 
 In particular, the semantics of a hook (i.e. the meaning of the hook from the perspective of the EHR) cannot be changed. EHRs that implement specific hooks are responsible for ensuring the hook is called from the appropriate point in the workflow.
 
-Note that this means that the name of the hook carries major version semantics. That is not to say that the name must include the major version, that is left as a choice by users of the specification. Clean hook names increase usability. Ideally, an active hook name accurately defines the meaning and workflow of the hook in actual words.
+Note that this means that the name of the hook carries major version semantics. That is not to say that the name must include the major version, that is left as a choice to authors of the specification. For example, following version 1.x, the major version MAY be included in the name as "-2", "-3", etc. Eg: patient-view-2, patient-view-3, etc. Clean hook names increase usability. Ideally, an active hook name accurately defines the meaning and workflow of the hook in actual words.
 
 The following types of changes are possible for a hook definition:
 
 Change | Version Impact
 ------ | ----
 Clarifications and corrections to documentation that do not impact functionality | Patch
 Change of prefetch token status of an existing context field | Patch
-Addition of a new field to the context | Minor
+Addition of a new, REQUIRED field to the context | Major
+Addition of a new, OPTIONAL field to the context | Minor
 Change of optionality of an existing context field | Major
 Change of type or cardinality of an existing context field | Major
 Removal of an existing context field | Major

docs/hooks/medication-prescribe.md

@@ -11,13 +11,13 @@ The user is in the process of prescribing one or more new medications.
 
 ## Context
 
-The set of medications proposed or in progress of being prescribed. All FHIR resources in this context MUST be based on the same FHIR version.
+The set of medications proposed or in progress of being prescribed. All FHIR resources in this context MUST be based on the same FHIR version. All FHIR resources in the medications object MUST have a status of _draft_.
 
 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
 `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 MedicationOrder resources <br/> STU3 - FHIR Bundle of MedicationOrder
+`medications` | REQUIRED | No | *object* | DSTU2 - FHIR Bundle of _draft_ MedicationOrder resources <br/> STU3 - FHIR Bundle of _draft_ MedicationRequest resources
 
 ### Example (DSTU2)
 

docs/hooks/order-review.md

@@ -11,13 +11,13 @@ The user is in the process of reviewing a set of orders to sign.
 
 ## Context
 
-The set of orders being reviewed for signature on-screen. All FHIR resources in this _context_ MUST be based on the same FHIR version.
+The set of orders being reviewed for signature on-screen. All FHIR resources in this _context_ MUST be based on the same FHIR version. All FHIR resources in the medications object MUST have a status of _draft_.
 
 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
 `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 <br/> STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription
+`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
 
 ### Example (DSTU2)
 

docs/quickstart.md

@@ -6,13 +6,13 @@ A CDS Hooks scenario typically includes two main actors: an EHR and a CDS Servic
 ![patient-view Hook Overview](images/patient-view-hook-launch_spec.png)
 
 ## Building a CDS Service
-A CDS Service is an external service that responds to EHR requests through cards. There are several steps to setting up a CDS Service: 
+A CDS Service is an external service that responds to EHR requests through cards. A card can optionally link to a SMART app. There are several steps to setting up a CDS Service: 
 
 1. Create an endpoint for discovery
 2. Develop a service
 3. Test the service with the [sandbox](http://sandbox.cds-hooks.org/)
-4. Create a SMART app (or [borrow one](https://apps.smarthealthit.org/apps/pricing/open-source))
-5. Test the service and SMART app with an EHR
+4. If applicable, create a SMART app (or [borrow one](https://apps.smarthealthit.org/apps/pricing/open-source))
+5. Test the service (and, if applicable, SMART app) with an EHR
 
 This tutorial recommends implementing the CDS Hooks [security model](specification/1.0/#security-and-safety) after successful open access testing.
 
@@ -80,20 +80,20 @@ Delete the existing hooks, and then do a quick add with a reference to your CDS
 
 After testing with the sandbox, you are ready to connect with an EHR service.
 
-## Building an EHR Service
+## Integrating CDS Services into an EHR
 Build out following sections:
 
-1. Calls discovery endpoint 
+1. Call discovery endpoint 
 2. Invoke service on patient-view 
-3. Support for FHIR resources on request (context or pre-fetch)
-4. Exposed non-secured FHIR server
+3. Support FHIR resource on CDS requests (context or pre-fetch)
+4. Expose non-secured FHIR server for testing
 5. Render card
 6. Launch SMART app 
-7. Tested with external CDS Service
+7. Test with external CDS Service
 
 This tutorial recommends implementing the CDS Hooks [security model](specification/1.0/#security-and-safety) after successful open access testing.
 
-### Calls discovery endpoint 
+### Call discovery endpoint 
 The CDS discovery endpoint provides the list of services a CDS provider supports, and the hooks a service should be invoked on. An EHR may configure their system to support a set of hooks at a certain location in their users work flow, or build a dynamic capability to interact with a CDS Service provider within a work flow. For the best end-user experience, this guide recommends a business analyst configure which hooks an EHR will support. 
 
 Below is an example work flow where a business analyst accesses this list of available services by calling 
@@ -109,7 +109,7 @@ This image captures a business analyst reviewing services from one CDS provider.
 ### Invoke service on patient-view hook
 The `patient-view` hook is invoked when a patient chart is opened. It's one of the most basic since the logic doesn't have any prior workflow dependencies. The service called on the `patient-view` hook could be dependent on patient characteristics, for example: sex, problems in problems list, active medications, etc. The current version of the CDS Hooks specification allows the EHR to decide which characteristics to consider. 
 
-### Support for FHIR resources on request or prefetch
+### Support FHIR resource on CDS requests (context or pre-fetch)
 Often a CDS Service will require additional information from the EHR to perform the decision support logic, or determine the appropriate SMART app to return. Prefetch provides the EHR the capability to pass a resource when invoking a service. For example, with a patient resource included a service could do a geography search for potential environmental risk factors. Below is an example request invoked on patient-view with a patient included: 
 
 ```json
@@ -140,8 +140,8 @@ In some cases, additional information beyond what is included in the prefetch ma
 
 It is recommended FHIR servers implement, and CDS Services follow, locale specific implementation guides. In the US, the recommended implementation guides to follow are the [Argonaut Data Query Guide (DSTU2)](http://www.fhir.org/guides/argonaut/r2/) or [HL7 US Core (STU3)](http://hl7.org/fhir/us/core/index.html). Each profile page within these implementation guides includes queries FHIR servers are required to support. 
 
-### Exposed non-secured FHIR server
-A non secured FHIR server is important to support testing with a CDS Service. When the EHR moves a hook to production the system is expected to follow the guidelines in the [security](specification/1.0/#security-and-safety) requirements.
+### Expose non-secured FHIR server for testing
+A non-secured FHIR server is important to support testing with a CDS Service. When the EHR moves a hook to production the system is expected to follow the guidelines in the [security](specification/1.0/#security-and-safety) requirements.
 
 ### Render card
 The CDS Service will provide a response in the form a of a 'card'. Your EHR needs to be able to display the card.
@@ -174,7 +174,7 @@ Example card rendered: ![Card with SMART App link](images/Bilirubin_SMART_App_Ca
 
 For some CDS Services the end step will just display the card. For the patient-view hook discussed here, we are focused on launching a SMART app. The CDS Hooks guide places no additional constraints for launching a SMART app beyond those from [SMART on FHIR](http://docs.smarthealthit.org/authorization/). 
 
-## Test with an external CDS Service
+## Test with external CDS Service
 
 No development is complete without testing with a CDS Service provider. Find a member in the [community](community) and test away.