Merge branch 'master' into iss308-fix-link-to-MedRequest

isaacvetter · web-flow · commit 26d79d4e9cc2 · 2018-08-09T13:15:23.000-05:00
diff --git a/docs/hooks/index.md b/docs/hooks/index.md
@@ -169,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
diff --git a/docs/quickstart.md b/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. 
 
diff --git a/docs/specification/1.0.md b/docs/specification/1.0.md
@@ -34,7 +34,7 @@ A CDS Service provider SHALL expose its Discovery endpoint at"
 ```
 ### HTTP Request
 
-The discovery endpoint SHALL always be available at `{baseUrl}/cds-services`. For example, if the `baseUrl` is https://example.com, the EHR would invoke:
+The discovery endpoint SHALL always be available at `{baseUrl}/cds-services`. For example, if the `baseUrl` is https://example.com, the EHR MAY invoke:
 
 `GET https://example.com/cds-services`
 
@@ -62,6 +62,8 @@ Code | Description
 ---- | -----------
 `200 OK` | A successful response
 
+CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes.
+
 ### Discovery Example
 
 ```shell
@@ -465,7 +467,7 @@ Once a CDS Service provider is selected, the EHR vendor/provider negotiates the
 
 Every interaction between an EHR and a CDS Service is initiated by the EHR sending a service request to a CDS Service endpoint protected using the [Transport Layer Security protocol](https://tools.ietf.org/html/rfc5246).   Through the TLS protocol the identity of the CDS Service is authenticated, and an encrypted transmission channel is established between the EHR and the CDS Service. Both the Discovery endpoint and individual CDS Service endpoints are TLS secured.
 
-The EHR’s authorization server is responsible for enforcing restrictions on the CDS Services that may be called and the scope of the FHIR resources that may be prefetched or retrieved from the FHIR server.  Therefore, all CDS Services to be called from within an EHR system MUST BE pre-registered with the authorization server of that EHR.  Pre-registration MUST include registering a CDS client identifier, and agreeing upon the scope of FHIR access that is minimally necessary to provide the clinical decision support required.
+The EHR’s authorization server is responsible for enforcing restrictions on the CDS Services that may be called and the scope of the FHIR resources that may be prefetched or retrieved from the FHIR server.  Therefore, all CDS Services to be called from within an EHR system are pre-registered with the authorization server of that EHR.  Pre-registration includes registering a CDS client identifier, and agreeing upon the scope of FHIR access that is minimally necessary to provide the clinical decision support required.
 
 ### Trusting EHRs
 
