Add CDS Hooks

content/cds_hooks.md

@@ -0,0 +1,117 @@
+---
+title: CDS Hooks
+layout: cds_hooks
+---
+
+# CDS Hooks #
+------------------------------------------------------------------------
+<%= beta_tag(resource: false) %>
+* TOC
+{:toc}
+
+## General ##
+
+### Introduction ###
+The CDS Hooks (Clinical Decision Support Hooks) workflow defines a specification for external CDS Service developers to send notification cards to an electronic health record (EHR). These cards are triggered based on conditions such as the opening of a patient chart of a specified demographic(age, gender, etc.) or when an order is selected. These cards can contain information, a suggestion for the user, or a link to launch a SMART app (See [SMART](./smart) for more information).
+
+As a CDS Service Developer, you will work with clients or on your own to create a service that will be called by the CDS Hooks Server when a condition you specify is met. To develop a service, you should first gather the information needed for clients to register your service (See [CDS Service Registration](./cds_hooks/#cds-service-registration)). Then, build your service API so that is uses correct authorization (See [Service Authorization](./cds_hooks/#service-registration)) and returns a properly formatted response (See [Service Response](./cds_hooks/#service-response)). Finally, your service should be available for the CDS Hooks Server to call on a client by client basis.
+
+### Authorization Model ###
+1. Cerner must validate and register every CDS service.
+2. Each client decides whether they want to allow a CDS Service on a domain-by-domain basis.
+3. Each client decides which users and roles can access the CDS Service.
+
+### Supported Hooks ###
+Currently, Cerner supports the following CDS Hooks:
+
+- [Patient View](https://cds-hooks.org/hooks/patient-view/)
+
+## CDS Service Registration ##
+In order for a service to be registered for a client, the following information must be provided first.
+
+Name         | Required     | Description | Example
+-------------|--------------|-------------|--------
+hook              | Yes | The hook this service should be invoked on. See [Supported Hooks](#supported-hooks). | patient-view
+title             | Yes | The human-friendly name of this service.    | Severe Condition Alerter
+trigger condition | Yes | The condition(s) under which the service is called | Female patient with age > 65 years
+service url       | Yes | The url for the service that the CDS server will call to get the service card response.  | https://company.myservice.com/call
+fhir server       | Yes | The FHIR server that the service queries.   | https://fhir-ehr.cerner.com/r4/ec2458f2-1e24-41c8-b71b-0e701af7583d 
+description       | No  | Further information about the service. | Sends alerts for patients above age 65 who may have a severe condition.
+owner email       | No  | Required when scopes are provided. The email address of the owner of the service.        | [email protected]
+tenants           | No  | A list of tenants where the service is enabled. | C1941 - ec2458f2-1e24-41c8-b71b-0e701af7583d, A1234 - as1558f2-1e24-44c8-b71b-0e701af787f3d
+fhir scopes       | No  | A list of the FHIR scopes required for any FHIR calls this CDS service makes. | patient/Patient.read, patient/Encounter.read, patient/Observations.read
+allowed links     | No  | A list of all links allowed in the response. Any links not in this list will be removed. | https://www.google.com, https://www.cerner.com
+smart apps        | No  | A list of launch urls for any SMART applications that may be linked to in CDS service responses. | https://www.myapp.com, https://www.otherapp.org
+
+For more information on CDS Service attributes see the Discovery Response section [here](https://cds-hooks.hl7.org/1.0/#response).
+
+## CDS Service Workflow ##
+Once a CDS service is registered, it will be called whenever the trigger condition is met in the EHR (e.g. a chart is opened for a patient of the specified demographic). The trigger condition will notify the CDS Hooks Server, which will call the CDS Service using a JWT token and the service url (provided during Registration). The CDS Service response cards will then be displayed in the EHR as either critical notification pop-ups or non-critical notification cards in a sidebar, depending on the card indicator value.
+
+### Service Authorization ###
+When Cerner's CDS Hooks server calls a service, authorization will be accomplished with a JWT token.
+
+1. The JWT issuer `iss` will be ```https://cds-hooks.cerner.com```. Make sure this is whitelisted as a trusted CDS Client.
+2. The JWT signature should be verified by calling the Cerner Authorization well-known endpoint: ```https://authorization.cerner.com/jwk``` to get the list of JKUs and confirm the token JKU is present.
+
+
+For more information on CDS Authorization best practices, see [this page](https://cds-hooks.org/best-practices/#jwt).
+
+### Service Response ###
+When the specified condition(s) in the EHR are met, the CDS Hooks Server will make a GET request to the provided service url. The CDS service should return an array of cards formatted according to the [CDS Service HTTP Response specification](https://cds-hooks.hl7.org/1.0/#http-response). 
+
+#### Example Response from a CDS Service ####
+
+      {
+        "cards": [
+          {
+            "summary": "A summary of the card.",
+            "detail": "Additional card detail.",
+            "indicator": "info",
+            "source": {
+              "label": "Company",
+              "url": "https://company.com",
+              "icon": "https://company.com/company-logo.png"
+            },
+            "links": [
+              {
+                "label": "Webpage",
+                "url": "https://webpage.com",
+                "type": "absolute"
+              }
+            ]
+          },
+          {
+            "summary": "A summary of the card.",
+            "detail": "Additional card detail. See https://webpage.com.",
+            "indicator": "critical",
+            "source": {
+              "label": "External"
+            },
+            "links": [
+              {
+                "label": "Webpage In Detail",
+                "url": "https://webpage.com",
+                "type": "absolute"
+              },
+              {
+                "label": "Smart App",
+                "url": "https://smart.cerner.com/smart/eb2384f8-839e-4c6e-8b29-18e71db1a034/apps/a77a3d9a-28fe-48te-a96a-2ff09bed599a",
+                "type": "smart"
+             },
+            ]
+          }
+        ]
+      }
+
+### SMART Apps ###
+Some CDS services return SMART app link cards. For information on registering a SMART app, see [this page](./smart).
+
+_Note: Each client decides whether they want a SMART app to run on a domain-by-domain basis. An app link card will only work correctly in a domain in which the corresponding SMART app is enabled._
+
+## Additional Resources ##
+
+- [CDS Hooks Specification](https://cds-hooks.org/)
+- [Cerner Millennium FHIR API Documentation](http://fhir.cerner.com/millennium/r4/)
+- [Cerner Authorization Documentation](http://fhir.cerner.com/authorization/)
+- [Cerner FHIR Developers Google Group](https://groups.google.com/forum/#!forum/cerner-fhir-developers)

layouts/cds_hooks.html

@@ -0,0 +1,14 @@
+<%= render '/head.*' %>
+
+<body class="<%= @item[:version].to_s %>_api">
+<%= render '/header.*' %>
+
+<div id="wrapper">
+  <div class="content">
+    <%= yield %>
+  </div>
+</div><!-- #wrapper -->
+
+<%= render '/footer.*' %>
+</body>
+</html>

layouts/header.html

@@ -19,6 +19,7 @@
         <li><a href="/soarian/dstu2/">Soarian</a></li>
         <li><a href="/authorization">Authorization</a></li>
         <li><a href="/smart">SMART</a></li>
+        <li><a href="/cds_hooks" class="nav-dstu2-api">CDS Hooks</a></li>
       </ul>
 
     </div><!-- /.header-wrapper -->

lib/resources.rb

@@ -145,12 +145,13 @@ def disclaimer
 
       # Public: Helper method to create a tag to denote if a resource/action is still under development.
       #
-      # @param action [boolean] flag to denote if a resource action is under development. Defaults to false.
+      # @param action [boolean] flag to denote if a resource action or feature is under development. Defaults to false.
       # @param known_issues [Array<String>] an array of known issues for the resource/action.
       #
       # @return [String] an HTML div for beta tag.
-      def beta_tag(action: false, known_issues: nil)
-        beta = "<div class=\"beta-tag\"><p>This Resource#{' Action' if action} is still under development.</p>"
+      def beta_tag(resource: true, action: false, known_issues: nil)
+        beta = "<div class=\"beta-tag\"><p>This#{resource ? ' Resource' : ' feature'}"
+        beta += "#{' Action' if action} is still under development.</p>"
 
         if known_issues
           beta += '<p>Known Issues:</p><ul>'

spec/lib/resources_spec.rb

@@ -661,7 +661,9 @@
     end
 
     context 'when parameters are passed in' do
-      subject(:beta_tag_parameters) { Cerner::Resources::Helpers.beta_tag(action: action, known_issues: issues) }
+      subject(:beta_tag_parameters) do
+        Cerner::Resources::Helpers.beta_tag(resource: resource, action: action, known_issues: issues)
+      end
       let(:issues) { %w[hi hello] }
       let(:beta_tag_div) do
         '<div class="beta-tag"></div>This Resource is still under development.<p>Known Issues:</p><ul><li>hi</li>'\
@@ -677,8 +679,23 @@
             '<div class="beta-tag"><p>This Resource is still under development.</p></div>'
           end
 
-          it 'returns the beta_tag div for a Resource' do
-            expect(beta_tag_parameters).to eq(beta_tag_div)
+          context 'when resource is false' do
+            let(:resource) { false }
+            let(:beta_tag_div) do
+              '<div class="beta-tag"><p>This feature is still under development.</p></div>'
+            end
+
+            it 'returns the beta_tag div for a feature' do
+              expect(beta_tag_parameters).to eq(beta_tag_div)
+            end
+          end
+
+          context 'when resource is true' do
+            let(:resource) { true }
+
+            it 'returns the beta_tag div for a Resource' do
+              expect(beta_tag_parameters).to eq(beta_tag_div)
+            end
           end
         end
 
@@ -688,14 +705,31 @@
             '<li>hi</li><li>hello</li></ul></div>'
           end
 
-          it 'returns the beta_tag div for a Resource with known issues' do
-            expect(beta_tag_parameters).to eq(beta_tag_div)
+          context 'when resource is false' do
+            let(:resource) { false }
+            let(:beta_tag_div) do
+              '<div class="beta-tag"><p>This feature is still under development.</p><p>Known Issues:</p><ul>'\
+              '<li>hi</li><li>hello</li></ul></div>'
+            end
+
+            it 'returns the beta_tag div for a feature with known issues' do
+              expect(beta_tag_parameters).to eq(beta_tag_div)
+            end
+          end
+
+          context 'when resource is true' do
+            let(:resource) { true }
+
+            it 'returns the beta_tag div for a Resource with known issues' do
+              expect(beta_tag_parameters).to eq(beta_tag_div)
+            end
           end
         end
       end
 
       context 'when action is true' do
         let(:action) { true }
+        let(:resource) { true }
 
         context 'when known issues are not present' do
           let(:issues) { nil }