diff --git a/hooks/order-select/index.html b/hooks/order-select/index.html
index 1e789aab..13a6ea51 100644
--- a/hooks/order-select/index.html
+++ b/hooks/order-select/index.html
@@ -712,16 +712,14 @@ <h1 id="order-select"><code>order-select</code><a class="headerlink" href="#orde
 </tbody>
 </table>
 <h2 id="workflow">Workflow<a class="headerlink" href="#workflow" title="Permanent link">&para;</a></h2>
-<p>The <code>order-select</code> 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 <code>order-select</code> hook occurs after the clinician selects the order and before signing. </p>
-<p>This hook is intended to replace (deprecate) the <code>medication-prescribe</code> hook. </p>
+<p>The order-select hook occurs after the clinician selects the order and before signing.</p>
+<p>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.</p>
+<p><code>order-select</code> 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. </p>
+<p>This hook is intended to replace (deprecate) the medication-prescribe hook.</p>
 <h2 id="context">Context<a class="headerlink" href="#context" title="Permanent link">&para;</a></h2>
-<p>Decision support should focus on the 'selected' orders - those that are newly selected or actively being authored.  The non-selected orders are included in the context to provide context and to allow decision support to take into account other pending actions that might not yet be stored in the system (and therefore not queryable).
-The context of this hook distinguishes between the list of unsigned orders from the clinician's ordering session, and the one or more orders just added to this list. The <code>selections</code> field contains a list of ids of these newly selected orders; the <code>draftOrders</code> Bundle contains an entry for all unsigned orders from this session, including newly selected orders.</p>
+<p>Decision support should focus on the 'selected' orders - those that are newly selected or actively being authored. The non-selected orders are included in the context to provide context and to allow decision support to take into account other pending actions that might not yet be stored in the system (and therefore not queryable).
+The context of this hook distinguishes between the list of unsigned orders from the clinician's ordering session, and the one or more orders just added to this list. The <code>selections</code> field contains a list of ids of these newly selected orders; the draftOrders Bundle contains an entry for all unsigned orders from this session, including newly selected orders.</p>
+<p>The selected order(s) may or may not define the additional details necessary to finalize the order (such as route, dose, etc). Note that at the point of the related order-sign hook, all order details are known. </p>
 <table>
 <thead>
 <tr>
diff --git a/search/search_index.json b/search/search_index.json
index e652a7af..fd003e5f 100644
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Continuous Improvement Build This is the continuous integration, community release of the CDS Hooks specification. All stable releases are available at https://cds-hooks.hl7.org . Overview \u00b6 This specification describes a \"hook\" -based pattern for invoking decision support from within a clinician's workflow. The API supports: Synchronous, workflow-triggered CDS calls returning information and suggestions Launching a user-facing SMART app when CDS requires additional interaction How it works \u00b6 User activity inside the clinician's workflow triggers CDS hooks in real-time. For example: patient-view when opening a new patient record order-select when selecting one or more orders to place for a patient order-sign immediately before an order is signed When a triggering activity occurs, the CDS Client notifies each CDS service registered for the activity. These services must then provide near-real-time feedback about the triggering event. Each service gets basic details about the clinical workflow context (via the context parameter of the hook) plus whatever service-specific data are required (via the pre-fetch-template parameter). CDS Cards \u00b6 Each CDS service can return any number of cards in response to the hook. Cards convey some combination of text ( information card ), alternative suggestions ( suggestion card ), and links to apps or reference materials ( app link card ). A user sees these cards \u2014 one or more of each type \u2014 embedded in the workflow, and can interact with them as follows: information card : provides text for the user to read. suggestion card : provides a specific suggestion for which the CDS Client renders a button that the user can click to accept. Clicking automatically populates the suggested change into the clinician's UI. app link card : provides a link to an app (often a SMART app) where the user can supply details, step through a flowchart, or do anything else required to help reach an informed decision. Try it! \u00b6 You can try CDS Hooks in our Sandbox at http://sandbox.cds-hooks.org An OpenAPI Specification (formally known as the Swagger Specification) interface of CDS Hooks is available. Using the CDS Hooks OpenAPI specification, you can generate client or server code to help you get started with your implementation. You can download the API specification and view it online via the Swagger Editor . CDS Hooks implementers are not required to use the OpenAPI Specification interface of CDS Hooks.","title":"Overview"},{"location":"#overview","text":"This specification describes a \"hook\" -based pattern for invoking decision support from within a clinician's workflow. The API supports: Synchronous, workflow-triggered CDS calls returning information and suggestions Launching a user-facing SMART app when CDS requires additional interaction","title":"Overview"},{"location":"#how-it-works","text":"User activity inside the clinician's workflow triggers CDS hooks in real-time. For example: patient-view when opening a new patient record order-select when selecting one or more orders to place for a patient order-sign immediately before an order is signed When a triggering activity occurs, the CDS Client notifies each CDS service registered for the activity. These services must then provide near-real-time feedback about the triggering event. Each service gets basic details about the clinical workflow context (via the context parameter of the hook) plus whatever service-specific data are required (via the pre-fetch-template parameter).","title":"How it works"},{"location":"#cds-cards","text":"Each CDS service can return any number of cards in response to the hook. Cards convey some combination of text ( information card ), alternative suggestions ( suggestion card ), and links to apps or reference materials ( app link card ). A user sees these cards \u2014 one or more of each type \u2014 embedded in the workflow, and can interact with them as follows: information card : provides text for the user to read. suggestion card : provides a specific suggestion for which the CDS Client renders a button that the user can click to accept. Clicking automatically populates the suggested change into the clinician's UI. app link card : provides a link to an app (often a SMART app) where the user can supply details, step through a flowchart, or do anything else required to help reach an informed decision.","title":"CDS Cards"},{"location":"#try-it","text":"You can try CDS Hooks in our Sandbox at http://sandbox.cds-hooks.org An OpenAPI Specification (formally known as the Swagger Specification) interface of CDS Hooks is available. Using the CDS Hooks OpenAPI specification, you can generate client or server code to help you get started with your implementation. You can download the API specification and view it online via the Swagger Editor . CDS Hooks implementers are not required to use the OpenAPI Specification interface of CDS Hooks.","title":"Try it!"},{"location":"best-practices/","text":"Implementation Best Practices \u00b6 This page serves as best practice guidance for CDS Hooks implementers. The best practices outlined here are not mandatory implementation rules; rather, they are suggested guidance. This is a living, in progress document and the best practices outlined here should not be considered absolute or complete. Security \u00b6 The CDS Hooks security model requires thought and consideration from implementers. Security topics are never binary, are often complex, and robust implementations should factor in concepts such as risk and usability. Implementers should approach their security related development with thoughtful care. The CDS Hooks specifications already provides some guidance in this space. The information here is supplemental to the existing specification documentation. The CDS Hooks security model leverages several existing RFCs. These should be read and fully understood by all implementers. rfc7519: JSON Web Tokens (JWT) rfc7517: JSON Web Key (JWK) rfc7515: JSON Web Signature (JWS) rfc7518: JSON Web Algorithms (JWA) CDS Clients \u00b6 Implementers of CDS Clients should: Maintain a allowlist of CDS Service endpoints that may be invoked. Only endpoints on the allowlist can be invoked. This ensures that CDS Clients invoke only trusted CDS Services. This is especially important since CDS Clients may send an authorization token that allows the CDS Service temporary access to the FHIR server. Issue secure FHIR access tokens. If a CDS Clients generates access tokens to its FHIR server, the tokens should: Be unique for each CDS Service endpoint. Be very short-lived. Provide the minimum necessary access for the CDS Service. This includes both SMART scopes as well as the patient(s)/data that can be accessed. Audit CDS Service's access to data * Regardless of the use of prefetch or more typical FHIR RESTful APIs, CDS Clients should audit and report on data access. CDS Services \u00b6 JWT \u00b6 Upon being invoked by a CDS Client, the CDS Service should first process the given JWT to determine whether to process the given request. In processing the JWT, CDS Services should: Ensure that the iss value exists in the CDS Service's allowlist of trusted CDS Clients. Ensure that the aud value matches the CDS Service endpoint currently processing the request. Ensure that the exp value is not before the current date/time. Ensure that the tenant value exists in the CDS Service's allowlist of trusted tenants (may not be applicable to all CDS Services). Ensure that the JWT signature matches the public key on record with the CDS Service. See additional notes below. Ensure that the jti value doesn't exist in the short-term storage of JWTs previously processed by this CDS Service. Once the JWT has been deemed to be valid, the jti value should be stored in the short-term storage of processed JWTs. Values in this storage only need to be kept for the maximum duration of all JWTs processed by this CDS Service. If the CDS Clients are adhering to best practices, this should be no more than an hour. Verifying the JWT signature is a critical step in establishing trust of the caller of the CDS Service. As part of the allowlist of trusted CDS Clients, information on the public key(s) used by the CDS Client should also be stored. In some cases, this public key may be shared out-of-band. In other cases, the public key may be available at a remote endpoint and cycled on a regular basis. It is this latter case in which CDS Services should maintain their own rotating cache of public keys for the CDS Client. CDS Services should never store, share, or log JWTs to minimize the risk of theft and replay attacks. Information within the JWT (for instance, iss , tenant , jti ) can be logged safely and is especially useful for analytics. If a CDS Service deems a JWT to be invalid for any reason, it should not leak the details of why the JWT failed validation back to the caller. If the caller were a malicious threat actor, leaking detailed information as to what was invalid may give the threat actor guidance on how to shape future attacks. Instead, responding to the request with a HTTP 401 Unauthorized response status code without any additional information is recommended. FHIR Access \u00b6 CDS Services should never store, share, or log the FHIR access token ( fhirAuthorization.access_token ) given to it by the CDS Client. The access token should be treated as an extremely sensitive, transient piece of data.","title":"Best Practices"},{"location":"best-practices/#implementation-best-practices","text":"This page serves as best practice guidance for CDS Hooks implementers. The best practices outlined here are not mandatory implementation rules; rather, they are suggested guidance. This is a living, in progress document and the best practices outlined here should not be considered absolute or complete.","title":"Implementation Best Practices"},{"location":"best-practices/#security","text":"The CDS Hooks security model requires thought and consideration from implementers. Security topics are never binary, are often complex, and robust implementations should factor in concepts such as risk and usability. Implementers should approach their security related development with thoughtful care. The CDS Hooks specifications already provides some guidance in this space. The information here is supplemental to the existing specification documentation. The CDS Hooks security model leverages several existing RFCs. These should be read and fully understood by all implementers. rfc7519: JSON Web Tokens (JWT) rfc7517: JSON Web Key (JWK) rfc7515: JSON Web Signature (JWS) rfc7518: JSON Web Algorithms (JWA)","title":"Security"},{"location":"best-practices/#cds-clients","text":"Implementers of CDS Clients should: Maintain a allowlist of CDS Service endpoints that may be invoked. Only endpoints on the allowlist can be invoked. This ensures that CDS Clients invoke only trusted CDS Services. This is especially important since CDS Clients may send an authorization token that allows the CDS Service temporary access to the FHIR server. Issue secure FHIR access tokens. If a CDS Clients generates access tokens to its FHIR server, the tokens should: Be unique for each CDS Service endpoint. Be very short-lived. Provide the minimum necessary access for the CDS Service. This includes both SMART scopes as well as the patient(s)/data that can be accessed. Audit CDS Service's access to data * Regardless of the use of prefetch or more typical FHIR RESTful APIs, CDS Clients should audit and report on data access.","title":"CDS Clients"},{"location":"best-practices/#cds-services","text":"","title":"CDS Services"},{"location":"best-practices/#jwt","text":"Upon being invoked by a CDS Client, the CDS Service should first process the given JWT to determine whether to process the given request. In processing the JWT, CDS Services should: Ensure that the iss value exists in the CDS Service's allowlist of trusted CDS Clients. Ensure that the aud value matches the CDS Service endpoint currently processing the request. Ensure that the exp value is not before the current date/time. Ensure that the tenant value exists in the CDS Service's allowlist of trusted tenants (may not be applicable to all CDS Services). Ensure that the JWT signature matches the public key on record with the CDS Service. See additional notes below. Ensure that the jti value doesn't exist in the short-term storage of JWTs previously processed by this CDS Service. Once the JWT has been deemed to be valid, the jti value should be stored in the short-term storage of processed JWTs. Values in this storage only need to be kept for the maximum duration of all JWTs processed by this CDS Service. If the CDS Clients are adhering to best practices, this should be no more than an hour. Verifying the JWT signature is a critical step in establishing trust of the caller of the CDS Service. As part of the allowlist of trusted CDS Clients, information on the public key(s) used by the CDS Client should also be stored. In some cases, this public key may be shared out-of-band. In other cases, the public key may be available at a remote endpoint and cycled on a regular basis. It is this latter case in which CDS Services should maintain their own rotating cache of public keys for the CDS Client. CDS Services should never store, share, or log JWTs to minimize the risk of theft and replay attacks. Information within the JWT (for instance, iss , tenant , jti ) can be logged safely and is especially useful for analytics. If a CDS Service deems a JWT to be invalid for any reason, it should not leak the details of why the JWT failed validation back to the caller. If the caller were a malicious threat actor, leaking detailed information as to what was invalid may give the threat actor guidance on how to shape future attacks. Instead, responding to the request with a HTTP 401 Unauthorized response status code without any additional information is recommended.","title":"JWT"},{"location":"best-practices/#fhir-access","text":"CDS Services should never store, share, or log the FHIR access token ( fhirAuthorization.access_token ) given to it by the CDS Client. The access token should be treated as an extremely sensitive, transient piece of data.","title":"FHIR Access"},{"location":"changelog/","text":"Change Log \u00b6 CDS Hooks 1.1 \u00b6 Non-compatible (breaking) changes \u00b6 The CDS Hooks project team strives to not brek backward compatibility between versions of the CDS Hooks specifications to aid both in interoperability and to prioritize existing implementations. In cases where this isn't possible, changes made in the CDS Hooks 1.1 specification that break backward compatibility are documented below. CDS Clients may now paginate search results in prefetch. Previously, CDS Clients were not permitted to return partial search results using the typical FHIR pagination mechanism . When using prefetch, CDS Services should expect to receive continuation links which enable access to the remainder of the search results over REST.","title":"Change Log"},{"location":"changelog/#change-log","text":"","title":"Change Log"},{"location":"changelog/#cds-hooks-11","text":"","title":"CDS Hooks 1.1"},{"location":"changelog/#non-compatible-breaking-changes","text":"The CDS Hooks project team strives to not brek backward compatibility between versions of the CDS Hooks specifications to aid both in interoperability and to prioritize existing implementations. In cases where this isn't possible, changes made in the CDS Hooks 1.1 specification that break backward compatibility are documented below. CDS Clients may now paginate search results in prefetch. Previously, CDS Clients were not permitted to return partial search results using the typical FHIR pagination mechanism . When using prefetch, CDS Services should expect to receive continuation links which enable access to the remainder of the search results over REST.","title":"Non-compatible (breaking) changes"},{"location":"community/","text":"Community \u00b6 Get Involved \u00b6 There are several ways in which you can get involved with the CDS Hooks community. Ask a question and participate in discussions via the CDS Hooks Google Group Chat via Zulip at https://chat.fhir.org in the cds-hooks stream Contribute to the code and documentation on Github Check out the CDS services available for testing and contribute your own. CDS Hooks Sprint Program \u00b6 Objectives \u00b6 Promote creation of clinical-grade service integrations (CDS Clients + CDS Services) Gain implementation experience with real-world systems Refine the spec, balancing ease of use, flexibility, and stability Drive toward pilot deployments with the ability to measure results Want to help build our test infrastructure? \u00b6 help-wanted issues Proposed Milestones","title":"Community"},{"location":"community/#community","text":"","title":"Community"},{"location":"community/#get-involved","text":"There are several ways in which you can get involved with the CDS Hooks community. Ask a question and participate in discussions via the CDS Hooks Google Group Chat via Zulip at https://chat.fhir.org in the cds-hooks stream Contribute to the code and documentation on Github Check out the CDS services available for testing and contribute your own.","title":"Get Involved"},{"location":"community/#cds-hooks-sprint-program","text":"","title":"CDS Hooks Sprint Program"},{"location":"community/#objectives","text":"Promote creation of clinical-grade service integrations (CDS Clients + CDS Services) Gain implementation experience with real-world systems Refine the spec, balancing ease of use, flexibility, and stability Drive toward pilot deployments with the ability to measure results","title":"Objectives"},{"location":"community/#want-to-help-build-our-test-infrastructure","text":"help-wanted issues Proposed Milestones","title":"Want to help build our test infrastructure?"},{"location":"examples/","text":"Examples \u00b6 CDC Guideline for Prescribing Opioids for Chronic Pain \u00b6 CDS Service Request The example illustrates a prescription for Acetaminophen/Hydrocodone Bitartrate for a patient that already has a prescription for Oxycodone Hydrochloride: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://fhir.example.com\" , \"hook\" : \"order-sign\" , \"context\" : { \"userId\" : \"Practitioner/example\" , \"medications\" : [ { \"resourceType\" : \"MedicationOrder\" , \"id\" : \"medrx001\" , \"dateWritten\" : \"2017-05-05\" , \"status\" : \"draft\" , \"patient\" : { \"reference\" : \"Patient/example\" }, \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"857001\" , \"display\" : \"Acetaminophen 325 MG / Hydrocodone Bitartrate 10 MG Oral Tablet\" } ] }, \"dosageInstruction\" : [ { \"text\" : \"Take 1 tablet Oral every 4 hours as needed\" , \"timing\" : { \"repeat\" : { \"frequency\" : 6 , \"frequencyMax\" : 6 , \"period\" : 1 , \"unit\" : \"d\" } }, \"asNeededBoolean\" : true , \"doseQuantity\" : { \"value\" : 10 , \"unit\" : \"mg\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mg\" } } ] } ], \"patientId\" : \"1288992\" }, \"prefetch\" : { \"medication\" : { \"response\" : { \"status\" : \"200 OK\" }, \"resource\" : { \"resourceType\" : \"MedicationOrder\" , \"id\" : \"medrx002\" , \"dateWritten\" : \"2017-04-25\" , \"status\" : \"active\" , \"patient\" : { \"reference\" : \"Patient/example\" }, \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"1049621\" , \"display\" : \"Oxycodone Hydrochloride 5 MG Oral Tablet\" } ] }, \"dosageInstruction\" : [ { \"text\" : \"Take 1 tablet by mouth every 4 hours as needed for pain.\" , \"timing\" : { \"repeat\" : { \"frequency\" : 6 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"asNeededBoolean\" : true , \"doseQuantity\" : { \"value\" : 5 , \"unit\" : \"mg\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mg\" } } ] } } } } This example illustrates the use of the CDS Hooks medication-prescribe hook to implement Recommendation #5 from the CDC guideline for prescribing opioids for chronic pain . This example is taken from the Opioid Prescribing Support Implementation Guide , developed in partnership with the Centers for Disease Control and Prevention (CDC) . CDS Service Response The opioid guideline request results in the following response that indicates the patient is at high risk for opioid overdose according to the CDC guidelines, and the dosage should be tapered to less than 50 MME. Links are provided to the guideline, as well as to the MME conversion tables provided by CDC. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { \"summary\" : \"High risk for opioid overdose - taper now\" , \"indicator\" : \"warning\" , \"links\" : [ { \"label\" : \"CDC guideline for prescribing opioids for chronic pain\" , \"type\" : \"absolute\" , \"url\" : \"https://guidelines.gov/summaries/summary/50153/cdc-guideline-for-prescribing-opioids-for-chronic-pain---united-states-2016#420\" }, { \"label\" : \"MME Conversion Tables\" , \"type\" : \"absolute\" , \"url\" : \"https://www.cdc.gov/drugoverdose/pdf/calculating_total_daily_dose-a.pdf\" } ], \"detail\" : \"Total morphine milligram equivalent (MME) is 125mg. Taper to less than 50.\" } Radiology Appropriateness \u00b6 CDS Service Request This example illustrates the use of the CDS Hooks order-select hook to implement Radiology Appropriateness scoring. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 { \"hook\" : \"order-select\" , \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://hooks.smarthealthit.org:9080\" , \"context\" : { \"userId\" : \"Practitioner/123\" , \"patientId\" : \"MRI-59879846\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"ServiceRequest/example-MRI-59879846\" ], \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"status\" : \"draft\" , \"intent\" : \"plan\" , \"code\" : { \"coding\" : [ { \"system\" : \"http://loinc.org\" , \"code\" : \"36801-9\" } ], \"text\" : \"MRA Knee Vessels Right\" }, \"subject\" : { \"reference\" : \"Patient/MRI-59879846\" }, \"reasonCode\" : [ { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/sid/icd-10\" , \"code\" : \"S83.511\" , \"display\" : \"Sprain of anterior cruciate ligament of right knee\" } ] } ] } } ] } } } CDS Service Response The appropriateness score is communicated via a systemAction of the ServiceRequest that adds an extension element to indicate the appropriateness rating. See the CDS Hooks for PAMA Argonaut specification for more. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 { \"cards\" :[ ], \"systemActions\" :[ { \"type\" : \"update\" , \"resource\" :{ \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"extension\" :[ { \"url\" : \"http://fhir.org/argonaut/Extension/pama-rating\" , \"valueCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://fhir.org/argonaut/CodeSystem/pama-rating\" , \"code\" : \"appropriate\" } ] } }, { \"url\" : \"http://fhir.org/argonaut/Extension/pama-rating-consult-id\" , \"valueUri\" : \"urn:uuid:55f3b7fc-9955-420e-a460-ff284b2956e6\" } ], \"status\" : \"draft\" , \"intent\" : \"plan\" , \"code\" :{ \"coding\" :[ { \"system\" : \"http://loinc.org\" , \"code\" : \"36801-9\" } ], \"text\" : \"MRA Knee Vessels Right\" }, \"subject\" :{ \"reference\" : \"Patient/MRI-59879846\" }, \"reasonCode\" :[ { \"coding\" :[ { \"system\" : \"http://hl7.org/fhir/sid/icd-10\" , \"code\" : \"S83.511\" , \"display\" : \"Sprain of anterior cruciate ligament of right knee\" } ] } ] } } ] }","title":"Examples"},{"location":"examples/#examples","text":"","title":"Examples"},{"location":"examples/#cdc-guideline-for-prescribing-opioids-for-chronic-pain","text":"CDS Service Request The example illustrates a prescription for Acetaminophen/Hydrocodone Bitartrate for a patient that already has a prescription for Oxycodone Hydrochloride: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://fhir.example.com\" , \"hook\" : \"order-sign\" , \"context\" : { \"userId\" : \"Practitioner/example\" , \"medications\" : [ { \"resourceType\" : \"MedicationOrder\" , \"id\" : \"medrx001\" , \"dateWritten\" : \"2017-05-05\" , \"status\" : \"draft\" , \"patient\" : { \"reference\" : \"Patient/example\" }, \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"857001\" , \"display\" : \"Acetaminophen 325 MG / Hydrocodone Bitartrate 10 MG Oral Tablet\" } ] }, \"dosageInstruction\" : [ { \"text\" : \"Take 1 tablet Oral every 4 hours as needed\" , \"timing\" : { \"repeat\" : { \"frequency\" : 6 , \"frequencyMax\" : 6 , \"period\" : 1 , \"unit\" : \"d\" } }, \"asNeededBoolean\" : true , \"doseQuantity\" : { \"value\" : 10 , \"unit\" : \"mg\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mg\" } } ] } ], \"patientId\" : \"1288992\" }, \"prefetch\" : { \"medication\" : { \"response\" : { \"status\" : \"200 OK\" }, \"resource\" : { \"resourceType\" : \"MedicationOrder\" , \"id\" : \"medrx002\" , \"dateWritten\" : \"2017-04-25\" , \"status\" : \"active\" , \"patient\" : { \"reference\" : \"Patient/example\" }, \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"1049621\" , \"display\" : \"Oxycodone Hydrochloride 5 MG Oral Tablet\" } ] }, \"dosageInstruction\" : [ { \"text\" : \"Take 1 tablet by mouth every 4 hours as needed for pain.\" , \"timing\" : { \"repeat\" : { \"frequency\" : 6 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"asNeededBoolean\" : true , \"doseQuantity\" : { \"value\" : 5 , \"unit\" : \"mg\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mg\" } } ] } } } } This example illustrates the use of the CDS Hooks medication-prescribe hook to implement Recommendation #5 from the CDC guideline for prescribing opioids for chronic pain . This example is taken from the Opioid Prescribing Support Implementation Guide , developed in partnership with the Centers for Disease Control and Prevention (CDC) . CDS Service Response The opioid guideline request results in the following response that indicates the patient is at high risk for opioid overdose according to the CDC guidelines, and the dosage should be tapered to less than 50 MME. Links are provided to the guideline, as well as to the MME conversion tables provided by CDC. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { \"summary\" : \"High risk for opioid overdose - taper now\" , \"indicator\" : \"warning\" , \"links\" : [ { \"label\" : \"CDC guideline for prescribing opioids for chronic pain\" , \"type\" : \"absolute\" , \"url\" : \"https://guidelines.gov/summaries/summary/50153/cdc-guideline-for-prescribing-opioids-for-chronic-pain---united-states-2016#420\" }, { \"label\" : \"MME Conversion Tables\" , \"type\" : \"absolute\" , \"url\" : \"https://www.cdc.gov/drugoverdose/pdf/calculating_total_daily_dose-a.pdf\" } ], \"detail\" : \"Total morphine milligram equivalent (MME) is 125mg. Taper to less than 50.\" }","title":"CDC Guideline for Prescribing Opioids for Chronic Pain"},{"location":"examples/#radiology-appropriateness","text":"CDS Service Request This example illustrates the use of the CDS Hooks order-select hook to implement Radiology Appropriateness scoring. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 { \"hook\" : \"order-select\" , \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://hooks.smarthealthit.org:9080\" , \"context\" : { \"userId\" : \"Practitioner/123\" , \"patientId\" : \"MRI-59879846\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"ServiceRequest/example-MRI-59879846\" ], \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"status\" : \"draft\" , \"intent\" : \"plan\" , \"code\" : { \"coding\" : [ { \"system\" : \"http://loinc.org\" , \"code\" : \"36801-9\" } ], \"text\" : \"MRA Knee Vessels Right\" }, \"subject\" : { \"reference\" : \"Patient/MRI-59879846\" }, \"reasonCode\" : [ { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/sid/icd-10\" , \"code\" : \"S83.511\" , \"display\" : \"Sprain of anterior cruciate ligament of right knee\" } ] } ] } } ] } } } CDS Service Response The appropriateness score is communicated via a systemAction of the ServiceRequest that adds an extension element to indicate the appropriateness rating. See the CDS Hooks for PAMA Argonaut specification for more. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 { \"cards\" :[ ], \"systemActions\" :[ { \"type\" : \"update\" , \"resource\" :{ \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"extension\" :[ { \"url\" : \"http://fhir.org/argonaut/Extension/pama-rating\" , \"valueCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://fhir.org/argonaut/CodeSystem/pama-rating\" , \"code\" : \"appropriate\" } ] } }, { \"url\" : \"http://fhir.org/argonaut/Extension/pama-rating-consult-id\" , \"valueUri\" : \"urn:uuid:55f3b7fc-9955-420e-a460-ff284b2956e6\" } ], \"status\" : \"draft\" , \"intent\" : \"plan\" , \"code\" :{ \"coding\" :[ { \"system\" : \"http://loinc.org\" , \"code\" : \"36801-9\" } ], \"text\" : \"MRA Knee Vessels Right\" }, \"subject\" :{ \"reference\" : \"Patient/MRI-59879846\" }, \"reasonCode\" :[ { \"coding\" :[ { \"system\" : \"http://hl7.org/fhir/sid/icd-10\" , \"code\" : \"S83.511\" , \"display\" : \"Sprain of anterior cruciate ligament of right knee\" } ] } ] } } ] }","title":"Radiology Appropriateness"},{"location":"logo-use/","text":"Use of CDS Hooks Logos \u00b6 The CDS Hooks logos are owned by The Children's Medical Center Corporation and may be used in accordance with guidelines and policy at https://smarthealthit.org/cds-hooks-logo . These guidelines describe how CDS Hooks logos can be used in connection with: scholastic publications, news reports, conferences, meetings, seminars and webinars the sale, promotion and advertising of products that are compatible with CDS Hooks","title":"Logo Use"},{"location":"logo-use/#use-of-cds-hooks-logos","text":"The CDS Hooks logos are owned by The Children's Medical Center Corporation and may be used in accordance with guidelines and policy at https://smarthealthit.org/cds-hooks-logo . These guidelines describe how CDS Hooks logos can be used in connection with: scholastic publications, news reports, conferences, meetings, seminars and webinars the sale, promotion and advertising of products that are compatible with CDS Hooks","title":"Use of CDS Hooks Logos"},{"location":"quickstart/","text":"Quick Start \u00b6 This quick start tutorial defines each of the actors and provides details for implementing the patient-view hook. A CDS Hooks scenario typically includes two main actors: an CDS Client and a CDS Service, where the CDS Client may be an EHR, CPOE or other clinical workflow system. Below is an example interaction for the patient-view hook. Building a CDS Service \u00b6 A CDS Service is an external service that responds to CDS Client requests through cards. A card can optionally link to a SMART app. There are several steps to setting up a CDS Service: Create an endpoint for discovery Develop a service Test the service with the sandbox If applicable, create a SMART app (or borrow one ) Test the service (and, if applicable, SMART app) with an CDS Client This tutorial recommends implementing the CDS Hooks security model after successful open access testing. Endpoint for discovery \u00b6 The CDS Service must provide a stable endpoint for the CDS Client to discover the available services. A system must expose their services at {baseUrl}/cds-services . A service endpoint that supports the patient-view hook may return: 1 2 3 4 5 6 7 8 9 10 11 12 13 { \"services\" : [ { \"hook\" : \"patient-view\" , \"name\" : \"Static CDS Service Example\" , \"description\" : \"An example of a CDS Service that returns a card with SMART app recommendations.\" , \"id\" : \"static-patient-view\" , \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } } ] } The attributes available to describe a CDS Services is documented in the CDS Hooks specification . Develop a service \u00b6 With a stable open end point available it's time to complete development of a service. A CDS Service could provide information , a suggestion , or a SMART app link. The focus of the Argonaut CDS Hooks effort is a patient-view hook launching a SMART app so this guide will focus on the SMART app link. A CDS patient-view hook could return the following card: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { \"cards\" : [ { \"summary\" : \"SMART App Success Card\" , \"indicator\" : \"success\" , \"detail\" : \"This is an example SMART App success card.\" , \"source\" : { \"label\" : \"Static CDS Service Example\" , \"url\" : \"https://example.com\" }, \"links\" : [ { \"label\" : \"SMART Example App\" , \"url\" : \"https://smart.example.com/launch\" , \"type\" : \"smart\" } ] } ] } Create a SMART App \u00b6 You may already have created a SMART app prior to this step, but just in case this is a reminder. The SMART app is launched from the link returned in your service. If you want to borrow a SMART app, check out the app gallery . Test service with a sandbox \u00b6 The CDS Hooks community provides a publicly available sandbox to test your service. Select the configure hooks: Delete the existing hooks, and then do a quick add with a reference to your CDS Service: After testing with the sandbox, you are ready to connect with an CDS Client. Integrating CDS Services into a CDS Client \u00b6 Build out following sections: Call discovery endpoint Invoke service on patient-view Support FHIR resource on CDS requests (context or pre-fetch) Expose non-secured FHIR server for testing Render card Launch SMART app Test with external CDS Service This tutorial recommends implementing the CDS Hooks security model after successful open access testing. Call discovery endpoint \u00b6 The CDS discovery endpoint provides the list of services a CDS provider supports, and the hooks a service should be invoked on. A CDS Client 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 a CDS Client will support. Below is an example work flow where a business analyst accesses this list of available services by calling GET https://example.com/cds-services and then configures them in the system. This image captures a business analyst reviewing services from one CDS provider. A business analyst may review services from multiple providers and configure appropriate services per user profiles. Invoke service on patient-view hook \u00b6 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 CDS Client to decide which characteristics to consider. Support FHIR resource on CDS requests (context or pre-fetch) \u00b6 Often a CDS Service will require additional information from the CDS Client to perform the decision support logic, or determine the appropriate SMART app to return. Prefetch provides the CDS Client 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: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { \"hookInstance\" : \"23f1a303-991f-4118-86c5-11d99a39222e\" , \"fhirServer\" : \"https://fhir.example.org\" , \"hook\" : \"patient-view\" , \"context\" : { \"patientId\" : \"1288992\" , \"userId\" : \"Practitioner/example\" }, \"prefetch\" : { \"patientToGreet\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1925-12-23\" , \"id\" : \"1288992\" , \"active\" : true } } } In some cases, additional information beyond what is included in the prefetch may be required. The CDS Service can request additional information using the FHIR REST APIs: GET [base]/AllergyIntolerance?patient=[id] 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) and HL7 US Core (STU3 and R4) . Each profile page within these implementation guides includes queries FHIR servers are required to support. Expose non-secured FHIR server for testing \u00b6 A non-secured FHIR server is important to support testing with a CDS Service. When the CDS Client moves a hook to production the system is expected to follow the guidelines in the security requirements. Render card \u00b6 The CDS Service will provide a response in the form a of a 'card'. Your CDS Client needs to be able to display the card. Example card JSON: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { \"summary\" : \"Bilirubin: Based on the age of this patient consider overlaying bilirubin [Mass/volume] results over a time-based risk chart\" , \"indicator\" : \"info\" , \"detail\" : \"The focus of this app is to reduce the incidence of severe hyperbilirubinemia and bilirubin encephalopathy while minimizing the risks of unintended harm such as maternal anxiety, decreased breastfeeding, and unnecessary costs or treatment.\" , \"source\" : { \"label\" : \"Intermountain\" , \"url\" : null }, \"links\" : [ { \"label\" : \"Bilirubin SMART app\" , \"url\" : \"https://example.com/launch\" , \"type\" : \"smart\" } ] } Example card rendered: Launch SMART app \u00b6 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 . Test with external CDS Service \u00b6 No development is complete without testing with a CDS Service provider. Find a member in the community and test away.","title":"Quick Start"},{"location":"quickstart/#quick-start","text":"This quick start tutorial defines each of the actors and provides details for implementing the patient-view hook. A CDS Hooks scenario typically includes two main actors: an CDS Client and a CDS Service, where the CDS Client may be an EHR, CPOE or other clinical workflow system. Below is an example interaction for the patient-view hook.","title":"Quick Start"},{"location":"quickstart/#building-a-cds-service","text":"A CDS Service is an external service that responds to CDS Client requests through cards. A card can optionally link to a SMART app. There are several steps to setting up a CDS Service: Create an endpoint for discovery Develop a service Test the service with the sandbox If applicable, create a SMART app (or borrow one ) Test the service (and, if applicable, SMART app) with an CDS Client This tutorial recommends implementing the CDS Hooks security model after successful open access testing.","title":"Building a CDS Service"},{"location":"quickstart/#endpoint-for-discovery","text":"The CDS Service must provide a stable endpoint for the CDS Client to discover the available services. A system must expose their services at {baseUrl}/cds-services . A service endpoint that supports the patient-view hook may return: 1 2 3 4 5 6 7 8 9 10 11 12 13 { \"services\" : [ { \"hook\" : \"patient-view\" , \"name\" : \"Static CDS Service Example\" , \"description\" : \"An example of a CDS Service that returns a card with SMART app recommendations.\" , \"id\" : \"static-patient-view\" , \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } } ] } The attributes available to describe a CDS Services is documented in the CDS Hooks specification .","title":"Endpoint for discovery"},{"location":"quickstart/#develop-a-service","text":"With a stable open end point available it's time to complete development of a service. A CDS Service could provide information , a suggestion , or a SMART app link. The focus of the Argonaut CDS Hooks effort is a patient-view hook launching a SMART app so this guide will focus on the SMART app link. A CDS patient-view hook could return the following card: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { \"cards\" : [ { \"summary\" : \"SMART App Success Card\" , \"indicator\" : \"success\" , \"detail\" : \"This is an example SMART App success card.\" , \"source\" : { \"label\" : \"Static CDS Service Example\" , \"url\" : \"https://example.com\" }, \"links\" : [ { \"label\" : \"SMART Example App\" , \"url\" : \"https://smart.example.com/launch\" , \"type\" : \"smart\" } ] } ] }","title":"Develop a service"},{"location":"quickstart/#create-a-smart-app","text":"You may already have created a SMART app prior to this step, but just in case this is a reminder. The SMART app is launched from the link returned in your service. If you want to borrow a SMART app, check out the app gallery .","title":"Create a SMART App"},{"location":"quickstart/#test-service-with-a-sandbox","text":"The CDS Hooks community provides a publicly available sandbox to test your service. Select the configure hooks: Delete the existing hooks, and then do a quick add with a reference to your CDS Service: After testing with the sandbox, you are ready to connect with an CDS Client.","title":"Test service with a sandbox"},{"location":"quickstart/#integrating-cds-services-into-a-cds-client","text":"Build out following sections: Call discovery endpoint Invoke service on patient-view Support FHIR resource on CDS requests (context or pre-fetch) Expose non-secured FHIR server for testing Render card Launch SMART app Test with external CDS Service This tutorial recommends implementing the CDS Hooks security model after successful open access testing.","title":"Integrating CDS Services into a CDS Client"},{"location":"quickstart/#call-discovery-endpoint","text":"The CDS discovery endpoint provides the list of services a CDS provider supports, and the hooks a service should be invoked on. A CDS Client 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 a CDS Client will support. Below is an example work flow where a business analyst accesses this list of available services by calling GET https://example.com/cds-services and then configures them in the system. This image captures a business analyst reviewing services from one CDS provider. A business analyst may review services from multiple providers and configure appropriate services per user profiles.","title":"Call discovery endpoint"},{"location":"quickstart/#invoke-service-on-patient-view-hook","text":"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 CDS Client to decide which characteristics to consider.","title":"Invoke service on patient-view hook"},{"location":"quickstart/#support-fhir-resource-on-cds-requests-context-or-pre-fetch","text":"Often a CDS Service will require additional information from the CDS Client to perform the decision support logic, or determine the appropriate SMART app to return. Prefetch provides the CDS Client 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: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { \"hookInstance\" : \"23f1a303-991f-4118-86c5-11d99a39222e\" , \"fhirServer\" : \"https://fhir.example.org\" , \"hook\" : \"patient-view\" , \"context\" : { \"patientId\" : \"1288992\" , \"userId\" : \"Practitioner/example\" }, \"prefetch\" : { \"patientToGreet\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1925-12-23\" , \"id\" : \"1288992\" , \"active\" : true } } } In some cases, additional information beyond what is included in the prefetch may be required. The CDS Service can request additional information using the FHIR REST APIs: GET [base]/AllergyIntolerance?patient=[id] 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) and HL7 US Core (STU3 and R4) . Each profile page within these implementation guides includes queries FHIR servers are required to support.","title":"Support FHIR resource on CDS requests (context or pre-fetch)"},{"location":"quickstart/#expose-non-secured-fhir-server-for-testing","text":"A non-secured FHIR server is important to support testing with a CDS Service. When the CDS Client moves a hook to production the system is expected to follow the guidelines in the security requirements.","title":"Expose non-secured FHIR server for testing"},{"location":"quickstart/#render-card","text":"The CDS Service will provide a response in the form a of a 'card'. Your CDS Client needs to be able to display the card. Example card JSON: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { \"summary\" : \"Bilirubin: Based on the age of this patient consider overlaying bilirubin [Mass/volume] results over a time-based risk chart\" , \"indicator\" : \"info\" , \"detail\" : \"The focus of this app is to reduce the incidence of severe hyperbilirubinemia and bilirubin encephalopathy while minimizing the risks of unintended harm such as maternal anxiety, decreased breastfeeding, and unnecessary costs or treatment.\" , \"source\" : { \"label\" : \"Intermountain\" , \"url\" : null }, \"links\" : [ { \"label\" : \"Bilirubin SMART app\" , \"url\" : \"https://example.com/launch\" , \"type\" : \"smart\" } ] } Example card rendered:","title":"Render card"},{"location":"quickstart/#launch-smart-app","text":"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 .","title":"Launch SMART app"},{"location":"quickstart/#test-with-external-cds-service","text":"No development is complete without testing with a CDS Service provider. Find a member in the community and test away.","title":"Test with external CDS Service"},{"location":"cheat-sheet/","text":"CDS Hooks Cheat Sheet \u00b6 Whether for general development or distribution at events, it's helpful to have a concise \"cheat sheet\" as a reminder of essential structures and syntax. The Markdown version in this folder is meant to provide the source of truth content for such a doument, leaving further formatting and arrangement up to the consumer. A rendered version created by Firely based on the markdown is also available within this folder and linked to in the navigation section.","title":"CDS Hooks Cheat Sheet"},{"location":"cheat-sheet/#cds-hooks-cheat-sheet","text":"Whether for general development or distribution at events, it's helpful to have a concise \"cheat sheet\" as a reminder of essential structures and syntax. The Markdown version in this folder is meant to provide the source of truth content for such a doument, leaving further formatting and arrangement up to the consumer. A rendered version created by Firely based on the markdown is also available within this folder and linked to in the navigation section.","title":"CDS Hooks Cheat Sheet"},{"location":"cheat-sheet/cheat-sheet/","text":"Overview \u00b6 Links \u00b6 Spec: https://cds-hooks.hl7.org/1.0/ Sandbox: http://sandbox.cds-hooks.org/ Quick Start: https://cds-hooks.org/quickstart/ CDS Service Discovery \u00b6 GET {baseUrl}/cds-services Response Body \u00b6 services - An array of CDS Service s CDS Service: \u00b6 Field Optionality Summary hook REQUIRED hook this service should be invoked on title RECOMMENDED human-friendly name of this service description REQUIRED description of this service id REQUIRED {id} portion of service URL: {baseUrl}/cds-services/{id} prefetch OPTIONAL Object containing key/value pairs of FHIR queries that this service is requesting the CDS Client to include on service calls Example \u00b6 { \"services\": [ { \"hook\": \"hook-noun-verb\", \"title\": \"CDS Service Example\", \"description\": \"An example of a CDS Service that returns a card\", \"id\": \"patient-greeter\", \"prefetch\": { \"patientToGreet\": \"Patient/{{context.patientId}}\" } } ] } CDS Service Request \u00b6 POST {baseUrl}/cds-services/{id} Request Body \u00b6 Field Optionality Summary hook REQUIRED hook that triggered this CDS Service call hookInstance REQUIRED UUID for this hook call fhirServer OPTIONAL base URL for CDS Client\u2019s FHIR server fhirAuthorization OPTIONAL structure with FHIR Authorization information for the above url context REQUIRED hook-specific contextual data prefetch OPTIONAL FHIR data prefetched by the CDS Client FHIR Authorization \u00b6 Field Optionality Summary access_token REQUIRED OAuth 2.0 access token token_type REQUIRED fixed value: Bearer expires_in REQUIRED lifetime in seconds of the access token scope REQUIRED scopes the access token grants to the CDS Service subject REQUIRED OAuth 2.0 client id of the CDS Service\u2019s auth server registration Example ## \u00b6 { \"hook\": \"hook-noun-verb\", \"hookInstance\": \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\", \"fhirServer\": \"https://fhir.client.com/version\", \"fhirAuthorization\": { \"access_token\": \"opaque-token\", \"...\": \"<snipped for brevity>\" }, \"context\": { \"userId\": \"Practitioner/example\", \"...\": \"<snipped for brevity>\" }, \"prefetch\": { \"patientToGreet\": { \"resourceType\": \"Patient\", \"...\": \"<snipped for brevity>\" } } } CDS Service Response Body \u00b6 Field Optionality Summary cards REQUIRED an array of Card s with a combination of information, suggested actions, and links Card \u00b6 Field Optionality Summary summary REQUIRED <140-character summary sentence for display to the user inside of this card detail OPTIONAL optional detailed information to display (GitHub Flavored Markdown) indicator REQUIRED urgency/importance of what this card conveys ( info/warning/critical ) source REQUIRED grouping structure for the Source of information displayed on this card suggestions OPTIONAL array of Suggestion s for changes in the context of the current activity selectionBehavior OPTIONAL intended behavior of the suggestions. If suggestions present, value must be at-most-one links OPTIONAL array of Link s to suggest an app or other additional information Source \u00b6 Field Optionality Summary label REQUIRED short, human-readable label to display source of the card\u2019s information url OPTIONAL optional absolute URL to load to learn more about the organization or data set icon OPTIONAL absolute url for an icon for the source of this card (100x100 pixel PNG without any transparent regions) Suggestion \u00b6 Field Optionality Summary label REQUIRED human-readable label to display for this suggestion uuid OPTIONAL unique identifier for auditing and logging suggestions actions OPTIONAL array of suggested Actions (logically AND\u2019d together) Action \u00b6 Field Optionality Summary type REQUIRED type of action being performed ( create/update/delete ) description REQUIRED human-readable description of the suggested action resource OPTIONAL FHIR resource to create/update or id of resource to delete Link \u00b6 Field Optionality Summary label REQUIRED human-readable label to display url REQUIRED URL to GET when link is clicked type REQUIRED type of the given URL ( absolute/smart ) appContext OPTIONAL additional context to share with a linked SMART app Example \u00b6 { \"cards\": [ { \"summary\": \"<140 char Summary Message\", \"detail\": \"optional GitHub Markdown details\", \"indicator\": \"info\", \"source\": { \"label\": \"Human-readable source label\", \"url\": \"https://example.com\", \"icon\": \"https://example.com/img/icon-100px.png\" }, \"suggestions\": [ { \"label\": \"Human-readable suggestion label\", \"uuid\": \"e1187895-ad57-4ff7-a1f1-ccf954b2fe46\", \"actions\": [ { \"type\": \"create\", \"description\": \"Create a prescription for Acetaminophen 250 MG\", \"resource\": { \"resourceType\": \"MedicationRequest\", \"...\": \"<snipped for brevity>\" } } ] } ], \"links\": [ { \"label\": \"SMART Example App\", \"...\": \"<snipped for brevity>\" } ] } ] }","title":"Overview"},{"location":"cheat-sheet/cheat-sheet/#overview","text":"","title":"Overview"},{"location":"cheat-sheet/cheat-sheet/#links","text":"Spec: https://cds-hooks.hl7.org/1.0/ Sandbox: http://sandbox.cds-hooks.org/ Quick Start: https://cds-hooks.org/quickstart/","title":"Links"},{"location":"cheat-sheet/cheat-sheet/#cds-service-discovery","text":"GET {baseUrl}/cds-services","title":"CDS Service Discovery"},{"location":"cheat-sheet/cheat-sheet/#response-body","text":"services - An array of CDS Service s","title":"Response Body"},{"location":"cheat-sheet/cheat-sheet/#cds-service","text":"Field Optionality Summary hook REQUIRED hook this service should be invoked on title RECOMMENDED human-friendly name of this service description REQUIRED description of this service id REQUIRED {id} portion of service URL: {baseUrl}/cds-services/{id} prefetch OPTIONAL Object containing key/value pairs of FHIR queries that this service is requesting the CDS Client to include on service calls","title":"CDS Service:"},{"location":"cheat-sheet/cheat-sheet/#example","text":"{ \"services\": [ { \"hook\": \"hook-noun-verb\", \"title\": \"CDS Service Example\", \"description\": \"An example of a CDS Service that returns a card\", \"id\": \"patient-greeter\", \"prefetch\": { \"patientToGreet\": \"Patient/{{context.patientId}}\" } } ] }","title":"Example"},{"location":"cheat-sheet/cheat-sheet/#cds-service-request","text":"POST {baseUrl}/cds-services/{id}","title":"CDS Service Request"},{"location":"cheat-sheet/cheat-sheet/#request-body","text":"Field Optionality Summary hook REQUIRED hook that triggered this CDS Service call hookInstance REQUIRED UUID for this hook call fhirServer OPTIONAL base URL for CDS Client\u2019s FHIR server fhirAuthorization OPTIONAL structure with FHIR Authorization information for the above url context REQUIRED hook-specific contextual data prefetch OPTIONAL FHIR data prefetched by the CDS Client","title":"Request Body"},{"location":"cheat-sheet/cheat-sheet/#fhir-authorization","text":"Field Optionality Summary access_token REQUIRED OAuth 2.0 access token token_type REQUIRED fixed value: Bearer expires_in REQUIRED lifetime in seconds of the access token scope REQUIRED scopes the access token grants to the CDS Service subject REQUIRED OAuth 2.0 client id of the CDS Service\u2019s auth server registration","title":"FHIR Authorization"},{"location":"cheat-sheet/cheat-sheet/#example_1","text":"{ \"hook\": \"hook-noun-verb\", \"hookInstance\": \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\", \"fhirServer\": \"https://fhir.client.com/version\", \"fhirAuthorization\": { \"access_token\": \"opaque-token\", \"...\": \"<snipped for brevity>\" }, \"context\": { \"userId\": \"Practitioner/example\", \"...\": \"<snipped for brevity>\" }, \"prefetch\": { \"patientToGreet\": { \"resourceType\": \"Patient\", \"...\": \"<snipped for brevity>\" } } }","title":"Example ##"},{"location":"cheat-sheet/cheat-sheet/#cds-service-response-body","text":"Field Optionality Summary cards REQUIRED an array of Card s with a combination of information, suggested actions, and links","title":"CDS Service Response Body"},{"location":"cheat-sheet/cheat-sheet/#card","text":"Field Optionality Summary summary REQUIRED <140-character summary sentence for display to the user inside of this card detail OPTIONAL optional detailed information to display (GitHub Flavored Markdown) indicator REQUIRED urgency/importance of what this card conveys ( info/warning/critical ) source REQUIRED grouping structure for the Source of information displayed on this card suggestions OPTIONAL array of Suggestion s for changes in the context of the current activity selectionBehavior OPTIONAL intended behavior of the suggestions. If suggestions present, value must be at-most-one links OPTIONAL array of Link s to suggest an app or other additional information","title":"Card"},{"location":"cheat-sheet/cheat-sheet/#source","text":"Field Optionality Summary label REQUIRED short, human-readable label to display source of the card\u2019s information url OPTIONAL optional absolute URL to load to learn more about the organization or data set icon OPTIONAL absolute url for an icon for the source of this card (100x100 pixel PNG without any transparent regions)","title":"Source"},{"location":"cheat-sheet/cheat-sheet/#suggestion","text":"Field Optionality Summary label REQUIRED human-readable label to display for this suggestion uuid OPTIONAL unique identifier for auditing and logging suggestions actions OPTIONAL array of suggested Actions (logically AND\u2019d together)","title":"Suggestion"},{"location":"cheat-sheet/cheat-sheet/#action","text":"Field Optionality Summary type REQUIRED type of action being performed ( create/update/delete ) description REQUIRED human-readable description of the suggested action resource OPTIONAL FHIR resource to create/update or id of resource to delete","title":"Action"},{"location":"cheat-sheet/cheat-sheet/#link","text":"Field Optionality Summary label REQUIRED human-readable label to display url REQUIRED URL to GET when link is clicked type REQUIRED type of the given URL ( absolute/smart ) appContext OPTIONAL additional context to share with a linked SMART app","title":"Link"},{"location":"cheat-sheet/cheat-sheet/#example_2","text":"{ \"cards\": [ { \"summary\": \"<140 char Summary Message\", \"detail\": \"optional GitHub Markdown details\", \"indicator\": \"info\", \"source\": { \"label\": \"Human-readable source label\", \"url\": \"https://example.com\", \"icon\": \"https://example.com/img/icon-100px.png\" }, \"suggestions\": [ { \"label\": \"Human-readable suggestion label\", \"uuid\": \"e1187895-ad57-4ff7-a1f1-ccf954b2fe46\", \"actions\": [ { \"type\": \"create\", \"description\": \"Create a prescription for Acetaminophen 250 MG\", \"resource\": { \"resourceType\": \"MedicationRequest\", \"...\": \"<snipped for brevity>\" } } ] } ], \"links\": [ { \"label\": \"SMART Example App\", \"...\": \"<snipped for brevity>\" } ] } ] }","title":"Example"},{"location":"hooks/appointment-book/","text":"appointment-book \u00b6 Looking for Feedback Hey implementers, we want to hear from you! - What obstacles are there to limiting this hook to firing only when the appointment is confirmed or finalized as booked? - For which users should this hook fire? - Many appointments are scheduled directly into the EHR by the patient, without provider staff involvement ... Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted Workflow \u00b6 This hook is invoked when the user is scheduling one or more future encounters/visits for the patient. For example, the appointment-book hook may be triggered for an appointment with the appointment creator, a clinician within the same organization as the appointment creator or even for an appointment outside the creator's organization. It may be invoked at the start and end of the booking process and/or any time between those two points. This hook enables CDS Services to intervene in the decision of when future appointments should be scheduled, where they should be scheduled, what services should be booked, to identify actions that need to occur prior to scheduled appointments, etc. Context \u00b6 The Patient whose appointment(s) are being booked, as well as the proposed Appointment records. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user could be of type Practitioner , PractitionerRole , Patient , or RelatedPerson . For example, PractitionerRole/123 . Patient or RelatedPerson are appropriate when a patient or their proxy are booking the appointment. patientId REQUIRED Yes string The FHIR Patient.id of Patient appointment(s) is/are for encounterId OPTIONAL Yes string The FHIR Encounter.id of Encounter where booking was initiated appointments REQUIRED No object DSTU2/STU3/R4 - FHIR Bundle of Appointments in 'proposed' state Examples (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"appointments\" : [ { \"resourceType\" : \"Appointment\" , \"id\" : \"apt1\" , \"status\" : \"proposed\" , \"serviceType\" : [ { \"coding\" : [ { \"code\" : \"183\" , \"display\" : \"Sleep Medicine\" } ] } ], \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v2/0276\" , \"code\" : \"FOLLOWUP\" , \"display\" : \"A follow up visit from a previous appointment\" } ] }, \"reason\" : { \"coding\" : { \"system\" : \"\" , \"code\" : \"1023001\" , \"display\" : \"Apnea\" } }, \"description\" : \"CPAP adjustments\" , \"start\" : \"2019-08-10T09:00:00-06:00\" , \"end\" : \"2019-08-10T09:10:00:00-06:00\" , \"created\" : \"2019-08-01\" , \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" } ] }, { \"resourceType\" : \"Appointment\" , \"id\" : \"apt1\" , \"status\" : \"proposed\" , \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v2/0276\" , \"code\" : \"CHECKUP\" , \"display\" : \"A routine check-up, such as an annual physical\" } ] }, \"description\" : \"Regular physical\" , \"start\" : \"2020-08-01T13:00:00-06:00\" , \"end\" : \"2020-08-01T13:30:00:00-06:00\" , \"created\" : \"2019-08-01\" , \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" } ] } ] } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" , \"appointments\" : [ { \"resourceType\" : \"Appointment\" , \"id\" : \"example\" , \"text\" : { \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Brian MRI results discussion</div>\" }, \"status\" : \"proposed\" , \"serviceCategory\" : { \"coding\" : [ { \"system\" : \"http://example.org/service-category\" , \"code\" : \"gp\" , \"display\" : \"General Practice\" } ] }, \"serviceType\" : [ { \"coding\" : [ { \"code\" : \"52\" , \"display\" : \"General Discussion\" } ] } ], \"specialty\" : [ { \"coding\" : [ { \"system\" : \"http://example.org/specialty\" , \"code\" : \"gp\" , \"display\" : \"General Practice\" } ] } ], \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://example.org/appointment-type\" , \"code\" : \"follow\" , \"display\" : \"Followup\" } ] }, \"indication\" : [ { \"reference\" : \"Condition/example\" , \"display\" : \"Severe burn of left ear\" } ], \"priority\" : 5 , \"description\" : \"Discussion on the results of your recent MRI\" , \"start\" : \"2013-12-10T09:00:00Z\" , \"end\" : \"2013-12-10T11:00:00Z\" , \"created\" : \"2013-10-10\" , \"comment\" : \"Further expand on the results of the MRI and determine the next actions that may be appropriate.\" , \"incomingReferral\" : [ { \"reference\" : \"ReferralRequest/example\" } ], \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"type\" : [ { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v3/ParticipationType\" , \"code\" : \"ATND\" } ] } ], \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" }, { \"actor\" : { \"reference\" : \"Location/1\" , \"display\" : \"South Wing, second floor\" }, \"required\" : \"required\" , \"status\" : \"action-needed\" } ] } ] } Change Log \u00b6 Version Description 1.0 Initial Release","title":"appointment-book 1"},{"location":"hooks/appointment-book/#appointment-book","text":"Looking for Feedback Hey implementers, we want to hear from you! - What obstacles are there to limiting this hook to firing only when the appointment is confirmed or finalized as booked? - For which users should this hook fire? - Many appointments are scheduled directly into the EHR by the patient, without provider staff involvement ... Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted","title":"appointment-book"},{"location":"hooks/appointment-book/#workflow","text":"This hook is invoked when the user is scheduling one or more future encounters/visits for the patient. For example, the appointment-book hook may be triggered for an appointment with the appointment creator, a clinician within the same organization as the appointment creator or even for an appointment outside the creator's organization. It may be invoked at the start and end of the booking process and/or any time between those two points. This hook enables CDS Services to intervene in the decision of when future appointments should be scheduled, where they should be scheduled, what services should be booked, to identify actions that need to occur prior to scheduled appointments, etc.","title":"Workflow"},{"location":"hooks/appointment-book/#context","text":"The Patient whose appointment(s) are being booked, as well as the proposed Appointment records. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user could be of type Practitioner , PractitionerRole , Patient , or RelatedPerson . For example, PractitionerRole/123 . Patient or RelatedPerson are appropriate when a patient or their proxy are booking the appointment. patientId REQUIRED Yes string The FHIR Patient.id of Patient appointment(s) is/are for encounterId OPTIONAL Yes string The FHIR Encounter.id of Encounter where booking was initiated appointments REQUIRED No object DSTU2/STU3/R4 - FHIR Bundle of Appointments in 'proposed' state","title":"Context"},{"location":"hooks/appointment-book/#examples-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"appointments\" : [ { \"resourceType\" : \"Appointment\" , \"id\" : \"apt1\" , \"status\" : \"proposed\" , \"serviceType\" : [ { \"coding\" : [ { \"code\" : \"183\" , \"display\" : \"Sleep Medicine\" } ] } ], \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v2/0276\" , \"code\" : \"FOLLOWUP\" , \"display\" : \"A follow up visit from a previous appointment\" } ] }, \"reason\" : { \"coding\" : { \"system\" : \"\" , \"code\" : \"1023001\" , \"display\" : \"Apnea\" } }, \"description\" : \"CPAP adjustments\" , \"start\" : \"2019-08-10T09:00:00-06:00\" , \"end\" : \"2019-08-10T09:10:00:00-06:00\" , \"created\" : \"2019-08-01\" , \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" } ] }, { \"resourceType\" : \"Appointment\" , \"id\" : \"apt1\" , \"status\" : \"proposed\" , \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v2/0276\" , \"code\" : \"CHECKUP\" , \"display\" : \"A routine check-up, such as an annual physical\" } ] }, \"description\" : \"Regular physical\" , \"start\" : \"2020-08-01T13:00:00-06:00\" , \"end\" : \"2020-08-01T13:30:00:00-06:00\" , \"created\" : \"2019-08-01\" , \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" } ] } ] } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" , \"appointments\" : [ { \"resourceType\" : \"Appointment\" , \"id\" : \"example\" , \"text\" : { \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Brian MRI results discussion</div>\" }, \"status\" : \"proposed\" , \"serviceCategory\" : { \"coding\" : [ { \"system\" : \"http://example.org/service-category\" , \"code\" : \"gp\" , \"display\" : \"General Practice\" } ] }, \"serviceType\" : [ { \"coding\" : [ { \"code\" : \"52\" , \"display\" : \"General Discussion\" } ] } ], \"specialty\" : [ { \"coding\" : [ { \"system\" : \"http://example.org/specialty\" , \"code\" : \"gp\" , \"display\" : \"General Practice\" } ] } ], \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://example.org/appointment-type\" , \"code\" : \"follow\" , \"display\" : \"Followup\" } ] }, \"indication\" : [ { \"reference\" : \"Condition/example\" , \"display\" : \"Severe burn of left ear\" } ], \"priority\" : 5 , \"description\" : \"Discussion on the results of your recent MRI\" , \"start\" : \"2013-12-10T09:00:00Z\" , \"end\" : \"2013-12-10T11:00:00Z\" , \"created\" : \"2013-10-10\" , \"comment\" : \"Further expand on the results of the MRI and determine the next actions that may be appropriate.\" , \"incomingReferral\" : [ { \"reference\" : \"ReferralRequest/example\" } ], \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"type\" : [ { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v3/ParticipationType\" , \"code\" : \"ATND\" } ] } ], \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" }, { \"actor\" : { \"reference\" : \"Location/1\" , \"display\" : \"South Wing, second floor\" }, \"required\" : \"required\" , \"status\" : \"action-needed\" } ] } ] }","title":"Examples (STU3)"},{"location":"hooks/appointment-book/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/encounter-discharge/","text":"encounter-discharge \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted Workflow \u00b6 This hook is invoked when the user is performing the discharge process for an encounter where the notion of 'discharge' is relevant - typically an inpatient encounter. It may be invoked at the start and end of the discharge process or any time between those two points. It allows hook services to intervene in the decision of whether discharge is appropriate, to verify discharge medications, to check for continuity of care planning, to ensure necessary documentation is present for discharge processing, etc. Context \u00b6 The patient who is being discharged and the encounter being ended. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, Practitioner/123 patientId REQUIRED Yes string The FHIR Patient.id of the being discharged encounterId REQUIRED Yes string The FHIR Encounter.id of the Encounter being ended Examples \u00b6 1 2 3 4 5 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" } Change Log \u00b6 Version Description 1.0 Initial Release","title":"encounter-discharge 1"},{"location":"hooks/encounter-discharge/#encounter-discharge","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted","title":"encounter-discharge"},{"location":"hooks/encounter-discharge/#workflow","text":"This hook is invoked when the user is performing the discharge process for an encounter where the notion of 'discharge' is relevant - typically an inpatient encounter. It may be invoked at the start and end of the discharge process or any time between those two points. It allows hook services to intervene in the decision of whether discharge is appropriate, to verify discharge medications, to check for continuity of care planning, to ensure necessary documentation is present for discharge processing, etc.","title":"Workflow"},{"location":"hooks/encounter-discharge/#context","text":"The patient who is being discharged and the encounter being ended. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, Practitioner/123 patientId REQUIRED Yes string The FHIR Patient.id of the being discharged encounterId REQUIRED Yes string The FHIR Encounter.id of the Encounter being ended","title":"Context"},{"location":"hooks/encounter-discharge/#examples","text":"1 2 3 4 5 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" }","title":"Examples"},{"location":"hooks/encounter-discharge/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/encounter-start/","text":"encounter-start \u00b6 Looking for Feedback Hey implementers, we want to hear from you! - What's the greatest opportunity for delivering remote CDS at the start of an encounter? - For which users should this hook fire? - When in a hospitalization workflow, an ambulatory workflow, does an encounter start? - How many and what types of encounters are there in a single hospitalization, a single ambulatory visit? - Is there value in an encounter start hook pairing with an (typically inpatient) encounter discharge hook? - Please explain your encounter workflow. Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted Workflow \u00b6 This hook is invoked when the user is initiating a new encounter. In an inpatient setting, this would be the time of admission. In an outpatient/community environment, this would be the time of patient-check-in for a face-to-face or equivalent for a virtual/telephone encounter. The Encounter should either be in one of the following states: planned | arrived | triaged | in-progress . Note that there can be multiple 'starts' for the same encounter as each user becomes engaged. For example, when a scheduled encounter is presented at the beginning of the day for planning purposes, when the patient arrives, when the patient first encounters a clinician, etc. Hooks may present different information depending on user role and Encounter.status. Note: This is distinct from the patient-view hook which occurs any time the patient's record is looked at - which might be done outside the context of any encounter and will often occur during workflows that are not linked to the initiation of an encounter. The intention is that the cards from any invoked CDS Services are available at the time when decisions are being made about what actions are going to occur during this encounter. For example, identifying that the patient is due for certain diagnostic tests or interventions, identifying additional information that should be collected to comply with protocols associated with clinical studies the patient is enrolled in, identifying any documentation or other requirements associated with patient insurance, etc. Context \u00b6 Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 patientId REQUIRED Yes string The FHIR Patient.id of the Patient the Encounter is for encounterId REQUIRED Yes string The FHIR Encounter.id of the Encounter being started Examples \u00b6 1 2 3 4 5 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" } Change Log \u00b6 Version Description 1.0 Initial Release","title":"encounter-start 1"},{"location":"hooks/encounter-start/#encounter-start","text":"Looking for Feedback Hey implementers, we want to hear from you! - What's the greatest opportunity for delivering remote CDS at the start of an encounter? - For which users should this hook fire? - When in a hospitalization workflow, an ambulatory workflow, does an encounter start? - How many and what types of encounters are there in a single hospitalization, a single ambulatory visit? - Is there value in an encounter start hook pairing with an (typically inpatient) encounter discharge hook? - Please explain your encounter workflow. Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted","title":"encounter-start"},{"location":"hooks/encounter-start/#workflow","text":"This hook is invoked when the user is initiating a new encounter. In an inpatient setting, this would be the time of admission. In an outpatient/community environment, this would be the time of patient-check-in for a face-to-face or equivalent for a virtual/telephone encounter. The Encounter should either be in one of the following states: planned | arrived | triaged | in-progress . Note that there can be multiple 'starts' for the same encounter as each user becomes engaged. For example, when a scheduled encounter is presented at the beginning of the day for planning purposes, when the patient arrives, when the patient first encounters a clinician, etc. Hooks may present different information depending on user role and Encounter.status. Note: This is distinct from the patient-view hook which occurs any time the patient's record is looked at - which might be done outside the context of any encounter and will often occur during workflows that are not linked to the initiation of an encounter. The intention is that the cards from any invoked CDS Services are available at the time when decisions are being made about what actions are going to occur during this encounter. For example, identifying that the patient is due for certain diagnostic tests or interventions, identifying additional information that should be collected to comply with protocols associated with clinical studies the patient is enrolled in, identifying any documentation or other requirements associated with patient insurance, etc.","title":"Workflow"},{"location":"hooks/encounter-start/#context","text":"Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 patientId REQUIRED Yes string The FHIR Patient.id of the Patient the Encounter is for encounterId REQUIRED Yes string The FHIR Encounter.id of the Encounter being started","title":"Context"},{"location":"hooks/encounter-start/#examples","text":"1 2 3 4 5 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" }","title":"Examples"},{"location":"hooks/encounter-start/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/medication-prescribe/","text":"medication-prescribe \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 2 - Tested Deprecation Notice \u00b6 This hook is deprecated in favor of the order-select and order-sign hooks, with the goal of clarifying workflow trigger points and supporting orders beyond medications. In this refactoring, medication-prescribe and order-review hooks are being deprecated in favor of newly created order-select and order-sign hooks. This notice is a placeholder to this effect while CDS Hooks determines the appropriate process for deprecating hooks . Workflow \u00b6 The user is in the process of prescribing one or more new medications. Context \u00b6 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 userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner . 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 STU3 - FHIR Bundle of draft MedicationRequest resources Example (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-104\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:26:48.124-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Azithromycin 20 MG/ML Oral Suspension [Zithromax] (rxnorm: 211307)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-104\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Change Log \u00b6 Version Description 1.0 Initial Release","title":"medication-prescribe \ud83d\udeab"},{"location":"hooks/medication-prescribe/#medication-prescribe","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 2 - Tested","title":"medication-prescribe"},{"location":"hooks/medication-prescribe/#deprecation-notice","text":"This hook is deprecated in favor of the order-select and order-sign hooks, with the goal of clarifying workflow trigger points and supporting orders beyond medications. In this refactoring, medication-prescribe and order-review hooks are being deprecated in favor of newly created order-select and order-sign hooks. This notice is a placeholder to this effect while CDS Hooks determines the appropriate process for deprecating hooks .","title":"Deprecation Notice"},{"location":"hooks/medication-prescribe/#workflow","text":"The user is in the process of prescribing one or more new medications.","title":"Workflow"},{"location":"hooks/medication-prescribe/#context","text":"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 userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner . 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 STU3 - FHIR Bundle of draft MedicationRequest resources","title":"Context"},{"location":"hooks/medication-prescribe/#example-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-104\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:26:48.124-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Azithromycin 20 MG/ML Oral Suspension [Zithromax] (rxnorm: 211307)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (STU3)"},{"location":"hooks/medication-prescribe/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-104\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (DSTU2)"},{"location":"hooks/medication-prescribe/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/medication-refill/","text":"medication-refill \u00b6 Metadata Value specificationVersion 2.0 hookVersion 0.1.0 hookMaturity 1 - Submitted Workflow \u00b6 The medication-refill hook fires when a medication refill request for an existing prescription of a specific medication is received. A refill request may be made as part of an encounter or out-of-band through a pharmacy or patient portal. Since a prescription refill is requested outside of the prescriber's workflow, there often is not a user in context. Similarly, the encounter may be an auto-generated refill encounter or there may not be an encounter in context when the refill request is received. A CDS service may use this hook to deliver medication refill protocol guidance to a clinician. Given the asynchronous workflow of refill requests, the guidance returned by the service may be viewed immediately, or not. This hook does not fire for an initial prescription (see order-sign). \"Re-prescribing\" or replacing a previously active prescription with a new perscription for the same medication does not fire the medication-refill. Context \u00b6 The set of medications in the process of being refilled. 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 userId OPTIONAL Yes string In the case when this field is empty, consider the FHIR resource's requestor and recorder elements. The id of the current user entering the refill request within the CPOE. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc. patientId REQUIRED Yes string The FHIR Patient.id of the current patient in context encounterId OPTIONAL Yes string The FHIR Encounter.id of the encounter associated with the refill of the prescription. medications REQUIRED No object R4 - FHIR Bundle of draft , order MedicationRequest resources Example (R4) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-104\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationReference\" : { \"reference\" : \"Medication/eFnx9hyX.YTNJ407PR9g4zpiT8lXCElOXkldLgGDYrAU-fszvYmrUZlYzRfJl-qKj3\" , \"display\" : \"oxybutynin (DITROPAN XL) CR tablet\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-104\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Change Log \u00b6 Version Description 0.1.0 Initial Release","title":"medication-refill 1"},{"location":"hooks/medication-refill/#medication-refill","text":"Metadata Value specificationVersion 2.0 hookVersion 0.1.0 hookMaturity 1 - Submitted","title":"medication-refill"},{"location":"hooks/medication-refill/#workflow","text":"The medication-refill hook fires when a medication refill request for an existing prescription of a specific medication is received. A refill request may be made as part of an encounter or out-of-band through a pharmacy or patient portal. Since a prescription refill is requested outside of the prescriber's workflow, there often is not a user in context. Similarly, the encounter may be an auto-generated refill encounter or there may not be an encounter in context when the refill request is received. A CDS service may use this hook to deliver medication refill protocol guidance to a clinician. Given the asynchronous workflow of refill requests, the guidance returned by the service may be viewed immediately, or not. This hook does not fire for an initial prescription (see order-sign). \"Re-prescribing\" or replacing a previously active prescription with a new perscription for the same medication does not fire the medication-refill.","title":"Workflow"},{"location":"hooks/medication-refill/#context","text":"The set of medications in the process of being refilled. 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 userId OPTIONAL Yes string In the case when this field is empty, consider the FHIR resource's requestor and recorder elements. The id of the current user entering the refill request within the CPOE. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc. patientId REQUIRED Yes string The FHIR Patient.id of the current patient in context encounterId OPTIONAL Yes string The FHIR Encounter.id of the encounter associated with the refill of the prescription. medications REQUIRED No object R4 - FHIR Bundle of draft , order MedicationRequest resources","title":"Context"},{"location":"hooks/medication-refill/#example-r4","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-104\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationReference\" : { \"reference\" : \"Medication/eFnx9hyX.YTNJ407PR9g4zpiT8lXCElOXkldLgGDYrAU-fszvYmrUZlYzRfJl-qKj3\" , \"display\" : \"oxybutynin (DITROPAN XL) CR tablet\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (R4)"},{"location":"hooks/medication-refill/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-104\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (DSTU2)"},{"location":"hooks/medication-refill/#change-log","text":"Version Description 0.1.0 Initial Release","title":"Change Log"},{"location":"hooks/order-dispatch/","text":"order-dispatch \u00b6 Metadata Value specificationVersion 2.0 hookVersion 1.1 hookMaturity 0 - Draft Workflow \u00b6 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 . 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. Decision support that may be relevant for this hook might include information related to coverage, prior-authorization and/or in-network/out-of-network evaluations with respect to the chosen performer; determination of practitioner availability or qualification; enforcement/guidance with respect to patient performer preferences; etc. Context \u00b6 Field Optionality Prefetch Token Type Description patientId REQUIRED Yes string The FHIR Patient.id of the current patient in context 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 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 \u00b6 Example (R4) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 \"context\" :{ \"patientId\" : \"1288992\" , \"dispatched-orders\" : [ \"ServiceRequest/proc002\" ], \"performer\" : \"Organization/some-performer\" , \"fulfillment-tasks\" : [{ \"resourceType\" : \"Task\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"code\" : { \"coding\" : [{ \"system\" : \"http://hl7.org/fhir/CodeSystem/task-code\" , \"code\" : \"fulfill\" }] }, \"focus\" : { \"reference\" : \"ServiceRequest/proc002\" }, \"for\" : { \"reference\" : \"Patient/1288992\" }, \"authoredOn\" : \"2016-03-10T22:39:32-04:00\" , \"lastModified\" : \"2016-03-10T22:39:32-04:00\" , \"requester\" : { \"reference\" : \"Practitioner/456\" }, \"owner\" : { \"reference\" : \"Organziation/some-performer\" } }] } Change Log \u00b6 Version Description 1.0 Initial Release 1.1 Adjusted context names and cardinalities based on feedback","title":"order-dispatch 0"},{"location":"hooks/order-dispatch/#order-dispatch","text":"Metadata Value specificationVersion 2.0 hookVersion 1.1 hookMaturity 0 - Draft","title":"order-dispatch"},{"location":"hooks/order-dispatch/#workflow","text":"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 . 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. Decision support that may be relevant for this hook might include information related to coverage, prior-authorization and/or in-network/out-of-network evaluations with respect to the chosen performer; determination of practitioner availability or qualification; enforcement/guidance with respect to patient performer preferences; etc.","title":"Workflow"},{"location":"hooks/order-dispatch/#context","text":"Field Optionality Prefetch Token Type Description patientId REQUIRED Yes string The FHIR Patient.id of the current patient in context 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 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.","title":"Context"},{"location":"hooks/order-dispatch/#examples","text":"","title":"Examples"},{"location":"hooks/order-dispatch/#example-r4","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 \"context\" :{ \"patientId\" : \"1288992\" , \"dispatched-orders\" : [ \"ServiceRequest/proc002\" ], \"performer\" : \"Organization/some-performer\" , \"fulfillment-tasks\" : [{ \"resourceType\" : \"Task\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"code\" : { \"coding\" : [{ \"system\" : \"http://hl7.org/fhir/CodeSystem/task-code\" , \"code\" : \"fulfill\" }] }, \"focus\" : { \"reference\" : \"ServiceRequest/proc002\" }, \"for\" : { \"reference\" : \"Patient/1288992\" }, \"authoredOn\" : \"2016-03-10T22:39:32-04:00\" , \"lastModified\" : \"2016-03-10T22:39:32-04:00\" , \"requester\" : { \"reference\" : \"Practitioner/456\" }, \"owner\" : { \"reference\" : \"Organziation/some-performer\" } }] }","title":"Example (R4)"},{"location":"hooks/order-dispatch/#change-log","text":"Version Description 1.0 Initial Release 1.1 Adjusted context names and cardinalities based on feedback","title":"Change Log"},{"location":"hooks/order-review/","text":"order-review \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 3 - Considered Deprecation Notice \u00b6 This hook is deprecated in favor of the order-sign hooks, with the goal of clarifying workflow trigger points and supporting orders beyond medications. In this refactoring, medication-prescribe and order-review hooks are being deprecated in favor of newly created order-select and order-sign hooks. This notice is a placeholder to this effect while CDS Hooks determines the appropriate process for deprecating hooks . Workflow \u00b6 The user is in the process of reviewing a set of orders to sign. Context \u00b6 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 orders object MUST have a status of draft . Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner . 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 STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status Example (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"orders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"orders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } Change Log \u00b6 Version Description 1.0 Initial Release","title":"order-review \ud83d\udeab"},{"location":"hooks/order-review/#order-review","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 3 - Considered","title":"order-review"},{"location":"hooks/order-review/#deprecation-notice","text":"This hook is deprecated in favor of the order-sign hooks, with the goal of clarifying workflow trigger points and supporting orders beyond medications. In this refactoring, medication-prescribe and order-review hooks are being deprecated in favor of newly created order-select and order-sign hooks. This notice is a placeholder to this effect while CDS Hooks determines the appropriate process for deprecating hooks .","title":"Deprecation Notice"},{"location":"hooks/order-review/#workflow","text":"The user is in the process of reviewing a set of orders to sign.","title":"Workflow"},{"location":"hooks/order-review/#context","text":"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 orders object MUST have a status of draft . Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner . 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 STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status","title":"Context"},{"location":"hooks/order-review/#example-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"orders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (STU3)"},{"location":"hooks/order-review/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"orders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } }","title":"Example (DSTU2)"},{"location":"hooks/order-review/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/order-select/","text":"order-select \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 4 - Documented Workflow \u00b6 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. This hook is intended to replace (deprecate) the medication-prescribe hook. Context \u00b6 Decision support should focus on the 'selected' orders - those that are newly selected or actively being authored. The non-selected orders are included in the context to provide context and to allow decision support to take into account other pending actions that might not yet be stored in the system (and therefore not queryable). The context of this hook distinguishes between the list of unsigned orders from the clinician's ordering session, and the one or more orders just added to this list. The selections field contains a list of ids of these newly selected orders; the draftOrders Bundle contains an entry for all unsigned orders from this session, including newly selected orders. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 or Practitioner/abc . 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 selections REQUIRED No array The FHIR id of the newly selected order(s). The selections field references FHIR resources in the draftOrders Bundle. For example, MedicationRequest/103 . draftOrders REQUIRED No object DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status R4 - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription with draft status Examples \u00b6 Example (R4) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 { \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"NutritionOrder/pureeddiet-simple\" , \"MedicationRequest/smart-MedicationRequest-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseAndRate\" :{ \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 { \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"NutritionOrder/pureeddiet-simple\" , \"MedicationRequest/smart-MedicationRequest-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" :[ \"NutritionOrder/nest-patient-1-NUTR1\" , \"MedicationOrder/smart-MedicationOrder-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } Change Log \u00b6 Version Description 1.0 Initial Release 1.0.1 Small documentation correction 1.0.2 Add DeviceRequest to list of order resources for R4.","title":"order-select 4"},{"location":"hooks/order-select/#order-select","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 4 - Documented","title":"order-select"},{"location":"hooks/order-select/#workflow","text":"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. This hook is intended to replace (deprecate) the medication-prescribe hook.","title":"Workflow"},{"location":"hooks/order-select/#context","text":"Decision support should focus on the 'selected' orders - those that are newly selected or actively being authored. The non-selected orders are included in the context to provide context and to allow decision support to take into account other pending actions that might not yet be stored in the system (and therefore not queryable). The context of this hook distinguishes between the list of unsigned orders from the clinician's ordering session, and the one or more orders just added to this list. The selections field contains a list of ids of these newly selected orders; the draftOrders Bundle contains an entry for all unsigned orders from this session, including newly selected orders. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 or Practitioner/abc . 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 selections REQUIRED No array The FHIR id of the newly selected order(s). The selections field references FHIR resources in the draftOrders Bundle. For example, MedicationRequest/103 . draftOrders REQUIRED No object DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status R4 - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription with draft status","title":"Context"},{"location":"hooks/order-select/#examples","text":"","title":"Examples"},{"location":"hooks/order-select/#example-r4","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 { \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"NutritionOrder/pureeddiet-simple\" , \"MedicationRequest/smart-MedicationRequest-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseAndRate\" :{ \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (R4)"},{"location":"hooks/order-select/#example-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 { \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"NutritionOrder/pureeddiet-simple\" , \"MedicationRequest/smart-MedicationRequest-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (STU3)"},{"location":"hooks/order-select/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" :[ \"NutritionOrder/nest-patient-1-NUTR1\" , \"MedicationOrder/smart-MedicationOrder-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } }","title":"Example (DSTU2)"},{"location":"hooks/order-select/#change-log","text":"Version Description 1.0 Initial Release 1.0.1 Small documentation correction 1.0.2 Add DeviceRequest to list of order resources for R4.","title":"Change Log"},{"location":"hooks/order-sign/","text":"order-sign \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 5 - Mature Workflow \u00b6 The order-sign hook fires when a clinician is ready to sign one or more orders for a patient, (including orders for medications, procedures, labs and other 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. 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 case, the orders would typically have a status other than 'draft'. In some cases, the hook might fire with a mixture of new and revised orders. This hook is intended to replace (deprecate) the medication-prescribe and order-review hooks. Context \u00b6 Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 or Practitioner/abc . 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 draftOrders REQUIRED No object DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription (typically with draft status) STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription (typically with draft status) R4 - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription (typically with draft status) Examples \u00b6 Example (R4) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 { \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 { \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseAndRate\" :{ \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 \"context\" :{ \"userId\" : \"Practitioner/abc\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } Change Log \u00b6 Version Description 1.0 Initial Release 1.0.1 Add DeviceRequest to list of order resources for R4. 1.1.0 Updated hook to all for use in order-revision situations","title":"order-sign 5"},{"location":"hooks/order-sign/#order-sign","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 5 - Mature","title":"order-sign"},{"location":"hooks/order-sign/#workflow","text":"The order-sign hook fires when a clinician is ready to sign one or more orders for a patient, (including orders for medications, procedures, labs and other 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. 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 case, the orders would typically have a status other than 'draft'. In some cases, the hook might fire with a mixture of new and revised orders. This hook is intended to replace (deprecate) the medication-prescribe and order-review hooks.","title":"Workflow"},{"location":"hooks/order-sign/#context","text":"Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 or Practitioner/abc . 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 draftOrders REQUIRED No object DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription (typically with draft status) STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription (typically with draft status) R4 - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription (typically with draft status)","title":"Context"},{"location":"hooks/order-sign/#examples","text":"","title":"Examples"},{"location":"hooks/order-sign/#example-r4","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 { \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (R4)"},{"location":"hooks/order-sign/#example-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 { \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseAndRate\" :{ \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (STU3)"},{"location":"hooks/order-sign/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 \"context\" :{ \"userId\" : \"Practitioner/abc\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } }","title":"Example (DSTU2)"},{"location":"hooks/order-sign/#change-log","text":"Version Description 1.0 Initial Release 1.0.1 Add DeviceRequest to list of order resources for R4. 1.1.0 Updated hook to all for use in order-revision situations","title":"Change Log"},{"location":"hooks/patient-view/","text":"patient-view \u00b6 Info This page defines a workflow hook for the purpose of providing clinical decision support using CDS Hooks. This is a build at the level of Trial Use . Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 5 - Mature Workflow \u00b6 The user has just opened a patient's record; typically called only once at the beginning of a user's interaction with a specific patient's record. Context \u00b6 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. Must be in the format [ResourceType]/[id] . For this hook, the user is expected to be of type Practitioner , PractitionerRole , Patient , or RelatedPerson . Patient or RelatedPerson are appropriate when a patient or their proxy are viewing the record. For example, Practitioner/abc or Patient/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 \u00b6 1 2 3 4 \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" } 1 2 3 4 5 \"context\" :{ \"userId\" : \"Practitioner/abc\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" } Change Log \u00b6 Version Description 1.0 Initial Release","title":"patient-view 5"},{"location":"hooks/patient-view/#patient-view","text":"Info This page defines a workflow hook for the purpose of providing clinical decision support using CDS Hooks. This is a build at the level of Trial Use . Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 5 - Mature","title":"patient-view"},{"location":"hooks/patient-view/#workflow","text":"The user has just opened a patient's record; typically called only once at the beginning of a user's interaction with a specific patient's record.","title":"Workflow"},{"location":"hooks/patient-view/#context","text":"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. Must be in the format [ResourceType]/[id] . For this hook, the user is expected to be of type Practitioner , PractitionerRole , Patient , or RelatedPerson . Patient or RelatedPerson are appropriate when a patient or their proxy are viewing the record. For example, Practitioner/abc or Patient/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","title":"Context"},{"location":"hooks/patient-view/#examples","text":"1 2 3 4 \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" } 1 2 3 4 5 \"context\" :{ \"userId\" : \"Practitioner/abc\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" }","title":"Examples"},{"location":"hooks/patient-view/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/template/","text":"hook-name-expressed-as-noun-verb \u00b6 Info This page defines a workflow hook for the purpose of providing clinical decision support using CDS Hooks. This is a build | snapshot | ballot | release at the level of Draft | Trial Use | Normative | Informative | Deprecated Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 0 - Draft Workflow \u00b6 Describe when the hook occurs in a workflow. Hook creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion amongst implementers. The hook name should take the form noun-verb , such as encounter-start , or order-select according to the Hook Definition Format . Context \u00b6 Define context values that are available when this hook occurs, and indicate whether they must be provided, and whether they are available for parameterizing prefetch templates. Field Optionality Prefetch Token Type Description exampleId REQUIRED Yes string Describe the context value encounterId OPTIONAL Yes string Describe the context value Examples \u00b6 1 2 3 \"context\" :{ \"patientId\" : \"1288992\" } 1 2 3 4 \"context\" :{ \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" } Change Log \u00b6 Version Description 1.0 Initial Release","title":"new-hook-template"},{"location":"hooks/template/#hook-name-expressed-as-noun-verb","text":"Info This page defines a workflow hook for the purpose of providing clinical decision support using CDS Hooks. This is a build | snapshot | ballot | release at the level of Draft | Trial Use | Normative | Informative | Deprecated Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 0 - Draft","title":"hook-name-expressed-as-noun-verb"},{"location":"hooks/template/#workflow","text":"Describe when the hook occurs in a workflow. Hook creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion amongst implementers. The hook name should take the form noun-verb , such as encounter-start , or order-select according to the Hook Definition Format .","title":"Workflow"},{"location":"hooks/template/#context","text":"Define context values that are available when this hook occurs, and indicate whether they must be provided, and whether they are available for parameterizing prefetch templates. Field Optionality Prefetch Token Type Description exampleId REQUIRED Yes string Describe the context value encounterId OPTIONAL Yes string Describe the context value","title":"Context"},{"location":"hooks/template/#examples","text":"1 2 3 \"context\" :{ \"patientId\" : \"1288992\" } 1 2 3 4 \"context\" :{ \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" }","title":"Examples"},{"location":"hooks/template/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"specification/current/","text":"Current (draft) This is the continuous integration, community release of the CDS Hooks specification. All stable releases are available at https://cds-hooks.hl7.org . Overview \u00b6 The CDS Hooks specification describes the RESTful APIs and interactions using JSON over HTTPS to integrate Clinical Decision Support (CDS) between CDS Clients (typically Electronic Health Record Systems (EHRs) or other health information systems) and CDS Services. Conformance Language \u00b6 The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this specification are to be interpreted as described in RFC2119 . Further, the key word \"CONDITIONAL\" indicates that a particular item is either REQUIRED or OPTIONAL, based upon another item. Use of JSON \u00b6 All data exchanged through production RESTful APIs MUST be sent and received as JSON (JavaScript Object Notation) structures and are transmitted over HTTPS. See Security and Safety section. Null and empty JSON elements JSON elements SHALL NOT be null, unless otherwise specified. JSON elements SHALL NOT be empty, unless otherwise specified (e.g. to indicate no guidance with an empty array of cards in the CDS Hooks response). If a JSON attribute is defined as OPTIONAL, and does not have a value, implementers MUST omit it. For instance, OPTIONAL JSON string and array attributes are omitted rather than having a null or empty value. Unless otherwise specified, JSON attribute values SHALL NOT be null or empty, so null , \"\" , [] , or {} are prohibited. If a JSON attribute is defined with as OPTIONAL, and does not have a value, implementers SHALL omit it. CDS Hooks Anatomy \u00b6 This specification describes a \"hook\" -based pattern for invoking decision support from within a clinician's workflow. The API supports: Synchronous, workflow-triggered CDS calls returning information and suggestions Launching a web page to provide additional information to the user Launching a user-facing SMART app when CDS requires additional interaction The main concepts of the specification are Services, CDS Clients, and Cards. CDS Services \u00b6 A CDS Service is a service that provides recommendations and guidance through the RESTful APIs described by this specification. The primary APIs are Discovery , which allows a CDS Developer to publish the types of CDS Services it provides. The Service API that CDS Clients use to request decision support. The Feedback API through which services learn the outcomes of their recommendations and guidance. CDS Clients \u00b6 A CDS Client is an Electronic Health Record (EHR), or other clinical information system that uses decision support by calling CDS Services at specific points in the application's workflow called hooks . Each hook defines the hook context (contextual information available within the CDS Client and specific to the workflow) that is provided as part of the request. Each service advertises which hooks it supports and what prefetch data (information needed by the CDS Service to determine what decision support should be presented) it requires. In addition, CDS Clients typically provide the FHIR resource server location and associated authorization information as part of the request to enable services to request additional information. Cards \u00b6 Decision support is then returned to the CDS Client in the form of cards , which the CDS Client MAY display to the end-user as part of their workflow. Cards may be informational, or they may provide suggestions that the user may accept or reject they may provide a link to additional information or even launch a SMART app when additional user interaction is required. Discovery \u00b6 A CDS Service is discoverable via a stable endpoint by CDS Clients. The Discovery endpoint includes information such as a description of the CDS Service, when it should be invoked, and any data that is requested to be prefetched. A CDS Service provider exposes its discovery endpoint at: 1 { baseURL } /cds-services HTTP Request \u00b6 The Discovery endpoint SHALL always be available at {baseUrl}/cds-services . For example, if the baseUrl is https://example.com, the CDS Client can retrieve the list of CDS Services by invoking: GET https://example.com/cds-services Response \u00b6 The response to the discovery endpoint SHALL be an object containing a list of CDS Services. Field Description services array . An array of CDS Services . If your CDS server hosts no CDS Services, the discovery endpoint should return a 200 HTTP response with an empty array of services. Each CDS Service SHALL be described by the following attributes. Field Optionality Type Description hook REQUIRED string The hook this service should be invoked on. See Hooks . title RECOMMENDED string The human-friendly name of this service. description REQUIRED string The description of this service. id REQUIRED string The {id} portion of the URL to this service which is available at {baseUrl}/cds-services/{id} prefetch OPTIONAL object An object containing key/value pairs of FHIR queries that this service is requesting the CDS Client to perform and provide on each service call. The key is a string that describes the type of data being requested and the value is a string representing the FHIR query. See Prefetch Template . usageRequirements OPTIONAL string Human-friendly description of any preconditions for the use of this CDS Service. Note that a CDS server can host multiple entries of CDS service with the same id for different hook s. This allows a service to update its advice based on changes in workflow as discussed in update stale guidance . HTTP Status Codes \u00b6 Code Description 200 OK A successful response. CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes. Discovery Example \u00b6 1 curl \"https://example.com/cds-services\" The above command returns JSON structured like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 { \"services\" : [ { \"hook\" : \"patient-view\" , \"title\" : \"Static CDS Service Example\" , \"description\" : \"An example of a CDS Service that returns a static set of cards\" , \"id\" : \"static-patient-greeter\" , \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } }, { \"hook\" : \"order-select\" , \"title\" : \"Order Echo CDS Service\" , \"description\" : \"An example of a CDS Service that simply echoes the order(s) being placed\" , \"id\" : \"order-echo\" , \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" , \"medications\" : \"MedicationRequest?patient={{context.patientId}}\" } }, { \"hook\" : \"order-sign\" , \"title\" : \"Pharmacogenomics CDS Service\" , \"description\" : \"An example of a more advanced, precision medicine CDS Service\" , \"id\" : \"pgx-on-order-sign\" , \"usageRequirements\" : \"Note: functionality of this CDS Service is degraded without access to a FHIR Restful API as part of CDS recommendation generation.\" } ] } Calling a CDS Service \u00b6 HTTP Request \u00b6 A CDS Client SHALL call a CDS Service by POST ing a JSON document to the service as described in this section. The CDS Service endpoint can be constructed from the CDS Service base URL and an individual service id as {baseUrl}/cds-services/{service.id} . CDS Clients may add additional requirements for the triggering of a hook, based upon the user, workflow, CDS Service or other reasons (e.g. if the service is provided by a payer, the patient has active coverage with that payer). See Trusting CDS Services for additional considerations. The request SHALL include a JSON POST body with the following input fields: Field Optionality Type Description hook REQUIRED string The hook that triggered this CDS Service call. See Hooks . hookInstance REQUIRED string A universally unique identifier (UUID) for this particular hook call (see more information below). fhirServer CONDITIONAL URL The base URL of the CDS Client's FHIR server. If fhirAuthorization is provided, this field is REQUIRED. The scheme MUST be https when production data is exchanged. fhirAuthorization OPTIONAL object A structure holding an 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 section for more information. context REQUIRED object Hook-specific contextual data that the CDS service will need. For example, with the patient-view hook this will include the FHIR id of the Patient being viewed. For details, see the Hooks specific specification page (example: patient-view ). prefetch OPTIONAL object The FHIR data that was prefetched by the CDS Client (see more information below). hookInstance \u00b6 While working in the CDS Client, a user can perform multiple actions in series or in parallel. For example, a clinician might prescribe two drugs in a row; each prescription action would be assigned a unique hookInstance . This allows a CDS Service to uniquely identify each hook invocation. Note: the hookInstance is globally unique and should contain enough entropy to be un-guessable. Example \u00b6 1 2 3 4 5 curl -X POST \\ -H 'Content-type: application/json' \\ --data @hook-details-see-example-below \"https://example.com/cds-services/static-patient-greeter\" 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://hooks.smarthealthit.org:9080\" , \"hook\" : \"patient-view\" , \"fhirAuthorization\" : { \"access_token\" : \"some-opaque-fhir-access-token\" , \"token_type\" : \"Bearer\" , \"expires_in\" : 300 , \"scope\" : \"user/Patient.read user/Observation.read\" , \"subject\" : \"cds-service4\" }, \"context\" : { \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" }, \"prefetch\" : { \"patientToGreet\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1925-12-23\" , \"id\" : \"1288992\" , \"active\" : true } } } Providing FHIR Resources to a CDS Service \u00b6 CDS Services require specific FHIR resources in order to compute the recommendations the CDS Client requests. If real-world performance were no issue, a CDS Client could launch a CDS Service passing only context data (such as the current user and patient ids), and the CDS Service could obtain authorization to access the CDS Client's FHIR API, retrieving any resources required via FHIR read or search interactions. Given that CDS Services SHOULD respond quickly (on the order of 500 ms.), this specification defines mechanisms that allow a CDS Service to request and obtain FHIR resources more efficiently. Two optional methods are provided. In the first method, FHIR resources MAY be obtained by passing \"prefetched\" data from the CDS Client to the CDS Service in the service call. If data is to be prefetched, the CDS Service registers a set of \"prefetch templates\" with the CDS Client, as described in the Prefetch Template section below. These \"prefetch templates\" are defined in the CDS Service discovery response . The FHIR resources are passed as key-value pairs, with each key matching a key described in the discovery response, and each value being a FHIR resource. Note that in the case of searches, this resource may be a searchset Bundle. The second method enables the CDS Service to retrieve FHIR resources for itself, without the need to request and obtain its own authorization. If the CDS Client decides to have the CDS Service fetch its own FHIR resources, the CDS Client obtains and passes directly to the CDS Service a bearer token issued for the CDS Service's use in executing FHIR API calls against the CDS Client's FHIR server to obtain the required resources. Some CDS Clients MAY pass prefetched data, along with a bearer token for the CDS Service to use if additional resources are required. Each CDS Client SHOULD decide which approach, or combination, is preferred, based on performance considerations and assessment of attendant security and safety risks. CDS Services should be capable of accessing FHIR resources via either prefetch or from the CDS Client's FHIR server. For more detail, see the FHIR Resource Access section below. Similarly, each CDS Client will decide what FHIR resources to authorize and to prefetch, based on the CDS Service discovery response's \"prefetch\" request and on the provider's assessment of the \"minimum necessary.\" The CDS Client provider and the CDS Service provider will negotiate the set of FHIR resources to be provided, and how these data will be provided, as part of their service agreement. Prefetch Template \u00b6 A prefetch template is a FHIR read or search request that describes relevant data needed by the CDS Service. For example, the following is a prefetch template for hemoglobin A1c observations: 1 Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date To allow for prefetch templates that are dependent on the workflow context, prefetch templates may include references to context using prefetch tokens . In the above example, {{context.patientId}} is a prefetch token. The prefetch field of a CDS Service discovery response defines the set of prefetch templates for that service, providing a prefetch key for each one that is used to identify the prefetch data in the CDS request. For example: 1 2 3 4 5 { \"prefetch\" : { \"hemoglobin-a1c\" : \"Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date\" } } In this prefetch , hemoglobin-a1c is the prefetch key for this prefetch template. For a complete worked example, see below . A CDS Client MAY choose to honor zero, some, or all of the desired prefetch templates, and is free to choose the most appropriate source for these data. For example: The CDS Client MAY have some of the desired prefetched data already in memory, thereby removing the need for any network call The CDS Client MAY compute an efficient set of prefetch templates from multiple CDS Services, thereby reducing the number of calls to a minimum The CDS Client MAY satisfy some of the desired prefetched templates via some internal service or even its own FHIR server. The CDS Client SHALL only provide access to resources that are within the user's authorized scope. As part of preparing the request, a CDS Client processes each prefetch template it intends to satisfy by replacing the prefetch tokens in the prefetch template to construct a relative FHIR request URL. This specification is not prescriptive about how this request is actually processed. The relative URL may be appended to the base URL for the CDS Client's FHIR server and directly invoked, or the CDS Client may use internal infrastructure to satisfy the request in the same way that invoking against the FHIR server would. Regardless of how the CDS Client satisfies the prefetch templates (if at all), the prefetched data given to the CDS Service MUST be equivalent to the data the CDS Service would receive if it were making its own call to the CDS Client's FHIR server using the parameterized prefetch template. Note that this means that CDS services will receive only the information they have requested and are authorized to receive. Prefetch data for other services registered to the same hook MUST NOT be provided. In other words, services SHALL only receive the data they requested in their prefetch. The resulting response is passed along to the CDS Service using the prefetch parameter (see below . Note that a CDS Client MAY paginate prefetch results. The intent of allowing pagination is to ensure that prefetch queries that may be too large for a single payload can still be retrieved by the service. The decision to paginate and the size of pages is entirely at the CDS Client's discretion. CDS Clients are encouraged to only use pagination when absolutely necessary, keeping performance and user experience in mind. The CDS Client MUST NOT send any prefetch template key that it chooses not to satisfy. If the CDS Client encounters errors prefetching the requested data, OperationOutcome(s) SHOULD be used to communicate those errors to prevent the CDS Service from incurring an unneeded follow-up query. CDS Clients MUST omit the prefetch key if relevant details cannot be provided (e.g. intermittent connectivity issues). CDS Services SHOULD check any prefetched data for the existence of OperationOutcomes. If the CDS Client has no data to populate a template prefetch key, the prefetch template key MUST have a value of null . Note that the null result is used rather than a bundle with zero entries to account for the possibility that the prefetch url is a single-resource request. It is the CDS Service's responsibility to check prefetched data against its template to determine what requests were satisfied (if any) and to programmatically retrieve any additional necessary data. If the CDS Service is unable to obtain required data because it cannot access the FHIR server and the request did not contain the necessary prefetch keys, the service SHALL respond with an HTTP 412 Precondition Failed status code. Prefetch tokens \u00b6 A prefetch token is a placeholder in a prefetch template that is replaced by information from the hook's context to construct the FHIR URL used to request the prefetch data. Prefetch tokens MUST be delimited by {{ and }} , and MUST contain only the qualified path to a hook context field or one of the following user identifiers: userPractitionerId , userPractitionerRoleId , userPatientId , or userRelatedPersonId . 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 example, {{context.medication.id}} is not a valid prefetch token because it attempts to access the id field of the medication field. Prefetch tokens identifying the user \u00b6 A prefetch template enables a CDS Service to learn more about the current user through a FHIR read, like so: 1 2 3 4 5 { \"prefetch\": { \"user\": \"{{context.userId}}\" } } or though a FHIR search: 1 2 3 4 5 { \"prefetch\": { \"user\": \"PractitionerRole?_id={{userPractitionerRoleId}}&_include=PractitionerRole:practitioner\" } } A prefetch template may include any of the following prefetch tokens: Token Description {{userPractitionerId}} FHIR id of the Practitioner resource corresponding to the current user. {{userPractitionerRoleId}} FHIR id of the PractitionerRole resource corresponding to the current user. {{userPatientId}} FHIR id of the Patient resource corresponding to the current user. {{userRelatedPersonId}} FHIR id of the RelatedPerson resource corresponding to the current user. No single FHIR resource represents a user, rather Practitioner and PractitionerRole may be jointly used to represent a provider, and Patient or RelatedPerson are used to represent a patient or their proxy. Hook definitions typically define a context.userId field and corresponding prefetch token. Prefetch query restrictions \u00b6 To reduce the implementation burden on CDS Clients that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. When using this subset, valid prefetch templates MUST only make use of: instance level read interactions (for resources with known ids such as Patient , Practitioner , or Encounter ) type level search interactions; e.g. patient={{context.patientId}} Resource references (e.g. patient={{context.patientId}} ) token search parameters using equality (e.g. code=4548-4 ) and optionally the :in modifier (no other modifiers for token parameters) date search parameters on date , dateTime , instant , or Period types only, and using only the prefixes eq , lt , gt , ge , le the _count parameter to limit the number of results returned the _sort parameter to allow for most recent and first queries Example prefetch token \u00b6 Often a prefetch template builds on the contextual data associated with the hook. For example, a particular CDS Service might recommend guidance based on a patient's conditions when the chart is opened. The FHIR query to retrieve these conditions might be Condition?patient=123 . In order to express this as a prefetch template, the CDS Service must express the FHIR id of the patient as a token so that the CDS Client can replace the token with the appropriate value. When context fields are used as tokens, their token name MUST be context.name-of-the-field . For example, given a context like: 1 2 3 4 5 { \"context\" : { \"patientId\" : \"123\" } } The token name would be {{context.patientId}} . Again using our above conditions example, the complete prefetch template would be Condition?patient={{context.patientId}} . Only the first level fields in context may be considered for tokens. For example, given the following context that contains amongst other things, a MedicationRequest FHIR resource: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { \"context\" : { \"encounterId\" : \"456\" , \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"123\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }]}, \"subject\" : { \"reference\" : \"Patient/1288992\" } } } ] } } } Only the encounterId field in this example is eligible to be a prefetch token as it is a first level field and the datatype (string) can be placed into the FHIR query. The MedicationRequest.id value in the context is not eligible to be a prefetch token because it is not a first level field. If the hook creator intends for the MedicationRequest.id value to be available as a prefetch token, it must be made available as a first level field. Using the aforementioned example, we simply add a new medicationRequestId field: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 { \"context\" : { \"medicationRequestId\" : \"123\" , \"encounterId\" : \"456\" , \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"123\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }]}, \"subject\" : { \"reference\" : \"Patient/1288992\" } } } ] } } } Example prefetch templates \u00b6 1 2 3 4 5 6 7 8 { \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" , \"hemoglobin-a1c\" : \"Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date\" , \"diabetes-type2\" : \"Condition?patient={{context.patientId}}&code=44054006&category=problem-list-item&status=active\" , \"user\" : \"PractitionerRole?_id={{userPractitionerRoleId}}\" } } Here is an example prefetch field from a CDS Service discovery endpoint. The goal is to know, at call time: Key Description patient Patient demographics. hemoglobin-a1c Most recent Hemoglobin A1c reading for this patient. diabetes-type2 If the patient has an active condition of diabetes mellitus on their problem list. user Information on the current user. Example prefetch data \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 { \"prefetch\" : { \"patient\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1974-12-25\" , \"...\" : \"<snipped for brevity>\" }, \"hemoglobin-a1c\" : { \"resourceType\" : \"Bundle\" , \"type\" : \"searchset\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"Observation\" , \"code\" : { \"coding\" : [ { \"system\" : \"http://loinc.org\" , \"code\" : \"4548-4\" , \"display\" : \"Hemoglobin A1c\" } ] }, \"...\" : \"<snipped for brevity>\" } } ] }, \"user\" : \"123\" } } The CDS Hooks request is augmented to include two prefetch values, where the dictionary keys match the request keys ( patient and hemoglobin-a1c in this case). Note that the missing diabetes-type2 key indicates that either the CDS Client has decided not to satisfy this particular prefetch template or it was not able to retrieve this prefetched data. The CDS Service is responsible for retrieving the FHIR resource representing the user from the FHIR server (if required). FHIR Resource Access \u00b6 If the CDS Client provides both fhirServer and fhirAuthorization request parameters, the CDS Service MAY use the FHIR server to obtain any FHIR resources for which it's authorized, beyond those provided by the CDS Client as prefetched data. This is similar to the approach used by SMART on FHIR wherein the SMART app requests and ultimately obtains an access token from the CDS Client's Authorization server using the SMART launch workflow, as described in SMART App Launch Implementation Guide . Like SMART on FHIR, CDS Hooks requires that CDS Services present a valid access token to the FHIR server with each API call. Thus, a CDS Service requires an access token before communicating with the CDS Client's FHIR resource server. While CDS Hooks shares the underlying technical framework and standards as SMART on FHIR, the CDS Hooks workflow MUST accommodate the automated, low-latency delivery of an access token to the CDS service. With CDS Hooks, if the CDS Client wants to provide the CDS Service direct access to FHIR resources, the CDS Client creates or obtains an access token prior to invoking the CDS Service, passing this token to the CDS Service as part of the service call. This approach remains compatible with OAuth 2.0's bearer token protocol while minimizing the number of HTTPS round-trips and the service invocation latency. The CDS Client remains in control of providing an access token that is associated with the specific CDS Service, user, and context of the invocation. As the CDS Service executes on behalf of a user, the data to which the CDS Service is given access by the CDS Client MUST be limited to the same restrictions and authorizations afforded the current user. As such, the access token SHALL be scoped to: The CDS Service being invoked The current user Passing the Access Token to the CDS Service \u00b6 The access token is specified in the CDS Service request via the fhirAuthorization request parameter. This parameter is an object that contains both the access token as well as other related information as specified below. If the CDS Client chooses not to pass along an access token, the fhirAuthorization parameter is omitted. Field Optionality Type Description access_token REQUIRED string This is the OAuth 2.0 access token that provides access to the FHIR server. token_type REQUIRED string Fixed value: Bearer expires_in REQUIRED integer The lifetime in seconds of the access token. scope REQUIRED string The scopes the access token grants the CDS Service. subject REQUIRED string The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server. 'patient` CONDITIONAL string If the granted SMART scopes include patient scopes (i.e. \"patient/\"), the access token is restricted to a specific patient. This field SHOULD be populated to identify the FHIR id of that patient. The scopes granted to the CDS Service via the scope field are defined by the SMART on FHIR specification . The expires_in value is established by the authorization server and SHOULD BE very short lived, as the access token MUST be treated as a transient value by the CDS Service. CDS Clients SHOULD revoke an issued access token upon the completion of the CDS Hooks request/response to limit the validity period of the token. Below is an example fhirAuthorization parameter: 1 2 3 4 5 6 7 8 9 { \"fhirAuthorization\" : { \"access_token\" : \"some-opaque-fhir-access-token\" , \"token_type\" : \"Bearer\" , \"expires_in\" : 300 , \"scope\" : \"user/Patient.read user/Observation.read\" , \"subject\" : \"cds-service4\" } } CDS Service Response \u00b6 For successful responses, CDS Services SHALL respond with a 200 HTTP response with an object containing a cards array and optionally a systemActions array as described below. Each card contains decision support guidance from the CDS Service. Cards are intended for display to an end user. The data format of a card defines a very minimal set of required attributes with several more optional attributes to suit a variety of use cases, such as: narrative informational decision support, actionable suggestions to modify data, and links to SMART apps. Note that because the CDS client may be invoking multiple services from the same hook, there may be multiple responses related to the same information. This specification does not address these scenarios specifically; both CDS Services and CDS Clients should consider the implications of multiple CDS Services in their integrations and are invited to consider card attributes when determining prioritization and presentation options. HTTP Status Codes \u00b6 Code Description 200 OK A successful response. 412 Precondition Failed The CDS Service is unable to retrieve the necessary FHIR data to execute its decision support, either through a prefetch request or directly calling the FHIR server. CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes. HTTP Response \u00b6 Field Optionality Type Description cards REQUIRED array of Cards An array of Cards . Cards can provide a combination of information (for reading), suggested actions (to be applied if a user selects them), and links (to launch an app if the user selects them). The CDS Client decides how to display cards, but this specification recommends displaying suggestions using buttons, and links using underlined text. systemActions OPTIONAL array of Actions An array of Actions that the CDS Service proposes to auto-apply. Each action follows the schema of a card-based suggestion.action . The CDS Client decides whether to auto-apply actions. If your CDS Service has no decision support for the user, your service should return a 200 HTTP response with an empty array of cards, for example: 1 2 3 { \"cards\" : [] } Clients SHOULD remove cards returned by previous invocations of a hook to a service with the same id when a new hook is triggered (see update stale guidance ). Card Attributes \u00b6 Each Card is described by the following attributes. Field Optionality Type Description uuid OPTIONAL string Unique identifier of the card. MAY be used for auditing and logging cards and SHALL be included in any subsequent calls to the CDS service's feedback endpoint. summary REQUIRED string One-sentence, <140-character summary message for display to the user inside of this card. detail OPTIONAL string Optional detailed information to display; if provided MUST be represented in (GitHub Flavored) Markdown . (For non-urgent cards, the CDS Client MAY hide these details until the user clicks a link like \"view more details...\"). indicator REQUIRED string Urgency/importance of what this card conveys. Allowed values, in order of increasing urgency, are: info , warning , critical . The CDS Client MAY use this field to help make UI display decisions such as sort order or coloring. source REQUIRED object Grouping structure for the Source of the information displayed on this card. The source should be the primary source of guidance for the decision support the card represents. suggestions OPTIONAL array of Suggestions Allows a service to suggest a set of changes in the context of the current activity (e.g. changing the dose of a medication currently being prescribed, for the order-sign activity). If suggestions are present, selectionBehavior MUST also be provided. selectionBehavior CONDITIONAL string Describes the intended selection behavior of the suggestions in the card. Allowed values are: at-most-one , indicating that the user may choose none or at most one of the suggestions; any , indicating that the end user may choose any number of suggestions including none of them and all of them. CDS Clients that do not understand the value MUST treat the card as an error. overrideReasons OPTIONAL array of Coding Override reasons can be selected by the end user when overriding a card without taking the suggested recommendations. The CDS service MAY return a list of override reasons to the CDS client. If override reasons are present, the CDS Service MUST populate a display value for each reason's Coding . The CDS Client SHOULD present these reasons to the clinician when they dismiss a card. A CDS Client MAY augment the override reasons presented to the user with its own reasons. links OPTIONAL array of Links Allows a service to suggest a link to an app that the user might want to run for additional information or to help guide a decision. Source \u00b6 The Source is described by the following attributes. Field Optionality Type Description label REQUIRED string A short, human-readable label to display for the source of the information displayed on this card. If a url is also specified, this MAY be the text for the hyperlink. url OPTIONAL URL An optional absolute URL to load (via GET , in a browser context) when a user clicks on this link to learn more about the organization or data set that provided the information on this card. Note that this URL should not be used to supply a context-specific \"drill-down\" view of the information on this card. For that, use card.link.url instead. icon OPTIONAL URL An absolute URL to an icon for the source of this card. The icon returned by this URL SHOULD be a 100x100 pixel PNG image without any transparent regions. The CDS Client may ignore or scale the image during display as appropriate for user experience. topic OPTIONAL Coding A topic describes the content of the card by providing a high-level categorization that can be useful for filtering, searching or ordered display of related cards in the CDS client's UI. This specification does not prescribe a standard set of topics. Below is an example source parameter: 1 2 3 4 5 6 7 8 9 10 11 12 { \"source\" : { \"label\" : \"Zika Virus Management\" , \"url\" : \"https://example.com/cdc-zika-virus-mgmt\" , \"icon\" : \"https://example.com/cdc-zika-virus-mgmt/100.png\" , \"topic\" : { \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/topics\" , \"code\" : \"12345\" , \"display\" : \"Mosquito born virus\" } } } Suggestion \u00b6 Each Suggestion is described by the following attributes. Field Optionality Type Description label REQUIRED string Human-readable label to display for this suggestion (e.g. the CDS Client might render this as the text on a button tied to this suggestion). uuid OPTIONAL string Unique identifier, used for auditing and logging suggestions. isRecommended OPTIONAL boolean When there are multiple suggestions, allows a service to indicate that a specific suggestion is recommended from all the available suggestions on the card. CDS Hooks clients may choose to influence their UI based on this value, such as pre-selecting, or highlighting recommended suggestions. Multiple suggestions MAY be recommended, if card.selectionBehavior is any . actions OPTIONAL array of Actions Array of objects, each defining a suggested action. Within a suggestion, all actions are logically AND'd together, such that a user selecting a suggestion selects all of the actions within it. When a suggestion contains multiple actions, the actions SHOULD be processed as per FHIR's rules for processing transactions with the CDS Client's fhirServer as the base url for the inferred full URL of the transaction bundle entries. (Specifically, deletes happen first, then creates, then updates). Action \u00b6 Each Action is described by the following attributes. Field Optionality Type Description type REQUIRED string The type of action being performed. Allowed values are: create , update , delete . description REQUIRED string Human-readable description of the suggested action MAY be presented to the end-user. resource CONDITIONAL object A FHIR resource. When the type attribute is create , the resource attribute SHALL contain a new FHIR resource to be created. For update , this holds the updated resource in its entirety and not just the changed fields. Use of this field to communicate a string of a FHIR id for delete suggestions is DEPRECATED and resourceId SHOULD be used instead. resourceId CONDITIONAL string A relative reference to the relevant resource. SHOULD be provided when the type attribute is delete . The following example illustrates a create action: 1 2 3 4 5 6 7 8 9 { \"type\" : \"create\" , \"description\" : \"Create a prescription for Acetaminophen 250 MG\" , \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"medrx001\" , \"...\" : \"<snipped for brevity>\" } } The following example illustrates an update action: 1 2 3 4 5 6 7 8 9 { \"type\" : \"update\" , \"description\" : \"Update the order to record the appropriateness score\" , \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"procedure-request-1\" , \"...\" : \"<snipped for brevity>\" } } The following example illustrates a delete action: 1 2 3 4 5 { \"type\" : \"delete\" , \"description\" : \"Remove the inappropriate order\" , \"resourceId\" : \"ServiceRequest/procedure-request-1\" } Reasons for rejecting a card \u00b6 overrideReasons is an array of Coding that captures a codified set of reasons an end user may select from as the rejection reason when rejecting the advice presented in the card. When using the coding object to represent a reason, CDS Services MUST provide a human readable text in the display property and CDS Clients MAY incorporate it into their user interface. This specification does not prescribe a standard set of override reasons; implementers are encouraged to submit suggestions for standardization. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 { \"overrideReasons\" : [ { \"code\" : \"reason-code-provided-by-service\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Patient refused\" }, { \"code\" : \"12354\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Contraindicated\" } ] } Link \u00b6 Each Link is described by the following attributes. Field Optionality Type Description label REQUIRED string Human-readable label to display for this link (e.g. the CDS Client might render this as the underlined text of a clickable link). url REQUIRED URL URL to load (via GET , in a browser context) when a user clicks on this link. Note that this MAY be a \"deep link\" with context embedded in path segments, query parameters, or a hash. type REQUIRED string The type of the given URL. There are two possible values for this field. A type of absolute indicates that the URL is absolute and should be treated as-is. A type of smart indicates that the URL is a SMART app launch URL and the CDS Client should ensure the SMART app launch URL is populated with the appropriate SMART launch parameters. appContext OPTIONAL string An optional field that allows the CDS Service to share information from the CDS card with a subsequently launched SMART app. The appContext field should only be valued if the link type is smart and is not valid for absolute links. The appContext field and value will be sent to the SMART app as part of the OAuth 2.0 access token response, alongside the other SMART launch parameters when the SMART app is launched. Note that appContext could be escaped JSON, base64 encoded XML, or even a simple string, so long as the SMART app can recognize it. CDS Client support for appContext requires additional coordination with the authorization server that is not described or specified in CDS Hooks nor SMART. autolaunchable OPTIONAL boolean This field serves as a hint to the CDS Client suggesting this link be immediately launched, without displaying the card and without manual user interaction. Note that CDS Hooks cards which contain links with this field set to true, may not be shown to the user. Sufficiently advanced CDS Clients may support automatically launching multiple links or multiple cards. Implementer guidance is requested to determine if the specification should preclude these advanced scenarios. Considerations for autolaunchable and user experience \u00b6 The intent of this optional feature is to improve individual user experience by removing the otherwise unnecessary click of a link by the user. Appropriate support of this feature includes guardrails from both the CDS Service developer and the CDS Client, as well as additional local control by the organization using the service. The CDS Client ultimately determines if a link can be automatically launched, taking into consideration user interface needs, workflow considerations, or even absence of support for this optional feature. If a CDS Hooks response contains guidance in addition to an autolaunchable link, it's the CDS Service's responsibility to ensure that any decision support that exists in the CDS Hooks response's card(s) is communicated via the launched app. System Action \u00b6 A systemAction is the same Action which may be returned in a suggestion, but is instead returned alongside the array of cards. A systemAction is not presented to the user within a card, but rather may be auto-applied without user intervention. 1 2 3 4 5 6 7 8 9 10 11 12 13 { \"cards\" : [], \"systemActions\" : [ { \"type\" : \"update\" , \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"...\" : \"<snipped for brevity\" } } ] } Example \u00b6 Example response 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 { \"cards\" : [ { \"uuid\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"summary\" : \"Example Card\" , \"indicator\" : \"info\" , \"detail\" : \"This is an example card.\" , \"source\" : { \"label\" : \"Static CDS Service Example\" , \"url\" : \"https://example.com\" , \"icon\" : \"https://example.com/img/icon-100px.png\" }, \"links\" : [ { \"label\" : \"Google\" , \"url\" : \"https://google.com\" , \"type\" : \"absolute\" }, { \"label\" : \"Github\" , \"url\" : \"https://github.com\" , \"type\" : \"absolute\" }, { \"label\" : \"SMART Example App\" , \"url\" : \"https://smart.example.com/launch\" , \"type\" : \"smart\" , \"appContext\" : \"{\\\"session\\\":3456356,\\\"settings\\\":{\\\"module\\\":4235}}\" } ] }, { \"summary\" : \"Another card\" , \"indicator\" : \"warning\" , \"source\" : { \"label\" : \"Static CDS Service Example\" }, \"overrideReasons\" : [ { \"code\" : \"reason-code-provided-by-service\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Patient refused\" }, { \"code\" : \"12354\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Contraindicated\" } ] } ] } Example response using autolaunchable 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { \"cards\" : [ { \"uuid\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"summary\" : \"Lung cancer screening shared decision making\" , \"detail\" : \"Patient is a current smoker with a 20 pack/year history. Consider advising patient to complete lung cancer screening. The Lung Cancer Screening Shared Decision Making App (LCSSDM) has been proven to increase patient followthrough for screening.\" , \"source\" : { \"label\" : \"Lung Cancer Screening Shared Decision Making App\" , \"url\" : \"https://example.com/LCS\" , \"icon\" : \"https://example.com/img/icon-100px.png\" }, \"links\" : [ { \"label\" : \"Github\" , \"url\" : \"https://github.com\" , \"type\" : \"absolute\" , \"autolaunchable\" : true } ] } ] } Feedback \u00b6 Once a CDS Hooks Service responds to a hook by returning a card, the service has no further interaction with the CDS Client. The acceptance of a suggestion or rejection of a card is valuable information to enable a service to improve its behavior towards the goal of the end-user having a positive and meaningful experience with the CDS. A feedback endpoint enables suggestion tracking & analytics. A CDS Service MAY support a feedback endpoint; a CDS Client SHOULD be capable of sending feedback. Upon receiving a card, a user may accept its suggestions, ignore it entirely, or dismiss it with or without an override reason. Note that while one or more suggestions can be accepted, an entire card is either ignored or overridden. Typically, an end user may only accept (a suggestion), or override a card once; however, a card once ignored could later be acted upon. CDS Hooks does not specify the UI behavior of CDS Clients, including the persistence of cards. CDS Clients should faithfully report each of these distinct end-user interactions as feedback. A CDS Client provides feedback by POSTing a JSON document. The feedback endpoint can be constructed from the CDS Service endpoint and a path segment of \"feedback\" as {baseUrl}/cds-services/{service.id}/feedback. The request to the feedback endpoint SHALL be an object containing an array. Field Description feedback array of Feedback Each Feedback SHALL be described by the following attributes. Field Optionality Type Description card REQUIRED string The card.uuid from the CDS Hooks response. Uniquely identifies the card. outcome REQUIRED string A value of accepted or overridden . acceptedSuggestions CONDITIONAL array An array of json objects identifying one or more of the user's AcceptedSuggestion s. Required for accepted outcomes. overrideReason OPTIONAL OverrideReason A json object capturing the override reason as a Coding as well as any comments entered by the user. outcomeTimestamp REQUIRED string ISO8601 representation of the date and time in Coordinated Universal Time (UTC) when action was taken on the card, as profiled in section 5.6 of RFC3339 . e.g. 1985-04-12T23:20:50.52Z Suggestion accepted \u00b6 The CDS Client can inform the service when one or more suggestions were accepted by POSTing a simple JSON object. The CDS Client authenticates to the CDS service as described in Trusting CDS Clients . Upon the user accepting a suggestion (perhaps when she clicks a displayed label (e.g., button) from a \"suggestion\" card), the CDS Client informs the service by posting the card and suggestion uuid s to the CDS Service's feedback endpoint with an outcome of accepted . To enable a positive clinical experience, the feedback endpoint may be called for multiple hook instances or multiple cards at the same time or even multiple times for a card or suggestion. Depending upon the UI and workflow of the CDS Client, a CDS Service may receive feedback for the same card instance multiple times. Each AcceptedSuggestion is described by the following attributes. Field Optionality Type Description id REQUIRED string The card.suggestion.uuid from the CDS Hooks response. Uniquely identifies the suggestion that was accepted. Example suggestion accepted \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" : [ { \"card\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"outcome\" : \"accepted\" , \"acceptedSuggestions\" : [ { \"id\" : \"e56e1945-20b3-4393-8503-a1a20fd73152\" } ], \"outcomeTimestamp\" : \"2021-12-11T10:05:31Z\" } ] } If either the card or the suggestion has no uuid , the CDS Client does not send a notification. Card ignored \u00b6 If the end-user doesn't interact with the CDS Service's card at all, the card is ignored . In this case, the CDS Client does not inform the CDS Service of the rejected guidance. Even with a card.uuid , a suggestion.uuid , and an available feedback service, the service is not informed (in part, because it may later be acted upon). Overridden guidance \u00b6 A CDS Client may enable the end user to override guidance without providing an explicit reason for doing so. The CDS Client can inform the service when a card was dismissed by specifying an outcome of overridden without providing an overrideReason . This may occur, for example, when the end user viewed the card and dismissed it without providing a reason why. Example overridden guidance without overrideReason \u00b6 1 2 3 4 5 6 7 8 9 10 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" : [ { \"card\" : \"f6b95768-b1c8-40dc-8385-bf3504b82ffb\" , // uuid from `card.uuid` \"outcome\" : \"overridden\" , \"outcomeTimestamp\" : \"2020-12-11T00:00:00Z\" } ] } Explicit reject with override reasons \u00b6 A CDS Client can inform the service when a card was rejected by POSTing an outcome of overridden along with an overrideReason to the service's feedback endpoint. The CDS Client may enable the clinician to provide an additional overrideReason or to supplement the overrideReason with a free text comment, supplied to the CDS Service in overrideReason.userComment . OverrideReason \u00b6 Each OverrideReason is described by the following attributes, in the feedback POST to the CDS Service. Field Optionality Type Description reason CONDITIONAL Coding The Coding object representing the override reason selected by the end user. Required if user selected an override reason from the list of reasons provided in the Card (instead of only leaving a userComment). userComment OPTIONAL string The CDS Client may enable the clinician to further explain why the card was rejected with free text. That user comment may be communicated to the CDS Service as a userComment . Example overridden guidance with overrideReason \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" :[ { \"card\" : \"9368d37b-283f-44a0-93ea-547cebab93ed\" , \"outcome\" : \"overridden\" , \"overrideReason\" :{ \"reason\" :{ \"code\" : \"d7ecf885\" , \"system\" : \"https://example.com/cds-hooks/override-reason-system\" }, \"userComment\" : \"A comment entered by the clinician.\" }, \"outcomeTimestamp\" : \"2020-12-11T00:00:00Z\" } ] } Security and Safety \u00b6 All data exchanged through the RESTful APIs MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in RFC2818 . Security and safety risks associated with the CDS Hooks API include: The risk that confidential information and privileged authorizations transmitted between a CDS Client and a CDS Service could be surreptitiously intercepted by an attacker; The risk that an attacker masquerading as a legitimate CDS Service could receive confidential information or privileged authorizations from a CDS Client, or could provide to a CDS Client decision support recommendations that could be harmful to a patient; The risk that an attacker masquerading as a legitimate service-subscribing CDS Client (i.e., man-in-the-middle) could intercept and possibly alter data exchanged between the two parties. The risk that a CDS Service could embed dangerous suggestions or links to dangerous apps in Cards returned to a CDS Client. The risk that a CDS Hooks browser-based deployment could be victimized by a Cross-Origin Resource Sharing (CORS) attack. The risk that a CDS Service could return a decision based on outdated patient data, resulting in a safety risk to the patient. CDS Hooks defines a security model that addresses these risks by assuring that the identities of both the CDS Service and the CDS Client are authenticated to each other; by protecting confidential information and privileged authorizations shared between a CDS Client and a CDS Service; by recommending means of assuring data freshness; and by incorporating business mechanisms through which trust is established and maintained between a CDS Client and a CDS Service. As with any access to protected patient information, systems should ensure that they have appropriate authorization and audit mechanisms in place to support transparency of use of the data. For more information, refer to Security Best Practices . Trusting CDS Services \u00b6 Prior to enabling CDS Clients to request decision support from any CDS Service, the CDS Client vendor and/or provider organization is expected to perform due diligence on the CDS Service provider. Each CDS Client vendor/provider is individually responsible for determining the suitability, safety and integrity of the CDS Services it uses, based on the organization's own risk-management strategy. Each CDS Client vendor/provider SHOULD maintain an \"allow list\" (and/or \"deny list\") of the CDS Services it has vetted, and the Card links that have been deemed safe to display from within the CDS Client context. Each provider organization is expected to work with its CDS Client vendor to choose what CDS Services to allow and to negotiate the conditions under which the CDS Services MAY be called. Once a CDS Service provider is selected, the CDS Client vendor/provider negotiates the terms under which service will be provided. This negotiation includes agreement on patient data elements that will be prefetched and provided to the CDS Service, the CDS Services used and the hooks that will trigger them, data elements that will be made available through an access token passed by the CDS Client, and steps the CDS Service MUST take to protect patient data and access tokens. The CDS Service can be registered with the CDS Client's authorization server, in part to define the FHIR resources that the CDS Service has authorization to access. These business arrangements are documented in the service agreement. Every interaction between a CDS Client and a CDS Service is initiated by the CDS Client sending a service request to a CDS Service endpoint protected using the Transport Layer Security protocol . Through the TLS protocol the identity of the CDS Service is authenticated, and an encrypted transmission channel is established between the CDS Client and the CDS Service. Both the Discovery endpoint and individual CDS Service endpoints are TLS secured. The CDS Client's FHIR server, using information provided by the authorization server, is responsible for enforcing restrictions on the information available to the CDS Service. Regardless of whether FHIR resources are prefetched or retrieved from the FHIR server, the CDS Client SHALL deny access to a requested resource if it is outside the user's authorized scope. If a CDS Client is satisfying prefetch requests from a CDS Service or sends a non-null fhirAuthorization object to a CDS Service so that it can call the FHIR server, the CDS Service MUST be pre-registered with the authorization server protecting access to the FHIR server. Pre-registration includes registering a client identifier, and agreeing upon the scope of FHIR access that is minimally necessary to provide the clinical decision support required. This specification does not address how the CDS Client, authorization server, and CDS Service perform this pre-registration. Trusting CDS Clients \u00b6 The service agreement negotiated between the CDS Client vendor/provider and the CDS Service provider will include obligations the CDS Client vendor/provider commits to the CDS Service provider. Some agreements MAY include the use of mutual TLS, in which both ends of the channel are authenticated. However, mutual TLS is impractical for many organizations. In the absence of mutual TLS, only the CDS Service endpoint will be authenticated because the CDS Client initiates the TLS channel set-up. To enable the CDS Service to authenticate the identity of the CDS Client, CDS Hooks uses digitally signed JSON web tokens (JWT) ( rfc7519 ). CDS Services SHOULD require authentication if invoking the service poses any risk of exposing sensitive data to the caller. Each time a CDS Client transmits a request to a CDS Service which requires authentication, the request MUST include an Authorization header presenting the JWT as a \u201cBearer\u201d token: 1 Authorization: Bearer {{JWT}} Note that this is for every single CDS Service call, whether that be a Discovery call, a single CDS Service invocation, or multiple exchanges relating to a single service. Also note that mutual TLS MAY be used alongside JSON web tokens to establish trust of the CDS Client by the CDS Service. The CDS Client MUST use its private key to digitally sign the JWT, using the JSON Web Signatures (rfc7515) standard. The JWT header contains the following fields (see rfc7515 section 4.1 for further information on these standard headers): Field Optionality Type Value alg REQUIRED string The cryptographic algorithm used to sign this JWT. kid REQUIRED string The identifier of the key-pair used to sign this JWT. This identifier MUST be unique within the CDS Client's JWK Set. typ REQUIRED string Fixed value: JWT jku OPTIONAL url The URL to the JWK Set containing the public key(s). The JWT payload contains the following fields: Field Optionality Type Value iss REQUIRED string The URI of the issuer of this JWT. Note that the JWT MAY be self-issued by the CDS Client, or MAY be issued by a third-party identity provider. aud REQUIRED string or array of string The CDS Service endpoint that is being called by the CDS Client. (See more details below). exp REQUIRED number Expiration time integer for this authentication JWT, expressed in seconds since the \"Epoch\" (1970-01-01T00:00:00Z UTC). iat REQUIRED number The time at which this JWT was issued, expressed in seconds since the \"Epoch\" (1970-01-01T00:00:00Z UTC). jti REQUIRED string A nonce string value that uniquely identifies this authentication JWT (used to protect against replay attacks). tenant OPTIONAL string An opaque string identifying the healthcare organization that is invoking the CDS Hooks request. CDS Services SHOULD limit the CDS Clients they trust by maintaining an allowlist of iss and jku urls. Per rfc7519 , the aud value is either a string or an array of strings. For CDS Hooks, this value MUST be the URL of the CDS Service endpoint being invoked. For example, consider a CDS Service available at a base URL of https://cds.example.org . When the CDS Client invokes the CDS Service discovery endpoint, the aud value is either \"https://cds.example.org/cds-services\" or [\"https://cds.example.org/cds-services\"] . Similarly, when the CDS Client invokes a particular CDS Service (say, some-service ), the aud value is either \"https://cds.example.org/cds-services/some-service\" or [\"https://cds.example.org/cds-services/some-service\"] . The CDS Client MUST make its public key, expressed as a JSON Web Key (JWK), available in a JWK Set, as defined by rfc7517 . The kid value from the JWT header allows a CDS Service to identify the correct JWK in the JWK Set that can be used to verify the signature. The CDS Client MAY make its JWK Set available via a URL identified by the jku header field, as defined by rfc7515 4.1.2 . If the jku header field is ommitted, the CDS Client and CDS Service SHALL communicate the JWK Set out-of-band. JWT Signing Algorithm \u00b6 The cryptographic signing algorithm of JWT is indicated in the alg header field. JSON Web Algorithms (rfc7518) defines several cryptographic algorithms for use in signing JWTs and should be referenced by CDS Hooks implementers. JWTs SHALL NOT be signed using the none algorithm, referred to in rfc7518 as unsecured JSON Web Signatures, as the lack of a cryptographic signature does not provide any integrity protection. Such JWTs could not be used by a CDS Service to identity the CDS Client preventing an establishment of trust. JWTs SHALL NOT be signed using any symmetric algorithm as these algorithms require the CDS Client and CDS Service to share a private key in order to verify the signature. For example, all HMAC based algorithms rely upon a shared private key and thus SHALL NOT be used to sign a JWT. When choosing an algorithm to sign their JWTs, CDS Clients SHOULD consider not only the algorithms (and key sizes) that are recommended within the security industry, but also how well those algorithms are supported in the various programming languages and libraries that may be used by CDS Services. At publication time of this specification, both ES384 and RS384 are RECOMMENDED for their regard within the larger security industry, strength, and support across popular programming languages and libraries. However, stronger and better algorithms are continually being introduced due to new threats, weaknesses, and increases in computing power. CDS Clients SHOULD continually re-evaluate their choice of an algorithm based upon these ever changing conditions. CDS Services SHOULD consider the algorithms they understand and trust based upon their tolerance for risk. Example \u00b6 An example JSON web token header, payload, and JWK set: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 // JSON Web Token Header { \"alg\" : \"ES384\" , \"typ\" : \"JWT\" , \"kid\" : \"example-kid\" , \"jku\" : \"https://fhir-ehr.example.com/jwk_uri\" } // JSON Web Token Payload { \"iss\" : \"https://fhir-ehr.example.com/\" , \"aud\" : \"https://cds.example.org/cds-services/some-service\" , \"exp\" : 1422568860 , \"iat\" : 1311280970 , \"jti\" : \"ee22b021-e1b7-4611-ba5b-8eec6a33ac1e\" , \"tenant\" : \"2ddd6c3a-8e9a-44c6-a305-52111ad302a2\" } // JSON Web Key Set (public key) // This public key is used by the CDS Service to verify the signature of the JWT { \"keys\" : [ { \"kty\" : \"EC\" , \"use\" : \"sig\" , \"crv\" : \"P-384\" , \"kid\" : \"example-kid\" , \"x\" : \"46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk\" , \"y\" : \"XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI\" , \"alg\" : \"ES384\" } ] } // JSON Web Key (private key) // This private key is used by the CDS Client to sign the JWT { \"kty\" : \"EC\" , \"d\" : \"SeFXUXda8UomZ8GFUl7HH_Oi15rIbfMcsWj9ecIsDR8kLbqsEz2CGNgwy_IcILxy\" , \"use\" : \"sig\" , \"crv\" : \"P-384\" , \"kid\" : \"example-kid\" , \"x\" : \"46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk\" , \"y\" : \"XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI\" , \"alg\" : \"ES384\" } Using the above JWT values and JWKs, the complete JWT as passed in the Authorization HTTP header would be: 1 Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6ImV4YW1wbGUta2lkIiwiamt1IjoiaHR0cHM6Ly9maGlyLWVoci5leGFtcGxlLmNvbS9qd2tfdXJpIn0.eyJpc3MiOiJodHRwczovL2ZoaXItZWhyLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vY2RzLmV4YW1wbGUub3JnL2Nkcy1zZXJ2aWNlcy9zb21lLXNlcnZpY2UiLCJleHAiOjE0MjI1Njg4NjAsImlhdCI6MTMxMTI4MDk3MCwianRpIjoiZWUyMmIwMjEtZTFiNy00NjExLWJhNWItOGVlYzZhMzNhYzFlIiwidGVuYW50IjoiMmRkZDZjM2EtOGU5YS00NGM2LWEzMDUtNTIxMTFhZDMwMmEyIn0.d1WfLjGRKlcWB94l9do4cM8REXeYJLL6SGUBO8VHZhfM8mwKYP70EMxJ67War4TQblEpaQrp11wx5p7oPFm2ETYgCicS84vXWEIYTdjooZdooCSDf2L8-i4awdoUwiEb Cross-Origin Resource Sharing \u00b6 Cross-origin resource sharing (CORS) is a World Wide Web Consortium (W3C) standard mechanism that uses additional HTTP headers to enable a web browser to gain permission to access resources from an Internet domain different from that which the browser is currently accessing. CORS is a client-side security mechanism with well-documented security risks. CDS Services and browser-based CDS Clients will require CORS support. A secure implementation guide for CORS is outside of the scope of this CDS Hooks specification. Organizations planning to implement CDS Hooks with CORS support are referred to the Cross-Origin Resource Sharing section of the OWASP HTML5 Security Cheat Sheet . Update stale guidance \u00b6 In the case that CDS Hooks cards are persisted, clients should take care to ensure that stale guidance does not negatively impact patient care. CDS Services can update their previously returned guidance by returning a new set of cards when the service is invoked based on a different hook . CDS Services indicate this intent by providing multiple CDS Services with the same id in discovery . Clients are recommended to remove cards returned by a previous invocation with the new cards . STU NOTE: We are seeking implementer feedback on how best to balance the needs of performance for implementations with the critical patient safety issues raised by the potential for stale guidance. Note that CDS Services will need to negotiate with CDS Clients to ensure that hooks that are required to ensure patient safety are supported by the CDS Client. Extensions \u00b6 The specification is not prescriptive about support for extensions. However, to support extensions, the specification reserves the name extension and will never define an element with that name, allowing implementations to use it to provide custom behavior and information. The value of an extension element MUST be a pre-coordinated JSON object. Extension structures SHOULD use a strategy for naming that ensures global uniqueness, such as reverse-domain-name notation, as in the examples below. The intention here is that anything that has broad ranging value across the community enough to be a standardized extension has broad ranging value enough to be a first class citizen rather than an extension in CDS Hooks. STU Note: We seek implementer feedback on whether the recommendation to use namespace-based unique naming in the extension specification should be made mandatory or that we consider adding a mandatory field to extensions that indicates the source/type of the extension (as is done with FHIR). For example, an extension on a request could look like this: 1 2 3 4 5 6 7 8 9 10 11 12 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://fhir.example.org:9080\" , \"hook\" : \"patient-view\" , \"context\" : { \"userId\" : \"Practitioner/example\" }, \"extension\" : { \"com.example.timestamp\" : \"2017-11-27T22:13:25Z\" , \"com.cds-hooks.sandbox.myextension-practitionerspecialty\" : \"gastroenterology\" } } As another example, an extension defined on the discovery response could look like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { \"services\" : [ { \"title\" : \"Example CDS Service Discovery\" , \"hook\" : \"patient-view\" , \"id\" : \"patientview\" , \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" }, \"description\" : \"clinical decision support for patient view\" , \"extension\" : { \"com.example.clientConformance\" : \"http://hooks.example.org/fhir/102/Conformance/patientview\" } } ] } Data Types \u00b6 CDS Hooks leverages json data types throughout. This section defines data structures re-used across the specification. Coding \u00b6 The Coding data type captures the concept of a code. A code is understood only when the given code, code-system, and a optionally a human readable display are available. This coding type is a standalone data type in CDS Hooks modeled after a trimmed down version of the FHIR Coding data type . Field Optionality Type Description code REQUIRED string The code for what is being represented system REQUIRED string The codesystem for this code . display CONDITIONAL string A short, human-readable label to display. REQUIRED for Override Reasons provided by the CDS Service, OPTIONAL for Topic . Hooks \u00b6 Overview \u00b6 As a specification, CDS Hooks does not prescribe a default or required set of hooks for implementers. Rather, the set of hooks defined here are merely a set of common use cases that were used to aid in the creation of CDS Hooks. The set of hooks defined here are not a closed set; anyone is able to define new hooks to fit their use cases and propose those hooks to the community. New hooks are proposed in a prescribed format using the documentation template by submitting a pull request for community feedback. Hooks are versioned , and mature according to the Hook Maturity Model . Note that each hook (e.g. order-select ) represents something the user is doing in the CDS Client and multiple CDS Services might respond to the same hook (e.g. a \"price check\" service and a \"prior authorization\" service might both respond to order-select ). Hook context and prefetch \u00b6 What's the difference? \u00b6 Any user workflow or action within a CDS Client will naturally include contextual information such as the current user and patient. CDS Hooks refers to this information as context and allows each hook to define the information that is available in the context. Because CDS Hooks is intended to support usage within any CDS Client, this context can contain both required and optional data, depending on the capabilities of individual CDS Clients. However, the context information is intended to be relevant to most CDS Services subscribing to the hook. For example, consider a simple patient-view hook that is invoked whenever the user views a patient's information within the CDS Client. At this point in the workflow, the contextual information would include at least the current user and the patient that is being viewed. The hook declares this as context , and passes it to the CDS Service as part of the request in the context field: 1 2 3 4 \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" } Prefetch data, on the other hand, is defined by CDS Services as a way to allow the CDS Client to provide the data that a CDS Service needs as part of the initial request to the service. When the context data relates to a FHIR resource, it is important not to conflate context and prefetch. For instance, in the hook described above for opening a patient's chart, the hook context includes the id of the patient whose chart is being opened, not the full patient FHIR resource. In this case, the FHIR id of the patient is appropriate as the CDS Services may not be interested in details from the patient resource but instead other data related to this patient. Therefore, including the full patient resource in context would be unnecessary. Alternatively, a CDS Service may need the full patient resource in certain scenarios, in which case they can fetch it as needed from the FHIR server or request it to be prefetched using a prefetch template in their discovery response, such as: 1 2 3 \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } See the section on prefetch tokens for more information on how contextual information can be used to parameterize prefetch templates. Consider another hook for when a new patient is being registered. In this case, it would likely be appropriate for the context to contain the full FHIR resource for the patient being registered as the patient may not be yet recorded in the CDS Client (and thus not available from the FHIR server) and CDS Services using this hook would predominantly be interested in the details of the patient being registered. Additionally, consider a PGX CDS Service and a Zika screening CDS Service, each of which is subscribed to the same hook. The context data specified by their shared hook should contain data relevant to both CDS Services; however, each service will have other specific data needs that will necessitate disparate prefetch requests. For instance, the PGX CDS Service likely is interested in genomics data whereas the Zika screening CDS Service will want Observations. In summary, context is specified in the hook definition to guide developers on the information available at the point in the workflow when the hook is triggered. Prefetch data is defined by each CDS Service because it is specific to the information that service needs in order to process. Hook Definition Format \u00b6 Hooks are defined in the following format. hook-name-expressed-as-noun-verb \u00b6 The name of the hook SHOULD succinctly and clearly describe the activity or event. Hook names are unique so hook creators SHOULD take care to ensure newly proposed hooks do not conflict with an existing hook name. Hook creators SHALL name their hook with reverse domain notation (e.g. org.example.patient-transmogrify ) if the hook is specific to an organization. Reverse domain notation SHALL not be used by a standard hooks catalog. When naming hooks, the name should start with the subject (noun) of the hook and be followed by the activity (verb). For example, patient-view (not view-patient ) or order-sign (not sign-order ). Workflow \u00b6 Describe when this hook occurs in a workflow. Hook creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion among implementers. Context \u00b6 Describe the set of contextual data used by this hook. Only data logically and necessarily associated with the purpose of this hook should be represented in context. All fields defined by the hook's context MUST be defined in a table where each field is described by the following attributes: Field: The name of the field in the context JSON object. Hook authors SHOULD name their context fields to be consistent with other existing hooks when referring to the same context field. Optionality: A string value of either REQUIRED or OPTIONAL Prefetch Token: A string value of either Yes or No , indicating whether this field can be tokenized in a prefetch template. 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. The table below illustrates a sample hook context table: Field Optionality Prefetch Token Type Description someField REQUIRED Yes string A clear description of the value of this field. anotherField OPTIONAL No number A clear description of the value of this field. someObject REQUIRED No object A clear description of the value of this field. 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 \u00b6 For context fields that may contain multiple FHIR resources, the field SHOULD be defined as a FHIR Bundle, rather than as an array of FHIR resources. For example, multiple FHIR resources are necessary to describe all of the orders under review in the order-sign hook's draftOrders 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, imagine a hook, order-select that is invoked when a user selects a medication during an order workflow. The context data for this hook would contain draft FHIR resources representing the medications that have been selected for ordering. In this case, the CDS Client 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 \u00b6 Hook creators SHOULD include examples of the context. 1 2 3 4 5 6 7 8 9 \"context\" :{ \"someField\" : \"foo\" , \"anotherField\" : 123 , \"someObject\" : { \"color\" : \"red\" , \"version\" : 1 }, \"moreObjects\" :[] } If the context contains FHIR data, hook creators SHOULD include examples across multiple versions of FHIR if differences across FHIR versions are possible. Hook Maturity Model \u00b6 The intent of the CDS Hooks Maturity Model is to attain broad community engagement and consensus, before a hook is labeled as mature, that the hook is necessary, implementable, and worthwhile to the CDS Services and CDS Clients that would reasonably be expected to use it. Implementer feedback should drive the maturity of new hooks. Diverse participation in open developer forums and events, such as HL7 FHIR Connectathons, is necessary to achieve significant implementer feedback. The below criteria will be evaluated with these goals in mind. 1 Hook maturity | 3 - Considered The Hook maturity levels use the term CDS Client to generically refer to the clinical workflow system in which a CDS Services returned cards are displayed. Maturity Level Maturity title Requirements 0 Draft Hook is defined according to the hook definition format . 1 Submitted The above, and \u2026 Hook definition is written up as a github pull request using the Hook template and community feedback is solicited on the zulip CDS Hooks stream . 2 Tested The above, and \u2026 The hook has been tested and successfully supports interoperability among at least one CDS Client and two independent CDS Services using semi-realistic data and scenarios (e.g. at a FHIR Connectathon). The github pull request defining the hook is approved and published by the CDS Hooks Project Management Committee. 3 Considered The above, and \u2026 At least 3 distinct organizations recorded ten distinct implementer comments (including a github issue, tracker item, or comment on the hook definition page), including at least two CDS Clients and three independent CDS Services. The hook has been tested at two Connectathons. 4 Documented The above, and \u2026 The author agrees that the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes. The hook is implemented in the standard CDS Hooks sandbox and multiple prototype projects. The Hook specification SHALL: Identify a broad set of example contexts in which the hook may be used with a minimum of three, but as many as 8-10. Clearly differentiate the hook from similar hooks or other standards to help an implementer determine if the hook is correct for their scenario. Explicitly document example scenarios when the hook should not be used. 5 Mature The above, and ... The hook has been implemented in production in at least two CDS Clients and three independent CDS Services. An HL7 working group ballots the hook and the hook has passed HL7 STU ballot. 6 Normative The above, and ... the responsible HL7 working group and the CDS working group agree the material is ready to lock down and the hook has passed HL7 normative ballot Changes to a Hook \u00b6 Each hook MUST include a Metadata table at the beginning of the hook with the specification version and hook version as described in the following sections. Specification Version \u00b6 Because hooks are such an integral part of the CDS Hooks specification, hook definitions are associated with specific versions of the specification. The hook definition MUST include the version (or versions) of the CDS Hooks specification that it is defined to work with. 1 specificationVersion | 1.0 Because the specification itself follows semantic versioning, the version specified here is a minimum specification version. In other words, a hook defined to work against 1.0 should continue to work against the 1.1 version of CDS Hooks. However, a hook that specifies 1.1 would not be expected to work in a CDS Hooks 1.0 environment. Hook Version \u00b6 To enable tracking of changes to hook definitions, each hook MUST include a version indicator, expressed as a string. 1 hookVersion | 1.0 To help ensure the stability of CDS Hooks implementations, once a hook has been defined (i.e. published with a particular name so that it is available for implementation), breaking changes MUST NOT be made. This means that fields can be added and restrictions relaxed, but fields cannot be changed, and restrictions cannot be tightened. In particular, the semantics of a hook (i.e. the meaning of the hook from the perspective of the CDS Client) cannot be changed. CDS Clients 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 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 Major 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 Change of semantics of an existing context field Major Change of semantics of the hook Major When a major change is made, the hook definition MUST be published under a new name. When a minor or patch change is made, the hook version MUST be updated. Hook definers MUST use semantic versioning to communicate the impact of changes in an industry standard way. Note that the intent of this table is to outline possible breaking changes. The authors have attempted to enumerate these types of changes exhaustively, but as new types of breaking changes are identified, this list will be updated. Hook Maturity \u00b6 As each hook progresses through a process of being defined, tested, implemented, used in production environments, and balloted, the hook's formal maturity level increases. Each hook has its own maturity level, which MUST be defined in the hook's definition and correspond to the Hook Maturity Model . 1 hookMaturity | 0 - Draft Change Log \u00b6 Changes made to a hook's definition MUST be documented in a change log to ensure hook consumers can track what has been changed over the life of a hook. The change log MUST contain the following elements: Version: The version of the change Description: A description of the change and its impact For example: Version Description 1.1 Added new context variable 1.0.1 Clarified context variable usage 1.0 Initial Release","title":"Current (draft)"},{"location":"specification/current/#overview","text":"The CDS Hooks specification describes the RESTful APIs and interactions using JSON over HTTPS to integrate Clinical Decision Support (CDS) between CDS Clients (typically Electronic Health Record Systems (EHRs) or other health information systems) and CDS Services.","title":"Overview"},{"location":"specification/current/#conformance-language","text":"The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this specification are to be interpreted as described in RFC2119 . Further, the key word \"CONDITIONAL\" indicates that a particular item is either REQUIRED or OPTIONAL, based upon another item.","title":"Conformance Language"},{"location":"specification/current/#use-of-json","text":"All data exchanged through production RESTful APIs MUST be sent and received as JSON (JavaScript Object Notation) structures and are transmitted over HTTPS. See Security and Safety section. Null and empty JSON elements JSON elements SHALL NOT be null, unless otherwise specified. JSON elements SHALL NOT be empty, unless otherwise specified (e.g. to indicate no guidance with an empty array of cards in the CDS Hooks response). If a JSON attribute is defined as OPTIONAL, and does not have a value, implementers MUST omit it. For instance, OPTIONAL JSON string and array attributes are omitted rather than having a null or empty value. Unless otherwise specified, JSON attribute values SHALL NOT be null or empty, so null , \"\" , [] , or {} are prohibited. If a JSON attribute is defined with as OPTIONAL, and does not have a value, implementers SHALL omit it.","title":"Use of JSON"},{"location":"specification/current/#cds-hooks-anatomy","text":"This specification describes a \"hook\" -based pattern for invoking decision support from within a clinician's workflow. The API supports: Synchronous, workflow-triggered CDS calls returning information and suggestions Launching a web page to provide additional information to the user Launching a user-facing SMART app when CDS requires additional interaction The main concepts of the specification are Services, CDS Clients, and Cards.","title":"CDS Hooks Anatomy"},{"location":"specification/current/#cds-services","text":"A CDS Service is a service that provides recommendations and guidance through the RESTful APIs described by this specification. The primary APIs are Discovery , which allows a CDS Developer to publish the types of CDS Services it provides. The Service API that CDS Clients use to request decision support. The Feedback API through which services learn the outcomes of their recommendations and guidance.","title":"CDS Services"},{"location":"specification/current/#cds-clients","text":"A CDS Client is an Electronic Health Record (EHR), or other clinical information system that uses decision support by calling CDS Services at specific points in the application's workflow called hooks . Each hook defines the hook context (contextual information available within the CDS Client and specific to the workflow) that is provided as part of the request. Each service advertises which hooks it supports and what prefetch data (information needed by the CDS Service to determine what decision support should be presented) it requires. In addition, CDS Clients typically provide the FHIR resource server location and associated authorization information as part of the request to enable services to request additional information.","title":"CDS Clients"},{"location":"specification/current/#cards","text":"Decision support is then returned to the CDS Client in the form of cards , which the CDS Client MAY display to the end-user as part of their workflow. Cards may be informational, or they may provide suggestions that the user may accept or reject they may provide a link to additional information or even launch a SMART app when additional user interaction is required.","title":"Cards"},{"location":"specification/current/#discovery","text":"A CDS Service is discoverable via a stable endpoint by CDS Clients. The Discovery endpoint includes information such as a description of the CDS Service, when it should be invoked, and any data that is requested to be prefetched. A CDS Service provider exposes its discovery endpoint at: 1 { baseURL } /cds-services","title":"Discovery"},{"location":"specification/current/#http-request","text":"The Discovery endpoint SHALL always be available at {baseUrl}/cds-services . For example, if the baseUrl is https://example.com, the CDS Client can retrieve the list of CDS Services by invoking: GET https://example.com/cds-services","title":"HTTP Request"},{"location":"specification/current/#response","text":"The response to the discovery endpoint SHALL be an object containing a list of CDS Services. Field Description services array . An array of CDS Services . If your CDS server hosts no CDS Services, the discovery endpoint should return a 200 HTTP response with an empty array of services. Each CDS Service SHALL be described by the following attributes. Field Optionality Type Description hook REQUIRED string The hook this service should be invoked on. See Hooks . title RECOMMENDED string The human-friendly name of this service. description REQUIRED string The description of this service. id REQUIRED string The {id} portion of the URL to this service which is available at {baseUrl}/cds-services/{id} prefetch OPTIONAL object An object containing key/value pairs of FHIR queries that this service is requesting the CDS Client to perform and provide on each service call. The key is a string that describes the type of data being requested and the value is a string representing the FHIR query. See Prefetch Template . usageRequirements OPTIONAL string Human-friendly description of any preconditions for the use of this CDS Service. Note that a CDS server can host multiple entries of CDS service with the same id for different hook s. This allows a service to update its advice based on changes in workflow as discussed in update stale guidance .","title":"Response"},{"location":"specification/current/#http-status-codes","text":"Code Description 200 OK A successful response. CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes.","title":"HTTP Status Codes"},{"location":"specification/current/#discovery-example","text":"1 curl \"https://example.com/cds-services\" The above command returns JSON structured like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 { \"services\" : [ { \"hook\" : \"patient-view\" , \"title\" : \"Static CDS Service Example\" , \"description\" : \"An example of a CDS Service that returns a static set of cards\" , \"id\" : \"static-patient-greeter\" , \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } }, { \"hook\" : \"order-select\" , \"title\" : \"Order Echo CDS Service\" , \"description\" : \"An example of a CDS Service that simply echoes the order(s) being placed\" , \"id\" : \"order-echo\" , \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" , \"medications\" : \"MedicationRequest?patient={{context.patientId}}\" } }, { \"hook\" : \"order-sign\" , \"title\" : \"Pharmacogenomics CDS Service\" , \"description\" : \"An example of a more advanced, precision medicine CDS Service\" , \"id\" : \"pgx-on-order-sign\" , \"usageRequirements\" : \"Note: functionality of this CDS Service is degraded without access to a FHIR Restful API as part of CDS recommendation generation.\" } ] }","title":"Discovery Example"},{"location":"specification/current/#calling-a-cds-service","text":"","title":"Calling a CDS Service"},{"location":"specification/current/#http-request_1","text":"A CDS Client SHALL call a CDS Service by POST ing a JSON document to the service as described in this section. The CDS Service endpoint can be constructed from the CDS Service base URL and an individual service id as {baseUrl}/cds-services/{service.id} . CDS Clients may add additional requirements for the triggering of a hook, based upon the user, workflow, CDS Service or other reasons (e.g. if the service is provided by a payer, the patient has active coverage with that payer). See Trusting CDS Services for additional considerations. The request SHALL include a JSON POST body with the following input fields: Field Optionality Type Description hook REQUIRED string The hook that triggered this CDS Service call. See Hooks . hookInstance REQUIRED string A universally unique identifier (UUID) for this particular hook call (see more information below). fhirServer CONDITIONAL URL The base URL of the CDS Client's FHIR server. If fhirAuthorization is provided, this field is REQUIRED. The scheme MUST be https when production data is exchanged. fhirAuthorization OPTIONAL object A structure holding an 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 section for more information. context REQUIRED object Hook-specific contextual data that the CDS service will need. For example, with the patient-view hook this will include the FHIR id of the Patient being viewed. For details, see the Hooks specific specification page (example: patient-view ). prefetch OPTIONAL object The FHIR data that was prefetched by the CDS Client (see more information below).","title":"HTTP Request"},{"location":"specification/current/#hookinstance","text":"While working in the CDS Client, a user can perform multiple actions in series or in parallel. For example, a clinician might prescribe two drugs in a row; each prescription action would be assigned a unique hookInstance . This allows a CDS Service to uniquely identify each hook invocation. Note: the hookInstance is globally unique and should contain enough entropy to be un-guessable.","title":"hookInstance"},{"location":"specification/current/#example","text":"1 2 3 4 5 curl -X POST \\ -H 'Content-type: application/json' \\ --data @hook-details-see-example-below \"https://example.com/cds-services/static-patient-greeter\" 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://hooks.smarthealthit.org:9080\" , \"hook\" : \"patient-view\" , \"fhirAuthorization\" : { \"access_token\" : \"some-opaque-fhir-access-token\" , \"token_type\" : \"Bearer\" , \"expires_in\" : 300 , \"scope\" : \"user/Patient.read user/Observation.read\" , \"subject\" : \"cds-service4\" }, \"context\" : { \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" }, \"prefetch\" : { \"patientToGreet\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1925-12-23\" , \"id\" : \"1288992\" , \"active\" : true } } }","title":"Example"},{"location":"specification/current/#providing-fhir-resources-to-a-cds-service","text":"CDS Services require specific FHIR resources in order to compute the recommendations the CDS Client requests. If real-world performance were no issue, a CDS Client could launch a CDS Service passing only context data (such as the current user and patient ids), and the CDS Service could obtain authorization to access the CDS Client's FHIR API, retrieving any resources required via FHIR read or search interactions. Given that CDS Services SHOULD respond quickly (on the order of 500 ms.), this specification defines mechanisms that allow a CDS Service to request and obtain FHIR resources more efficiently. Two optional methods are provided. In the first method, FHIR resources MAY be obtained by passing \"prefetched\" data from the CDS Client to the CDS Service in the service call. If data is to be prefetched, the CDS Service registers a set of \"prefetch templates\" with the CDS Client, as described in the Prefetch Template section below. These \"prefetch templates\" are defined in the CDS Service discovery response . The FHIR resources are passed as key-value pairs, with each key matching a key described in the discovery response, and each value being a FHIR resource. Note that in the case of searches, this resource may be a searchset Bundle. The second method enables the CDS Service to retrieve FHIR resources for itself, without the need to request and obtain its own authorization. If the CDS Client decides to have the CDS Service fetch its own FHIR resources, the CDS Client obtains and passes directly to the CDS Service a bearer token issued for the CDS Service's use in executing FHIR API calls against the CDS Client's FHIR server to obtain the required resources. Some CDS Clients MAY pass prefetched data, along with a bearer token for the CDS Service to use if additional resources are required. Each CDS Client SHOULD decide which approach, or combination, is preferred, based on performance considerations and assessment of attendant security and safety risks. CDS Services should be capable of accessing FHIR resources via either prefetch or from the CDS Client's FHIR server. For more detail, see the FHIR Resource Access section below. Similarly, each CDS Client will decide what FHIR resources to authorize and to prefetch, based on the CDS Service discovery response's \"prefetch\" request and on the provider's assessment of the \"minimum necessary.\" The CDS Client provider and the CDS Service provider will negotiate the set of FHIR resources to be provided, and how these data will be provided, as part of their service agreement.","title":"Providing FHIR Resources to a CDS Service"},{"location":"specification/current/#prefetch-template","text":"A prefetch template is a FHIR read or search request that describes relevant data needed by the CDS Service. For example, the following is a prefetch template for hemoglobin A1c observations: 1 Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date To allow for prefetch templates that are dependent on the workflow context, prefetch templates may include references to context using prefetch tokens . In the above example, {{context.patientId}} is a prefetch token. The prefetch field of a CDS Service discovery response defines the set of prefetch templates for that service, providing a prefetch key for each one that is used to identify the prefetch data in the CDS request. For example: 1 2 3 4 5 { \"prefetch\" : { \"hemoglobin-a1c\" : \"Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date\" } } In this prefetch , hemoglobin-a1c is the prefetch key for this prefetch template. For a complete worked example, see below . A CDS Client MAY choose to honor zero, some, or all of the desired prefetch templates, and is free to choose the most appropriate source for these data. For example: The CDS Client MAY have some of the desired prefetched data already in memory, thereby removing the need for any network call The CDS Client MAY compute an efficient set of prefetch templates from multiple CDS Services, thereby reducing the number of calls to a minimum The CDS Client MAY satisfy some of the desired prefetched templates via some internal service or even its own FHIR server. The CDS Client SHALL only provide access to resources that are within the user's authorized scope. As part of preparing the request, a CDS Client processes each prefetch template it intends to satisfy by replacing the prefetch tokens in the prefetch template to construct a relative FHIR request URL. This specification is not prescriptive about how this request is actually processed. The relative URL may be appended to the base URL for the CDS Client's FHIR server and directly invoked, or the CDS Client may use internal infrastructure to satisfy the request in the same way that invoking against the FHIR server would. Regardless of how the CDS Client satisfies the prefetch templates (if at all), the prefetched data given to the CDS Service MUST be equivalent to the data the CDS Service would receive if it were making its own call to the CDS Client's FHIR server using the parameterized prefetch template. Note that this means that CDS services will receive only the information they have requested and are authorized to receive. Prefetch data for other services registered to the same hook MUST NOT be provided. In other words, services SHALL only receive the data they requested in their prefetch. The resulting response is passed along to the CDS Service using the prefetch parameter (see below . Note that a CDS Client MAY paginate prefetch results. The intent of allowing pagination is to ensure that prefetch queries that may be too large for a single payload can still be retrieved by the service. The decision to paginate and the size of pages is entirely at the CDS Client's discretion. CDS Clients are encouraged to only use pagination when absolutely necessary, keeping performance and user experience in mind. The CDS Client MUST NOT send any prefetch template key that it chooses not to satisfy. If the CDS Client encounters errors prefetching the requested data, OperationOutcome(s) SHOULD be used to communicate those errors to prevent the CDS Service from incurring an unneeded follow-up query. CDS Clients MUST omit the prefetch key if relevant details cannot be provided (e.g. intermittent connectivity issues). CDS Services SHOULD check any prefetched data for the existence of OperationOutcomes. If the CDS Client has no data to populate a template prefetch key, the prefetch template key MUST have a value of null . Note that the null result is used rather than a bundle with zero entries to account for the possibility that the prefetch url is a single-resource request. It is the CDS Service's responsibility to check prefetched data against its template to determine what requests were satisfied (if any) and to programmatically retrieve any additional necessary data. If the CDS Service is unable to obtain required data because it cannot access the FHIR server and the request did not contain the necessary prefetch keys, the service SHALL respond with an HTTP 412 Precondition Failed status code.","title":"Prefetch Template"},{"location":"specification/current/#prefetch-tokens","text":"A prefetch token is a placeholder in a prefetch template that is replaced by information from the hook's context to construct the FHIR URL used to request the prefetch data. Prefetch tokens MUST be delimited by {{ and }} , and MUST contain only the qualified path to a hook context field or one of the following user identifiers: userPractitionerId , userPractitionerRoleId , userPatientId , or userRelatedPersonId . 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 example, {{context.medication.id}} is not a valid prefetch token because it attempts to access the id field of the medication field.","title":"Prefetch tokens"},{"location":"specification/current/#prefetch-tokens-identifying-the-user","text":"A prefetch template enables a CDS Service to learn more about the current user through a FHIR read, like so: 1 2 3 4 5 { \"prefetch\": { \"user\": \"{{context.userId}}\" } } or though a FHIR search: 1 2 3 4 5 { \"prefetch\": { \"user\": \"PractitionerRole?_id={{userPractitionerRoleId}}&_include=PractitionerRole:practitioner\" } } A prefetch template may include any of the following prefetch tokens: Token Description {{userPractitionerId}} FHIR id of the Practitioner resource corresponding to the current user. {{userPractitionerRoleId}} FHIR id of the PractitionerRole resource corresponding to the current user. {{userPatientId}} FHIR id of the Patient resource corresponding to the current user. {{userRelatedPersonId}} FHIR id of the RelatedPerson resource corresponding to the current user. No single FHIR resource represents a user, rather Practitioner and PractitionerRole may be jointly used to represent a provider, and Patient or RelatedPerson are used to represent a patient or their proxy. Hook definitions typically define a context.userId field and corresponding prefetch token.","title":"Prefetch tokens identifying the user"},{"location":"specification/current/#prefetch-query-restrictions","text":"To reduce the implementation burden on CDS Clients that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. When using this subset, valid prefetch templates MUST only make use of: instance level read interactions (for resources with known ids such as Patient , Practitioner , or Encounter ) type level search interactions; e.g. patient={{context.patientId}} Resource references (e.g. patient={{context.patientId}} ) token search parameters using equality (e.g. code=4548-4 ) and optionally the :in modifier (no other modifiers for token parameters) date search parameters on date , dateTime , instant , or Period types only, and using only the prefixes eq , lt , gt , ge , le the _count parameter to limit the number of results returned the _sort parameter to allow for most recent and first queries","title":"Prefetch query restrictions"},{"location":"specification/current/#example-prefetch-token","text":"Often a prefetch template builds on the contextual data associated with the hook. For example, a particular CDS Service might recommend guidance based on a patient's conditions when the chart is opened. The FHIR query to retrieve these conditions might be Condition?patient=123 . In order to express this as a prefetch template, the CDS Service must express the FHIR id of the patient as a token so that the CDS Client can replace the token with the appropriate value. When context fields are used as tokens, their token name MUST be context.name-of-the-field . For example, given a context like: 1 2 3 4 5 { \"context\" : { \"patientId\" : \"123\" } } The token name would be {{context.patientId}} . Again using our above conditions example, the complete prefetch template would be Condition?patient={{context.patientId}} . Only the first level fields in context may be considered for tokens. For example, given the following context that contains amongst other things, a MedicationRequest FHIR resource: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { \"context\" : { \"encounterId\" : \"456\" , \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"123\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }]}, \"subject\" : { \"reference\" : \"Patient/1288992\" } } } ] } } } Only the encounterId field in this example is eligible to be a prefetch token as it is a first level field and the datatype (string) can be placed into the FHIR query. The MedicationRequest.id value in the context is not eligible to be a prefetch token because it is not a first level field. If the hook creator intends for the MedicationRequest.id value to be available as a prefetch token, it must be made available as a first level field. Using the aforementioned example, we simply add a new medicationRequestId field: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 { \"context\" : { \"medicationRequestId\" : \"123\" , \"encounterId\" : \"456\" , \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"123\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }]}, \"subject\" : { \"reference\" : \"Patient/1288992\" } } } ] } } }","title":"Example prefetch token"},{"location":"specification/current/#example-prefetch-templates","text":"1 2 3 4 5 6 7 8 { \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" , \"hemoglobin-a1c\" : \"Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date\" , \"diabetes-type2\" : \"Condition?patient={{context.patientId}}&code=44054006&category=problem-list-item&status=active\" , \"user\" : \"PractitionerRole?_id={{userPractitionerRoleId}}\" } } Here is an example prefetch field from a CDS Service discovery endpoint. The goal is to know, at call time: Key Description patient Patient demographics. hemoglobin-a1c Most recent Hemoglobin A1c reading for this patient. diabetes-type2 If the patient has an active condition of diabetes mellitus on their problem list. user Information on the current user.","title":"Example prefetch templates"},{"location":"specification/current/#example-prefetch-data","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 { \"prefetch\" : { \"patient\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1974-12-25\" , \"...\" : \"<snipped for brevity>\" }, \"hemoglobin-a1c\" : { \"resourceType\" : \"Bundle\" , \"type\" : \"searchset\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"Observation\" , \"code\" : { \"coding\" : [ { \"system\" : \"http://loinc.org\" , \"code\" : \"4548-4\" , \"display\" : \"Hemoglobin A1c\" } ] }, \"...\" : \"<snipped for brevity>\" } } ] }, \"user\" : \"123\" } } The CDS Hooks request is augmented to include two prefetch values, where the dictionary keys match the request keys ( patient and hemoglobin-a1c in this case). Note that the missing diabetes-type2 key indicates that either the CDS Client has decided not to satisfy this particular prefetch template or it was not able to retrieve this prefetched data. The CDS Service is responsible for retrieving the FHIR resource representing the user from the FHIR server (if required).","title":"Example prefetch data"},{"location":"specification/current/#fhir-resource-access","text":"If the CDS Client provides both fhirServer and fhirAuthorization request parameters, the CDS Service MAY use the FHIR server to obtain any FHIR resources for which it's authorized, beyond those provided by the CDS Client as prefetched data. This is similar to the approach used by SMART on FHIR wherein the SMART app requests and ultimately obtains an access token from the CDS Client's Authorization server using the SMART launch workflow, as described in SMART App Launch Implementation Guide . Like SMART on FHIR, CDS Hooks requires that CDS Services present a valid access token to the FHIR server with each API call. Thus, a CDS Service requires an access token before communicating with the CDS Client's FHIR resource server. While CDS Hooks shares the underlying technical framework and standards as SMART on FHIR, the CDS Hooks workflow MUST accommodate the automated, low-latency delivery of an access token to the CDS service. With CDS Hooks, if the CDS Client wants to provide the CDS Service direct access to FHIR resources, the CDS Client creates or obtains an access token prior to invoking the CDS Service, passing this token to the CDS Service as part of the service call. This approach remains compatible with OAuth 2.0's bearer token protocol while minimizing the number of HTTPS round-trips and the service invocation latency. The CDS Client remains in control of providing an access token that is associated with the specific CDS Service, user, and context of the invocation. As the CDS Service executes on behalf of a user, the data to which the CDS Service is given access by the CDS Client MUST be limited to the same restrictions and authorizations afforded the current user. As such, the access token SHALL be scoped to: The CDS Service being invoked The current user","title":"FHIR Resource Access"},{"location":"specification/current/#passing-the-access-token-to-the-cds-service","text":"The access token is specified in the CDS Service request via the fhirAuthorization request parameter. This parameter is an object that contains both the access token as well as other related information as specified below. If the CDS Client chooses not to pass along an access token, the fhirAuthorization parameter is omitted. Field Optionality Type Description access_token REQUIRED string This is the OAuth 2.0 access token that provides access to the FHIR server. token_type REQUIRED string Fixed value: Bearer expires_in REQUIRED integer The lifetime in seconds of the access token. scope REQUIRED string The scopes the access token grants the CDS Service. subject REQUIRED string The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server. 'patient` CONDITIONAL string If the granted SMART scopes include patient scopes (i.e. \"patient/\"), the access token is restricted to a specific patient. This field SHOULD be populated to identify the FHIR id of that patient. The scopes granted to the CDS Service via the scope field are defined by the SMART on FHIR specification . The expires_in value is established by the authorization server and SHOULD BE very short lived, as the access token MUST be treated as a transient value by the CDS Service. CDS Clients SHOULD revoke an issued access token upon the completion of the CDS Hooks request/response to limit the validity period of the token. Below is an example fhirAuthorization parameter: 1 2 3 4 5 6 7 8 9 { \"fhirAuthorization\" : { \"access_token\" : \"some-opaque-fhir-access-token\" , \"token_type\" : \"Bearer\" , \"expires_in\" : 300 , \"scope\" : \"user/Patient.read user/Observation.read\" , \"subject\" : \"cds-service4\" } }","title":"Passing the Access Token to the CDS Service"},{"location":"specification/current/#cds-service-response","text":"For successful responses, CDS Services SHALL respond with a 200 HTTP response with an object containing a cards array and optionally a systemActions array as described below. Each card contains decision support guidance from the CDS Service. Cards are intended for display to an end user. The data format of a card defines a very minimal set of required attributes with several more optional attributes to suit a variety of use cases, such as: narrative informational decision support, actionable suggestions to modify data, and links to SMART apps. Note that because the CDS client may be invoking multiple services from the same hook, there may be multiple responses related to the same information. This specification does not address these scenarios specifically; both CDS Services and CDS Clients should consider the implications of multiple CDS Services in their integrations and are invited to consider card attributes when determining prioritization and presentation options.","title":"CDS Service Response"},{"location":"specification/current/#http-status-codes_1","text":"Code Description 200 OK A successful response. 412 Precondition Failed The CDS Service is unable to retrieve the necessary FHIR data to execute its decision support, either through a prefetch request or directly calling the FHIR server. CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes.","title":"HTTP Status Codes"},{"location":"specification/current/#http-response","text":"Field Optionality Type Description cards REQUIRED array of Cards An array of Cards . Cards can provide a combination of information (for reading), suggested actions (to be applied if a user selects them), and links (to launch an app if the user selects them). The CDS Client decides how to display cards, but this specification recommends displaying suggestions using buttons, and links using underlined text. systemActions OPTIONAL array of Actions An array of Actions that the CDS Service proposes to auto-apply. Each action follows the schema of a card-based suggestion.action . The CDS Client decides whether to auto-apply actions. If your CDS Service has no decision support for the user, your service should return a 200 HTTP response with an empty array of cards, for example: 1 2 3 { \"cards\" : [] } Clients SHOULD remove cards returned by previous invocations of a hook to a service with the same id when a new hook is triggered (see update stale guidance ).","title":"HTTP Response"},{"location":"specification/current/#card-attributes","text":"Each Card is described by the following attributes. Field Optionality Type Description uuid OPTIONAL string Unique identifier of the card. MAY be used for auditing and logging cards and SHALL be included in any subsequent calls to the CDS service's feedback endpoint. summary REQUIRED string One-sentence, <140-character summary message for display to the user inside of this card. detail OPTIONAL string Optional detailed information to display; if provided MUST be represented in (GitHub Flavored) Markdown . (For non-urgent cards, the CDS Client MAY hide these details until the user clicks a link like \"view more details...\"). indicator REQUIRED string Urgency/importance of what this card conveys. Allowed values, in order of increasing urgency, are: info , warning , critical . The CDS Client MAY use this field to help make UI display decisions such as sort order or coloring. source REQUIRED object Grouping structure for the Source of the information displayed on this card. The source should be the primary source of guidance for the decision support the card represents. suggestions OPTIONAL array of Suggestions Allows a service to suggest a set of changes in the context of the current activity (e.g. changing the dose of a medication currently being prescribed, for the order-sign activity). If suggestions are present, selectionBehavior MUST also be provided. selectionBehavior CONDITIONAL string Describes the intended selection behavior of the suggestions in the card. Allowed values are: at-most-one , indicating that the user may choose none or at most one of the suggestions; any , indicating that the end user may choose any number of suggestions including none of them and all of them. CDS Clients that do not understand the value MUST treat the card as an error. overrideReasons OPTIONAL array of Coding Override reasons can be selected by the end user when overriding a card without taking the suggested recommendations. The CDS service MAY return a list of override reasons to the CDS client. If override reasons are present, the CDS Service MUST populate a display value for each reason's Coding . The CDS Client SHOULD present these reasons to the clinician when they dismiss a card. A CDS Client MAY augment the override reasons presented to the user with its own reasons. links OPTIONAL array of Links Allows a service to suggest a link to an app that the user might want to run for additional information or to help guide a decision.","title":"Card Attributes"},{"location":"specification/current/#source","text":"The Source is described by the following attributes. Field Optionality Type Description label REQUIRED string A short, human-readable label to display for the source of the information displayed on this card. If a url is also specified, this MAY be the text for the hyperlink. url OPTIONAL URL An optional absolute URL to load (via GET , in a browser context) when a user clicks on this link to learn more about the organization or data set that provided the information on this card. Note that this URL should not be used to supply a context-specific \"drill-down\" view of the information on this card. For that, use card.link.url instead. icon OPTIONAL URL An absolute URL to an icon for the source of this card. The icon returned by this URL SHOULD be a 100x100 pixel PNG image without any transparent regions. The CDS Client may ignore or scale the image during display as appropriate for user experience. topic OPTIONAL Coding A topic describes the content of the card by providing a high-level categorization that can be useful for filtering, searching or ordered display of related cards in the CDS client's UI. This specification does not prescribe a standard set of topics. Below is an example source parameter: 1 2 3 4 5 6 7 8 9 10 11 12 { \"source\" : { \"label\" : \"Zika Virus Management\" , \"url\" : \"https://example.com/cdc-zika-virus-mgmt\" , \"icon\" : \"https://example.com/cdc-zika-virus-mgmt/100.png\" , \"topic\" : { \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/topics\" , \"code\" : \"12345\" , \"display\" : \"Mosquito born virus\" } } }","title":"Source"},{"location":"specification/current/#suggestion","text":"Each Suggestion is described by the following attributes. Field Optionality Type Description label REQUIRED string Human-readable label to display for this suggestion (e.g. the CDS Client might render this as the text on a button tied to this suggestion). uuid OPTIONAL string Unique identifier, used for auditing and logging suggestions. isRecommended OPTIONAL boolean When there are multiple suggestions, allows a service to indicate that a specific suggestion is recommended from all the available suggestions on the card. CDS Hooks clients may choose to influence their UI based on this value, such as pre-selecting, or highlighting recommended suggestions. Multiple suggestions MAY be recommended, if card.selectionBehavior is any . actions OPTIONAL array of Actions Array of objects, each defining a suggested action. Within a suggestion, all actions are logically AND'd together, such that a user selecting a suggestion selects all of the actions within it. When a suggestion contains multiple actions, the actions SHOULD be processed as per FHIR's rules for processing transactions with the CDS Client's fhirServer as the base url for the inferred full URL of the transaction bundle entries. (Specifically, deletes happen first, then creates, then updates).","title":"Suggestion"},{"location":"specification/current/#action","text":"Each Action is described by the following attributes. Field Optionality Type Description type REQUIRED string The type of action being performed. Allowed values are: create , update , delete . description REQUIRED string Human-readable description of the suggested action MAY be presented to the end-user. resource CONDITIONAL object A FHIR resource. When the type attribute is create , the resource attribute SHALL contain a new FHIR resource to be created. For update , this holds the updated resource in its entirety and not just the changed fields. Use of this field to communicate a string of a FHIR id for delete suggestions is DEPRECATED and resourceId SHOULD be used instead. resourceId CONDITIONAL string A relative reference to the relevant resource. SHOULD be provided when the type attribute is delete . The following example illustrates a create action: 1 2 3 4 5 6 7 8 9 { \"type\" : \"create\" , \"description\" : \"Create a prescription for Acetaminophen 250 MG\" , \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"medrx001\" , \"...\" : \"<snipped for brevity>\" } } The following example illustrates an update action: 1 2 3 4 5 6 7 8 9 { \"type\" : \"update\" , \"description\" : \"Update the order to record the appropriateness score\" , \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"procedure-request-1\" , \"...\" : \"<snipped for brevity>\" } } The following example illustrates a delete action: 1 2 3 4 5 { \"type\" : \"delete\" , \"description\" : \"Remove the inappropriate order\" , \"resourceId\" : \"ServiceRequest/procedure-request-1\" }","title":"Action"},{"location":"specification/current/#reasons-for-rejecting-a-card","text":"overrideReasons is an array of Coding that captures a codified set of reasons an end user may select from as the rejection reason when rejecting the advice presented in the card. When using the coding object to represent a reason, CDS Services MUST provide a human readable text in the display property and CDS Clients MAY incorporate it into their user interface. This specification does not prescribe a standard set of override reasons; implementers are encouraged to submit suggestions for standardization. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 { \"overrideReasons\" : [ { \"code\" : \"reason-code-provided-by-service\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Patient refused\" }, { \"code\" : \"12354\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Contraindicated\" } ] }","title":"Reasons for rejecting a card"},{"location":"specification/current/#link","text":"Each Link is described by the following attributes. Field Optionality Type Description label REQUIRED string Human-readable label to display for this link (e.g. the CDS Client might render this as the underlined text of a clickable link). url REQUIRED URL URL to load (via GET , in a browser context) when a user clicks on this link. Note that this MAY be a \"deep link\" with context embedded in path segments, query parameters, or a hash. type REQUIRED string The type of the given URL. There are two possible values for this field. A type of absolute indicates that the URL is absolute and should be treated as-is. A type of smart indicates that the URL is a SMART app launch URL and the CDS Client should ensure the SMART app launch URL is populated with the appropriate SMART launch parameters. appContext OPTIONAL string An optional field that allows the CDS Service to share information from the CDS card with a subsequently launched SMART app. The appContext field should only be valued if the link type is smart and is not valid for absolute links. The appContext field and value will be sent to the SMART app as part of the OAuth 2.0 access token response, alongside the other SMART launch parameters when the SMART app is launched. Note that appContext could be escaped JSON, base64 encoded XML, or even a simple string, so long as the SMART app can recognize it. CDS Client support for appContext requires additional coordination with the authorization server that is not described or specified in CDS Hooks nor SMART. autolaunchable OPTIONAL boolean This field serves as a hint to the CDS Client suggesting this link be immediately launched, without displaying the card and without manual user interaction. Note that CDS Hooks cards which contain links with this field set to true, may not be shown to the user. Sufficiently advanced CDS Clients may support automatically launching multiple links or multiple cards. Implementer guidance is requested to determine if the specification should preclude these advanced scenarios.","title":"Link"},{"location":"specification/current/#considerations-for-autolaunchable-and-user-experience","text":"The intent of this optional feature is to improve individual user experience by removing the otherwise unnecessary click of a link by the user. Appropriate support of this feature includes guardrails from both the CDS Service developer and the CDS Client, as well as additional local control by the organization using the service. The CDS Client ultimately determines if a link can be automatically launched, taking into consideration user interface needs, workflow considerations, or even absence of support for this optional feature. If a CDS Hooks response contains guidance in addition to an autolaunchable link, it's the CDS Service's responsibility to ensure that any decision support that exists in the CDS Hooks response's card(s) is communicated via the launched app.","title":"Considerations for autolaunchable and user experience"},{"location":"specification/current/#system-action","text":"A systemAction is the same Action which may be returned in a suggestion, but is instead returned alongside the array of cards. A systemAction is not presented to the user within a card, but rather may be auto-applied without user intervention. 1 2 3 4 5 6 7 8 9 10 11 12 13 { \"cards\" : [], \"systemActions\" : [ { \"type\" : \"update\" , \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"...\" : \"<snipped for brevity\" } } ] }","title":"System Action"},{"location":"specification/current/#example_1","text":"Example response 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 { \"cards\" : [ { \"uuid\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"summary\" : \"Example Card\" , \"indicator\" : \"info\" , \"detail\" : \"This is an example card.\" , \"source\" : { \"label\" : \"Static CDS Service Example\" , \"url\" : \"https://example.com\" , \"icon\" : \"https://example.com/img/icon-100px.png\" }, \"links\" : [ { \"label\" : \"Google\" , \"url\" : \"https://google.com\" , \"type\" : \"absolute\" }, { \"label\" : \"Github\" , \"url\" : \"https://github.com\" , \"type\" : \"absolute\" }, { \"label\" : \"SMART Example App\" , \"url\" : \"https://smart.example.com/launch\" , \"type\" : \"smart\" , \"appContext\" : \"{\\\"session\\\":3456356,\\\"settings\\\":{\\\"module\\\":4235}}\" } ] }, { \"summary\" : \"Another card\" , \"indicator\" : \"warning\" , \"source\" : { \"label\" : \"Static CDS Service Example\" }, \"overrideReasons\" : [ { \"code\" : \"reason-code-provided-by-service\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Patient refused\" }, { \"code\" : \"12354\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Contraindicated\" } ] } ] } Example response using autolaunchable 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { \"cards\" : [ { \"uuid\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"summary\" : \"Lung cancer screening shared decision making\" , \"detail\" : \"Patient is a current smoker with a 20 pack/year history. Consider advising patient to complete lung cancer screening. The Lung Cancer Screening Shared Decision Making App (LCSSDM) has been proven to increase patient followthrough for screening.\" , \"source\" : { \"label\" : \"Lung Cancer Screening Shared Decision Making App\" , \"url\" : \"https://example.com/LCS\" , \"icon\" : \"https://example.com/img/icon-100px.png\" }, \"links\" : [ { \"label\" : \"Github\" , \"url\" : \"https://github.com\" , \"type\" : \"absolute\" , \"autolaunchable\" : true } ] } ] }","title":"Example"},{"location":"specification/current/#feedback","text":"Once a CDS Hooks Service responds to a hook by returning a card, the service has no further interaction with the CDS Client. The acceptance of a suggestion or rejection of a card is valuable information to enable a service to improve its behavior towards the goal of the end-user having a positive and meaningful experience with the CDS. A feedback endpoint enables suggestion tracking & analytics. A CDS Service MAY support a feedback endpoint; a CDS Client SHOULD be capable of sending feedback. Upon receiving a card, a user may accept its suggestions, ignore it entirely, or dismiss it with or without an override reason. Note that while one or more suggestions can be accepted, an entire card is either ignored or overridden. Typically, an end user may only accept (a suggestion), or override a card once; however, a card once ignored could later be acted upon. CDS Hooks does not specify the UI behavior of CDS Clients, including the persistence of cards. CDS Clients should faithfully report each of these distinct end-user interactions as feedback. A CDS Client provides feedback by POSTing a JSON document. The feedback endpoint can be constructed from the CDS Service endpoint and a path segment of \"feedback\" as {baseUrl}/cds-services/{service.id}/feedback. The request to the feedback endpoint SHALL be an object containing an array. Field Description feedback array of Feedback Each Feedback SHALL be described by the following attributes. Field Optionality Type Description card REQUIRED string The card.uuid from the CDS Hooks response. Uniquely identifies the card. outcome REQUIRED string A value of accepted or overridden . acceptedSuggestions CONDITIONAL array An array of json objects identifying one or more of the user's AcceptedSuggestion s. Required for accepted outcomes. overrideReason OPTIONAL OverrideReason A json object capturing the override reason as a Coding as well as any comments entered by the user. outcomeTimestamp REQUIRED string ISO8601 representation of the date and time in Coordinated Universal Time (UTC) when action was taken on the card, as profiled in section 5.6 of RFC3339 . e.g. 1985-04-12T23:20:50.52Z","title":"Feedback"},{"location":"specification/current/#suggestion-accepted","text":"The CDS Client can inform the service when one or more suggestions were accepted by POSTing a simple JSON object. The CDS Client authenticates to the CDS service as described in Trusting CDS Clients . Upon the user accepting a suggestion (perhaps when she clicks a displayed label (e.g., button) from a \"suggestion\" card), the CDS Client informs the service by posting the card and suggestion uuid s to the CDS Service's feedback endpoint with an outcome of accepted . To enable a positive clinical experience, the feedback endpoint may be called for multiple hook instances or multiple cards at the same time or even multiple times for a card or suggestion. Depending upon the UI and workflow of the CDS Client, a CDS Service may receive feedback for the same card instance multiple times. Each AcceptedSuggestion is described by the following attributes. Field Optionality Type Description id REQUIRED string The card.suggestion.uuid from the CDS Hooks response. Uniquely identifies the suggestion that was accepted.","title":"Suggestion accepted"},{"location":"specification/current/#example-suggestion-accepted","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" : [ { \"card\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"outcome\" : \"accepted\" , \"acceptedSuggestions\" : [ { \"id\" : \"e56e1945-20b3-4393-8503-a1a20fd73152\" } ], \"outcomeTimestamp\" : \"2021-12-11T10:05:31Z\" } ] } If either the card or the suggestion has no uuid , the CDS Client does not send a notification.","title":"Example suggestion accepted"},{"location":"specification/current/#card-ignored","text":"If the end-user doesn't interact with the CDS Service's card at all, the card is ignored . In this case, the CDS Client does not inform the CDS Service of the rejected guidance. Even with a card.uuid , a suggestion.uuid , and an available feedback service, the service is not informed (in part, because it may later be acted upon).","title":"Card ignored"},{"location":"specification/current/#overridden-guidance","text":"A CDS Client may enable the end user to override guidance without providing an explicit reason for doing so. The CDS Client can inform the service when a card was dismissed by specifying an outcome of overridden without providing an overrideReason . This may occur, for example, when the end user viewed the card and dismissed it without providing a reason why.","title":"Overridden guidance"},{"location":"specification/current/#example-overridden-guidance-without-overridereason","text":"1 2 3 4 5 6 7 8 9 10 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" : [ { \"card\" : \"f6b95768-b1c8-40dc-8385-bf3504b82ffb\" , // uuid from `card.uuid` \"outcome\" : \"overridden\" , \"outcomeTimestamp\" : \"2020-12-11T00:00:00Z\" } ] }","title":"Example overridden guidance without overrideReason"},{"location":"specification/current/#explicit-reject-with-override-reasons","text":"A CDS Client can inform the service when a card was rejected by POSTing an outcome of overridden along with an overrideReason to the service's feedback endpoint. The CDS Client may enable the clinician to provide an additional overrideReason or to supplement the overrideReason with a free text comment, supplied to the CDS Service in overrideReason.userComment .","title":"Explicit reject with override reasons"},{"location":"specification/current/#overridereason","text":"Each OverrideReason is described by the following attributes, in the feedback POST to the CDS Service. Field Optionality Type Description reason CONDITIONAL Coding The Coding object representing the override reason selected by the end user. Required if user selected an override reason from the list of reasons provided in the Card (instead of only leaving a userComment). userComment OPTIONAL string The CDS Client may enable the clinician to further explain why the card was rejected with free text. That user comment may be communicated to the CDS Service as a userComment .","title":"OverrideReason"},{"location":"specification/current/#example-overridden-guidance-with-overridereason","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" :[ { \"card\" : \"9368d37b-283f-44a0-93ea-547cebab93ed\" , \"outcome\" : \"overridden\" , \"overrideReason\" :{ \"reason\" :{ \"code\" : \"d7ecf885\" , \"system\" : \"https://example.com/cds-hooks/override-reason-system\" }, \"userComment\" : \"A comment entered by the clinician.\" }, \"outcomeTimestamp\" : \"2020-12-11T00:00:00Z\" } ] }","title":"Example overridden guidance with overrideReason"},{"location":"specification/current/#security-and-safety","text":"All data exchanged through the RESTful APIs MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in RFC2818 . Security and safety risks associated with the CDS Hooks API include: The risk that confidential information and privileged authorizations transmitted between a CDS Client and a CDS Service could be surreptitiously intercepted by an attacker; The risk that an attacker masquerading as a legitimate CDS Service could receive confidential information or privileged authorizations from a CDS Client, or could provide to a CDS Client decision support recommendations that could be harmful to a patient; The risk that an attacker masquerading as a legitimate service-subscribing CDS Client (i.e., man-in-the-middle) could intercept and possibly alter data exchanged between the two parties. The risk that a CDS Service could embed dangerous suggestions or links to dangerous apps in Cards returned to a CDS Client. The risk that a CDS Hooks browser-based deployment could be victimized by a Cross-Origin Resource Sharing (CORS) attack. The risk that a CDS Service could return a decision based on outdated patient data, resulting in a safety risk to the patient. CDS Hooks defines a security model that addresses these risks by assuring that the identities of both the CDS Service and the CDS Client are authenticated to each other; by protecting confidential information and privileged authorizations shared between a CDS Client and a CDS Service; by recommending means of assuring data freshness; and by incorporating business mechanisms through which trust is established and maintained between a CDS Client and a CDS Service. As with any access to protected patient information, systems should ensure that they have appropriate authorization and audit mechanisms in place to support transparency of use of the data. For more information, refer to Security Best Practices .","title":"Security and Safety"},{"location":"specification/current/#trusting-cds-services","text":"Prior to enabling CDS Clients to request decision support from any CDS Service, the CDS Client vendor and/or provider organization is expected to perform due diligence on the CDS Service provider. Each CDS Client vendor/provider is individually responsible for determining the suitability, safety and integrity of the CDS Services it uses, based on the organization's own risk-management strategy. Each CDS Client vendor/provider SHOULD maintain an \"allow list\" (and/or \"deny list\") of the CDS Services it has vetted, and the Card links that have been deemed safe to display from within the CDS Client context. Each provider organization is expected to work with its CDS Client vendor to choose what CDS Services to allow and to negotiate the conditions under which the CDS Services MAY be called. Once a CDS Service provider is selected, the CDS Client vendor/provider negotiates the terms under which service will be provided. This negotiation includes agreement on patient data elements that will be prefetched and provided to the CDS Service, the CDS Services used and the hooks that will trigger them, data elements that will be made available through an access token passed by the CDS Client, and steps the CDS Service MUST take to protect patient data and access tokens. The CDS Service can be registered with the CDS Client's authorization server, in part to define the FHIR resources that the CDS Service has authorization to access. These business arrangements are documented in the service agreement. Every interaction between a CDS Client and a CDS Service is initiated by the CDS Client sending a service request to a CDS Service endpoint protected using the Transport Layer Security protocol . Through the TLS protocol the identity of the CDS Service is authenticated, and an encrypted transmission channel is established between the CDS Client and the CDS Service. Both the Discovery endpoint and individual CDS Service endpoints are TLS secured. The CDS Client's FHIR server, using information provided by the authorization server, is responsible for enforcing restrictions on the information available to the CDS Service. Regardless of whether FHIR resources are prefetched or retrieved from the FHIR server, the CDS Client SHALL deny access to a requested resource if it is outside the user's authorized scope. If a CDS Client is satisfying prefetch requests from a CDS Service or sends a non-null fhirAuthorization object to a CDS Service so that it can call the FHIR server, the CDS Service MUST be pre-registered with the authorization server protecting access to the FHIR server. Pre-registration includes registering a client identifier, and agreeing upon the scope of FHIR access that is minimally necessary to provide the clinical decision support required. This specification does not address how the CDS Client, authorization server, and CDS Service perform this pre-registration.","title":"Trusting CDS Services"},{"location":"specification/current/#trusting-cds-clients","text":"The service agreement negotiated between the CDS Client vendor/provider and the CDS Service provider will include obligations the CDS Client vendor/provider commits to the CDS Service provider. Some agreements MAY include the use of mutual TLS, in which both ends of the channel are authenticated. However, mutual TLS is impractical for many organizations. In the absence of mutual TLS, only the CDS Service endpoint will be authenticated because the CDS Client initiates the TLS channel set-up. To enable the CDS Service to authenticate the identity of the CDS Client, CDS Hooks uses digitally signed JSON web tokens (JWT) ( rfc7519 ). CDS Services SHOULD require authentication if invoking the service poses any risk of exposing sensitive data to the caller. Each time a CDS Client transmits a request to a CDS Service which requires authentication, the request MUST include an Authorization header presenting the JWT as a \u201cBearer\u201d token: 1 Authorization: Bearer {{JWT}} Note that this is for every single CDS Service call, whether that be a Discovery call, a single CDS Service invocation, or multiple exchanges relating to a single service. Also note that mutual TLS MAY be used alongside JSON web tokens to establish trust of the CDS Client by the CDS Service. The CDS Client MUST use its private key to digitally sign the JWT, using the JSON Web Signatures (rfc7515) standard. The JWT header contains the following fields (see rfc7515 section 4.1 for further information on these standard headers): Field Optionality Type Value alg REQUIRED string The cryptographic algorithm used to sign this JWT. kid REQUIRED string The identifier of the key-pair used to sign this JWT. This identifier MUST be unique within the CDS Client's JWK Set. typ REQUIRED string Fixed value: JWT jku OPTIONAL url The URL to the JWK Set containing the public key(s). The JWT payload contains the following fields: Field Optionality Type Value iss REQUIRED string The URI of the issuer of this JWT. Note that the JWT MAY be self-issued by the CDS Client, or MAY be issued by a third-party identity provider. aud REQUIRED string or array of string The CDS Service endpoint that is being called by the CDS Client. (See more details below). exp REQUIRED number Expiration time integer for this authentication JWT, expressed in seconds since the \"Epoch\" (1970-01-01T00:00:00Z UTC). iat REQUIRED number The time at which this JWT was issued, expressed in seconds since the \"Epoch\" (1970-01-01T00:00:00Z UTC). jti REQUIRED string A nonce string value that uniquely identifies this authentication JWT (used to protect against replay attacks). tenant OPTIONAL string An opaque string identifying the healthcare organization that is invoking the CDS Hooks request. CDS Services SHOULD limit the CDS Clients they trust by maintaining an allowlist of iss and jku urls. Per rfc7519 , the aud value is either a string or an array of strings. For CDS Hooks, this value MUST be the URL of the CDS Service endpoint being invoked. For example, consider a CDS Service available at a base URL of https://cds.example.org . When the CDS Client invokes the CDS Service discovery endpoint, the aud value is either \"https://cds.example.org/cds-services\" or [\"https://cds.example.org/cds-services\"] . Similarly, when the CDS Client invokes a particular CDS Service (say, some-service ), the aud value is either \"https://cds.example.org/cds-services/some-service\" or [\"https://cds.example.org/cds-services/some-service\"] . The CDS Client MUST make its public key, expressed as a JSON Web Key (JWK), available in a JWK Set, as defined by rfc7517 . The kid value from the JWT header allows a CDS Service to identify the correct JWK in the JWK Set that can be used to verify the signature. The CDS Client MAY make its JWK Set available via a URL identified by the jku header field, as defined by rfc7515 4.1.2 . If the jku header field is ommitted, the CDS Client and CDS Service SHALL communicate the JWK Set out-of-band.","title":"Trusting CDS Clients"},{"location":"specification/current/#jwt-signing-algorithm","text":"The cryptographic signing algorithm of JWT is indicated in the alg header field. JSON Web Algorithms (rfc7518) defines several cryptographic algorithms for use in signing JWTs and should be referenced by CDS Hooks implementers. JWTs SHALL NOT be signed using the none algorithm, referred to in rfc7518 as unsecured JSON Web Signatures, as the lack of a cryptographic signature does not provide any integrity protection. Such JWTs could not be used by a CDS Service to identity the CDS Client preventing an establishment of trust. JWTs SHALL NOT be signed using any symmetric algorithm as these algorithms require the CDS Client and CDS Service to share a private key in order to verify the signature. For example, all HMAC based algorithms rely upon a shared private key and thus SHALL NOT be used to sign a JWT. When choosing an algorithm to sign their JWTs, CDS Clients SHOULD consider not only the algorithms (and key sizes) that are recommended within the security industry, but also how well those algorithms are supported in the various programming languages and libraries that may be used by CDS Services. At publication time of this specification, both ES384 and RS384 are RECOMMENDED for their regard within the larger security industry, strength, and support across popular programming languages and libraries. However, stronger and better algorithms are continually being introduced due to new threats, weaknesses, and increases in computing power. CDS Clients SHOULD continually re-evaluate their choice of an algorithm based upon these ever changing conditions. CDS Services SHOULD consider the algorithms they understand and trust based upon their tolerance for risk.","title":"JWT Signing Algorithm"},{"location":"specification/current/#example_2","text":"An example JSON web token header, payload, and JWK set: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 // JSON Web Token Header { \"alg\" : \"ES384\" , \"typ\" : \"JWT\" , \"kid\" : \"example-kid\" , \"jku\" : \"https://fhir-ehr.example.com/jwk_uri\" } // JSON Web Token Payload { \"iss\" : \"https://fhir-ehr.example.com/\" , \"aud\" : \"https://cds.example.org/cds-services/some-service\" , \"exp\" : 1422568860 , \"iat\" : 1311280970 , \"jti\" : \"ee22b021-e1b7-4611-ba5b-8eec6a33ac1e\" , \"tenant\" : \"2ddd6c3a-8e9a-44c6-a305-52111ad302a2\" } // JSON Web Key Set (public key) // This public key is used by the CDS Service to verify the signature of the JWT { \"keys\" : [ { \"kty\" : \"EC\" , \"use\" : \"sig\" , \"crv\" : \"P-384\" , \"kid\" : \"example-kid\" , \"x\" : \"46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk\" , \"y\" : \"XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI\" , \"alg\" : \"ES384\" } ] } // JSON Web Key (private key) // This private key is used by the CDS Client to sign the JWT { \"kty\" : \"EC\" , \"d\" : \"SeFXUXda8UomZ8GFUl7HH_Oi15rIbfMcsWj9ecIsDR8kLbqsEz2CGNgwy_IcILxy\" , \"use\" : \"sig\" , \"crv\" : \"P-384\" , \"kid\" : \"example-kid\" , \"x\" : \"46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk\" , \"y\" : \"XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI\" , \"alg\" : \"ES384\" } Using the above JWT values and JWKs, the complete JWT as passed in the Authorization HTTP header would be: 1 Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6ImV4YW1wbGUta2lkIiwiamt1IjoiaHR0cHM6Ly9maGlyLWVoci5leGFtcGxlLmNvbS9qd2tfdXJpIn0.eyJpc3MiOiJodHRwczovL2ZoaXItZWhyLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vY2RzLmV4YW1wbGUub3JnL2Nkcy1zZXJ2aWNlcy9zb21lLXNlcnZpY2UiLCJleHAiOjE0MjI1Njg4NjAsImlhdCI6MTMxMTI4MDk3MCwianRpIjoiZWUyMmIwMjEtZTFiNy00NjExLWJhNWItOGVlYzZhMzNhYzFlIiwidGVuYW50IjoiMmRkZDZjM2EtOGU5YS00NGM2LWEzMDUtNTIxMTFhZDMwMmEyIn0.d1WfLjGRKlcWB94l9do4cM8REXeYJLL6SGUBO8VHZhfM8mwKYP70EMxJ67War4TQblEpaQrp11wx5p7oPFm2ETYgCicS84vXWEIYTdjooZdooCSDf2L8-i4awdoUwiEb","title":"Example"},{"location":"specification/current/#cross-origin-resource-sharing","text":"Cross-origin resource sharing (CORS) is a World Wide Web Consortium (W3C) standard mechanism that uses additional HTTP headers to enable a web browser to gain permission to access resources from an Internet domain different from that which the browser is currently accessing. CORS is a client-side security mechanism with well-documented security risks. CDS Services and browser-based CDS Clients will require CORS support. A secure implementation guide for CORS is outside of the scope of this CDS Hooks specification. Organizations planning to implement CDS Hooks with CORS support are referred to the Cross-Origin Resource Sharing section of the OWASP HTML5 Security Cheat Sheet .","title":"Cross-Origin Resource Sharing"},{"location":"specification/current/#update-stale-guidance","text":"In the case that CDS Hooks cards are persisted, clients should take care to ensure that stale guidance does not negatively impact patient care. CDS Services can update their previously returned guidance by returning a new set of cards when the service is invoked based on a different hook . CDS Services indicate this intent by providing multiple CDS Services with the same id in discovery . Clients are recommended to remove cards returned by a previous invocation with the new cards . STU NOTE: We are seeking implementer feedback on how best to balance the needs of performance for implementations with the critical patient safety issues raised by the potential for stale guidance. Note that CDS Services will need to negotiate with CDS Clients to ensure that hooks that are required to ensure patient safety are supported by the CDS Client.","title":"Update stale guidance"},{"location":"specification/current/#extensions","text":"The specification is not prescriptive about support for extensions. However, to support extensions, the specification reserves the name extension and will never define an element with that name, allowing implementations to use it to provide custom behavior and information. The value of an extension element MUST be a pre-coordinated JSON object. Extension structures SHOULD use a strategy for naming that ensures global uniqueness, such as reverse-domain-name notation, as in the examples below. The intention here is that anything that has broad ranging value across the community enough to be a standardized extension has broad ranging value enough to be a first class citizen rather than an extension in CDS Hooks. STU Note: We seek implementer feedback on whether the recommendation to use namespace-based unique naming in the extension specification should be made mandatory or that we consider adding a mandatory field to extensions that indicates the source/type of the extension (as is done with FHIR). For example, an extension on a request could look like this: 1 2 3 4 5 6 7 8 9 10 11 12 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://fhir.example.org:9080\" , \"hook\" : \"patient-view\" , \"context\" : { \"userId\" : \"Practitioner/example\" }, \"extension\" : { \"com.example.timestamp\" : \"2017-11-27T22:13:25Z\" , \"com.cds-hooks.sandbox.myextension-practitionerspecialty\" : \"gastroenterology\" } } As another example, an extension defined on the discovery response could look like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { \"services\" : [ { \"title\" : \"Example CDS Service Discovery\" , \"hook\" : \"patient-view\" , \"id\" : \"patientview\" , \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" }, \"description\" : \"clinical decision support for patient view\" , \"extension\" : { \"com.example.clientConformance\" : \"http://hooks.example.org/fhir/102/Conformance/patientview\" } } ] }","title":"Extensions"},{"location":"specification/current/#data-types","text":"CDS Hooks leverages json data types throughout. This section defines data structures re-used across the specification.","title":"Data Types"},{"location":"specification/current/#coding","text":"The Coding data type captures the concept of a code. A code is understood only when the given code, code-system, and a optionally a human readable display are available. This coding type is a standalone data type in CDS Hooks modeled after a trimmed down version of the FHIR Coding data type . Field Optionality Type Description code REQUIRED string The code for what is being represented system REQUIRED string The codesystem for this code . display CONDITIONAL string A short, human-readable label to display. REQUIRED for Override Reasons provided by the CDS Service, OPTIONAL for Topic .","title":"Coding"},{"location":"specification/current/#hooks","text":"","title":"Hooks"},{"location":"specification/current/#overview_1","text":"As a specification, CDS Hooks does not prescribe a default or required set of hooks for implementers. Rather, the set of hooks defined here are merely a set of common use cases that were used to aid in the creation of CDS Hooks. The set of hooks defined here are not a closed set; anyone is able to define new hooks to fit their use cases and propose those hooks to the community. New hooks are proposed in a prescribed format using the documentation template by submitting a pull request for community feedback. Hooks are versioned , and mature according to the Hook Maturity Model . Note that each hook (e.g. order-select ) represents something the user is doing in the CDS Client and multiple CDS Services might respond to the same hook (e.g. a \"price check\" service and a \"prior authorization\" service might both respond to order-select ).","title":"Overview"},{"location":"specification/current/#hook-context-and-prefetch","text":"","title":"Hook context and prefetch"},{"location":"specification/current/#whats-the-difference","text":"Any user workflow or action within a CDS Client will naturally include contextual information such as the current user and patient. CDS Hooks refers to this information as context and allows each hook to define the information that is available in the context. Because CDS Hooks is intended to support usage within any CDS Client, this context can contain both required and optional data, depending on the capabilities of individual CDS Clients. However, the context information is intended to be relevant to most CDS Services subscribing to the hook. For example, consider a simple patient-view hook that is invoked whenever the user views a patient's information within the CDS Client. At this point in the workflow, the contextual information would include at least the current user and the patient that is being viewed. The hook declares this as context , and passes it to the CDS Service as part of the request in the context field: 1 2 3 4 \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" } Prefetch data, on the other hand, is defined by CDS Services as a way to allow the CDS Client to provide the data that a CDS Service needs as part of the initial request to the service. When the context data relates to a FHIR resource, it is important not to conflate context and prefetch. For instance, in the hook described above for opening a patient's chart, the hook context includes the id of the patient whose chart is being opened, not the full patient FHIR resource. In this case, the FHIR id of the patient is appropriate as the CDS Services may not be interested in details from the patient resource but instead other data related to this patient. Therefore, including the full patient resource in context would be unnecessary. Alternatively, a CDS Service may need the full patient resource in certain scenarios, in which case they can fetch it as needed from the FHIR server or request it to be prefetched using a prefetch template in their discovery response, such as: 1 2 3 \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } See the section on prefetch tokens for more information on how contextual information can be used to parameterize prefetch templates. Consider another hook for when a new patient is being registered. In this case, it would likely be appropriate for the context to contain the full FHIR resource for the patient being registered as the patient may not be yet recorded in the CDS Client (and thus not available from the FHIR server) and CDS Services using this hook would predominantly be interested in the details of the patient being registered. Additionally, consider a PGX CDS Service and a Zika screening CDS Service, each of which is subscribed to the same hook. The context data specified by their shared hook should contain data relevant to both CDS Services; however, each service will have other specific data needs that will necessitate disparate prefetch requests. For instance, the PGX CDS Service likely is interested in genomics data whereas the Zika screening CDS Service will want Observations. In summary, context is specified in the hook definition to guide developers on the information available at the point in the workflow when the hook is triggered. Prefetch data is defined by each CDS Service because it is specific to the information that service needs in order to process.","title":"What's the difference?"},{"location":"specification/current/#hook-definition-format","text":"Hooks are defined in the following format.","title":"Hook Definition Format"},{"location":"specification/current/#hook-name-expressed-as-noun-verb","text":"The name of the hook SHOULD succinctly and clearly describe the activity or event. Hook names are unique so hook creators SHOULD take care to ensure newly proposed hooks do not conflict with an existing hook name. Hook creators SHALL name their hook with reverse domain notation (e.g. org.example.patient-transmogrify ) if the hook is specific to an organization. Reverse domain notation SHALL not be used by a standard hooks catalog. When naming hooks, the name should start with the subject (noun) of the hook and be followed by the activity (verb). For example, patient-view (not view-patient ) or order-sign (not sign-order ).","title":"hook-name-expressed-as-noun-verb"},{"location":"specification/current/#workflow","text":"Describe when this hook occurs in a workflow. Hook creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion among implementers.","title":"Workflow"},{"location":"specification/current/#context","text":"Describe the set of contextual data used by this hook. Only data logically and necessarily associated with the purpose of this hook should be represented in context. All fields defined by the hook's context MUST be defined in a table where each field is described by the following attributes: Field: The name of the field in the context JSON object. Hook authors SHOULD name their context fields to be consistent with other existing hooks when referring to the same context field. Optionality: A string value of either REQUIRED or OPTIONAL Prefetch Token: A string value of either Yes or No , indicating whether this field can be tokenized in a prefetch template. 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. The table below illustrates a sample hook context table: Field Optionality Prefetch Token Type Description someField REQUIRED Yes string A clear description of the value of this field. anotherField OPTIONAL No number A clear description of the value of this field. someObject REQUIRED No object A clear description of the value of this field. 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.","title":"Context"},{"location":"specification/current/#fhir-resources-in-context","text":"For context fields that may contain multiple FHIR resources, the field SHOULD be defined as a FHIR Bundle, rather than as an array of FHIR resources. For example, multiple FHIR resources are necessary to describe all of the orders under review in the order-sign hook's draftOrders 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, imagine a hook, order-select that is invoked when a user selects a medication during an order workflow. The context data for this hook would contain draft FHIR resources representing the medications that have been selected for ordering. In this case, the CDS Client 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.","title":"FHIR resources in context"},{"location":"specification/current/#examples","text":"Hook creators SHOULD include examples of the context. 1 2 3 4 5 6 7 8 9 \"context\" :{ \"someField\" : \"foo\" , \"anotherField\" : 123 , \"someObject\" : { \"color\" : \"red\" , \"version\" : 1 }, \"moreObjects\" :[] } If the context contains FHIR data, hook creators SHOULD include examples across multiple versions of FHIR if differences across FHIR versions are possible.","title":"Examples"},{"location":"specification/current/#hook-maturity-model","text":"The intent of the CDS Hooks Maturity Model is to attain broad community engagement and consensus, before a hook is labeled as mature, that the hook is necessary, implementable, and worthwhile to the CDS Services and CDS Clients that would reasonably be expected to use it. Implementer feedback should drive the maturity of new hooks. Diverse participation in open developer forums and events, such as HL7 FHIR Connectathons, is necessary to achieve significant implementer feedback. The below criteria will be evaluated with these goals in mind. 1 Hook maturity | 3 - Considered The Hook maturity levels use the term CDS Client to generically refer to the clinical workflow system in which a CDS Services returned cards are displayed. Maturity Level Maturity title Requirements 0 Draft Hook is defined according to the hook definition format . 1 Submitted The above, and \u2026 Hook definition is written up as a github pull request using the Hook template and community feedback is solicited on the zulip CDS Hooks stream . 2 Tested The above, and \u2026 The hook has been tested and successfully supports interoperability among at least one CDS Client and two independent CDS Services using semi-realistic data and scenarios (e.g. at a FHIR Connectathon). The github pull request defining the hook is approved and published by the CDS Hooks Project Management Committee. 3 Considered The above, and \u2026 At least 3 distinct organizations recorded ten distinct implementer comments (including a github issue, tracker item, or comment on the hook definition page), including at least two CDS Clients and three independent CDS Services. The hook has been tested at two Connectathons. 4 Documented The above, and \u2026 The author agrees that the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes. The hook is implemented in the standard CDS Hooks sandbox and multiple prototype projects. The Hook specification SHALL: Identify a broad set of example contexts in which the hook may be used with a minimum of three, but as many as 8-10. Clearly differentiate the hook from similar hooks or other standards to help an implementer determine if the hook is correct for their scenario. Explicitly document example scenarios when the hook should not be used. 5 Mature The above, and ... The hook has been implemented in production in at least two CDS Clients and three independent CDS Services. An HL7 working group ballots the hook and the hook has passed HL7 STU ballot. 6 Normative The above, and ... the responsible HL7 working group and the CDS working group agree the material is ready to lock down and the hook has passed HL7 normative ballot","title":"Hook Maturity Model"},{"location":"specification/current/#changes-to-a-hook","text":"Each hook MUST include a Metadata table at the beginning of the hook with the specification version and hook version as described in the following sections.","title":"Changes to a Hook"},{"location":"specification/current/#specification-version","text":"Because hooks are such an integral part of the CDS Hooks specification, hook definitions are associated with specific versions of the specification. The hook definition MUST include the version (or versions) of the CDS Hooks specification that it is defined to work with. 1 specificationVersion | 1.0 Because the specification itself follows semantic versioning, the version specified here is a minimum specification version. In other words, a hook defined to work against 1.0 should continue to work against the 1.1 version of CDS Hooks. However, a hook that specifies 1.1 would not be expected to work in a CDS Hooks 1.0 environment.","title":"Specification Version"},{"location":"specification/current/#hook-version","text":"To enable tracking of changes to hook definitions, each hook MUST include a version indicator, expressed as a string. 1 hookVersion | 1.0 To help ensure the stability of CDS Hooks implementations, once a hook has been defined (i.e. published with a particular name so that it is available for implementation), breaking changes MUST NOT be made. This means that fields can be added and restrictions relaxed, but fields cannot be changed, and restrictions cannot be tightened. In particular, the semantics of a hook (i.e. the meaning of the hook from the perspective of the CDS Client) cannot be changed. CDS Clients 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 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 Major 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 Change of semantics of an existing context field Major Change of semantics of the hook Major When a major change is made, the hook definition MUST be published under a new name. When a minor or patch change is made, the hook version MUST be updated. Hook definers MUST use semantic versioning to communicate the impact of changes in an industry standard way. Note that the intent of this table is to outline possible breaking changes. The authors have attempted to enumerate these types of changes exhaustively, but as new types of breaking changes are identified, this list will be updated.","title":"Hook Version"},{"location":"specification/current/#hook-maturity","text":"As each hook progresses through a process of being defined, tested, implemented, used in production environments, and balloted, the hook's formal maturity level increases. Each hook has its own maturity level, which MUST be defined in the hook's definition and correspond to the Hook Maturity Model . 1 hookMaturity | 0 - Draft","title":"Hook Maturity"},{"location":"specification/current/#change-log","text":"Changes made to a hook's definition MUST be documented in a change log to ensure hook consumers can track what has been changed over the life of a hook. The change log MUST contain the following elements: Version: The version of the change Description: A description of the change and its impact For example: Version Description 1.1 Added new context variable 1.0.1 Clarified context variable usage 1.0 Initial Release","title":"Change Log"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"prebuild_index":false,"separator":"[\\s\\-]+"},"docs":[{"location":"","text":"Continuous Improvement Build This is the continuous integration, community release of the CDS Hooks specification. All stable releases are available at https://cds-hooks.hl7.org . Overview \u00b6 This specification describes a \"hook\" -based pattern for invoking decision support from within a clinician's workflow. The API supports: Synchronous, workflow-triggered CDS calls returning information and suggestions Launching a user-facing SMART app when CDS requires additional interaction How it works \u00b6 User activity inside the clinician's workflow triggers CDS hooks in real-time. For example: patient-view when opening a new patient record order-select when selecting one or more orders to place for a patient order-sign immediately before an order is signed When a triggering activity occurs, the CDS Client notifies each CDS service registered for the activity. These services must then provide near-real-time feedback about the triggering event. Each service gets basic details about the clinical workflow context (via the context parameter of the hook) plus whatever service-specific data are required (via the pre-fetch-template parameter). CDS Cards \u00b6 Each CDS service can return any number of cards in response to the hook. Cards convey some combination of text ( information card ), alternative suggestions ( suggestion card ), and links to apps or reference materials ( app link card ). A user sees these cards \u2014 one or more of each type \u2014 embedded in the workflow, and can interact with them as follows: information card : provides text for the user to read. suggestion card : provides a specific suggestion for which the CDS Client renders a button that the user can click to accept. Clicking automatically populates the suggested change into the clinician's UI. app link card : provides a link to an app (often a SMART app) where the user can supply details, step through a flowchart, or do anything else required to help reach an informed decision. Try it! \u00b6 You can try CDS Hooks in our Sandbox at http://sandbox.cds-hooks.org An OpenAPI Specification (formally known as the Swagger Specification) interface of CDS Hooks is available. Using the CDS Hooks OpenAPI specification, you can generate client or server code to help you get started with your implementation. You can download the API specification and view it online via the Swagger Editor . CDS Hooks implementers are not required to use the OpenAPI Specification interface of CDS Hooks.","title":"Overview"},{"location":"#overview","text":"This specification describes a \"hook\" -based pattern for invoking decision support from within a clinician's workflow. The API supports: Synchronous, workflow-triggered CDS calls returning information and suggestions Launching a user-facing SMART app when CDS requires additional interaction","title":"Overview"},{"location":"#how-it-works","text":"User activity inside the clinician's workflow triggers CDS hooks in real-time. For example: patient-view when opening a new patient record order-select when selecting one or more orders to place for a patient order-sign immediately before an order is signed When a triggering activity occurs, the CDS Client notifies each CDS service registered for the activity. These services must then provide near-real-time feedback about the triggering event. Each service gets basic details about the clinical workflow context (via the context parameter of the hook) plus whatever service-specific data are required (via the pre-fetch-template parameter).","title":"How it works"},{"location":"#cds-cards","text":"Each CDS service can return any number of cards in response to the hook. Cards convey some combination of text ( information card ), alternative suggestions ( suggestion card ), and links to apps or reference materials ( app link card ). A user sees these cards \u2014 one or more of each type \u2014 embedded in the workflow, and can interact with them as follows: information card : provides text for the user to read. suggestion card : provides a specific suggestion for which the CDS Client renders a button that the user can click to accept. Clicking automatically populates the suggested change into the clinician's UI. app link card : provides a link to an app (often a SMART app) where the user can supply details, step through a flowchart, or do anything else required to help reach an informed decision.","title":"CDS Cards"},{"location":"#try-it","text":"You can try CDS Hooks in our Sandbox at http://sandbox.cds-hooks.org An OpenAPI Specification (formally known as the Swagger Specification) interface of CDS Hooks is available. Using the CDS Hooks OpenAPI specification, you can generate client or server code to help you get started with your implementation. You can download the API specification and view it online via the Swagger Editor . CDS Hooks implementers are not required to use the OpenAPI Specification interface of CDS Hooks.","title":"Try it!"},{"location":"best-practices/","text":"Implementation Best Practices \u00b6 This page serves as best practice guidance for CDS Hooks implementers. The best practices outlined here are not mandatory implementation rules; rather, they are suggested guidance. This is a living, in progress document and the best practices outlined here should not be considered absolute or complete. Security \u00b6 The CDS Hooks security model requires thought and consideration from implementers. Security topics are never binary, are often complex, and robust implementations should factor in concepts such as risk and usability. Implementers should approach their security related development with thoughtful care. The CDS Hooks specifications already provides some guidance in this space. The information here is supplemental to the existing specification documentation. The CDS Hooks security model leverages several existing RFCs. These should be read and fully understood by all implementers. rfc7519: JSON Web Tokens (JWT) rfc7517: JSON Web Key (JWK) rfc7515: JSON Web Signature (JWS) rfc7518: JSON Web Algorithms (JWA) CDS Clients \u00b6 Implementers of CDS Clients should: Maintain a allowlist of CDS Service endpoints that may be invoked. Only endpoints on the allowlist can be invoked. This ensures that CDS Clients invoke only trusted CDS Services. This is especially important since CDS Clients may send an authorization token that allows the CDS Service temporary access to the FHIR server. Issue secure FHIR access tokens. If a CDS Clients generates access tokens to its FHIR server, the tokens should: Be unique for each CDS Service endpoint. Be very short-lived. Provide the minimum necessary access for the CDS Service. This includes both SMART scopes as well as the patient(s)/data that can be accessed. Audit CDS Service's access to data * Regardless of the use of prefetch or more typical FHIR RESTful APIs, CDS Clients should audit and report on data access. CDS Services \u00b6 JWT \u00b6 Upon being invoked by a CDS Client, the CDS Service should first process the given JWT to determine whether to process the given request. In processing the JWT, CDS Services should: Ensure that the iss value exists in the CDS Service's allowlist of trusted CDS Clients. Ensure that the aud value matches the CDS Service endpoint currently processing the request. Ensure that the exp value is not before the current date/time. Ensure that the tenant value exists in the CDS Service's allowlist of trusted tenants (may not be applicable to all CDS Services). Ensure that the JWT signature matches the public key on record with the CDS Service. See additional notes below. Ensure that the jti value doesn't exist in the short-term storage of JWTs previously processed by this CDS Service. Once the JWT has been deemed to be valid, the jti value should be stored in the short-term storage of processed JWTs. Values in this storage only need to be kept for the maximum duration of all JWTs processed by this CDS Service. If the CDS Clients are adhering to best practices, this should be no more than an hour. Verifying the JWT signature is a critical step in establishing trust of the caller of the CDS Service. As part of the allowlist of trusted CDS Clients, information on the public key(s) used by the CDS Client should also be stored. In some cases, this public key may be shared out-of-band. In other cases, the public key may be available at a remote endpoint and cycled on a regular basis. It is this latter case in which CDS Services should maintain their own rotating cache of public keys for the CDS Client. CDS Services should never store, share, or log JWTs to minimize the risk of theft and replay attacks. Information within the JWT (for instance, iss , tenant , jti ) can be logged safely and is especially useful for analytics. If a CDS Service deems a JWT to be invalid for any reason, it should not leak the details of why the JWT failed validation back to the caller. If the caller were a malicious threat actor, leaking detailed information as to what was invalid may give the threat actor guidance on how to shape future attacks. Instead, responding to the request with a HTTP 401 Unauthorized response status code without any additional information is recommended. FHIR Access \u00b6 CDS Services should never store, share, or log the FHIR access token ( fhirAuthorization.access_token ) given to it by the CDS Client. The access token should be treated as an extremely sensitive, transient piece of data.","title":"Best Practices"},{"location":"best-practices/#implementation-best-practices","text":"This page serves as best practice guidance for CDS Hooks implementers. The best practices outlined here are not mandatory implementation rules; rather, they are suggested guidance. This is a living, in progress document and the best practices outlined here should not be considered absolute or complete.","title":"Implementation Best Practices"},{"location":"best-practices/#security","text":"The CDS Hooks security model requires thought and consideration from implementers. Security topics are never binary, are often complex, and robust implementations should factor in concepts such as risk and usability. Implementers should approach their security related development with thoughtful care. The CDS Hooks specifications already provides some guidance in this space. The information here is supplemental to the existing specification documentation. The CDS Hooks security model leverages several existing RFCs. These should be read and fully understood by all implementers. rfc7519: JSON Web Tokens (JWT) rfc7517: JSON Web Key (JWK) rfc7515: JSON Web Signature (JWS) rfc7518: JSON Web Algorithms (JWA)","title":"Security"},{"location":"best-practices/#cds-clients","text":"Implementers of CDS Clients should: Maintain a allowlist of CDS Service endpoints that may be invoked. Only endpoints on the allowlist can be invoked. This ensures that CDS Clients invoke only trusted CDS Services. This is especially important since CDS Clients may send an authorization token that allows the CDS Service temporary access to the FHIR server. Issue secure FHIR access tokens. If a CDS Clients generates access tokens to its FHIR server, the tokens should: Be unique for each CDS Service endpoint. Be very short-lived. Provide the minimum necessary access for the CDS Service. This includes both SMART scopes as well as the patient(s)/data that can be accessed. Audit CDS Service's access to data * Regardless of the use of prefetch or more typical FHIR RESTful APIs, CDS Clients should audit and report on data access.","title":"CDS Clients"},{"location":"best-practices/#cds-services","text":"","title":"CDS Services"},{"location":"best-practices/#jwt","text":"Upon being invoked by a CDS Client, the CDS Service should first process the given JWT to determine whether to process the given request. In processing the JWT, CDS Services should: Ensure that the iss value exists in the CDS Service's allowlist of trusted CDS Clients. Ensure that the aud value matches the CDS Service endpoint currently processing the request. Ensure that the exp value is not before the current date/time. Ensure that the tenant value exists in the CDS Service's allowlist of trusted tenants (may not be applicable to all CDS Services). Ensure that the JWT signature matches the public key on record with the CDS Service. See additional notes below. Ensure that the jti value doesn't exist in the short-term storage of JWTs previously processed by this CDS Service. Once the JWT has been deemed to be valid, the jti value should be stored in the short-term storage of processed JWTs. Values in this storage only need to be kept for the maximum duration of all JWTs processed by this CDS Service. If the CDS Clients are adhering to best practices, this should be no more than an hour. Verifying the JWT signature is a critical step in establishing trust of the caller of the CDS Service. As part of the allowlist of trusted CDS Clients, information on the public key(s) used by the CDS Client should also be stored. In some cases, this public key may be shared out-of-band. In other cases, the public key may be available at a remote endpoint and cycled on a regular basis. It is this latter case in which CDS Services should maintain their own rotating cache of public keys for the CDS Client. CDS Services should never store, share, or log JWTs to minimize the risk of theft and replay attacks. Information within the JWT (for instance, iss , tenant , jti ) can be logged safely and is especially useful for analytics. If a CDS Service deems a JWT to be invalid for any reason, it should not leak the details of why the JWT failed validation back to the caller. If the caller were a malicious threat actor, leaking detailed information as to what was invalid may give the threat actor guidance on how to shape future attacks. Instead, responding to the request with a HTTP 401 Unauthorized response status code without any additional information is recommended.","title":"JWT"},{"location":"best-practices/#fhir-access","text":"CDS Services should never store, share, or log the FHIR access token ( fhirAuthorization.access_token ) given to it by the CDS Client. The access token should be treated as an extremely sensitive, transient piece of data.","title":"FHIR Access"},{"location":"changelog/","text":"Change Log \u00b6 CDS Hooks 1.1 \u00b6 Non-compatible (breaking) changes \u00b6 The CDS Hooks project team strives to not brek backward compatibility between versions of the CDS Hooks specifications to aid both in interoperability and to prioritize existing implementations. In cases where this isn't possible, changes made in the CDS Hooks 1.1 specification that break backward compatibility are documented below. CDS Clients may now paginate search results in prefetch. Previously, CDS Clients were not permitted to return partial search results using the typical FHIR pagination mechanism . When using prefetch, CDS Services should expect to receive continuation links which enable access to the remainder of the search results over REST.","title":"Change Log"},{"location":"changelog/#change-log","text":"","title":"Change Log"},{"location":"changelog/#cds-hooks-11","text":"","title":"CDS Hooks 1.1"},{"location":"changelog/#non-compatible-breaking-changes","text":"The CDS Hooks project team strives to not brek backward compatibility between versions of the CDS Hooks specifications to aid both in interoperability and to prioritize existing implementations. In cases where this isn't possible, changes made in the CDS Hooks 1.1 specification that break backward compatibility are documented below. CDS Clients may now paginate search results in prefetch. Previously, CDS Clients were not permitted to return partial search results using the typical FHIR pagination mechanism . When using prefetch, CDS Services should expect to receive continuation links which enable access to the remainder of the search results over REST.","title":"Non-compatible (breaking) changes"},{"location":"community/","text":"Community \u00b6 Get Involved \u00b6 There are several ways in which you can get involved with the CDS Hooks community. Ask a question and participate in discussions via the CDS Hooks Google Group Chat via Zulip at https://chat.fhir.org in the cds-hooks stream Contribute to the code and documentation on Github Check out the CDS services available for testing and contribute your own. CDS Hooks Sprint Program \u00b6 Objectives \u00b6 Promote creation of clinical-grade service integrations (CDS Clients + CDS Services) Gain implementation experience with real-world systems Refine the spec, balancing ease of use, flexibility, and stability Drive toward pilot deployments with the ability to measure results Want to help build our test infrastructure? \u00b6 help-wanted issues Proposed Milestones","title":"Community"},{"location":"community/#community","text":"","title":"Community"},{"location":"community/#get-involved","text":"There are several ways in which you can get involved with the CDS Hooks community. Ask a question and participate in discussions via the CDS Hooks Google Group Chat via Zulip at https://chat.fhir.org in the cds-hooks stream Contribute to the code and documentation on Github Check out the CDS services available for testing and contribute your own.","title":"Get Involved"},{"location":"community/#cds-hooks-sprint-program","text":"","title":"CDS Hooks Sprint Program"},{"location":"community/#objectives","text":"Promote creation of clinical-grade service integrations (CDS Clients + CDS Services) Gain implementation experience with real-world systems Refine the spec, balancing ease of use, flexibility, and stability Drive toward pilot deployments with the ability to measure results","title":"Objectives"},{"location":"community/#want-to-help-build-our-test-infrastructure","text":"help-wanted issues Proposed Milestones","title":"Want to help build our test infrastructure?"},{"location":"examples/","text":"Examples \u00b6 CDC Guideline for Prescribing Opioids for Chronic Pain \u00b6 CDS Service Request The example illustrates a prescription for Acetaminophen/Hydrocodone Bitartrate for a patient that already has a prescription for Oxycodone Hydrochloride: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://fhir.example.com\" , \"hook\" : \"order-sign\" , \"context\" : { \"userId\" : \"Practitioner/example\" , \"medications\" : [ { \"resourceType\" : \"MedicationOrder\" , \"id\" : \"medrx001\" , \"dateWritten\" : \"2017-05-05\" , \"status\" : \"draft\" , \"patient\" : { \"reference\" : \"Patient/example\" }, \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"857001\" , \"display\" : \"Acetaminophen 325 MG / Hydrocodone Bitartrate 10 MG Oral Tablet\" } ] }, \"dosageInstruction\" : [ { \"text\" : \"Take 1 tablet Oral every 4 hours as needed\" , \"timing\" : { \"repeat\" : { \"frequency\" : 6 , \"frequencyMax\" : 6 , \"period\" : 1 , \"unit\" : \"d\" } }, \"asNeededBoolean\" : true , \"doseQuantity\" : { \"value\" : 10 , \"unit\" : \"mg\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mg\" } } ] } ], \"patientId\" : \"1288992\" }, \"prefetch\" : { \"medication\" : { \"response\" : { \"status\" : \"200 OK\" }, \"resource\" : { \"resourceType\" : \"MedicationOrder\" , \"id\" : \"medrx002\" , \"dateWritten\" : \"2017-04-25\" , \"status\" : \"active\" , \"patient\" : { \"reference\" : \"Patient/example\" }, \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"1049621\" , \"display\" : \"Oxycodone Hydrochloride 5 MG Oral Tablet\" } ] }, \"dosageInstruction\" : [ { \"text\" : \"Take 1 tablet by mouth every 4 hours as needed for pain.\" , \"timing\" : { \"repeat\" : { \"frequency\" : 6 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"asNeededBoolean\" : true , \"doseQuantity\" : { \"value\" : 5 , \"unit\" : \"mg\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mg\" } } ] } } } } This example illustrates the use of the CDS Hooks medication-prescribe hook to implement Recommendation #5 from the CDC guideline for prescribing opioids for chronic pain . This example is taken from the Opioid Prescribing Support Implementation Guide , developed in partnership with the Centers for Disease Control and Prevention (CDC) . CDS Service Response The opioid guideline request results in the following response that indicates the patient is at high risk for opioid overdose according to the CDC guidelines, and the dosage should be tapered to less than 50 MME. Links are provided to the guideline, as well as to the MME conversion tables provided by CDC. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { \"summary\" : \"High risk for opioid overdose - taper now\" , \"indicator\" : \"warning\" , \"links\" : [ { \"label\" : \"CDC guideline for prescribing opioids for chronic pain\" , \"type\" : \"absolute\" , \"url\" : \"https://guidelines.gov/summaries/summary/50153/cdc-guideline-for-prescribing-opioids-for-chronic-pain---united-states-2016#420\" }, { \"label\" : \"MME Conversion Tables\" , \"type\" : \"absolute\" , \"url\" : \"https://www.cdc.gov/drugoverdose/pdf/calculating_total_daily_dose-a.pdf\" } ], \"detail\" : \"Total morphine milligram equivalent (MME) is 125mg. Taper to less than 50.\" } Radiology Appropriateness \u00b6 CDS Service Request This example illustrates the use of the CDS Hooks order-select hook to implement Radiology Appropriateness scoring. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 { \"hook\" : \"order-select\" , \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://hooks.smarthealthit.org:9080\" , \"context\" : { \"userId\" : \"Practitioner/123\" , \"patientId\" : \"MRI-59879846\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"ServiceRequest/example-MRI-59879846\" ], \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"status\" : \"draft\" , \"intent\" : \"plan\" , \"code\" : { \"coding\" : [ { \"system\" : \"http://loinc.org\" , \"code\" : \"36801-9\" } ], \"text\" : \"MRA Knee Vessels Right\" }, \"subject\" : { \"reference\" : \"Patient/MRI-59879846\" }, \"reasonCode\" : [ { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/sid/icd-10\" , \"code\" : \"S83.511\" , \"display\" : \"Sprain of anterior cruciate ligament of right knee\" } ] } ] } } ] } } } CDS Service Response The appropriateness score is communicated via a systemAction of the ServiceRequest that adds an extension element to indicate the appropriateness rating. See the CDS Hooks for PAMA Argonaut specification for more. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 { \"cards\" :[ ], \"systemActions\" :[ { \"type\" : \"update\" , \"resource\" :{ \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"extension\" :[ { \"url\" : \"http://fhir.org/argonaut/Extension/pama-rating\" , \"valueCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://fhir.org/argonaut/CodeSystem/pama-rating\" , \"code\" : \"appropriate\" } ] } }, { \"url\" : \"http://fhir.org/argonaut/Extension/pama-rating-consult-id\" , \"valueUri\" : \"urn:uuid:55f3b7fc-9955-420e-a460-ff284b2956e6\" } ], \"status\" : \"draft\" , \"intent\" : \"plan\" , \"code\" :{ \"coding\" :[ { \"system\" : \"http://loinc.org\" , \"code\" : \"36801-9\" } ], \"text\" : \"MRA Knee Vessels Right\" }, \"subject\" :{ \"reference\" : \"Patient/MRI-59879846\" }, \"reasonCode\" :[ { \"coding\" :[ { \"system\" : \"http://hl7.org/fhir/sid/icd-10\" , \"code\" : \"S83.511\" , \"display\" : \"Sprain of anterior cruciate ligament of right knee\" } ] } ] } } ] }","title":"Examples"},{"location":"examples/#examples","text":"","title":"Examples"},{"location":"examples/#cdc-guideline-for-prescribing-opioids-for-chronic-pain","text":"CDS Service Request The example illustrates a prescription for Acetaminophen/Hydrocodone Bitartrate for a patient that already has a prescription for Oxycodone Hydrochloride: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://fhir.example.com\" , \"hook\" : \"order-sign\" , \"context\" : { \"userId\" : \"Practitioner/example\" , \"medications\" : [ { \"resourceType\" : \"MedicationOrder\" , \"id\" : \"medrx001\" , \"dateWritten\" : \"2017-05-05\" , \"status\" : \"draft\" , \"patient\" : { \"reference\" : \"Patient/example\" }, \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"857001\" , \"display\" : \"Acetaminophen 325 MG / Hydrocodone Bitartrate 10 MG Oral Tablet\" } ] }, \"dosageInstruction\" : [ { \"text\" : \"Take 1 tablet Oral every 4 hours as needed\" , \"timing\" : { \"repeat\" : { \"frequency\" : 6 , \"frequencyMax\" : 6 , \"period\" : 1 , \"unit\" : \"d\" } }, \"asNeededBoolean\" : true , \"doseQuantity\" : { \"value\" : 10 , \"unit\" : \"mg\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mg\" } } ] } ], \"patientId\" : \"1288992\" }, \"prefetch\" : { \"medication\" : { \"response\" : { \"status\" : \"200 OK\" }, \"resource\" : { \"resourceType\" : \"MedicationOrder\" , \"id\" : \"medrx002\" , \"dateWritten\" : \"2017-04-25\" , \"status\" : \"active\" , \"patient\" : { \"reference\" : \"Patient/example\" }, \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"1049621\" , \"display\" : \"Oxycodone Hydrochloride 5 MG Oral Tablet\" } ] }, \"dosageInstruction\" : [ { \"text\" : \"Take 1 tablet by mouth every 4 hours as needed for pain.\" , \"timing\" : { \"repeat\" : { \"frequency\" : 6 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"asNeededBoolean\" : true , \"doseQuantity\" : { \"value\" : 5 , \"unit\" : \"mg\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mg\" } } ] } } } } This example illustrates the use of the CDS Hooks medication-prescribe hook to implement Recommendation #5 from the CDC guideline for prescribing opioids for chronic pain . This example is taken from the Opioid Prescribing Support Implementation Guide , developed in partnership with the Centers for Disease Control and Prevention (CDC) . CDS Service Response The opioid guideline request results in the following response that indicates the patient is at high risk for opioid overdose according to the CDC guidelines, and the dosage should be tapered to less than 50 MME. Links are provided to the guideline, as well as to the MME conversion tables provided by CDC. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 { \"summary\" : \"High risk for opioid overdose - taper now\" , \"indicator\" : \"warning\" , \"links\" : [ { \"label\" : \"CDC guideline for prescribing opioids for chronic pain\" , \"type\" : \"absolute\" , \"url\" : \"https://guidelines.gov/summaries/summary/50153/cdc-guideline-for-prescribing-opioids-for-chronic-pain---united-states-2016#420\" }, { \"label\" : \"MME Conversion Tables\" , \"type\" : \"absolute\" , \"url\" : \"https://www.cdc.gov/drugoverdose/pdf/calculating_total_daily_dose-a.pdf\" } ], \"detail\" : \"Total morphine milligram equivalent (MME) is 125mg. Taper to less than 50.\" }","title":"CDC Guideline for Prescribing Opioids for Chronic Pain"},{"location":"examples/#radiology-appropriateness","text":"CDS Service Request This example illustrates the use of the CDS Hooks order-select hook to implement Radiology Appropriateness scoring. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 { \"hook\" : \"order-select\" , \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://hooks.smarthealthit.org:9080\" , \"context\" : { \"userId\" : \"Practitioner/123\" , \"patientId\" : \"MRI-59879846\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"ServiceRequest/example-MRI-59879846\" ], \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"status\" : \"draft\" , \"intent\" : \"plan\" , \"code\" : { \"coding\" : [ { \"system\" : \"http://loinc.org\" , \"code\" : \"36801-9\" } ], \"text\" : \"MRA Knee Vessels Right\" }, \"subject\" : { \"reference\" : \"Patient/MRI-59879846\" }, \"reasonCode\" : [ { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/sid/icd-10\" , \"code\" : \"S83.511\" , \"display\" : \"Sprain of anterior cruciate ligament of right knee\" } ] } ] } } ] } } } CDS Service Response The appropriateness score is communicated via a systemAction of the ServiceRequest that adds an extension element to indicate the appropriateness rating. See the CDS Hooks for PAMA Argonaut specification for more. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 { \"cards\" :[ ], \"systemActions\" :[ { \"type\" : \"update\" , \"resource\" :{ \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"extension\" :[ { \"url\" : \"http://fhir.org/argonaut/Extension/pama-rating\" , \"valueCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://fhir.org/argonaut/CodeSystem/pama-rating\" , \"code\" : \"appropriate\" } ] } }, { \"url\" : \"http://fhir.org/argonaut/Extension/pama-rating-consult-id\" , \"valueUri\" : \"urn:uuid:55f3b7fc-9955-420e-a460-ff284b2956e6\" } ], \"status\" : \"draft\" , \"intent\" : \"plan\" , \"code\" :{ \"coding\" :[ { \"system\" : \"http://loinc.org\" , \"code\" : \"36801-9\" } ], \"text\" : \"MRA Knee Vessels Right\" }, \"subject\" :{ \"reference\" : \"Patient/MRI-59879846\" }, \"reasonCode\" :[ { \"coding\" :[ { \"system\" : \"http://hl7.org/fhir/sid/icd-10\" , \"code\" : \"S83.511\" , \"display\" : \"Sprain of anterior cruciate ligament of right knee\" } ] } ] } } ] }","title":"Radiology Appropriateness"},{"location":"logo-use/","text":"Use of CDS Hooks Logos \u00b6 The CDS Hooks logos are owned by The Children's Medical Center Corporation and may be used in accordance with guidelines and policy at https://smarthealthit.org/cds-hooks-logo . These guidelines describe how CDS Hooks logos can be used in connection with: scholastic publications, news reports, conferences, meetings, seminars and webinars the sale, promotion and advertising of products that are compatible with CDS Hooks","title":"Logo Use"},{"location":"logo-use/#use-of-cds-hooks-logos","text":"The CDS Hooks logos are owned by The Children's Medical Center Corporation and may be used in accordance with guidelines and policy at https://smarthealthit.org/cds-hooks-logo . These guidelines describe how CDS Hooks logos can be used in connection with: scholastic publications, news reports, conferences, meetings, seminars and webinars the sale, promotion and advertising of products that are compatible with CDS Hooks","title":"Use of CDS Hooks Logos"},{"location":"quickstart/","text":"Quick Start \u00b6 This quick start tutorial defines each of the actors and provides details for implementing the patient-view hook. A CDS Hooks scenario typically includes two main actors: an CDS Client and a CDS Service, where the CDS Client may be an EHR, CPOE or other clinical workflow system. Below is an example interaction for the patient-view hook. Building a CDS Service \u00b6 A CDS Service is an external service that responds to CDS Client requests through cards. A card can optionally link to a SMART app. There are several steps to setting up a CDS Service: Create an endpoint for discovery Develop a service Test the service with the sandbox If applicable, create a SMART app (or borrow one ) Test the service (and, if applicable, SMART app) with an CDS Client This tutorial recommends implementing the CDS Hooks security model after successful open access testing. Endpoint for discovery \u00b6 The CDS Service must provide a stable endpoint for the CDS Client to discover the available services. A system must expose their services at {baseUrl}/cds-services . A service endpoint that supports the patient-view hook may return: 1 2 3 4 5 6 7 8 9 10 11 12 13 { \"services\" : [ { \"hook\" : \"patient-view\" , \"name\" : \"Static CDS Service Example\" , \"description\" : \"An example of a CDS Service that returns a card with SMART app recommendations.\" , \"id\" : \"static-patient-view\" , \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } } ] } The attributes available to describe a CDS Services is documented in the CDS Hooks specification . Develop a service \u00b6 With a stable open end point available it's time to complete development of a service. A CDS Service could provide information , a suggestion , or a SMART app link. The focus of the Argonaut CDS Hooks effort is a patient-view hook launching a SMART app so this guide will focus on the SMART app link. A CDS patient-view hook could return the following card: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { \"cards\" : [ { \"summary\" : \"SMART App Success Card\" , \"indicator\" : \"success\" , \"detail\" : \"This is an example SMART App success card.\" , \"source\" : { \"label\" : \"Static CDS Service Example\" , \"url\" : \"https://example.com\" }, \"links\" : [ { \"label\" : \"SMART Example App\" , \"url\" : \"https://smart.example.com/launch\" , \"type\" : \"smart\" } ] } ] } Create a SMART App \u00b6 You may already have created a SMART app prior to this step, but just in case this is a reminder. The SMART app is launched from the link returned in your service. If you want to borrow a SMART app, check out the app gallery . Test service with a sandbox \u00b6 The CDS Hooks community provides a publicly available sandbox to test your service. Select the configure hooks: Delete the existing hooks, and then do a quick add with a reference to your CDS Service: After testing with the sandbox, you are ready to connect with an CDS Client. Integrating CDS Services into a CDS Client \u00b6 Build out following sections: Call discovery endpoint Invoke service on patient-view Support FHIR resource on CDS requests (context or pre-fetch) Expose non-secured FHIR server for testing Render card Launch SMART app Test with external CDS Service This tutorial recommends implementing the CDS Hooks security model after successful open access testing. Call discovery endpoint \u00b6 The CDS discovery endpoint provides the list of services a CDS provider supports, and the hooks a service should be invoked on. A CDS Client 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 a CDS Client will support. Below is an example work flow where a business analyst accesses this list of available services by calling GET https://example.com/cds-services and then configures them in the system. This image captures a business analyst reviewing services from one CDS provider. A business analyst may review services from multiple providers and configure appropriate services per user profiles. Invoke service on patient-view hook \u00b6 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 CDS Client to decide which characteristics to consider. Support FHIR resource on CDS requests (context or pre-fetch) \u00b6 Often a CDS Service will require additional information from the CDS Client to perform the decision support logic, or determine the appropriate SMART app to return. Prefetch provides the CDS Client 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: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { \"hookInstance\" : \"23f1a303-991f-4118-86c5-11d99a39222e\" , \"fhirServer\" : \"https://fhir.example.org\" , \"hook\" : \"patient-view\" , \"context\" : { \"patientId\" : \"1288992\" , \"userId\" : \"Practitioner/example\" }, \"prefetch\" : { \"patientToGreet\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1925-12-23\" , \"id\" : \"1288992\" , \"active\" : true } } } In some cases, additional information beyond what is included in the prefetch may be required. The CDS Service can request additional information using the FHIR REST APIs: GET [base]/AllergyIntolerance?patient=[id] 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) and HL7 US Core (STU3 and R4) . Each profile page within these implementation guides includes queries FHIR servers are required to support. Expose non-secured FHIR server for testing \u00b6 A non-secured FHIR server is important to support testing with a CDS Service. When the CDS Client moves a hook to production the system is expected to follow the guidelines in the security requirements. Render card \u00b6 The CDS Service will provide a response in the form a of a 'card'. Your CDS Client needs to be able to display the card. Example card JSON: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { \"summary\" : \"Bilirubin: Based on the age of this patient consider overlaying bilirubin [Mass/volume] results over a time-based risk chart\" , \"indicator\" : \"info\" , \"detail\" : \"The focus of this app is to reduce the incidence of severe hyperbilirubinemia and bilirubin encephalopathy while minimizing the risks of unintended harm such as maternal anxiety, decreased breastfeeding, and unnecessary costs or treatment.\" , \"source\" : { \"label\" : \"Intermountain\" , \"url\" : null }, \"links\" : [ { \"label\" : \"Bilirubin SMART app\" , \"url\" : \"https://example.com/launch\" , \"type\" : \"smart\" } ] } Example card rendered: Launch SMART app \u00b6 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 . Test with external CDS Service \u00b6 No development is complete without testing with a CDS Service provider. Find a member in the community and test away.","title":"Quick Start"},{"location":"quickstart/#quick-start","text":"This quick start tutorial defines each of the actors and provides details for implementing the patient-view hook. A CDS Hooks scenario typically includes two main actors: an CDS Client and a CDS Service, where the CDS Client may be an EHR, CPOE or other clinical workflow system. Below is an example interaction for the patient-view hook.","title":"Quick Start"},{"location":"quickstart/#building-a-cds-service","text":"A CDS Service is an external service that responds to CDS Client requests through cards. A card can optionally link to a SMART app. There are several steps to setting up a CDS Service: Create an endpoint for discovery Develop a service Test the service with the sandbox If applicable, create a SMART app (or borrow one ) Test the service (and, if applicable, SMART app) with an CDS Client This tutorial recommends implementing the CDS Hooks security model after successful open access testing.","title":"Building a CDS Service"},{"location":"quickstart/#endpoint-for-discovery","text":"The CDS Service must provide a stable endpoint for the CDS Client to discover the available services. A system must expose their services at {baseUrl}/cds-services . A service endpoint that supports the patient-view hook may return: 1 2 3 4 5 6 7 8 9 10 11 12 13 { \"services\" : [ { \"hook\" : \"patient-view\" , \"name\" : \"Static CDS Service Example\" , \"description\" : \"An example of a CDS Service that returns a card with SMART app recommendations.\" , \"id\" : \"static-patient-view\" , \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } } ] } The attributes available to describe a CDS Services is documented in the CDS Hooks specification .","title":"Endpoint for discovery"},{"location":"quickstart/#develop-a-service","text":"With a stable open end point available it's time to complete development of a service. A CDS Service could provide information , a suggestion , or a SMART app link. The focus of the Argonaut CDS Hooks effort is a patient-view hook launching a SMART app so this guide will focus on the SMART app link. A CDS patient-view hook could return the following card: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 { \"cards\" : [ { \"summary\" : \"SMART App Success Card\" , \"indicator\" : \"success\" , \"detail\" : \"This is an example SMART App success card.\" , \"source\" : { \"label\" : \"Static CDS Service Example\" , \"url\" : \"https://example.com\" }, \"links\" : [ { \"label\" : \"SMART Example App\" , \"url\" : \"https://smart.example.com/launch\" , \"type\" : \"smart\" } ] } ] }","title":"Develop a service"},{"location":"quickstart/#create-a-smart-app","text":"You may already have created a SMART app prior to this step, but just in case this is a reminder. The SMART app is launched from the link returned in your service. If you want to borrow a SMART app, check out the app gallery .","title":"Create a SMART App"},{"location":"quickstart/#test-service-with-a-sandbox","text":"The CDS Hooks community provides a publicly available sandbox to test your service. Select the configure hooks: Delete the existing hooks, and then do a quick add with a reference to your CDS Service: After testing with the sandbox, you are ready to connect with an CDS Client.","title":"Test service with a sandbox"},{"location":"quickstart/#integrating-cds-services-into-a-cds-client","text":"Build out following sections: Call discovery endpoint Invoke service on patient-view Support FHIR resource on CDS requests (context or pre-fetch) Expose non-secured FHIR server for testing Render card Launch SMART app Test with external CDS Service This tutorial recommends implementing the CDS Hooks security model after successful open access testing.","title":"Integrating CDS Services into a CDS Client"},{"location":"quickstart/#call-discovery-endpoint","text":"The CDS discovery endpoint provides the list of services a CDS provider supports, and the hooks a service should be invoked on. A CDS Client 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 a CDS Client will support. Below is an example work flow where a business analyst accesses this list of available services by calling GET https://example.com/cds-services and then configures them in the system. This image captures a business analyst reviewing services from one CDS provider. A business analyst may review services from multiple providers and configure appropriate services per user profiles.","title":"Call discovery endpoint"},{"location":"quickstart/#invoke-service-on-patient-view-hook","text":"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 CDS Client to decide which characteristics to consider.","title":"Invoke service on patient-view hook"},{"location":"quickstart/#support-fhir-resource-on-cds-requests-context-or-pre-fetch","text":"Often a CDS Service will require additional information from the CDS Client to perform the decision support logic, or determine the appropriate SMART app to return. Prefetch provides the CDS Client 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: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 { \"hookInstance\" : \"23f1a303-991f-4118-86c5-11d99a39222e\" , \"fhirServer\" : \"https://fhir.example.org\" , \"hook\" : \"patient-view\" , \"context\" : { \"patientId\" : \"1288992\" , \"userId\" : \"Practitioner/example\" }, \"prefetch\" : { \"patientToGreet\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1925-12-23\" , \"id\" : \"1288992\" , \"active\" : true } } } In some cases, additional information beyond what is included in the prefetch may be required. The CDS Service can request additional information using the FHIR REST APIs: GET [base]/AllergyIntolerance?patient=[id] 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) and HL7 US Core (STU3 and R4) . Each profile page within these implementation guides includes queries FHIR servers are required to support.","title":"Support FHIR resource on CDS requests (context or pre-fetch)"},{"location":"quickstart/#expose-non-secured-fhir-server-for-testing","text":"A non-secured FHIR server is important to support testing with a CDS Service. When the CDS Client moves a hook to production the system is expected to follow the guidelines in the security requirements.","title":"Expose non-secured FHIR server for testing"},{"location":"quickstart/#render-card","text":"The CDS Service will provide a response in the form a of a 'card'. Your CDS Client needs to be able to display the card. Example card JSON: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { \"summary\" : \"Bilirubin: Based on the age of this patient consider overlaying bilirubin [Mass/volume] results over a time-based risk chart\" , \"indicator\" : \"info\" , \"detail\" : \"The focus of this app is to reduce the incidence of severe hyperbilirubinemia and bilirubin encephalopathy while minimizing the risks of unintended harm such as maternal anxiety, decreased breastfeeding, and unnecessary costs or treatment.\" , \"source\" : { \"label\" : \"Intermountain\" , \"url\" : null }, \"links\" : [ { \"label\" : \"Bilirubin SMART app\" , \"url\" : \"https://example.com/launch\" , \"type\" : \"smart\" } ] } Example card rendered:","title":"Render card"},{"location":"quickstart/#launch-smart-app","text":"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 .","title":"Launch SMART app"},{"location":"quickstart/#test-with-external-cds-service","text":"No development is complete without testing with a CDS Service provider. Find a member in the community and test away.","title":"Test with external CDS Service"},{"location":"cheat-sheet/","text":"CDS Hooks Cheat Sheet \u00b6 Whether for general development or distribution at events, it's helpful to have a concise \"cheat sheet\" as a reminder of essential structures and syntax. The Markdown version in this folder is meant to provide the source of truth content for such a doument, leaving further formatting and arrangement up to the consumer. A rendered version created by Firely based on the markdown is also available within this folder and linked to in the navigation section.","title":"CDS Hooks Cheat Sheet"},{"location":"cheat-sheet/#cds-hooks-cheat-sheet","text":"Whether for general development or distribution at events, it's helpful to have a concise \"cheat sheet\" as a reminder of essential structures and syntax. The Markdown version in this folder is meant to provide the source of truth content for such a doument, leaving further formatting and arrangement up to the consumer. A rendered version created by Firely based on the markdown is also available within this folder and linked to in the navigation section.","title":"CDS Hooks Cheat Sheet"},{"location":"cheat-sheet/cheat-sheet/","text":"Overview \u00b6 Links \u00b6 Spec: https://cds-hooks.hl7.org/1.0/ Sandbox: http://sandbox.cds-hooks.org/ Quick Start: https://cds-hooks.org/quickstart/ CDS Service Discovery \u00b6 GET {baseUrl}/cds-services Response Body \u00b6 services - An array of CDS Service s CDS Service: \u00b6 Field Optionality Summary hook REQUIRED hook this service should be invoked on title RECOMMENDED human-friendly name of this service description REQUIRED description of this service id REQUIRED {id} portion of service URL: {baseUrl}/cds-services/{id} prefetch OPTIONAL Object containing key/value pairs of FHIR queries that this service is requesting the CDS Client to include on service calls Example \u00b6 { \"services\": [ { \"hook\": \"hook-noun-verb\", \"title\": \"CDS Service Example\", \"description\": \"An example of a CDS Service that returns a card\", \"id\": \"patient-greeter\", \"prefetch\": { \"patientToGreet\": \"Patient/{{context.patientId}}\" } } ] } CDS Service Request \u00b6 POST {baseUrl}/cds-services/{id} Request Body \u00b6 Field Optionality Summary hook REQUIRED hook that triggered this CDS Service call hookInstance REQUIRED UUID for this hook call fhirServer OPTIONAL base URL for CDS Client\u2019s FHIR server fhirAuthorization OPTIONAL structure with FHIR Authorization information for the above url context REQUIRED hook-specific contextual data prefetch OPTIONAL FHIR data prefetched by the CDS Client FHIR Authorization \u00b6 Field Optionality Summary access_token REQUIRED OAuth 2.0 access token token_type REQUIRED fixed value: Bearer expires_in REQUIRED lifetime in seconds of the access token scope REQUIRED scopes the access token grants to the CDS Service subject REQUIRED OAuth 2.0 client id of the CDS Service\u2019s auth server registration Example ## \u00b6 { \"hook\": \"hook-noun-verb\", \"hookInstance\": \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\", \"fhirServer\": \"https://fhir.client.com/version\", \"fhirAuthorization\": { \"access_token\": \"opaque-token\", \"...\": \"<snipped for brevity>\" }, \"context\": { \"userId\": \"Practitioner/example\", \"...\": \"<snipped for brevity>\" }, \"prefetch\": { \"patientToGreet\": { \"resourceType\": \"Patient\", \"...\": \"<snipped for brevity>\" } } } CDS Service Response Body \u00b6 Field Optionality Summary cards REQUIRED an array of Card s with a combination of information, suggested actions, and links Card \u00b6 Field Optionality Summary summary REQUIRED <140-character summary sentence for display to the user inside of this card detail OPTIONAL optional detailed information to display (GitHub Flavored Markdown) indicator REQUIRED urgency/importance of what this card conveys ( info/warning/critical ) source REQUIRED grouping structure for the Source of information displayed on this card suggestions OPTIONAL array of Suggestion s for changes in the context of the current activity selectionBehavior OPTIONAL intended behavior of the suggestions. If suggestions present, value must be at-most-one links OPTIONAL array of Link s to suggest an app or other additional information Source \u00b6 Field Optionality Summary label REQUIRED short, human-readable label to display source of the card\u2019s information url OPTIONAL optional absolute URL to load to learn more about the organization or data set icon OPTIONAL absolute url for an icon for the source of this card (100x100 pixel PNG without any transparent regions) Suggestion \u00b6 Field Optionality Summary label REQUIRED human-readable label to display for this suggestion uuid OPTIONAL unique identifier for auditing and logging suggestions actions OPTIONAL array of suggested Actions (logically AND\u2019d together) Action \u00b6 Field Optionality Summary type REQUIRED type of action being performed ( create/update/delete ) description REQUIRED human-readable description of the suggested action resource OPTIONAL FHIR resource to create/update or id of resource to delete Link \u00b6 Field Optionality Summary label REQUIRED human-readable label to display url REQUIRED URL to GET when link is clicked type REQUIRED type of the given URL ( absolute/smart ) appContext OPTIONAL additional context to share with a linked SMART app Example \u00b6 { \"cards\": [ { \"summary\": \"<140 char Summary Message\", \"detail\": \"optional GitHub Markdown details\", \"indicator\": \"info\", \"source\": { \"label\": \"Human-readable source label\", \"url\": \"https://example.com\", \"icon\": \"https://example.com/img/icon-100px.png\" }, \"suggestions\": [ { \"label\": \"Human-readable suggestion label\", \"uuid\": \"e1187895-ad57-4ff7-a1f1-ccf954b2fe46\", \"actions\": [ { \"type\": \"create\", \"description\": \"Create a prescription for Acetaminophen 250 MG\", \"resource\": { \"resourceType\": \"MedicationRequest\", \"...\": \"<snipped for brevity>\" } } ] } ], \"links\": [ { \"label\": \"SMART Example App\", \"...\": \"<snipped for brevity>\" } ] } ] }","title":"Overview"},{"location":"cheat-sheet/cheat-sheet/#overview","text":"","title":"Overview"},{"location":"cheat-sheet/cheat-sheet/#links","text":"Spec: https://cds-hooks.hl7.org/1.0/ Sandbox: http://sandbox.cds-hooks.org/ Quick Start: https://cds-hooks.org/quickstart/","title":"Links"},{"location":"cheat-sheet/cheat-sheet/#cds-service-discovery","text":"GET {baseUrl}/cds-services","title":"CDS Service Discovery"},{"location":"cheat-sheet/cheat-sheet/#response-body","text":"services - An array of CDS Service s","title":"Response Body"},{"location":"cheat-sheet/cheat-sheet/#cds-service","text":"Field Optionality Summary hook REQUIRED hook this service should be invoked on title RECOMMENDED human-friendly name of this service description REQUIRED description of this service id REQUIRED {id} portion of service URL: {baseUrl}/cds-services/{id} prefetch OPTIONAL Object containing key/value pairs of FHIR queries that this service is requesting the CDS Client to include on service calls","title":"CDS Service:"},{"location":"cheat-sheet/cheat-sheet/#example","text":"{ \"services\": [ { \"hook\": \"hook-noun-verb\", \"title\": \"CDS Service Example\", \"description\": \"An example of a CDS Service that returns a card\", \"id\": \"patient-greeter\", \"prefetch\": { \"patientToGreet\": \"Patient/{{context.patientId}}\" } } ] }","title":"Example"},{"location":"cheat-sheet/cheat-sheet/#cds-service-request","text":"POST {baseUrl}/cds-services/{id}","title":"CDS Service Request"},{"location":"cheat-sheet/cheat-sheet/#request-body","text":"Field Optionality Summary hook REQUIRED hook that triggered this CDS Service call hookInstance REQUIRED UUID for this hook call fhirServer OPTIONAL base URL for CDS Client\u2019s FHIR server fhirAuthorization OPTIONAL structure with FHIR Authorization information for the above url context REQUIRED hook-specific contextual data prefetch OPTIONAL FHIR data prefetched by the CDS Client","title":"Request Body"},{"location":"cheat-sheet/cheat-sheet/#fhir-authorization","text":"Field Optionality Summary access_token REQUIRED OAuth 2.0 access token token_type REQUIRED fixed value: Bearer expires_in REQUIRED lifetime in seconds of the access token scope REQUIRED scopes the access token grants to the CDS Service subject REQUIRED OAuth 2.0 client id of the CDS Service\u2019s auth server registration","title":"FHIR Authorization"},{"location":"cheat-sheet/cheat-sheet/#example_1","text":"{ \"hook\": \"hook-noun-verb\", \"hookInstance\": \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\", \"fhirServer\": \"https://fhir.client.com/version\", \"fhirAuthorization\": { \"access_token\": \"opaque-token\", \"...\": \"<snipped for brevity>\" }, \"context\": { \"userId\": \"Practitioner/example\", \"...\": \"<snipped for brevity>\" }, \"prefetch\": { \"patientToGreet\": { \"resourceType\": \"Patient\", \"...\": \"<snipped for brevity>\" } } }","title":"Example ##"},{"location":"cheat-sheet/cheat-sheet/#cds-service-response-body","text":"Field Optionality Summary cards REQUIRED an array of Card s with a combination of information, suggested actions, and links","title":"CDS Service Response Body"},{"location":"cheat-sheet/cheat-sheet/#card","text":"Field Optionality Summary summary REQUIRED <140-character summary sentence for display to the user inside of this card detail OPTIONAL optional detailed information to display (GitHub Flavored Markdown) indicator REQUIRED urgency/importance of what this card conveys ( info/warning/critical ) source REQUIRED grouping structure for the Source of information displayed on this card suggestions OPTIONAL array of Suggestion s for changes in the context of the current activity selectionBehavior OPTIONAL intended behavior of the suggestions. If suggestions present, value must be at-most-one links OPTIONAL array of Link s to suggest an app or other additional information","title":"Card"},{"location":"cheat-sheet/cheat-sheet/#source","text":"Field Optionality Summary label REQUIRED short, human-readable label to display source of the card\u2019s information url OPTIONAL optional absolute URL to load to learn more about the organization or data set icon OPTIONAL absolute url for an icon for the source of this card (100x100 pixel PNG without any transparent regions)","title":"Source"},{"location":"cheat-sheet/cheat-sheet/#suggestion","text":"Field Optionality Summary label REQUIRED human-readable label to display for this suggestion uuid OPTIONAL unique identifier for auditing and logging suggestions actions OPTIONAL array of suggested Actions (logically AND\u2019d together)","title":"Suggestion"},{"location":"cheat-sheet/cheat-sheet/#action","text":"Field Optionality Summary type REQUIRED type of action being performed ( create/update/delete ) description REQUIRED human-readable description of the suggested action resource OPTIONAL FHIR resource to create/update or id of resource to delete","title":"Action"},{"location":"cheat-sheet/cheat-sheet/#link","text":"Field Optionality Summary label REQUIRED human-readable label to display url REQUIRED URL to GET when link is clicked type REQUIRED type of the given URL ( absolute/smart ) appContext OPTIONAL additional context to share with a linked SMART app","title":"Link"},{"location":"cheat-sheet/cheat-sheet/#example_2","text":"{ \"cards\": [ { \"summary\": \"<140 char Summary Message\", \"detail\": \"optional GitHub Markdown details\", \"indicator\": \"info\", \"source\": { \"label\": \"Human-readable source label\", \"url\": \"https://example.com\", \"icon\": \"https://example.com/img/icon-100px.png\" }, \"suggestions\": [ { \"label\": \"Human-readable suggestion label\", \"uuid\": \"e1187895-ad57-4ff7-a1f1-ccf954b2fe46\", \"actions\": [ { \"type\": \"create\", \"description\": \"Create a prescription for Acetaminophen 250 MG\", \"resource\": { \"resourceType\": \"MedicationRequest\", \"...\": \"<snipped for brevity>\" } } ] } ], \"links\": [ { \"label\": \"SMART Example App\", \"...\": \"<snipped for brevity>\" } ] } ] }","title":"Example"},{"location":"hooks/appointment-book/","text":"appointment-book \u00b6 Looking for Feedback Hey implementers, we want to hear from you! - What obstacles are there to limiting this hook to firing only when the appointment is confirmed or finalized as booked? - For which users should this hook fire? - Many appointments are scheduled directly into the EHR by the patient, without provider staff involvement ... Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted Workflow \u00b6 This hook is invoked when the user is scheduling one or more future encounters/visits for the patient. For example, the appointment-book hook may be triggered for an appointment with the appointment creator, a clinician within the same organization as the appointment creator or even for an appointment outside the creator's organization. It may be invoked at the start and end of the booking process and/or any time between those two points. This hook enables CDS Services to intervene in the decision of when future appointments should be scheduled, where they should be scheduled, what services should be booked, to identify actions that need to occur prior to scheduled appointments, etc. Context \u00b6 The Patient whose appointment(s) are being booked, as well as the proposed Appointment records. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user could be of type Practitioner , PractitionerRole , Patient , or RelatedPerson . For example, PractitionerRole/123 . Patient or RelatedPerson are appropriate when a patient or their proxy are booking the appointment. patientId REQUIRED Yes string The FHIR Patient.id of Patient appointment(s) is/are for encounterId OPTIONAL Yes string The FHIR Encounter.id of Encounter where booking was initiated appointments REQUIRED No object DSTU2/STU3/R4 - FHIR Bundle of Appointments in 'proposed' state Examples (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"appointments\" : [ { \"resourceType\" : \"Appointment\" , \"id\" : \"apt1\" , \"status\" : \"proposed\" , \"serviceType\" : [ { \"coding\" : [ { \"code\" : \"183\" , \"display\" : \"Sleep Medicine\" } ] } ], \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v2/0276\" , \"code\" : \"FOLLOWUP\" , \"display\" : \"A follow up visit from a previous appointment\" } ] }, \"reason\" : { \"coding\" : { \"system\" : \"\" , \"code\" : \"1023001\" , \"display\" : \"Apnea\" } }, \"description\" : \"CPAP adjustments\" , \"start\" : \"2019-08-10T09:00:00-06:00\" , \"end\" : \"2019-08-10T09:10:00:00-06:00\" , \"created\" : \"2019-08-01\" , \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" } ] }, { \"resourceType\" : \"Appointment\" , \"id\" : \"apt1\" , \"status\" : \"proposed\" , \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v2/0276\" , \"code\" : \"CHECKUP\" , \"display\" : \"A routine check-up, such as an annual physical\" } ] }, \"description\" : \"Regular physical\" , \"start\" : \"2020-08-01T13:00:00-06:00\" , \"end\" : \"2020-08-01T13:30:00:00-06:00\" , \"created\" : \"2019-08-01\" , \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" } ] } ] } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" , \"appointments\" : [ { \"resourceType\" : \"Appointment\" , \"id\" : \"example\" , \"text\" : { \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Brian MRI results discussion</div>\" }, \"status\" : \"proposed\" , \"serviceCategory\" : { \"coding\" : [ { \"system\" : \"http://example.org/service-category\" , \"code\" : \"gp\" , \"display\" : \"General Practice\" } ] }, \"serviceType\" : [ { \"coding\" : [ { \"code\" : \"52\" , \"display\" : \"General Discussion\" } ] } ], \"specialty\" : [ { \"coding\" : [ { \"system\" : \"http://example.org/specialty\" , \"code\" : \"gp\" , \"display\" : \"General Practice\" } ] } ], \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://example.org/appointment-type\" , \"code\" : \"follow\" , \"display\" : \"Followup\" } ] }, \"indication\" : [ { \"reference\" : \"Condition/example\" , \"display\" : \"Severe burn of left ear\" } ], \"priority\" : 5 , \"description\" : \"Discussion on the results of your recent MRI\" , \"start\" : \"2013-12-10T09:00:00Z\" , \"end\" : \"2013-12-10T11:00:00Z\" , \"created\" : \"2013-10-10\" , \"comment\" : \"Further expand on the results of the MRI and determine the next actions that may be appropriate.\" , \"incomingReferral\" : [ { \"reference\" : \"ReferralRequest/example\" } ], \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"type\" : [ { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v3/ParticipationType\" , \"code\" : \"ATND\" } ] } ], \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" }, { \"actor\" : { \"reference\" : \"Location/1\" , \"display\" : \"South Wing, second floor\" }, \"required\" : \"required\" , \"status\" : \"action-needed\" } ] } ] } Change Log \u00b6 Version Description 1.0 Initial Release","title":"appointment-book 1"},{"location":"hooks/appointment-book/#appointment-book","text":"Looking for Feedback Hey implementers, we want to hear from you! - What obstacles are there to limiting this hook to firing only when the appointment is confirmed or finalized as booked? - For which users should this hook fire? - Many appointments are scheduled directly into the EHR by the patient, without provider staff involvement ... Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted","title":"appointment-book"},{"location":"hooks/appointment-book/#workflow","text":"This hook is invoked when the user is scheduling one or more future encounters/visits for the patient. For example, the appointment-book hook may be triggered for an appointment with the appointment creator, a clinician within the same organization as the appointment creator or even for an appointment outside the creator's organization. It may be invoked at the start and end of the booking process and/or any time between those two points. This hook enables CDS Services to intervene in the decision of when future appointments should be scheduled, where they should be scheduled, what services should be booked, to identify actions that need to occur prior to scheduled appointments, etc.","title":"Workflow"},{"location":"hooks/appointment-book/#context","text":"The Patient whose appointment(s) are being booked, as well as the proposed Appointment records. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user could be of type Practitioner , PractitionerRole , Patient , or RelatedPerson . For example, PractitionerRole/123 . Patient or RelatedPerson are appropriate when a patient or their proxy are booking the appointment. patientId REQUIRED Yes string The FHIR Patient.id of Patient appointment(s) is/are for encounterId OPTIONAL Yes string The FHIR Encounter.id of Encounter where booking was initiated appointments REQUIRED No object DSTU2/STU3/R4 - FHIR Bundle of Appointments in 'proposed' state","title":"Context"},{"location":"hooks/appointment-book/#examples-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"appointments\" : [ { \"resourceType\" : \"Appointment\" , \"id\" : \"apt1\" , \"status\" : \"proposed\" , \"serviceType\" : [ { \"coding\" : [ { \"code\" : \"183\" , \"display\" : \"Sleep Medicine\" } ] } ], \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v2/0276\" , \"code\" : \"FOLLOWUP\" , \"display\" : \"A follow up visit from a previous appointment\" } ] }, \"reason\" : { \"coding\" : { \"system\" : \"\" , \"code\" : \"1023001\" , \"display\" : \"Apnea\" } }, \"description\" : \"CPAP adjustments\" , \"start\" : \"2019-08-10T09:00:00-06:00\" , \"end\" : \"2019-08-10T09:10:00:00-06:00\" , \"created\" : \"2019-08-01\" , \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" } ] }, { \"resourceType\" : \"Appointment\" , \"id\" : \"apt1\" , \"status\" : \"proposed\" , \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v2/0276\" , \"code\" : \"CHECKUP\" , \"display\" : \"A routine check-up, such as an annual physical\" } ] }, \"description\" : \"Regular physical\" , \"start\" : \"2020-08-01T13:00:00-06:00\" , \"end\" : \"2020-08-01T13:30:00:00-06:00\" , \"created\" : \"2019-08-01\" , \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" } ] } ] } 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" , \"appointments\" : [ { \"resourceType\" : \"Appointment\" , \"id\" : \"example\" , \"text\" : { \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Brian MRI results discussion</div>\" }, \"status\" : \"proposed\" , \"serviceCategory\" : { \"coding\" : [ { \"system\" : \"http://example.org/service-category\" , \"code\" : \"gp\" , \"display\" : \"General Practice\" } ] }, \"serviceType\" : [ { \"coding\" : [ { \"code\" : \"52\" , \"display\" : \"General Discussion\" } ] } ], \"specialty\" : [ { \"coding\" : [ { \"system\" : \"http://example.org/specialty\" , \"code\" : \"gp\" , \"display\" : \"General Practice\" } ] } ], \"appointmentType\" : { \"coding\" : [ { \"system\" : \"http://example.org/appointment-type\" , \"code\" : \"follow\" , \"display\" : \"Followup\" } ] }, \"indication\" : [ { \"reference\" : \"Condition/example\" , \"display\" : \"Severe burn of left ear\" } ], \"priority\" : 5 , \"description\" : \"Discussion on the results of your recent MRI\" , \"start\" : \"2013-12-10T09:00:00Z\" , \"end\" : \"2013-12-10T11:00:00Z\" , \"created\" : \"2013-10-10\" , \"comment\" : \"Further expand on the results of the MRI and determine the next actions that may be appropriate.\" , \"incomingReferral\" : [ { \"reference\" : \"ReferralRequest/example\" } ], \"participant\" : [ { \"actor\" : { \"reference\" : \"Patient/example\" , \"display\" : \"Peter James Chalmers\" }, \"required\" : \"required\" , \"status\" : \"tentative\" }, { \"type\" : [ { \"coding\" : [ { \"system\" : \"http://hl7.org/fhir/v3/ParticipationType\" , \"code\" : \"ATND\" } ] } ], \"actor\" : { \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"required\" : \"required\" , \"status\" : \"accepted\" }, { \"actor\" : { \"reference\" : \"Location/1\" , \"display\" : \"South Wing, second floor\" }, \"required\" : \"required\" , \"status\" : \"action-needed\" } ] } ] }","title":"Examples (STU3)"},{"location":"hooks/appointment-book/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/encounter-discharge/","text":"encounter-discharge \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted Workflow \u00b6 This hook is invoked when the user is performing the discharge process for an encounter where the notion of 'discharge' is relevant - typically an inpatient encounter. It may be invoked at the start and end of the discharge process or any time between those two points. It allows hook services to intervene in the decision of whether discharge is appropriate, to verify discharge medications, to check for continuity of care planning, to ensure necessary documentation is present for discharge processing, etc. Context \u00b6 The patient who is being discharged and the encounter being ended. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, Practitioner/123 patientId REQUIRED Yes string The FHIR Patient.id of the being discharged encounterId REQUIRED Yes string The FHIR Encounter.id of the Encounter being ended Examples \u00b6 1 2 3 4 5 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" } Change Log \u00b6 Version Description 1.0 Initial Release","title":"encounter-discharge 1"},{"location":"hooks/encounter-discharge/#encounter-discharge","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted","title":"encounter-discharge"},{"location":"hooks/encounter-discharge/#workflow","text":"This hook is invoked when the user is performing the discharge process for an encounter where the notion of 'discharge' is relevant - typically an inpatient encounter. It may be invoked at the start and end of the discharge process or any time between those two points. It allows hook services to intervene in the decision of whether discharge is appropriate, to verify discharge medications, to check for continuity of care planning, to ensure necessary documentation is present for discharge processing, etc.","title":"Workflow"},{"location":"hooks/encounter-discharge/#context","text":"The patient who is being discharged and the encounter being ended. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, Practitioner/123 patientId REQUIRED Yes string The FHIR Patient.id of the being discharged encounterId REQUIRED Yes string The FHIR Encounter.id of the Encounter being ended","title":"Context"},{"location":"hooks/encounter-discharge/#examples","text":"1 2 3 4 5 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" }","title":"Examples"},{"location":"hooks/encounter-discharge/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/encounter-start/","text":"encounter-start \u00b6 Looking for Feedback Hey implementers, we want to hear from you! - What's the greatest opportunity for delivering remote CDS at the start of an encounter? - For which users should this hook fire? - When in a hospitalization workflow, an ambulatory workflow, does an encounter start? - How many and what types of encounters are there in a single hospitalization, a single ambulatory visit? - Is there value in an encounter start hook pairing with an (typically inpatient) encounter discharge hook? - Please explain your encounter workflow. Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted Workflow \u00b6 This hook is invoked when the user is initiating a new encounter. In an inpatient setting, this would be the time of admission. In an outpatient/community environment, this would be the time of patient-check-in for a face-to-face or equivalent for a virtual/telephone encounter. The Encounter should either be in one of the following states: planned | arrived | triaged | in-progress . Note that there can be multiple 'starts' for the same encounter as each user becomes engaged. For example, when a scheduled encounter is presented at the beginning of the day for planning purposes, when the patient arrives, when the patient first encounters a clinician, etc. Hooks may present different information depending on user role and Encounter.status. Note: This is distinct from the patient-view hook which occurs any time the patient's record is looked at - which might be done outside the context of any encounter and will often occur during workflows that are not linked to the initiation of an encounter. The intention is that the cards from any invoked CDS Services are available at the time when decisions are being made about what actions are going to occur during this encounter. For example, identifying that the patient is due for certain diagnostic tests or interventions, identifying additional information that should be collected to comply with protocols associated with clinical studies the patient is enrolled in, identifying any documentation or other requirements associated with patient insurance, etc. Context \u00b6 Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 patientId REQUIRED Yes string The FHIR Patient.id of the Patient the Encounter is for encounterId REQUIRED Yes string The FHIR Encounter.id of the Encounter being started Examples \u00b6 1 2 3 4 5 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" } Change Log \u00b6 Version Description 1.0 Initial Release","title":"encounter-start 1"},{"location":"hooks/encounter-start/#encounter-start","text":"Looking for Feedback Hey implementers, we want to hear from you! - What's the greatest opportunity for delivering remote CDS at the start of an encounter? - For which users should this hook fire? - When in a hospitalization workflow, an ambulatory workflow, does an encounter start? - How many and what types of encounters are there in a single hospitalization, a single ambulatory visit? - Is there value in an encounter start hook pairing with an (typically inpatient) encounter discharge hook? - Please explain your encounter workflow. Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 1 - Submitted","title":"encounter-start"},{"location":"hooks/encounter-start/#workflow","text":"This hook is invoked when the user is initiating a new encounter. In an inpatient setting, this would be the time of admission. In an outpatient/community environment, this would be the time of patient-check-in for a face-to-face or equivalent for a virtual/telephone encounter. The Encounter should either be in one of the following states: planned | arrived | triaged | in-progress . Note that there can be multiple 'starts' for the same encounter as each user becomes engaged. For example, when a scheduled encounter is presented at the beginning of the day for planning purposes, when the patient arrives, when the patient first encounters a clinician, etc. Hooks may present different information depending on user role and Encounter.status. Note: This is distinct from the patient-view hook which occurs any time the patient's record is looked at - which might be done outside the context of any encounter and will often occur during workflows that are not linked to the initiation of an encounter. The intention is that the cards from any invoked CDS Services are available at the time when decisions are being made about what actions are going to occur during this encounter. For example, identifying that the patient is due for certain diagnostic tests or interventions, identifying additional information that should be collected to comply with protocols associated with clinical studies the patient is enrolled in, identifying any documentation or other requirements associated with patient insurance, etc.","title":"Workflow"},{"location":"hooks/encounter-start/#context","text":"Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 patientId REQUIRED Yes string The FHIR Patient.id of the Patient the Encounter is for encounterId REQUIRED Yes string The FHIR Encounter.id of the Encounter being started","title":"Context"},{"location":"hooks/encounter-start/#examples","text":"1 2 3 4 5 \"context\" :{ \"userId\" : \"PractitionerRole/A2340113\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" }","title":"Examples"},{"location":"hooks/encounter-start/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/medication-prescribe/","text":"medication-prescribe \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 2 - Tested Deprecation Notice \u00b6 This hook is deprecated in favor of the order-select and order-sign hooks, with the goal of clarifying workflow trigger points and supporting orders beyond medications. In this refactoring, medication-prescribe and order-review hooks are being deprecated in favor of newly created order-select and order-sign hooks. This notice is a placeholder to this effect while CDS Hooks determines the appropriate process for deprecating hooks . Workflow \u00b6 The user is in the process of prescribing one or more new medications. Context \u00b6 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 userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner . 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 STU3 - FHIR Bundle of draft MedicationRequest resources Example (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-104\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:26:48.124-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Azithromycin 20 MG/ML Oral Suspension [Zithromax] (rxnorm: 211307)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-104\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Change Log \u00b6 Version Description 1.0 Initial Release","title":"medication-prescribe \ud83d\udeab"},{"location":"hooks/medication-prescribe/#medication-prescribe","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 2 - Tested","title":"medication-prescribe"},{"location":"hooks/medication-prescribe/#deprecation-notice","text":"This hook is deprecated in favor of the order-select and order-sign hooks, with the goal of clarifying workflow trigger points and supporting orders beyond medications. In this refactoring, medication-prescribe and order-review hooks are being deprecated in favor of newly created order-select and order-sign hooks. This notice is a placeholder to this effect while CDS Hooks determines the appropriate process for deprecating hooks .","title":"Deprecation Notice"},{"location":"hooks/medication-prescribe/#workflow","text":"The user is in the process of prescribing one or more new medications.","title":"Workflow"},{"location":"hooks/medication-prescribe/#context","text":"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 userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner . 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 STU3 - FHIR Bundle of draft MedicationRequest resources","title":"Context"},{"location":"hooks/medication-prescribe/#example-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-104\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:26:48.124-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Azithromycin 20 MG/ML Oral Suspension [Zithromax] (rxnorm: 211307)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (STU3)"},{"location":"hooks/medication-prescribe/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-104\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (DSTU2)"},{"location":"hooks/medication-prescribe/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/medication-refill/","text":"medication-refill \u00b6 Metadata Value specificationVersion 2.0 hookVersion 0.1.0 hookMaturity 1 - Submitted Workflow \u00b6 The medication-refill hook fires when a medication refill request for an existing prescription of a specific medication is received. A refill request may be made as part of an encounter or out-of-band through a pharmacy or patient portal. Since a prescription refill is requested outside of the prescriber's workflow, there often is not a user in context. Similarly, the encounter may be an auto-generated refill encounter or there may not be an encounter in context when the refill request is received. A CDS service may use this hook to deliver medication refill protocol guidance to a clinician. Given the asynchronous workflow of refill requests, the guidance returned by the service may be viewed immediately, or not. This hook does not fire for an initial prescription (see order-sign). \"Re-prescribing\" or replacing a previously active prescription with a new perscription for the same medication does not fire the medication-refill. Context \u00b6 The set of medications in the process of being refilled. 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 userId OPTIONAL Yes string In the case when this field is empty, consider the FHIR resource's requestor and recorder elements. The id of the current user entering the refill request within the CPOE. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc. patientId REQUIRED Yes string The FHIR Patient.id of the current patient in context encounterId OPTIONAL Yes string The FHIR Encounter.id of the encounter associated with the refill of the prescription. medications REQUIRED No object R4 - FHIR Bundle of draft , order MedicationRequest resources Example (R4) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-104\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationReference\" : { \"reference\" : \"Medication/eFnx9hyX.YTNJ407PR9g4zpiT8lXCElOXkldLgGDYrAU-fszvYmrUZlYzRfJl-qKj3\" , \"display\" : \"oxybutynin (DITROPAN XL) CR tablet\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-104\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Change Log \u00b6 Version Description 0.1.0 Initial Release","title":"medication-refill 1"},{"location":"hooks/medication-refill/#medication-refill","text":"Metadata Value specificationVersion 2.0 hookVersion 0.1.0 hookMaturity 1 - Submitted","title":"medication-refill"},{"location":"hooks/medication-refill/#workflow","text":"The medication-refill hook fires when a medication refill request for an existing prescription of a specific medication is received. A refill request may be made as part of an encounter or out-of-band through a pharmacy or patient portal. Since a prescription refill is requested outside of the prescriber's workflow, there often is not a user in context. Similarly, the encounter may be an auto-generated refill encounter or there may not be an encounter in context when the refill request is received. A CDS service may use this hook to deliver medication refill protocol guidance to a clinician. Given the asynchronous workflow of refill requests, the guidance returned by the service may be viewed immediately, or not. This hook does not fire for an initial prescription (see order-sign). \"Re-prescribing\" or replacing a previously active prescription with a new perscription for the same medication does not fire the medication-refill.","title":"Workflow"},{"location":"hooks/medication-refill/#context","text":"The set of medications in the process of being refilled. 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 userId OPTIONAL Yes string In the case when this field is empty, consider the FHIR resource's requestor and recorder elements. The id of the current user entering the refill request within the CPOE. For this hook, the user is expected to be of type Practitioner or PractitionerRole. For example, PractitionerRole/123 or Practitioner/abc. patientId REQUIRED Yes string The FHIR Patient.id of the current patient in context encounterId OPTIONAL Yes string The FHIR Encounter.id of the encounter associated with the refill of the prescription. medications REQUIRED No object R4 - FHIR Bundle of draft , order MedicationRequest resources","title":"Context"},{"location":"hooks/medication-refill/#example-r4","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-104\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationReference\" : { \"reference\" : \"Medication/eFnx9hyX.YTNJ407PR9g4zpiT8lXCElOXkldLgGDYrAU-fszvYmrUZlYzRfJl-qKj3\" , \"display\" : \"oxybutynin (DITROPAN XL) CR tablet\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (R4)"},{"location":"hooks/medication-refill/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"medications\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-104\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"211307\" , \"display\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" } ], \"text\" : \"Azithromycin 20 MG/ML Oral Suspension [Zithromax]\" }, \"dosageInstruction\" :[ { \"text\" : \"15 mL daily x 3 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-18\" }, \"frequency\" : 1 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 15 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 3 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (DSTU2)"},{"location":"hooks/medication-refill/#change-log","text":"Version Description 0.1.0 Initial Release","title":"Change Log"},{"location":"hooks/order-dispatch/","text":"order-dispatch \u00b6 Metadata Value specificationVersion 2.0 hookVersion 1.1 hookMaturity 0 - Draft Workflow \u00b6 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 . 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. Decision support that may be relevant for this hook might include information related to coverage, prior-authorization and/or in-network/out-of-network evaluations with respect to the chosen performer; determination of practitioner availability or qualification; enforcement/guidance with respect to patient performer preferences; etc. Context \u00b6 Field Optionality Prefetch Token Type Description patientId REQUIRED Yes string The FHIR Patient.id of the current patient in context 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 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 \u00b6 Example (R4) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 \"context\" :{ \"patientId\" : \"1288992\" , \"dispatched-orders\" : [ \"ServiceRequest/proc002\" ], \"performer\" : \"Organization/some-performer\" , \"fulfillment-tasks\" : [{ \"resourceType\" : \"Task\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"code\" : { \"coding\" : [{ \"system\" : \"http://hl7.org/fhir/CodeSystem/task-code\" , \"code\" : \"fulfill\" }] }, \"focus\" : { \"reference\" : \"ServiceRequest/proc002\" }, \"for\" : { \"reference\" : \"Patient/1288992\" }, \"authoredOn\" : \"2016-03-10T22:39:32-04:00\" , \"lastModified\" : \"2016-03-10T22:39:32-04:00\" , \"requester\" : { \"reference\" : \"Practitioner/456\" }, \"owner\" : { \"reference\" : \"Organziation/some-performer\" } }] } Change Log \u00b6 Version Description 1.0 Initial Release 1.1 Adjusted context names and cardinalities based on feedback","title":"order-dispatch 0"},{"location":"hooks/order-dispatch/#order-dispatch","text":"Metadata Value specificationVersion 2.0 hookVersion 1.1 hookMaturity 0 - Draft","title":"order-dispatch"},{"location":"hooks/order-dispatch/#workflow","text":"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 . 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. Decision support that may be relevant for this hook might include information related to coverage, prior-authorization and/or in-network/out-of-network evaluations with respect to the chosen performer; determination of practitioner availability or qualification; enforcement/guidance with respect to patient performer preferences; etc.","title":"Workflow"},{"location":"hooks/order-dispatch/#context","text":"Field Optionality Prefetch Token Type Description patientId REQUIRED Yes string The FHIR Patient.id of the current patient in context 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 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.","title":"Context"},{"location":"hooks/order-dispatch/#examples","text":"","title":"Examples"},{"location":"hooks/order-dispatch/#example-r4","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 \"context\" :{ \"patientId\" : \"1288992\" , \"dispatched-orders\" : [ \"ServiceRequest/proc002\" ], \"performer\" : \"Organization/some-performer\" , \"fulfillment-tasks\" : [{ \"resourceType\" : \"Task\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"code\" : { \"coding\" : [{ \"system\" : \"http://hl7.org/fhir/CodeSystem/task-code\" , \"code\" : \"fulfill\" }] }, \"focus\" : { \"reference\" : \"ServiceRequest/proc002\" }, \"for\" : { \"reference\" : \"Patient/1288992\" }, \"authoredOn\" : \"2016-03-10T22:39:32-04:00\" , \"lastModified\" : \"2016-03-10T22:39:32-04:00\" , \"requester\" : { \"reference\" : \"Practitioner/456\" }, \"owner\" : { \"reference\" : \"Organziation/some-performer\" } }] }","title":"Example (R4)"},{"location":"hooks/order-dispatch/#change-log","text":"Version Description 1.0 Initial Release 1.1 Adjusted context names and cardinalities based on feedback","title":"Change Log"},{"location":"hooks/order-review/","text":"order-review \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 3 - Considered Deprecation Notice \u00b6 This hook is deprecated in favor of the order-sign hooks, with the goal of clarifying workflow trigger points and supporting orders beyond medications. In this refactoring, medication-prescribe and order-review hooks are being deprecated in favor of newly created order-select and order-sign hooks. This notice is a placeholder to this effect while CDS Hooks determines the appropriate process for deprecating hooks . Workflow \u00b6 The user is in the process of reviewing a set of orders to sign. Context \u00b6 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 orders object MUST have a status of draft . Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner . 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 STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status Example (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"orders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"orders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } Change Log \u00b6 Version Description 1.0 Initial Release","title":"order-review \ud83d\udeab"},{"location":"hooks/order-review/#order-review","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 3 - Considered","title":"order-review"},{"location":"hooks/order-review/#deprecation-notice","text":"This hook is deprecated in favor of the order-sign hooks, with the goal of clarifying workflow trigger points and supporting orders beyond medications. In this refactoring, medication-prescribe and order-review hooks are being deprecated in favor of newly created order-select and order-sign hooks. This notice is a placeholder to this effect while CDS Hooks determines the appropriate process for deprecating hooks .","title":"Deprecation Notice"},{"location":"hooks/order-review/#workflow","text":"The user is in the process of reviewing a set of orders to sign.","title":"Workflow"},{"location":"hooks/order-review/#context","text":"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 orders object MUST have a status of draft . Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner . 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 STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status","title":"Context"},{"location":"hooks/order-review/#example-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 { \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"orders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (STU3)"},{"location":"hooks/order-review/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 \"context\" :{ \"userId\" : \"Practitioner/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"orders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } }","title":"Example (DSTU2)"},{"location":"hooks/order-review/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/order-select/","text":"order-select \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 4 - Documented Workflow \u00b6 The order-select hook occurs after the clinician selects the order and before signing. 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. Context \u00b6 Decision support should focus on the 'selected' orders - those that are newly selected or actively being authored. The non-selected orders are included in the context to provide context and to allow decision support to take into account other pending actions that might not yet be stored in the system (and therefore not queryable). The context of this hook distinguishes between the list of unsigned orders from the clinician's ordering session, and the one or more orders just added to this list. The selections field contains a list of ids of these newly selected orders; the draftOrders Bundle contains an entry for all unsigned orders from this session, including newly selected orders. The selected order(s) may or may not define the additional details necessary to finalize the order (such as route, dose, etc). Note that at the point of the related order-sign hook, all order details are known. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 or Practitioner/abc . 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 selections REQUIRED No array The FHIR id of the newly selected order(s). The selections field references FHIR resources in the draftOrders Bundle. For example, MedicationRequest/103 . draftOrders REQUIRED No object DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status R4 - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription with draft status Examples \u00b6 Example (R4) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 { \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"NutritionOrder/pureeddiet-simple\" , \"MedicationRequest/smart-MedicationRequest-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseAndRate\" :{ \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 { \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"NutritionOrder/pureeddiet-simple\" , \"MedicationRequest/smart-MedicationRequest-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" :[ \"NutritionOrder/nest-patient-1-NUTR1\" , \"MedicationOrder/smart-MedicationOrder-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } Change Log \u00b6 Version Description 1.0 Initial Release 1.0.1 Small documentation correction 1.0.2 Add DeviceRequest to list of order resources for R4.","title":"order-select 4"},{"location":"hooks/order-select/#order-select","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 4 - Documented","title":"order-select"},{"location":"hooks/order-select/#workflow","text":"The order-select hook occurs after the clinician selects the order and before signing. 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.","title":"Workflow"},{"location":"hooks/order-select/#context","text":"Decision support should focus on the 'selected' orders - those that are newly selected or actively being authored. The non-selected orders are included in the context to provide context and to allow decision support to take into account other pending actions that might not yet be stored in the system (and therefore not queryable). The context of this hook distinguishes between the list of unsigned orders from the clinician's ordering session, and the one or more orders just added to this list. The selections field contains a list of ids of these newly selected orders; the draftOrders Bundle contains an entry for all unsigned orders from this session, including newly selected orders. The selected order(s) may or may not define the additional details necessary to finalize the order (such as route, dose, etc). Note that at the point of the related order-sign hook, all order details are known. Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 or Practitioner/abc . 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 selections REQUIRED No array The FHIR id of the newly selected order(s). The selections field references FHIR resources in the draftOrders Bundle. For example, MedicationRequest/103 . draftOrders REQUIRED No object DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription with draft status R4 - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription with draft status","title":"Context"},{"location":"hooks/order-select/#examples","text":"","title":"Examples"},{"location":"hooks/order-select/#example-r4","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 { \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"NutritionOrder/pureeddiet-simple\" , \"MedicationRequest/smart-MedicationRequest-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseAndRate\" :{ \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (R4)"},{"location":"hooks/order-select/#example-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 { \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" : [ \"NutritionOrder/pureeddiet-simple\" , \"MedicationRequest/smart-MedicationRequest-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (STU3)"},{"location":"hooks/order-select/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"selections\" :[ \"NutritionOrder/nest-patient-1-NUTR1\" , \"MedicationOrder/smart-MedicationOrder-103\" ], \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } }","title":"Example (DSTU2)"},{"location":"hooks/order-select/#change-log","text":"Version Description 1.0 Initial Release 1.0.1 Small documentation correction 1.0.2 Add DeviceRequest to list of order resources for R4.","title":"Change Log"},{"location":"hooks/order-sign/","text":"order-sign \u00b6 Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 5 - Mature Workflow \u00b6 The order-sign hook fires when a clinician is ready to sign one or more orders for a patient, (including orders for medications, procedures, labs and other 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. 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 case, the orders would typically have a status other than 'draft'. In some cases, the hook might fire with a mixture of new and revised orders. This hook is intended to replace (deprecate) the medication-prescribe and order-review hooks. Context \u00b6 Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 or Practitioner/abc . 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 draftOrders REQUIRED No object DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription (typically with draft status) STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription (typically with draft status) R4 - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription (typically with draft status) Examples \u00b6 Example (R4) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 { \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (STU3) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 { \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseAndRate\" :{ \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } } Example (DSTU2) \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 \"context\" :{ \"userId\" : \"Practitioner/abc\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } Change Log \u00b6 Version Description 1.0 Initial Release 1.0.1 Add DeviceRequest to list of order resources for R4. 1.1.0 Updated hook to all for use in order-revision situations","title":"order-sign 5"},{"location":"hooks/order-sign/#order-sign","text":"Metadata Value specificationVersion 1.0 hookVersion 1.0 Hook maturity 5 - Mature","title":"order-sign"},{"location":"hooks/order-sign/#workflow","text":"The order-sign hook fires when a clinician is ready to sign one or more orders for a patient, (including orders for medications, procedures, labs and other 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. 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 case, the orders would typically have a status other than 'draft'. In some cases, the hook might fire with a mixture of new and revised orders. This hook is intended to replace (deprecate) the medication-prescribe and order-review hooks.","title":"Workflow"},{"location":"hooks/order-sign/#context","text":"Field Optionality Prefetch Token Type Description userId REQUIRED Yes string The id of the current user. For this hook, the user is expected to be of type Practitioner or PractitionerRole . For example, PractitionerRole/123 or Practitioner/abc . 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 draftOrders REQUIRED No object DSTU2 - FHIR Bundle of MedicationOrder, DiagnosticOrder, DeviceUseRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription (typically with draft status) STU3 - FHIR Bundle of MedicationRequest, ReferralRequest, ProcedureRequest, NutritionOrder, VisionPrescription (typically with draft status) R4 - FHIR Bundle of DeviceRequest, MedicationRequest, NutritionOrder, ServiceRequest, VisionPrescription (typically with draft status)","title":"Context"},{"location":"hooks/order-sign/#examples","text":"","title":"Examples"},{"location":"hooks/order-sign/#example-r4","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 { \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (R4)"},{"location":"hooks/order-sign/#example-stu3","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 { \"context\" :{ \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"pureeddiet-simple\" , \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-requests\" , \"value\" : \"123\" } ], \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"dateTime\" : \"2014-09-17\" , \"orderer\" :{ \"reference\" : \"Practitioner/example\" , \"display\" : \"Dr Adam Careful\" }, \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"226211001\" , \"display\" : \"Pureed diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Pureed diet\" } ], \"text\" : \"Pureed diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnit\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228055009\" , \"display\" : \"Liquidized food\" } ], \"text\" : \"Pureed\" } } ], \"fluidConsistencyType\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"439021000124105\" , \"display\" : \"Dietary liquid consistency - nectar thick liquid\" } ], \"text\" : \"Nectar thick liquids\" } ] }, \"supplement\" :[ { \"type\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"442971000124100\" , \"display\" : \"Adult high energy formula\" }, { \"system\" : \"http://goodhealthhospital.org/supplement-type-codes\" , \"code\" : \"1040\" , \"display\" : \"Adult high energy pudding\" } ], \"text\" : \"Adult high energy pudding\" }, \"productName\" : \"Ensure Pudding 4 oz container\" , \"instruction\" : \"Ensure Pudding at breakfast, lunch, supper\" } ] } }, { \"resource\" :{ \"resourceType\" : \"MedicationRequest\" , \"id\" : \"smart-MedicationRequest-103\" , \"meta\" :{ \"lastUpdated\" : \"2018-04-30T13:25:40.845-04:00\" }, \"text\" :{ \"status\" : \"generated\" , \"div\" : \"<div xmlns=\\\"http://www.w3.org/1999/xhtml\\\">Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension (rxnorm: 617993)</div>\" }, \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"subject\" :{ \"reference\" : \"Patient/1288992\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnit\" : \"d\" } }, \"doseAndRate\" :{ \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } } }","title":"Example (STU3)"},{"location":"hooks/order-sign/#example-dstu2","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 \"context\" :{ \"userId\" : \"Practitioner/abc\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" , \"draftOrders\" :{ \"resourceType\" : \"Bundle\" , \"entry\" :[ { \"resource\" :{ \"resourceType\" : \"NutritionOrder\" , \"id\" : \"nest-patient-1-NUTR1\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"orderer\" :{ \"display\" : \"Dr Adam Careful\" }, \"identifier\" :[ { \"system\" : \"http://goodhealthhospital.org/nutrition-orders\" , \"value\" : \"123\" } ], \"dateTime\" : \"2014-09-17\" , \"status\" : \"draft\" , \"oralDiet\" :{ \"type\" :[ { \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"435801000124108\" , \"display\" : \"Texture modified diet\" }, { \"system\" : \"http://goodhealthhospital.org/diet-type-codes\" , \"code\" : \"1010\" , \"display\" : \"Texture modified diet\" } ], \"text\" : \"Texture modified diet\" } ], \"schedule\" :[ { \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2015-02-10\" }, \"frequency\" : 3 , \"period\" : 1 , \"periodUnits\" : \"d\" } } ], \"texture\" :[ { \"modifier\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"228049004\" , \"display\" : \"Chopped food\" } ], \"text\" : \"Regular, Chopped Meat\" }, \"foodType\" :{ \"coding\" :[ { \"system\" : \"http://snomed.info/sct\" , \"code\" : \"22836000\" , \"display\" : \"Vegetable\" } ], \"text\" : \"Regular, Chopped Meat\" } } ] } } }, { \"resource\" :{ \"resourceType\" : \"MedicationOrder\" , \"id\" : \"smart-MedicationOrder-103\" , \"status\" : \"draft\" , \"patient\" :{ \"reference\" : \"Patient/1288992\" }, \"medicationCodeableConcept\" :{ \"coding\" :[ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" } ], \"text\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }, \"dosageInstruction\" :[ { \"text\" : \"5 mL bid x 10 days\" , \"timing\" :{ \"repeat\" :{ \"boundsPeriod\" :{ \"start\" : \"2005-01-04\" }, \"frequency\" : 2 , \"period\" : 1 , \"periodUnits\" : \"d\" } }, \"doseQuantity\" :{ \"value\" : 5 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" } } ], \"dispenseRequest\" :{ \"numberOfRepeatsAllowed\" : 1 , \"quantity\" :{ \"value\" : 1 , \"unit\" : \"mL\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"mL\" }, \"expectedSupplyDuration\" :{ \"value\" : 10 , \"unit\" : \"days\" , \"system\" : \"http://unitsofmeasure.org\" , \"code\" : \"d\" } } } } ] } }","title":"Example (DSTU2)"},{"location":"hooks/order-sign/#change-log","text":"Version Description 1.0 Initial Release 1.0.1 Add DeviceRequest to list of order resources for R4. 1.1.0 Updated hook to all for use in order-revision situations","title":"Change Log"},{"location":"hooks/patient-view/","text":"patient-view \u00b6 Info This page defines a workflow hook for the purpose of providing clinical decision support using CDS Hooks. This is a build at the level of Trial Use . Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 5 - Mature Workflow \u00b6 The user has just opened a patient's record; typically called only once at the beginning of a user's interaction with a specific patient's record. Context \u00b6 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. Must be in the format [ResourceType]/[id] . For this hook, the user is expected to be of type Practitioner , PractitionerRole , Patient , or RelatedPerson . Patient or RelatedPerson are appropriate when a patient or their proxy are viewing the record. For example, Practitioner/abc or Patient/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 \u00b6 1 2 3 4 \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" } 1 2 3 4 5 \"context\" :{ \"userId\" : \"Practitioner/abc\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" } Change Log \u00b6 Version Description 1.0 Initial Release","title":"patient-view 5"},{"location":"hooks/patient-view/#patient-view","text":"Info This page defines a workflow hook for the purpose of providing clinical decision support using CDS Hooks. This is a build at the level of Trial Use . Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 5 - Mature","title":"patient-view"},{"location":"hooks/patient-view/#workflow","text":"The user has just opened a patient's record; typically called only once at the beginning of a user's interaction with a specific patient's record.","title":"Workflow"},{"location":"hooks/patient-view/#context","text":"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. Must be in the format [ResourceType]/[id] . For this hook, the user is expected to be of type Practitioner , PractitionerRole , Patient , or RelatedPerson . Patient or RelatedPerson are appropriate when a patient or their proxy are viewing the record. For example, Practitioner/abc or Patient/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","title":"Context"},{"location":"hooks/patient-view/#examples","text":"1 2 3 4 \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" } 1 2 3 4 5 \"context\" :{ \"userId\" : \"Practitioner/abc\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" }","title":"Examples"},{"location":"hooks/patient-view/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"hooks/template/","text":"hook-name-expressed-as-noun-verb \u00b6 Info This page defines a workflow hook for the purpose of providing clinical decision support using CDS Hooks. This is a build | snapshot | ballot | release at the level of Draft | Trial Use | Normative | Informative | Deprecated Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 0 - Draft Workflow \u00b6 Describe when the hook occurs in a workflow. Hook creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion amongst implementers. The hook name should take the form noun-verb , such as encounter-start , or order-select according to the Hook Definition Format . Context \u00b6 Define context values that are available when this hook occurs, and indicate whether they must be provided, and whether they are available for parameterizing prefetch templates. Field Optionality Prefetch Token Type Description exampleId REQUIRED Yes string Describe the context value encounterId OPTIONAL Yes string Describe the context value Examples \u00b6 1 2 3 \"context\" :{ \"patientId\" : \"1288992\" } 1 2 3 4 \"context\" :{ \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" } Change Log \u00b6 Version Description 1.0 Initial Release","title":"new-hook-template"},{"location":"hooks/template/#hook-name-expressed-as-noun-verb","text":"Info This page defines a workflow hook for the purpose of providing clinical decision support using CDS Hooks. This is a build | snapshot | ballot | release at the level of Draft | Trial Use | Normative | Informative | Deprecated Metadata Value specificationVersion 1.0 hookVersion 1.0 hookMaturity 0 - Draft","title":"hook-name-expressed-as-noun-verb"},{"location":"hooks/template/#workflow","text":"Describe when the hook occurs in a workflow. Hook creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion amongst implementers. The hook name should take the form noun-verb , such as encounter-start , or order-select according to the Hook Definition Format .","title":"Workflow"},{"location":"hooks/template/#context","text":"Define context values that are available when this hook occurs, and indicate whether they must be provided, and whether they are available for parameterizing prefetch templates. Field Optionality Prefetch Token Type Description exampleId REQUIRED Yes string Describe the context value encounterId OPTIONAL Yes string Describe the context value","title":"Context"},{"location":"hooks/template/#examples","text":"1 2 3 \"context\" :{ \"patientId\" : \"1288992\" } 1 2 3 4 \"context\" :{ \"patientId\" : \"1288992\" , \"encounterId\" : \"456\" }","title":"Examples"},{"location":"hooks/template/#change-log","text":"Version Description 1.0 Initial Release","title":"Change Log"},{"location":"specification/current/","text":"Current (draft) This is the continuous integration, community release of the CDS Hooks specification. All stable releases are available at https://cds-hooks.hl7.org . Overview \u00b6 The CDS Hooks specification describes the RESTful APIs and interactions using JSON over HTTPS to integrate Clinical Decision Support (CDS) between CDS Clients (typically Electronic Health Record Systems (EHRs) or other health information systems) and CDS Services. Conformance Language \u00b6 The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this specification are to be interpreted as described in RFC2119 . Further, the key word \"CONDITIONAL\" indicates that a particular item is either REQUIRED or OPTIONAL, based upon another item. Use of JSON \u00b6 All data exchanged through production RESTful APIs MUST be sent and received as JSON (JavaScript Object Notation) structures and are transmitted over HTTPS. See Security and Safety section. Null and empty JSON elements JSON elements SHALL NOT be null, unless otherwise specified. JSON elements SHALL NOT be empty, unless otherwise specified (e.g. to indicate no guidance with an empty array of cards in the CDS Hooks response). If a JSON attribute is defined as OPTIONAL, and does not have a value, implementers MUST omit it. For instance, OPTIONAL JSON string and array attributes are omitted rather than having a null or empty value. Unless otherwise specified, JSON attribute values SHALL NOT be null or empty, so null , \"\" , [] , or {} are prohibited. If a JSON attribute is defined with as OPTIONAL, and does not have a value, implementers SHALL omit it. CDS Hooks Anatomy \u00b6 This specification describes a \"hook\" -based pattern for invoking decision support from within a clinician's workflow. The API supports: Synchronous, workflow-triggered CDS calls returning information and suggestions Launching a web page to provide additional information to the user Launching a user-facing SMART app when CDS requires additional interaction The main concepts of the specification are Services, CDS Clients, and Cards. CDS Services \u00b6 A CDS Service is a service that provides recommendations and guidance through the RESTful APIs described by this specification. The primary APIs are Discovery , which allows a CDS Developer to publish the types of CDS Services it provides. The Service API that CDS Clients use to request decision support. The Feedback API through which services learn the outcomes of their recommendations and guidance. CDS Clients \u00b6 A CDS Client is an Electronic Health Record (EHR), or other clinical information system that uses decision support by calling CDS Services at specific points in the application's workflow called hooks . Each hook defines the hook context (contextual information available within the CDS Client and specific to the workflow) that is provided as part of the request. Each service advertises which hooks it supports and what prefetch data (information needed by the CDS Service to determine what decision support should be presented) it requires. In addition, CDS Clients typically provide the FHIR resource server location and associated authorization information as part of the request to enable services to request additional information. Cards \u00b6 Decision support is then returned to the CDS Client in the form of cards , which the CDS Client MAY display to the end-user as part of their workflow. Cards may be informational, or they may provide suggestions that the user may accept or reject they may provide a link to additional information or even launch a SMART app when additional user interaction is required. Discovery \u00b6 A CDS Service is discoverable via a stable endpoint by CDS Clients. The Discovery endpoint includes information such as a description of the CDS Service, when it should be invoked, and any data that is requested to be prefetched. A CDS Service provider exposes its discovery endpoint at: 1 { baseURL } /cds-services HTTP Request \u00b6 The Discovery endpoint SHALL always be available at {baseUrl}/cds-services . For example, if the baseUrl is https://example.com, the CDS Client can retrieve the list of CDS Services by invoking: GET https://example.com/cds-services Response \u00b6 The response to the discovery endpoint SHALL be an object containing a list of CDS Services. Field Description services array . An array of CDS Services . If your CDS server hosts no CDS Services, the discovery endpoint should return a 200 HTTP response with an empty array of services. Each CDS Service SHALL be described by the following attributes. Field Optionality Type Description hook REQUIRED string The hook this service should be invoked on. See Hooks . title RECOMMENDED string The human-friendly name of this service. description REQUIRED string The description of this service. id REQUIRED string The {id} portion of the URL to this service which is available at {baseUrl}/cds-services/{id} prefetch OPTIONAL object An object containing key/value pairs of FHIR queries that this service is requesting the CDS Client to perform and provide on each service call. The key is a string that describes the type of data being requested and the value is a string representing the FHIR query. See Prefetch Template . usageRequirements OPTIONAL string Human-friendly description of any preconditions for the use of this CDS Service. Note that a CDS server can host multiple entries of CDS service with the same id for different hook s. This allows a service to update its advice based on changes in workflow as discussed in update stale guidance . HTTP Status Codes \u00b6 Code Description 200 OK A successful response. CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes. Discovery Example \u00b6 1 curl \"https://example.com/cds-services\" The above command returns JSON structured like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 { \"services\" : [ { \"hook\" : \"patient-view\" , \"title\" : \"Static CDS Service Example\" , \"description\" : \"An example of a CDS Service that returns a static set of cards\" , \"id\" : \"static-patient-greeter\" , \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } }, { \"hook\" : \"order-select\" , \"title\" : \"Order Echo CDS Service\" , \"description\" : \"An example of a CDS Service that simply echoes the order(s) being placed\" , \"id\" : \"order-echo\" , \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" , \"medications\" : \"MedicationRequest?patient={{context.patientId}}\" } }, { \"hook\" : \"order-sign\" , \"title\" : \"Pharmacogenomics CDS Service\" , \"description\" : \"An example of a more advanced, precision medicine CDS Service\" , \"id\" : \"pgx-on-order-sign\" , \"usageRequirements\" : \"Note: functionality of this CDS Service is degraded without access to a FHIR Restful API as part of CDS recommendation generation.\" } ] } Calling a CDS Service \u00b6 HTTP Request \u00b6 A CDS Client SHALL call a CDS Service by POST ing a JSON document to the service as described in this section. The CDS Service endpoint can be constructed from the CDS Service base URL and an individual service id as {baseUrl}/cds-services/{service.id} . CDS Clients may add additional requirements for the triggering of a hook, based upon the user, workflow, CDS Service or other reasons (e.g. if the service is provided by a payer, the patient has active coverage with that payer). See Trusting CDS Services for additional considerations. The request SHALL include a JSON POST body with the following input fields: Field Optionality Type Description hook REQUIRED string The hook that triggered this CDS Service call. See Hooks . hookInstance REQUIRED string A universally unique identifier (UUID) for this particular hook call (see more information below). fhirServer CONDITIONAL URL The base URL of the CDS Client's FHIR server. If fhirAuthorization is provided, this field is REQUIRED. The scheme MUST be https when production data is exchanged. fhirAuthorization OPTIONAL object A structure holding an 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 section for more information. context REQUIRED object Hook-specific contextual data that the CDS service will need. For example, with the patient-view hook this will include the FHIR id of the Patient being viewed. For details, see the Hooks specific specification page (example: patient-view ). prefetch OPTIONAL object The FHIR data that was prefetched by the CDS Client (see more information below). hookInstance \u00b6 While working in the CDS Client, a user can perform multiple actions in series or in parallel. For example, a clinician might prescribe two drugs in a row; each prescription action would be assigned a unique hookInstance . This allows a CDS Service to uniquely identify each hook invocation. Note: the hookInstance is globally unique and should contain enough entropy to be un-guessable. Example \u00b6 1 2 3 4 5 curl -X POST \\ -H 'Content-type: application/json' \\ --data @hook-details-see-example-below \"https://example.com/cds-services/static-patient-greeter\" 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://hooks.smarthealthit.org:9080\" , \"hook\" : \"patient-view\" , \"fhirAuthorization\" : { \"access_token\" : \"some-opaque-fhir-access-token\" , \"token_type\" : \"Bearer\" , \"expires_in\" : 300 , \"scope\" : \"user/Patient.read user/Observation.read\" , \"subject\" : \"cds-service4\" }, \"context\" : { \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" }, \"prefetch\" : { \"patientToGreet\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1925-12-23\" , \"id\" : \"1288992\" , \"active\" : true } } } Providing FHIR Resources to a CDS Service \u00b6 CDS Services require specific FHIR resources in order to compute the recommendations the CDS Client requests. If real-world performance were no issue, a CDS Client could launch a CDS Service passing only context data (such as the current user and patient ids), and the CDS Service could obtain authorization to access the CDS Client's FHIR API, retrieving any resources required via FHIR read or search interactions. Given that CDS Services SHOULD respond quickly (on the order of 500 ms.), this specification defines mechanisms that allow a CDS Service to request and obtain FHIR resources more efficiently. Two optional methods are provided. In the first method, FHIR resources MAY be obtained by passing \"prefetched\" data from the CDS Client to the CDS Service in the service call. If data is to be prefetched, the CDS Service registers a set of \"prefetch templates\" with the CDS Client, as described in the Prefetch Template section below. These \"prefetch templates\" are defined in the CDS Service discovery response . The FHIR resources are passed as key-value pairs, with each key matching a key described in the discovery response, and each value being a FHIR resource. Note that in the case of searches, this resource may be a searchset Bundle. The second method enables the CDS Service to retrieve FHIR resources for itself, without the need to request and obtain its own authorization. If the CDS Client decides to have the CDS Service fetch its own FHIR resources, the CDS Client obtains and passes directly to the CDS Service a bearer token issued for the CDS Service's use in executing FHIR API calls against the CDS Client's FHIR server to obtain the required resources. Some CDS Clients MAY pass prefetched data, along with a bearer token for the CDS Service to use if additional resources are required. Each CDS Client SHOULD decide which approach, or combination, is preferred, based on performance considerations and assessment of attendant security and safety risks. CDS Services should be capable of accessing FHIR resources via either prefetch or from the CDS Client's FHIR server. For more detail, see the FHIR Resource Access section below. Similarly, each CDS Client will decide what FHIR resources to authorize and to prefetch, based on the CDS Service discovery response's \"prefetch\" request and on the provider's assessment of the \"minimum necessary.\" The CDS Client provider and the CDS Service provider will negotiate the set of FHIR resources to be provided, and how these data will be provided, as part of their service agreement. Prefetch Template \u00b6 A prefetch template is a FHIR read or search request that describes relevant data needed by the CDS Service. For example, the following is a prefetch template for hemoglobin A1c observations: 1 Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date To allow for prefetch templates that are dependent on the workflow context, prefetch templates may include references to context using prefetch tokens . In the above example, {{context.patientId}} is a prefetch token. The prefetch field of a CDS Service discovery response defines the set of prefetch templates for that service, providing a prefetch key for each one that is used to identify the prefetch data in the CDS request. For example: 1 2 3 4 5 { \"prefetch\" : { \"hemoglobin-a1c\" : \"Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date\" } } In this prefetch , hemoglobin-a1c is the prefetch key for this prefetch template. For a complete worked example, see below . A CDS Client MAY choose to honor zero, some, or all of the desired prefetch templates, and is free to choose the most appropriate source for these data. For example: The CDS Client MAY have some of the desired prefetched data already in memory, thereby removing the need for any network call The CDS Client MAY compute an efficient set of prefetch templates from multiple CDS Services, thereby reducing the number of calls to a minimum The CDS Client MAY satisfy some of the desired prefetched templates via some internal service or even its own FHIR server. The CDS Client SHALL only provide access to resources that are within the user's authorized scope. As part of preparing the request, a CDS Client processes each prefetch template it intends to satisfy by replacing the prefetch tokens in the prefetch template to construct a relative FHIR request URL. This specification is not prescriptive about how this request is actually processed. The relative URL may be appended to the base URL for the CDS Client's FHIR server and directly invoked, or the CDS Client may use internal infrastructure to satisfy the request in the same way that invoking against the FHIR server would. Regardless of how the CDS Client satisfies the prefetch templates (if at all), the prefetched data given to the CDS Service MUST be equivalent to the data the CDS Service would receive if it were making its own call to the CDS Client's FHIR server using the parameterized prefetch template. Note that this means that CDS services will receive only the information they have requested and are authorized to receive. Prefetch data for other services registered to the same hook MUST NOT be provided. In other words, services SHALL only receive the data they requested in their prefetch. The resulting response is passed along to the CDS Service using the prefetch parameter (see below . Note that a CDS Client MAY paginate prefetch results. The intent of allowing pagination is to ensure that prefetch queries that may be too large for a single payload can still be retrieved by the service. The decision to paginate and the size of pages is entirely at the CDS Client's discretion. CDS Clients are encouraged to only use pagination when absolutely necessary, keeping performance and user experience in mind. The CDS Client MUST NOT send any prefetch template key that it chooses not to satisfy. If the CDS Client encounters errors prefetching the requested data, OperationOutcome(s) SHOULD be used to communicate those errors to prevent the CDS Service from incurring an unneeded follow-up query. CDS Clients MUST omit the prefetch key if relevant details cannot be provided (e.g. intermittent connectivity issues). CDS Services SHOULD check any prefetched data for the existence of OperationOutcomes. If the CDS Client has no data to populate a template prefetch key, the prefetch template key MUST have a value of null . Note that the null result is used rather than a bundle with zero entries to account for the possibility that the prefetch url is a single-resource request. It is the CDS Service's responsibility to check prefetched data against its template to determine what requests were satisfied (if any) and to programmatically retrieve any additional necessary data. If the CDS Service is unable to obtain required data because it cannot access the FHIR server and the request did not contain the necessary prefetch keys, the service SHALL respond with an HTTP 412 Precondition Failed status code. Prefetch tokens \u00b6 A prefetch token is a placeholder in a prefetch template that is replaced by information from the hook's context to construct the FHIR URL used to request the prefetch data. Prefetch tokens MUST be delimited by {{ and }} , and MUST contain only the qualified path to a hook context field or one of the following user identifiers: userPractitionerId , userPractitionerRoleId , userPatientId , or userRelatedPersonId . 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 example, {{context.medication.id}} is not a valid prefetch token because it attempts to access the id field of the medication field. Prefetch tokens identifying the user \u00b6 A prefetch template enables a CDS Service to learn more about the current user through a FHIR read, like so: 1 2 3 4 5 { \"prefetch\": { \"user\": \"{{context.userId}}\" } } or though a FHIR search: 1 2 3 4 5 { \"prefetch\": { \"user\": \"PractitionerRole?_id={{userPractitionerRoleId}}&_include=PractitionerRole:practitioner\" } } A prefetch template may include any of the following prefetch tokens: Token Description {{userPractitionerId}} FHIR id of the Practitioner resource corresponding to the current user. {{userPractitionerRoleId}} FHIR id of the PractitionerRole resource corresponding to the current user. {{userPatientId}} FHIR id of the Patient resource corresponding to the current user. {{userRelatedPersonId}} FHIR id of the RelatedPerson resource corresponding to the current user. No single FHIR resource represents a user, rather Practitioner and PractitionerRole may be jointly used to represent a provider, and Patient or RelatedPerson are used to represent a patient or their proxy. Hook definitions typically define a context.userId field and corresponding prefetch token. Prefetch query restrictions \u00b6 To reduce the implementation burden on CDS Clients that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. When using this subset, valid prefetch templates MUST only make use of: instance level read interactions (for resources with known ids such as Patient , Practitioner , or Encounter ) type level search interactions; e.g. patient={{context.patientId}} Resource references (e.g. patient={{context.patientId}} ) token search parameters using equality (e.g. code=4548-4 ) and optionally the :in modifier (no other modifiers for token parameters) date search parameters on date , dateTime , instant , or Period types only, and using only the prefixes eq , lt , gt , ge , le the _count parameter to limit the number of results returned the _sort parameter to allow for most recent and first queries Example prefetch token \u00b6 Often a prefetch template builds on the contextual data associated with the hook. For example, a particular CDS Service might recommend guidance based on a patient's conditions when the chart is opened. The FHIR query to retrieve these conditions might be Condition?patient=123 . In order to express this as a prefetch template, the CDS Service must express the FHIR id of the patient as a token so that the CDS Client can replace the token with the appropriate value. When context fields are used as tokens, their token name MUST be context.name-of-the-field . For example, given a context like: 1 2 3 4 5 { \"context\" : { \"patientId\" : \"123\" } } The token name would be {{context.patientId}} . Again using our above conditions example, the complete prefetch template would be Condition?patient={{context.patientId}} . Only the first level fields in context may be considered for tokens. For example, given the following context that contains amongst other things, a MedicationRequest FHIR resource: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { \"context\" : { \"encounterId\" : \"456\" , \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"123\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }]}, \"subject\" : { \"reference\" : \"Patient/1288992\" } } } ] } } } Only the encounterId field in this example is eligible to be a prefetch token as it is a first level field and the datatype (string) can be placed into the FHIR query. The MedicationRequest.id value in the context is not eligible to be a prefetch token because it is not a first level field. If the hook creator intends for the MedicationRequest.id value to be available as a prefetch token, it must be made available as a first level field. Using the aforementioned example, we simply add a new medicationRequestId field: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 { \"context\" : { \"medicationRequestId\" : \"123\" , \"encounterId\" : \"456\" , \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"123\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }]}, \"subject\" : { \"reference\" : \"Patient/1288992\" } } } ] } } } Example prefetch templates \u00b6 1 2 3 4 5 6 7 8 { \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" , \"hemoglobin-a1c\" : \"Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date\" , \"diabetes-type2\" : \"Condition?patient={{context.patientId}}&code=44054006&category=problem-list-item&status=active\" , \"user\" : \"PractitionerRole?_id={{userPractitionerRoleId}}\" } } Here is an example prefetch field from a CDS Service discovery endpoint. The goal is to know, at call time: Key Description patient Patient demographics. hemoglobin-a1c Most recent Hemoglobin A1c reading for this patient. diabetes-type2 If the patient has an active condition of diabetes mellitus on their problem list. user Information on the current user. Example prefetch data \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 { \"prefetch\" : { \"patient\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1974-12-25\" , \"...\" : \"<snipped for brevity>\" }, \"hemoglobin-a1c\" : { \"resourceType\" : \"Bundle\" , \"type\" : \"searchset\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"Observation\" , \"code\" : { \"coding\" : [ { \"system\" : \"http://loinc.org\" , \"code\" : \"4548-4\" , \"display\" : \"Hemoglobin A1c\" } ] }, \"...\" : \"<snipped for brevity>\" } } ] }, \"user\" : \"123\" } } The CDS Hooks request is augmented to include two prefetch values, where the dictionary keys match the request keys ( patient and hemoglobin-a1c in this case). Note that the missing diabetes-type2 key indicates that either the CDS Client has decided not to satisfy this particular prefetch template or it was not able to retrieve this prefetched data. The CDS Service is responsible for retrieving the FHIR resource representing the user from the FHIR server (if required). FHIR Resource Access \u00b6 If the CDS Client provides both fhirServer and fhirAuthorization request parameters, the CDS Service MAY use the FHIR server to obtain any FHIR resources for which it's authorized, beyond those provided by the CDS Client as prefetched data. This is similar to the approach used by SMART on FHIR wherein the SMART app requests and ultimately obtains an access token from the CDS Client's Authorization server using the SMART launch workflow, as described in SMART App Launch Implementation Guide . Like SMART on FHIR, CDS Hooks requires that CDS Services present a valid access token to the FHIR server with each API call. Thus, a CDS Service requires an access token before communicating with the CDS Client's FHIR resource server. While CDS Hooks shares the underlying technical framework and standards as SMART on FHIR, the CDS Hooks workflow MUST accommodate the automated, low-latency delivery of an access token to the CDS service. With CDS Hooks, if the CDS Client wants to provide the CDS Service direct access to FHIR resources, the CDS Client creates or obtains an access token prior to invoking the CDS Service, passing this token to the CDS Service as part of the service call. This approach remains compatible with OAuth 2.0's bearer token protocol while minimizing the number of HTTPS round-trips and the service invocation latency. The CDS Client remains in control of providing an access token that is associated with the specific CDS Service, user, and context of the invocation. As the CDS Service executes on behalf of a user, the data to which the CDS Service is given access by the CDS Client MUST be limited to the same restrictions and authorizations afforded the current user. As such, the access token SHALL be scoped to: The CDS Service being invoked The current user Passing the Access Token to the CDS Service \u00b6 The access token is specified in the CDS Service request via the fhirAuthorization request parameter. This parameter is an object that contains both the access token as well as other related information as specified below. If the CDS Client chooses not to pass along an access token, the fhirAuthorization parameter is omitted. Field Optionality Type Description access_token REQUIRED string This is the OAuth 2.0 access token that provides access to the FHIR server. token_type REQUIRED string Fixed value: Bearer expires_in REQUIRED integer The lifetime in seconds of the access token. scope REQUIRED string The scopes the access token grants the CDS Service. subject REQUIRED string The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server. 'patient` CONDITIONAL string If the granted SMART scopes include patient scopes (i.e. \"patient/\"), the access token is restricted to a specific patient. This field SHOULD be populated to identify the FHIR id of that patient. The scopes granted to the CDS Service via the scope field are defined by the SMART on FHIR specification . The expires_in value is established by the authorization server and SHOULD BE very short lived, as the access token MUST be treated as a transient value by the CDS Service. CDS Clients SHOULD revoke an issued access token upon the completion of the CDS Hooks request/response to limit the validity period of the token. Below is an example fhirAuthorization parameter: 1 2 3 4 5 6 7 8 9 { \"fhirAuthorization\" : { \"access_token\" : \"some-opaque-fhir-access-token\" , \"token_type\" : \"Bearer\" , \"expires_in\" : 300 , \"scope\" : \"user/Patient.read user/Observation.read\" , \"subject\" : \"cds-service4\" } } CDS Service Response \u00b6 For successful responses, CDS Services SHALL respond with a 200 HTTP response with an object containing a cards array and optionally a systemActions array as described below. Each card contains decision support guidance from the CDS Service. Cards are intended for display to an end user. The data format of a card defines a very minimal set of required attributes with several more optional attributes to suit a variety of use cases, such as: narrative informational decision support, actionable suggestions to modify data, and links to SMART apps. Note that because the CDS client may be invoking multiple services from the same hook, there may be multiple responses related to the same information. This specification does not address these scenarios specifically; both CDS Services and CDS Clients should consider the implications of multiple CDS Services in their integrations and are invited to consider card attributes when determining prioritization and presentation options. HTTP Status Codes \u00b6 Code Description 200 OK A successful response. 412 Precondition Failed The CDS Service is unable to retrieve the necessary FHIR data to execute its decision support, either through a prefetch request or directly calling the FHIR server. CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes. HTTP Response \u00b6 Field Optionality Type Description cards REQUIRED array of Cards An array of Cards . Cards can provide a combination of information (for reading), suggested actions (to be applied if a user selects them), and links (to launch an app if the user selects them). The CDS Client decides how to display cards, but this specification recommends displaying suggestions using buttons, and links using underlined text. systemActions OPTIONAL array of Actions An array of Actions that the CDS Service proposes to auto-apply. Each action follows the schema of a card-based suggestion.action . The CDS Client decides whether to auto-apply actions. If your CDS Service has no decision support for the user, your service should return a 200 HTTP response with an empty array of cards, for example: 1 2 3 { \"cards\" : [] } Clients SHOULD remove cards returned by previous invocations of a hook to a service with the same id when a new hook is triggered (see update stale guidance ). Card Attributes \u00b6 Each Card is described by the following attributes. Field Optionality Type Description uuid OPTIONAL string Unique identifier of the card. MAY be used for auditing and logging cards and SHALL be included in any subsequent calls to the CDS service's feedback endpoint. summary REQUIRED string One-sentence, <140-character summary message for display to the user inside of this card. detail OPTIONAL string Optional detailed information to display; if provided MUST be represented in (GitHub Flavored) Markdown . (For non-urgent cards, the CDS Client MAY hide these details until the user clicks a link like \"view more details...\"). indicator REQUIRED string Urgency/importance of what this card conveys. Allowed values, in order of increasing urgency, are: info , warning , critical . The CDS Client MAY use this field to help make UI display decisions such as sort order or coloring. source REQUIRED object Grouping structure for the Source of the information displayed on this card. The source should be the primary source of guidance for the decision support the card represents. suggestions OPTIONAL array of Suggestions Allows a service to suggest a set of changes in the context of the current activity (e.g. changing the dose of a medication currently being prescribed, for the order-sign activity). If suggestions are present, selectionBehavior MUST also be provided. selectionBehavior CONDITIONAL string Describes the intended selection behavior of the suggestions in the card. Allowed values are: at-most-one , indicating that the user may choose none or at most one of the suggestions; any , indicating that the end user may choose any number of suggestions including none of them and all of them. CDS Clients that do not understand the value MUST treat the card as an error. overrideReasons OPTIONAL array of Coding Override reasons can be selected by the end user when overriding a card without taking the suggested recommendations. The CDS service MAY return a list of override reasons to the CDS client. If override reasons are present, the CDS Service MUST populate a display value for each reason's Coding . The CDS Client SHOULD present these reasons to the clinician when they dismiss a card. A CDS Client MAY augment the override reasons presented to the user with its own reasons. links OPTIONAL array of Links Allows a service to suggest a link to an app that the user might want to run for additional information or to help guide a decision. Source \u00b6 The Source is described by the following attributes. Field Optionality Type Description label REQUIRED string A short, human-readable label to display for the source of the information displayed on this card. If a url is also specified, this MAY be the text for the hyperlink. url OPTIONAL URL An optional absolute URL to load (via GET , in a browser context) when a user clicks on this link to learn more about the organization or data set that provided the information on this card. Note that this URL should not be used to supply a context-specific \"drill-down\" view of the information on this card. For that, use card.link.url instead. icon OPTIONAL URL An absolute URL to an icon for the source of this card. The icon returned by this URL SHOULD be a 100x100 pixel PNG image without any transparent regions. The CDS Client may ignore or scale the image during display as appropriate for user experience. topic OPTIONAL Coding A topic describes the content of the card by providing a high-level categorization that can be useful for filtering, searching or ordered display of related cards in the CDS client's UI. This specification does not prescribe a standard set of topics. Below is an example source parameter: 1 2 3 4 5 6 7 8 9 10 11 12 { \"source\" : { \"label\" : \"Zika Virus Management\" , \"url\" : \"https://example.com/cdc-zika-virus-mgmt\" , \"icon\" : \"https://example.com/cdc-zika-virus-mgmt/100.png\" , \"topic\" : { \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/topics\" , \"code\" : \"12345\" , \"display\" : \"Mosquito born virus\" } } } Suggestion \u00b6 Each Suggestion is described by the following attributes. Field Optionality Type Description label REQUIRED string Human-readable label to display for this suggestion (e.g. the CDS Client might render this as the text on a button tied to this suggestion). uuid OPTIONAL string Unique identifier, used for auditing and logging suggestions. isRecommended OPTIONAL boolean When there are multiple suggestions, allows a service to indicate that a specific suggestion is recommended from all the available suggestions on the card. CDS Hooks clients may choose to influence their UI based on this value, such as pre-selecting, or highlighting recommended suggestions. Multiple suggestions MAY be recommended, if card.selectionBehavior is any . actions OPTIONAL array of Actions Array of objects, each defining a suggested action. Within a suggestion, all actions are logically AND'd together, such that a user selecting a suggestion selects all of the actions within it. When a suggestion contains multiple actions, the actions SHOULD be processed as per FHIR's rules for processing transactions with the CDS Client's fhirServer as the base url for the inferred full URL of the transaction bundle entries. (Specifically, deletes happen first, then creates, then updates). Action \u00b6 Each Action is described by the following attributes. Field Optionality Type Description type REQUIRED string The type of action being performed. Allowed values are: create , update , delete . description REQUIRED string Human-readable description of the suggested action MAY be presented to the end-user. resource CONDITIONAL object A FHIR resource. When the type attribute is create , the resource attribute SHALL contain a new FHIR resource to be created. For update , this holds the updated resource in its entirety and not just the changed fields. Use of this field to communicate a string of a FHIR id for delete suggestions is DEPRECATED and resourceId SHOULD be used instead. resourceId CONDITIONAL string A relative reference to the relevant resource. SHOULD be provided when the type attribute is delete . The following example illustrates a create action: 1 2 3 4 5 6 7 8 9 { \"type\" : \"create\" , \"description\" : \"Create a prescription for Acetaminophen 250 MG\" , \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"medrx001\" , \"...\" : \"<snipped for brevity>\" } } The following example illustrates an update action: 1 2 3 4 5 6 7 8 9 { \"type\" : \"update\" , \"description\" : \"Update the order to record the appropriateness score\" , \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"procedure-request-1\" , \"...\" : \"<snipped for brevity>\" } } The following example illustrates a delete action: 1 2 3 4 5 { \"type\" : \"delete\" , \"description\" : \"Remove the inappropriate order\" , \"resourceId\" : \"ServiceRequest/procedure-request-1\" } Reasons for rejecting a card \u00b6 overrideReasons is an array of Coding that captures a codified set of reasons an end user may select from as the rejection reason when rejecting the advice presented in the card. When using the coding object to represent a reason, CDS Services MUST provide a human readable text in the display property and CDS Clients MAY incorporate it into their user interface. This specification does not prescribe a standard set of override reasons; implementers are encouraged to submit suggestions for standardization. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 { \"overrideReasons\" : [ { \"code\" : \"reason-code-provided-by-service\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Patient refused\" }, { \"code\" : \"12354\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Contraindicated\" } ] } Link \u00b6 Each Link is described by the following attributes. Field Optionality Type Description label REQUIRED string Human-readable label to display for this link (e.g. the CDS Client might render this as the underlined text of a clickable link). url REQUIRED URL URL to load (via GET , in a browser context) when a user clicks on this link. Note that this MAY be a \"deep link\" with context embedded in path segments, query parameters, or a hash. type REQUIRED string The type of the given URL. There are two possible values for this field. A type of absolute indicates that the URL is absolute and should be treated as-is. A type of smart indicates that the URL is a SMART app launch URL and the CDS Client should ensure the SMART app launch URL is populated with the appropriate SMART launch parameters. appContext OPTIONAL string An optional field that allows the CDS Service to share information from the CDS card with a subsequently launched SMART app. The appContext field should only be valued if the link type is smart and is not valid for absolute links. The appContext field and value will be sent to the SMART app as part of the OAuth 2.0 access token response, alongside the other SMART launch parameters when the SMART app is launched. Note that appContext could be escaped JSON, base64 encoded XML, or even a simple string, so long as the SMART app can recognize it. CDS Client support for appContext requires additional coordination with the authorization server that is not described or specified in CDS Hooks nor SMART. autolaunchable OPTIONAL boolean This field serves as a hint to the CDS Client suggesting this link be immediately launched, without displaying the card and without manual user interaction. Note that CDS Hooks cards which contain links with this field set to true, may not be shown to the user. Sufficiently advanced CDS Clients may support automatically launching multiple links or multiple cards. Implementer guidance is requested to determine if the specification should preclude these advanced scenarios. Considerations for autolaunchable and user experience \u00b6 The intent of this optional feature is to improve individual user experience by removing the otherwise unnecessary click of a link by the user. Appropriate support of this feature includes guardrails from both the CDS Service developer and the CDS Client, as well as additional local control by the organization using the service. The CDS Client ultimately determines if a link can be automatically launched, taking into consideration user interface needs, workflow considerations, or even absence of support for this optional feature. If a CDS Hooks response contains guidance in addition to an autolaunchable link, it's the CDS Service's responsibility to ensure that any decision support that exists in the CDS Hooks response's card(s) is communicated via the launched app. System Action \u00b6 A systemAction is the same Action which may be returned in a suggestion, but is instead returned alongside the array of cards. A systemAction is not presented to the user within a card, but rather may be auto-applied without user intervention. 1 2 3 4 5 6 7 8 9 10 11 12 13 { \"cards\" : [], \"systemActions\" : [ { \"type\" : \"update\" , \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"...\" : \"<snipped for brevity\" } } ] } Example \u00b6 Example response 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 { \"cards\" : [ { \"uuid\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"summary\" : \"Example Card\" , \"indicator\" : \"info\" , \"detail\" : \"This is an example card.\" , \"source\" : { \"label\" : \"Static CDS Service Example\" , \"url\" : \"https://example.com\" , \"icon\" : \"https://example.com/img/icon-100px.png\" }, \"links\" : [ { \"label\" : \"Google\" , \"url\" : \"https://google.com\" , \"type\" : \"absolute\" }, { \"label\" : \"Github\" , \"url\" : \"https://github.com\" , \"type\" : \"absolute\" }, { \"label\" : \"SMART Example App\" , \"url\" : \"https://smart.example.com/launch\" , \"type\" : \"smart\" , \"appContext\" : \"{\\\"session\\\":3456356,\\\"settings\\\":{\\\"module\\\":4235}}\" } ] }, { \"summary\" : \"Another card\" , \"indicator\" : \"warning\" , \"source\" : { \"label\" : \"Static CDS Service Example\" }, \"overrideReasons\" : [ { \"code\" : \"reason-code-provided-by-service\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Patient refused\" }, { \"code\" : \"12354\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Contraindicated\" } ] } ] } Example response using autolaunchable 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { \"cards\" : [ { \"uuid\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"summary\" : \"Lung cancer screening shared decision making\" , \"detail\" : \"Patient is a current smoker with a 20 pack/year history. Consider advising patient to complete lung cancer screening. The Lung Cancer Screening Shared Decision Making App (LCSSDM) has been proven to increase patient followthrough for screening.\" , \"source\" : { \"label\" : \"Lung Cancer Screening Shared Decision Making App\" , \"url\" : \"https://example.com/LCS\" , \"icon\" : \"https://example.com/img/icon-100px.png\" }, \"links\" : [ { \"label\" : \"Github\" , \"url\" : \"https://github.com\" , \"type\" : \"absolute\" , \"autolaunchable\" : true } ] } ] } Feedback \u00b6 Once a CDS Hooks Service responds to a hook by returning a card, the service has no further interaction with the CDS Client. The acceptance of a suggestion or rejection of a card is valuable information to enable a service to improve its behavior towards the goal of the end-user having a positive and meaningful experience with the CDS. A feedback endpoint enables suggestion tracking & analytics. A CDS Service MAY support a feedback endpoint; a CDS Client SHOULD be capable of sending feedback. Upon receiving a card, a user may accept its suggestions, ignore it entirely, or dismiss it with or without an override reason. Note that while one or more suggestions can be accepted, an entire card is either ignored or overridden. Typically, an end user may only accept (a suggestion), or override a card once; however, a card once ignored could later be acted upon. CDS Hooks does not specify the UI behavior of CDS Clients, including the persistence of cards. CDS Clients should faithfully report each of these distinct end-user interactions as feedback. A CDS Client provides feedback by POSTing a JSON document. The feedback endpoint can be constructed from the CDS Service endpoint and a path segment of \"feedback\" as {baseUrl}/cds-services/{service.id}/feedback. The request to the feedback endpoint SHALL be an object containing an array. Field Description feedback array of Feedback Each Feedback SHALL be described by the following attributes. Field Optionality Type Description card REQUIRED string The card.uuid from the CDS Hooks response. Uniquely identifies the card. outcome REQUIRED string A value of accepted or overridden . acceptedSuggestions CONDITIONAL array An array of json objects identifying one or more of the user's AcceptedSuggestion s. Required for accepted outcomes. overrideReason OPTIONAL OverrideReason A json object capturing the override reason as a Coding as well as any comments entered by the user. outcomeTimestamp REQUIRED string ISO8601 representation of the date and time in Coordinated Universal Time (UTC) when action was taken on the card, as profiled in section 5.6 of RFC3339 . e.g. 1985-04-12T23:20:50.52Z Suggestion accepted \u00b6 The CDS Client can inform the service when one or more suggestions were accepted by POSTing a simple JSON object. The CDS Client authenticates to the CDS service as described in Trusting CDS Clients . Upon the user accepting a suggestion (perhaps when she clicks a displayed label (e.g., button) from a \"suggestion\" card), the CDS Client informs the service by posting the card and suggestion uuid s to the CDS Service's feedback endpoint with an outcome of accepted . To enable a positive clinical experience, the feedback endpoint may be called for multiple hook instances or multiple cards at the same time or even multiple times for a card or suggestion. Depending upon the UI and workflow of the CDS Client, a CDS Service may receive feedback for the same card instance multiple times. Each AcceptedSuggestion is described by the following attributes. Field Optionality Type Description id REQUIRED string The card.suggestion.uuid from the CDS Hooks response. Uniquely identifies the suggestion that was accepted. Example suggestion accepted \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" : [ { \"card\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"outcome\" : \"accepted\" , \"acceptedSuggestions\" : [ { \"id\" : \"e56e1945-20b3-4393-8503-a1a20fd73152\" } ], \"outcomeTimestamp\" : \"2021-12-11T10:05:31Z\" } ] } If either the card or the suggestion has no uuid , the CDS Client does not send a notification. Card ignored \u00b6 If the end-user doesn't interact with the CDS Service's card at all, the card is ignored . In this case, the CDS Client does not inform the CDS Service of the rejected guidance. Even with a card.uuid , a suggestion.uuid , and an available feedback service, the service is not informed (in part, because it may later be acted upon). Overridden guidance \u00b6 A CDS Client may enable the end user to override guidance without providing an explicit reason for doing so. The CDS Client can inform the service when a card was dismissed by specifying an outcome of overridden without providing an overrideReason . This may occur, for example, when the end user viewed the card and dismissed it without providing a reason why. Example overridden guidance without overrideReason \u00b6 1 2 3 4 5 6 7 8 9 10 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" : [ { \"card\" : \"f6b95768-b1c8-40dc-8385-bf3504b82ffb\" , // uuid from `card.uuid` \"outcome\" : \"overridden\" , \"outcomeTimestamp\" : \"2020-12-11T00:00:00Z\" } ] } Explicit reject with override reasons \u00b6 A CDS Client can inform the service when a card was rejected by POSTing an outcome of overridden along with an overrideReason to the service's feedback endpoint. The CDS Client may enable the clinician to provide an additional overrideReason or to supplement the overrideReason with a free text comment, supplied to the CDS Service in overrideReason.userComment . OverrideReason \u00b6 Each OverrideReason is described by the following attributes, in the feedback POST to the CDS Service. Field Optionality Type Description reason CONDITIONAL Coding The Coding object representing the override reason selected by the end user. Required if user selected an override reason from the list of reasons provided in the Card (instead of only leaving a userComment). userComment OPTIONAL string The CDS Client may enable the clinician to further explain why the card was rejected with free text. That user comment may be communicated to the CDS Service as a userComment . Example overridden guidance with overrideReason \u00b6 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" :[ { \"card\" : \"9368d37b-283f-44a0-93ea-547cebab93ed\" , \"outcome\" : \"overridden\" , \"overrideReason\" :{ \"reason\" :{ \"code\" : \"d7ecf885\" , \"system\" : \"https://example.com/cds-hooks/override-reason-system\" }, \"userComment\" : \"A comment entered by the clinician.\" }, \"outcomeTimestamp\" : \"2020-12-11T00:00:00Z\" } ] } Security and Safety \u00b6 All data exchanged through the RESTful APIs MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in RFC2818 . Security and safety risks associated with the CDS Hooks API include: The risk that confidential information and privileged authorizations transmitted between a CDS Client and a CDS Service could be surreptitiously intercepted by an attacker; The risk that an attacker masquerading as a legitimate CDS Service could receive confidential information or privileged authorizations from a CDS Client, or could provide to a CDS Client decision support recommendations that could be harmful to a patient; The risk that an attacker masquerading as a legitimate service-subscribing CDS Client (i.e., man-in-the-middle) could intercept and possibly alter data exchanged between the two parties. The risk that a CDS Service could embed dangerous suggestions or links to dangerous apps in Cards returned to a CDS Client. The risk that a CDS Hooks browser-based deployment could be victimized by a Cross-Origin Resource Sharing (CORS) attack. The risk that a CDS Service could return a decision based on outdated patient data, resulting in a safety risk to the patient. CDS Hooks defines a security model that addresses these risks by assuring that the identities of both the CDS Service and the CDS Client are authenticated to each other; by protecting confidential information and privileged authorizations shared between a CDS Client and a CDS Service; by recommending means of assuring data freshness; and by incorporating business mechanisms through which trust is established and maintained between a CDS Client and a CDS Service. As with any access to protected patient information, systems should ensure that they have appropriate authorization and audit mechanisms in place to support transparency of use of the data. For more information, refer to Security Best Practices . Trusting CDS Services \u00b6 Prior to enabling CDS Clients to request decision support from any CDS Service, the CDS Client vendor and/or provider organization is expected to perform due diligence on the CDS Service provider. Each CDS Client vendor/provider is individually responsible for determining the suitability, safety and integrity of the CDS Services it uses, based on the organization's own risk-management strategy. Each CDS Client vendor/provider SHOULD maintain an \"allow list\" (and/or \"deny list\") of the CDS Services it has vetted, and the Card links that have been deemed safe to display from within the CDS Client context. Each provider organization is expected to work with its CDS Client vendor to choose what CDS Services to allow and to negotiate the conditions under which the CDS Services MAY be called. Once a CDS Service provider is selected, the CDS Client vendor/provider negotiates the terms under which service will be provided. This negotiation includes agreement on patient data elements that will be prefetched and provided to the CDS Service, the CDS Services used and the hooks that will trigger them, data elements that will be made available through an access token passed by the CDS Client, and steps the CDS Service MUST take to protect patient data and access tokens. The CDS Service can be registered with the CDS Client's authorization server, in part to define the FHIR resources that the CDS Service has authorization to access. These business arrangements are documented in the service agreement. Every interaction between a CDS Client and a CDS Service is initiated by the CDS Client sending a service request to a CDS Service endpoint protected using the Transport Layer Security protocol . Through the TLS protocol the identity of the CDS Service is authenticated, and an encrypted transmission channel is established between the CDS Client and the CDS Service. Both the Discovery endpoint and individual CDS Service endpoints are TLS secured. The CDS Client's FHIR server, using information provided by the authorization server, is responsible for enforcing restrictions on the information available to the CDS Service. Regardless of whether FHIR resources are prefetched or retrieved from the FHIR server, the CDS Client SHALL deny access to a requested resource if it is outside the user's authorized scope. If a CDS Client is satisfying prefetch requests from a CDS Service or sends a non-null fhirAuthorization object to a CDS Service so that it can call the FHIR server, the CDS Service MUST be pre-registered with the authorization server protecting access to the FHIR server. Pre-registration includes registering a client identifier, and agreeing upon the scope of FHIR access that is minimally necessary to provide the clinical decision support required. This specification does not address how the CDS Client, authorization server, and CDS Service perform this pre-registration. Trusting CDS Clients \u00b6 The service agreement negotiated between the CDS Client vendor/provider and the CDS Service provider will include obligations the CDS Client vendor/provider commits to the CDS Service provider. Some agreements MAY include the use of mutual TLS, in which both ends of the channel are authenticated. However, mutual TLS is impractical for many organizations. In the absence of mutual TLS, only the CDS Service endpoint will be authenticated because the CDS Client initiates the TLS channel set-up. To enable the CDS Service to authenticate the identity of the CDS Client, CDS Hooks uses digitally signed JSON web tokens (JWT) ( rfc7519 ). CDS Services SHOULD require authentication if invoking the service poses any risk of exposing sensitive data to the caller. Each time a CDS Client transmits a request to a CDS Service which requires authentication, the request MUST include an Authorization header presenting the JWT as a \u201cBearer\u201d token: 1 Authorization: Bearer {{JWT}} Note that this is for every single CDS Service call, whether that be a Discovery call, a single CDS Service invocation, or multiple exchanges relating to a single service. Also note that mutual TLS MAY be used alongside JSON web tokens to establish trust of the CDS Client by the CDS Service. The CDS Client MUST use its private key to digitally sign the JWT, using the JSON Web Signatures (rfc7515) standard. The JWT header contains the following fields (see rfc7515 section 4.1 for further information on these standard headers): Field Optionality Type Value alg REQUIRED string The cryptographic algorithm used to sign this JWT. kid REQUIRED string The identifier of the key-pair used to sign this JWT. This identifier MUST be unique within the CDS Client's JWK Set. typ REQUIRED string Fixed value: JWT jku OPTIONAL url The URL to the JWK Set containing the public key(s). The JWT payload contains the following fields: Field Optionality Type Value iss REQUIRED string The URI of the issuer of this JWT. Note that the JWT MAY be self-issued by the CDS Client, or MAY be issued by a third-party identity provider. aud REQUIRED string or array of string The CDS Service endpoint that is being called by the CDS Client. (See more details below). exp REQUIRED number Expiration time integer for this authentication JWT, expressed in seconds since the \"Epoch\" (1970-01-01T00:00:00Z UTC). iat REQUIRED number The time at which this JWT was issued, expressed in seconds since the \"Epoch\" (1970-01-01T00:00:00Z UTC). jti REQUIRED string A nonce string value that uniquely identifies this authentication JWT (used to protect against replay attacks). tenant OPTIONAL string An opaque string identifying the healthcare organization that is invoking the CDS Hooks request. CDS Services SHOULD limit the CDS Clients they trust by maintaining an allowlist of iss and jku urls. Per rfc7519 , the aud value is either a string or an array of strings. For CDS Hooks, this value MUST be the URL of the CDS Service endpoint being invoked. For example, consider a CDS Service available at a base URL of https://cds.example.org . When the CDS Client invokes the CDS Service discovery endpoint, the aud value is either \"https://cds.example.org/cds-services\" or [\"https://cds.example.org/cds-services\"] . Similarly, when the CDS Client invokes a particular CDS Service (say, some-service ), the aud value is either \"https://cds.example.org/cds-services/some-service\" or [\"https://cds.example.org/cds-services/some-service\"] . The CDS Client MUST make its public key, expressed as a JSON Web Key (JWK), available in a JWK Set, as defined by rfc7517 . The kid value from the JWT header allows a CDS Service to identify the correct JWK in the JWK Set that can be used to verify the signature. The CDS Client MAY make its JWK Set available via a URL identified by the jku header field, as defined by rfc7515 4.1.2 . If the jku header field is ommitted, the CDS Client and CDS Service SHALL communicate the JWK Set out-of-band. JWT Signing Algorithm \u00b6 The cryptographic signing algorithm of JWT is indicated in the alg header field. JSON Web Algorithms (rfc7518) defines several cryptographic algorithms for use in signing JWTs and should be referenced by CDS Hooks implementers. JWTs SHALL NOT be signed using the none algorithm, referred to in rfc7518 as unsecured JSON Web Signatures, as the lack of a cryptographic signature does not provide any integrity protection. Such JWTs could not be used by a CDS Service to identity the CDS Client preventing an establishment of trust. JWTs SHALL NOT be signed using any symmetric algorithm as these algorithms require the CDS Client and CDS Service to share a private key in order to verify the signature. For example, all HMAC based algorithms rely upon a shared private key and thus SHALL NOT be used to sign a JWT. When choosing an algorithm to sign their JWTs, CDS Clients SHOULD consider not only the algorithms (and key sizes) that are recommended within the security industry, but also how well those algorithms are supported in the various programming languages and libraries that may be used by CDS Services. At publication time of this specification, both ES384 and RS384 are RECOMMENDED for their regard within the larger security industry, strength, and support across popular programming languages and libraries. However, stronger and better algorithms are continually being introduced due to new threats, weaknesses, and increases in computing power. CDS Clients SHOULD continually re-evaluate their choice of an algorithm based upon these ever changing conditions. CDS Services SHOULD consider the algorithms they understand and trust based upon their tolerance for risk. Example \u00b6 An example JSON web token header, payload, and JWK set: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 // JSON Web Token Header { \"alg\" : \"ES384\" , \"typ\" : \"JWT\" , \"kid\" : \"example-kid\" , \"jku\" : \"https://fhir-ehr.example.com/jwk_uri\" } // JSON Web Token Payload { \"iss\" : \"https://fhir-ehr.example.com/\" , \"aud\" : \"https://cds.example.org/cds-services/some-service\" , \"exp\" : 1422568860 , \"iat\" : 1311280970 , \"jti\" : \"ee22b021-e1b7-4611-ba5b-8eec6a33ac1e\" , \"tenant\" : \"2ddd6c3a-8e9a-44c6-a305-52111ad302a2\" } // JSON Web Key Set (public key) // This public key is used by the CDS Service to verify the signature of the JWT { \"keys\" : [ { \"kty\" : \"EC\" , \"use\" : \"sig\" , \"crv\" : \"P-384\" , \"kid\" : \"example-kid\" , \"x\" : \"46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk\" , \"y\" : \"XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI\" , \"alg\" : \"ES384\" } ] } // JSON Web Key (private key) // This private key is used by the CDS Client to sign the JWT { \"kty\" : \"EC\" , \"d\" : \"SeFXUXda8UomZ8GFUl7HH_Oi15rIbfMcsWj9ecIsDR8kLbqsEz2CGNgwy_IcILxy\" , \"use\" : \"sig\" , \"crv\" : \"P-384\" , \"kid\" : \"example-kid\" , \"x\" : \"46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk\" , \"y\" : \"XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI\" , \"alg\" : \"ES384\" } Using the above JWT values and JWKs, the complete JWT as passed in the Authorization HTTP header would be: 1 Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6ImV4YW1wbGUta2lkIiwiamt1IjoiaHR0cHM6Ly9maGlyLWVoci5leGFtcGxlLmNvbS9qd2tfdXJpIn0.eyJpc3MiOiJodHRwczovL2ZoaXItZWhyLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vY2RzLmV4YW1wbGUub3JnL2Nkcy1zZXJ2aWNlcy9zb21lLXNlcnZpY2UiLCJleHAiOjE0MjI1Njg4NjAsImlhdCI6MTMxMTI4MDk3MCwianRpIjoiZWUyMmIwMjEtZTFiNy00NjExLWJhNWItOGVlYzZhMzNhYzFlIiwidGVuYW50IjoiMmRkZDZjM2EtOGU5YS00NGM2LWEzMDUtNTIxMTFhZDMwMmEyIn0.d1WfLjGRKlcWB94l9do4cM8REXeYJLL6SGUBO8VHZhfM8mwKYP70EMxJ67War4TQblEpaQrp11wx5p7oPFm2ETYgCicS84vXWEIYTdjooZdooCSDf2L8-i4awdoUwiEb Cross-Origin Resource Sharing \u00b6 Cross-origin resource sharing (CORS) is a World Wide Web Consortium (W3C) standard mechanism that uses additional HTTP headers to enable a web browser to gain permission to access resources from an Internet domain different from that which the browser is currently accessing. CORS is a client-side security mechanism with well-documented security risks. CDS Services and browser-based CDS Clients will require CORS support. A secure implementation guide for CORS is outside of the scope of this CDS Hooks specification. Organizations planning to implement CDS Hooks with CORS support are referred to the Cross-Origin Resource Sharing section of the OWASP HTML5 Security Cheat Sheet . Update stale guidance \u00b6 In the case that CDS Hooks cards are persisted, clients should take care to ensure that stale guidance does not negatively impact patient care. CDS Services can update their previously returned guidance by returning a new set of cards when the service is invoked based on a different hook . CDS Services indicate this intent by providing multiple CDS Services with the same id in discovery . Clients are recommended to remove cards returned by a previous invocation with the new cards . STU NOTE: We are seeking implementer feedback on how best to balance the needs of performance for implementations with the critical patient safety issues raised by the potential for stale guidance. Note that CDS Services will need to negotiate with CDS Clients to ensure that hooks that are required to ensure patient safety are supported by the CDS Client. Extensions \u00b6 The specification is not prescriptive about support for extensions. However, to support extensions, the specification reserves the name extension and will never define an element with that name, allowing implementations to use it to provide custom behavior and information. The value of an extension element MUST be a pre-coordinated JSON object. Extension structures SHOULD use a strategy for naming that ensures global uniqueness, such as reverse-domain-name notation, as in the examples below. The intention here is that anything that has broad ranging value across the community enough to be a standardized extension has broad ranging value enough to be a first class citizen rather than an extension in CDS Hooks. STU Note: We seek implementer feedback on whether the recommendation to use namespace-based unique naming in the extension specification should be made mandatory or that we consider adding a mandatory field to extensions that indicates the source/type of the extension (as is done with FHIR). For example, an extension on a request could look like this: 1 2 3 4 5 6 7 8 9 10 11 12 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://fhir.example.org:9080\" , \"hook\" : \"patient-view\" , \"context\" : { \"userId\" : \"Practitioner/example\" }, \"extension\" : { \"com.example.timestamp\" : \"2017-11-27T22:13:25Z\" , \"com.cds-hooks.sandbox.myextension-practitionerspecialty\" : \"gastroenterology\" } } As another example, an extension defined on the discovery response could look like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { \"services\" : [ { \"title\" : \"Example CDS Service Discovery\" , \"hook\" : \"patient-view\" , \"id\" : \"patientview\" , \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" }, \"description\" : \"clinical decision support for patient view\" , \"extension\" : { \"com.example.clientConformance\" : \"http://hooks.example.org/fhir/102/Conformance/patientview\" } } ] } Data Types \u00b6 CDS Hooks leverages json data types throughout. This section defines data structures re-used across the specification. Coding \u00b6 The Coding data type captures the concept of a code. A code is understood only when the given code, code-system, and a optionally a human readable display are available. This coding type is a standalone data type in CDS Hooks modeled after a trimmed down version of the FHIR Coding data type . Field Optionality Type Description code REQUIRED string The code for what is being represented system REQUIRED string The codesystem for this code . display CONDITIONAL string A short, human-readable label to display. REQUIRED for Override Reasons provided by the CDS Service, OPTIONAL for Topic . Hooks \u00b6 Overview \u00b6 As a specification, CDS Hooks does not prescribe a default or required set of hooks for implementers. Rather, the set of hooks defined here are merely a set of common use cases that were used to aid in the creation of CDS Hooks. The set of hooks defined here are not a closed set; anyone is able to define new hooks to fit their use cases and propose those hooks to the community. New hooks are proposed in a prescribed format using the documentation template by submitting a pull request for community feedback. Hooks are versioned , and mature according to the Hook Maturity Model . Note that each hook (e.g. order-select ) represents something the user is doing in the CDS Client and multiple CDS Services might respond to the same hook (e.g. a \"price check\" service and a \"prior authorization\" service might both respond to order-select ). Hook context and prefetch \u00b6 What's the difference? \u00b6 Any user workflow or action within a CDS Client will naturally include contextual information such as the current user and patient. CDS Hooks refers to this information as context and allows each hook to define the information that is available in the context. Because CDS Hooks is intended to support usage within any CDS Client, this context can contain both required and optional data, depending on the capabilities of individual CDS Clients. However, the context information is intended to be relevant to most CDS Services subscribing to the hook. For example, consider a simple patient-view hook that is invoked whenever the user views a patient's information within the CDS Client. At this point in the workflow, the contextual information would include at least the current user and the patient that is being viewed. The hook declares this as context , and passes it to the CDS Service as part of the request in the context field: 1 2 3 4 \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" } Prefetch data, on the other hand, is defined by CDS Services as a way to allow the CDS Client to provide the data that a CDS Service needs as part of the initial request to the service. When the context data relates to a FHIR resource, it is important not to conflate context and prefetch. For instance, in the hook described above for opening a patient's chart, the hook context includes the id of the patient whose chart is being opened, not the full patient FHIR resource. In this case, the FHIR id of the patient is appropriate as the CDS Services may not be interested in details from the patient resource but instead other data related to this patient. Therefore, including the full patient resource in context would be unnecessary. Alternatively, a CDS Service may need the full patient resource in certain scenarios, in which case they can fetch it as needed from the FHIR server or request it to be prefetched using a prefetch template in their discovery response, such as: 1 2 3 \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } See the section on prefetch tokens for more information on how contextual information can be used to parameterize prefetch templates. Consider another hook for when a new patient is being registered. In this case, it would likely be appropriate for the context to contain the full FHIR resource for the patient being registered as the patient may not be yet recorded in the CDS Client (and thus not available from the FHIR server) and CDS Services using this hook would predominantly be interested in the details of the patient being registered. Additionally, consider a PGX CDS Service and a Zika screening CDS Service, each of which is subscribed to the same hook. The context data specified by their shared hook should contain data relevant to both CDS Services; however, each service will have other specific data needs that will necessitate disparate prefetch requests. For instance, the PGX CDS Service likely is interested in genomics data whereas the Zika screening CDS Service will want Observations. In summary, context is specified in the hook definition to guide developers on the information available at the point in the workflow when the hook is triggered. Prefetch data is defined by each CDS Service because it is specific to the information that service needs in order to process. Hook Definition Format \u00b6 Hooks are defined in the following format. hook-name-expressed-as-noun-verb \u00b6 The name of the hook SHOULD succinctly and clearly describe the activity or event. Hook names are unique so hook creators SHOULD take care to ensure newly proposed hooks do not conflict with an existing hook name. Hook creators SHALL name their hook with reverse domain notation (e.g. org.example.patient-transmogrify ) if the hook is specific to an organization. Reverse domain notation SHALL not be used by a standard hooks catalog. When naming hooks, the name should start with the subject (noun) of the hook and be followed by the activity (verb). For example, patient-view (not view-patient ) or order-sign (not sign-order ). Workflow \u00b6 Describe when this hook occurs in a workflow. Hook creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion among implementers. Context \u00b6 Describe the set of contextual data used by this hook. Only data logically and necessarily associated with the purpose of this hook should be represented in context. All fields defined by the hook's context MUST be defined in a table where each field is described by the following attributes: Field: The name of the field in the context JSON object. Hook authors SHOULD name their context fields to be consistent with other existing hooks when referring to the same context field. Optionality: A string value of either REQUIRED or OPTIONAL Prefetch Token: A string value of either Yes or No , indicating whether this field can be tokenized in a prefetch template. 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. The table below illustrates a sample hook context table: Field Optionality Prefetch Token Type Description someField REQUIRED Yes string A clear description of the value of this field. anotherField OPTIONAL No number A clear description of the value of this field. someObject REQUIRED No object A clear description of the value of this field. 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 \u00b6 For context fields that may contain multiple FHIR resources, the field SHOULD be defined as a FHIR Bundle, rather than as an array of FHIR resources. For example, multiple FHIR resources are necessary to describe all of the orders under review in the order-sign hook's draftOrders 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, imagine a hook, order-select that is invoked when a user selects a medication during an order workflow. The context data for this hook would contain draft FHIR resources representing the medications that have been selected for ordering. In this case, the CDS Client 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 \u00b6 Hook creators SHOULD include examples of the context. 1 2 3 4 5 6 7 8 9 \"context\" :{ \"someField\" : \"foo\" , \"anotherField\" : 123 , \"someObject\" : { \"color\" : \"red\" , \"version\" : 1 }, \"moreObjects\" :[] } If the context contains FHIR data, hook creators SHOULD include examples across multiple versions of FHIR if differences across FHIR versions are possible. Hook Maturity Model \u00b6 The intent of the CDS Hooks Maturity Model is to attain broad community engagement and consensus, before a hook is labeled as mature, that the hook is necessary, implementable, and worthwhile to the CDS Services and CDS Clients that would reasonably be expected to use it. Implementer feedback should drive the maturity of new hooks. Diverse participation in open developer forums and events, such as HL7 FHIR Connectathons, is necessary to achieve significant implementer feedback. The below criteria will be evaluated with these goals in mind. 1 Hook maturity | 3 - Considered The Hook maturity levels use the term CDS Client to generically refer to the clinical workflow system in which a CDS Services returned cards are displayed. Maturity Level Maturity title Requirements 0 Draft Hook is defined according to the hook definition format . 1 Submitted The above, and \u2026 Hook definition is written up as a github pull request using the Hook template and community feedback is solicited on the zulip CDS Hooks stream . 2 Tested The above, and \u2026 The hook has been tested and successfully supports interoperability among at least one CDS Client and two independent CDS Services using semi-realistic data and scenarios (e.g. at a FHIR Connectathon). The github pull request defining the hook is approved and published by the CDS Hooks Project Management Committee. 3 Considered The above, and \u2026 At least 3 distinct organizations recorded ten distinct implementer comments (including a github issue, tracker item, or comment on the hook definition page), including at least two CDS Clients and three independent CDS Services. The hook has been tested at two Connectathons. 4 Documented The above, and \u2026 The author agrees that the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes. The hook is implemented in the standard CDS Hooks sandbox and multiple prototype projects. The Hook specification SHALL: Identify a broad set of example contexts in which the hook may be used with a minimum of three, but as many as 8-10. Clearly differentiate the hook from similar hooks or other standards to help an implementer determine if the hook is correct for their scenario. Explicitly document example scenarios when the hook should not be used. 5 Mature The above, and ... The hook has been implemented in production in at least two CDS Clients and three independent CDS Services. An HL7 working group ballots the hook and the hook has passed HL7 STU ballot. 6 Normative The above, and ... the responsible HL7 working group and the CDS working group agree the material is ready to lock down and the hook has passed HL7 normative ballot Changes to a Hook \u00b6 Each hook MUST include a Metadata table at the beginning of the hook with the specification version and hook version as described in the following sections. Specification Version \u00b6 Because hooks are such an integral part of the CDS Hooks specification, hook definitions are associated with specific versions of the specification. The hook definition MUST include the version (or versions) of the CDS Hooks specification that it is defined to work with. 1 specificationVersion | 1.0 Because the specification itself follows semantic versioning, the version specified here is a minimum specification version. In other words, a hook defined to work against 1.0 should continue to work against the 1.1 version of CDS Hooks. However, a hook that specifies 1.1 would not be expected to work in a CDS Hooks 1.0 environment. Hook Version \u00b6 To enable tracking of changes to hook definitions, each hook MUST include a version indicator, expressed as a string. 1 hookVersion | 1.0 To help ensure the stability of CDS Hooks implementations, once a hook has been defined (i.e. published with a particular name so that it is available for implementation), breaking changes MUST NOT be made. This means that fields can be added and restrictions relaxed, but fields cannot be changed, and restrictions cannot be tightened. In particular, the semantics of a hook (i.e. the meaning of the hook from the perspective of the CDS Client) cannot be changed. CDS Clients 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 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 Major 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 Change of semantics of an existing context field Major Change of semantics of the hook Major When a major change is made, the hook definition MUST be published under a new name. When a minor or patch change is made, the hook version MUST be updated. Hook definers MUST use semantic versioning to communicate the impact of changes in an industry standard way. Note that the intent of this table is to outline possible breaking changes. The authors have attempted to enumerate these types of changes exhaustively, but as new types of breaking changes are identified, this list will be updated. Hook Maturity \u00b6 As each hook progresses through a process of being defined, tested, implemented, used in production environments, and balloted, the hook's formal maturity level increases. Each hook has its own maturity level, which MUST be defined in the hook's definition and correspond to the Hook Maturity Model . 1 hookMaturity | 0 - Draft Change Log \u00b6 Changes made to a hook's definition MUST be documented in a change log to ensure hook consumers can track what has been changed over the life of a hook. The change log MUST contain the following elements: Version: The version of the change Description: A description of the change and its impact For example: Version Description 1.1 Added new context variable 1.0.1 Clarified context variable usage 1.0 Initial Release","title":"Current (draft)"},{"location":"specification/current/#overview","text":"The CDS Hooks specification describes the RESTful APIs and interactions using JSON over HTTPS to integrate Clinical Decision Support (CDS) between CDS Clients (typically Electronic Health Record Systems (EHRs) or other health information systems) and CDS Services.","title":"Overview"},{"location":"specification/current/#conformance-language","text":"The key words \"MUST\", \"MUST NOT\", \"REQUIRED\", \"SHALL\", \"SHALL NOT\", \"SHOULD\", \"SHOULD NOT\", \"RECOMMENDED\", \"MAY\", and \"OPTIONAL\" in this specification are to be interpreted as described in RFC2119 . Further, the key word \"CONDITIONAL\" indicates that a particular item is either REQUIRED or OPTIONAL, based upon another item.","title":"Conformance Language"},{"location":"specification/current/#use-of-json","text":"All data exchanged through production RESTful APIs MUST be sent and received as JSON (JavaScript Object Notation) structures and are transmitted over HTTPS. See Security and Safety section. Null and empty JSON elements JSON elements SHALL NOT be null, unless otherwise specified. JSON elements SHALL NOT be empty, unless otherwise specified (e.g. to indicate no guidance with an empty array of cards in the CDS Hooks response). If a JSON attribute is defined as OPTIONAL, and does not have a value, implementers MUST omit it. For instance, OPTIONAL JSON string and array attributes are omitted rather than having a null or empty value. Unless otherwise specified, JSON attribute values SHALL NOT be null or empty, so null , \"\" , [] , or {} are prohibited. If a JSON attribute is defined with as OPTIONAL, and does not have a value, implementers SHALL omit it.","title":"Use of JSON"},{"location":"specification/current/#cds-hooks-anatomy","text":"This specification describes a \"hook\" -based pattern for invoking decision support from within a clinician's workflow. The API supports: Synchronous, workflow-triggered CDS calls returning information and suggestions Launching a web page to provide additional information to the user Launching a user-facing SMART app when CDS requires additional interaction The main concepts of the specification are Services, CDS Clients, and Cards.","title":"CDS Hooks Anatomy"},{"location":"specification/current/#cds-services","text":"A CDS Service is a service that provides recommendations and guidance through the RESTful APIs described by this specification. The primary APIs are Discovery , which allows a CDS Developer to publish the types of CDS Services it provides. The Service API that CDS Clients use to request decision support. The Feedback API through which services learn the outcomes of their recommendations and guidance.","title":"CDS Services"},{"location":"specification/current/#cds-clients","text":"A CDS Client is an Electronic Health Record (EHR), or other clinical information system that uses decision support by calling CDS Services at specific points in the application's workflow called hooks . Each hook defines the hook context (contextual information available within the CDS Client and specific to the workflow) that is provided as part of the request. Each service advertises which hooks it supports and what prefetch data (information needed by the CDS Service to determine what decision support should be presented) it requires. In addition, CDS Clients typically provide the FHIR resource server location and associated authorization information as part of the request to enable services to request additional information.","title":"CDS Clients"},{"location":"specification/current/#cards","text":"Decision support is then returned to the CDS Client in the form of cards , which the CDS Client MAY display to the end-user as part of their workflow. Cards may be informational, or they may provide suggestions that the user may accept or reject they may provide a link to additional information or even launch a SMART app when additional user interaction is required.","title":"Cards"},{"location":"specification/current/#discovery","text":"A CDS Service is discoverable via a stable endpoint by CDS Clients. The Discovery endpoint includes information such as a description of the CDS Service, when it should be invoked, and any data that is requested to be prefetched. A CDS Service provider exposes its discovery endpoint at: 1 { baseURL } /cds-services","title":"Discovery"},{"location":"specification/current/#http-request","text":"The Discovery endpoint SHALL always be available at {baseUrl}/cds-services . For example, if the baseUrl is https://example.com, the CDS Client can retrieve the list of CDS Services by invoking: GET https://example.com/cds-services","title":"HTTP Request"},{"location":"specification/current/#response","text":"The response to the discovery endpoint SHALL be an object containing a list of CDS Services. Field Description services array . An array of CDS Services . If your CDS server hosts no CDS Services, the discovery endpoint should return a 200 HTTP response with an empty array of services. Each CDS Service SHALL be described by the following attributes. Field Optionality Type Description hook REQUIRED string The hook this service should be invoked on. See Hooks . title RECOMMENDED string The human-friendly name of this service. description REQUIRED string The description of this service. id REQUIRED string The {id} portion of the URL to this service which is available at {baseUrl}/cds-services/{id} prefetch OPTIONAL object An object containing key/value pairs of FHIR queries that this service is requesting the CDS Client to perform and provide on each service call. The key is a string that describes the type of data being requested and the value is a string representing the FHIR query. See Prefetch Template . usageRequirements OPTIONAL string Human-friendly description of any preconditions for the use of this CDS Service. Note that a CDS server can host multiple entries of CDS service with the same id for different hook s. This allows a service to update its advice based on changes in workflow as discussed in update stale guidance .","title":"Response"},{"location":"specification/current/#http-status-codes","text":"Code Description 200 OK A successful response. CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes.","title":"HTTP Status Codes"},{"location":"specification/current/#discovery-example","text":"1 curl \"https://example.com/cds-services\" The above command returns JSON structured like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 { \"services\" : [ { \"hook\" : \"patient-view\" , \"title\" : \"Static CDS Service Example\" , \"description\" : \"An example of a CDS Service that returns a static set of cards\" , \"id\" : \"static-patient-greeter\" , \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } }, { \"hook\" : \"order-select\" , \"title\" : \"Order Echo CDS Service\" , \"description\" : \"An example of a CDS Service that simply echoes the order(s) being placed\" , \"id\" : \"order-echo\" , \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" , \"medications\" : \"MedicationRequest?patient={{context.patientId}}\" } }, { \"hook\" : \"order-sign\" , \"title\" : \"Pharmacogenomics CDS Service\" , \"description\" : \"An example of a more advanced, precision medicine CDS Service\" , \"id\" : \"pgx-on-order-sign\" , \"usageRequirements\" : \"Note: functionality of this CDS Service is degraded without access to a FHIR Restful API as part of CDS recommendation generation.\" } ] }","title":"Discovery Example"},{"location":"specification/current/#calling-a-cds-service","text":"","title":"Calling a CDS Service"},{"location":"specification/current/#http-request_1","text":"A CDS Client SHALL call a CDS Service by POST ing a JSON document to the service as described in this section. The CDS Service endpoint can be constructed from the CDS Service base URL and an individual service id as {baseUrl}/cds-services/{service.id} . CDS Clients may add additional requirements for the triggering of a hook, based upon the user, workflow, CDS Service or other reasons (e.g. if the service is provided by a payer, the patient has active coverage with that payer). See Trusting CDS Services for additional considerations. The request SHALL include a JSON POST body with the following input fields: Field Optionality Type Description hook REQUIRED string The hook that triggered this CDS Service call. See Hooks . hookInstance REQUIRED string A universally unique identifier (UUID) for this particular hook call (see more information below). fhirServer CONDITIONAL URL The base URL of the CDS Client's FHIR server. If fhirAuthorization is provided, this field is REQUIRED. The scheme MUST be https when production data is exchanged. fhirAuthorization OPTIONAL object A structure holding an 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 section for more information. context REQUIRED object Hook-specific contextual data that the CDS service will need. For example, with the patient-view hook this will include the FHIR id of the Patient being viewed. For details, see the Hooks specific specification page (example: patient-view ). prefetch OPTIONAL object The FHIR data that was prefetched by the CDS Client (see more information below).","title":"HTTP Request"},{"location":"specification/current/#hookinstance","text":"While working in the CDS Client, a user can perform multiple actions in series or in parallel. For example, a clinician might prescribe two drugs in a row; each prescription action would be assigned a unique hookInstance . This allows a CDS Service to uniquely identify each hook invocation. Note: the hookInstance is globally unique and should contain enough entropy to be un-guessable.","title":"hookInstance"},{"location":"specification/current/#example","text":"1 2 3 4 5 curl -X POST \\ -H 'Content-type: application/json' \\ --data @hook-details-see-example-below \"https://example.com/cds-services/static-patient-greeter\" 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://hooks.smarthealthit.org:9080\" , \"hook\" : \"patient-view\" , \"fhirAuthorization\" : { \"access_token\" : \"some-opaque-fhir-access-token\" , \"token_type\" : \"Bearer\" , \"expires_in\" : 300 , \"scope\" : \"user/Patient.read user/Observation.read\" , \"subject\" : \"cds-service4\" }, \"context\" : { \"userId\" : \"Practitioner/example\" , \"patientId\" : \"1288992\" , \"encounterId\" : \"89284\" }, \"prefetch\" : { \"patientToGreet\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1925-12-23\" , \"id\" : \"1288992\" , \"active\" : true } } }","title":"Example"},{"location":"specification/current/#providing-fhir-resources-to-a-cds-service","text":"CDS Services require specific FHIR resources in order to compute the recommendations the CDS Client requests. If real-world performance were no issue, a CDS Client could launch a CDS Service passing only context data (such as the current user and patient ids), and the CDS Service could obtain authorization to access the CDS Client's FHIR API, retrieving any resources required via FHIR read or search interactions. Given that CDS Services SHOULD respond quickly (on the order of 500 ms.), this specification defines mechanisms that allow a CDS Service to request and obtain FHIR resources more efficiently. Two optional methods are provided. In the first method, FHIR resources MAY be obtained by passing \"prefetched\" data from the CDS Client to the CDS Service in the service call. If data is to be prefetched, the CDS Service registers a set of \"prefetch templates\" with the CDS Client, as described in the Prefetch Template section below. These \"prefetch templates\" are defined in the CDS Service discovery response . The FHIR resources are passed as key-value pairs, with each key matching a key described in the discovery response, and each value being a FHIR resource. Note that in the case of searches, this resource may be a searchset Bundle. The second method enables the CDS Service to retrieve FHIR resources for itself, without the need to request and obtain its own authorization. If the CDS Client decides to have the CDS Service fetch its own FHIR resources, the CDS Client obtains and passes directly to the CDS Service a bearer token issued for the CDS Service's use in executing FHIR API calls against the CDS Client's FHIR server to obtain the required resources. Some CDS Clients MAY pass prefetched data, along with a bearer token for the CDS Service to use if additional resources are required. Each CDS Client SHOULD decide which approach, or combination, is preferred, based on performance considerations and assessment of attendant security and safety risks. CDS Services should be capable of accessing FHIR resources via either prefetch or from the CDS Client's FHIR server. For more detail, see the FHIR Resource Access section below. Similarly, each CDS Client will decide what FHIR resources to authorize and to prefetch, based on the CDS Service discovery response's \"prefetch\" request and on the provider's assessment of the \"minimum necessary.\" The CDS Client provider and the CDS Service provider will negotiate the set of FHIR resources to be provided, and how these data will be provided, as part of their service agreement.","title":"Providing FHIR Resources to a CDS Service"},{"location":"specification/current/#prefetch-template","text":"A prefetch template is a FHIR read or search request that describes relevant data needed by the CDS Service. For example, the following is a prefetch template for hemoglobin A1c observations: 1 Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date To allow for prefetch templates that are dependent on the workflow context, prefetch templates may include references to context using prefetch tokens . In the above example, {{context.patientId}} is a prefetch token. The prefetch field of a CDS Service discovery response defines the set of prefetch templates for that service, providing a prefetch key for each one that is used to identify the prefetch data in the CDS request. For example: 1 2 3 4 5 { \"prefetch\" : { \"hemoglobin-a1c\" : \"Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date\" } } In this prefetch , hemoglobin-a1c is the prefetch key for this prefetch template. For a complete worked example, see below . A CDS Client MAY choose to honor zero, some, or all of the desired prefetch templates, and is free to choose the most appropriate source for these data. For example: The CDS Client MAY have some of the desired prefetched data already in memory, thereby removing the need for any network call The CDS Client MAY compute an efficient set of prefetch templates from multiple CDS Services, thereby reducing the number of calls to a minimum The CDS Client MAY satisfy some of the desired prefetched templates via some internal service or even its own FHIR server. The CDS Client SHALL only provide access to resources that are within the user's authorized scope. As part of preparing the request, a CDS Client processes each prefetch template it intends to satisfy by replacing the prefetch tokens in the prefetch template to construct a relative FHIR request URL. This specification is not prescriptive about how this request is actually processed. The relative URL may be appended to the base URL for the CDS Client's FHIR server and directly invoked, or the CDS Client may use internal infrastructure to satisfy the request in the same way that invoking against the FHIR server would. Regardless of how the CDS Client satisfies the prefetch templates (if at all), the prefetched data given to the CDS Service MUST be equivalent to the data the CDS Service would receive if it were making its own call to the CDS Client's FHIR server using the parameterized prefetch template. Note that this means that CDS services will receive only the information they have requested and are authorized to receive. Prefetch data for other services registered to the same hook MUST NOT be provided. In other words, services SHALL only receive the data they requested in their prefetch. The resulting response is passed along to the CDS Service using the prefetch parameter (see below . Note that a CDS Client MAY paginate prefetch results. The intent of allowing pagination is to ensure that prefetch queries that may be too large for a single payload can still be retrieved by the service. The decision to paginate and the size of pages is entirely at the CDS Client's discretion. CDS Clients are encouraged to only use pagination when absolutely necessary, keeping performance and user experience in mind. The CDS Client MUST NOT send any prefetch template key that it chooses not to satisfy. If the CDS Client encounters errors prefetching the requested data, OperationOutcome(s) SHOULD be used to communicate those errors to prevent the CDS Service from incurring an unneeded follow-up query. CDS Clients MUST omit the prefetch key if relevant details cannot be provided (e.g. intermittent connectivity issues). CDS Services SHOULD check any prefetched data for the existence of OperationOutcomes. If the CDS Client has no data to populate a template prefetch key, the prefetch template key MUST have a value of null . Note that the null result is used rather than a bundle with zero entries to account for the possibility that the prefetch url is a single-resource request. It is the CDS Service's responsibility to check prefetched data against its template to determine what requests were satisfied (if any) and to programmatically retrieve any additional necessary data. If the CDS Service is unable to obtain required data because it cannot access the FHIR server and the request did not contain the necessary prefetch keys, the service SHALL respond with an HTTP 412 Precondition Failed status code.","title":"Prefetch Template"},{"location":"specification/current/#prefetch-tokens","text":"A prefetch token is a placeholder in a prefetch template that is replaced by information from the hook's context to construct the FHIR URL used to request the prefetch data. Prefetch tokens MUST be delimited by {{ and }} , and MUST contain only the qualified path to a hook context field or one of the following user identifiers: userPractitionerId , userPractitionerRoleId , userPatientId , or userRelatedPersonId . 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 example, {{context.medication.id}} is not a valid prefetch token because it attempts to access the id field of the medication field.","title":"Prefetch tokens"},{"location":"specification/current/#prefetch-tokens-identifying-the-user","text":"A prefetch template enables a CDS Service to learn more about the current user through a FHIR read, like so: 1 2 3 4 5 { \"prefetch\": { \"user\": \"{{context.userId}}\" } } or though a FHIR search: 1 2 3 4 5 { \"prefetch\": { \"user\": \"PractitionerRole?_id={{userPractitionerRoleId}}&_include=PractitionerRole:practitioner\" } } A prefetch template may include any of the following prefetch tokens: Token Description {{userPractitionerId}} FHIR id of the Practitioner resource corresponding to the current user. {{userPractitionerRoleId}} FHIR id of the PractitionerRole resource corresponding to the current user. {{userPatientId}} FHIR id of the Patient resource corresponding to the current user. {{userRelatedPersonId}} FHIR id of the RelatedPerson resource corresponding to the current user. No single FHIR resource represents a user, rather Practitioner and PractitionerRole may be jointly used to represent a provider, and Patient or RelatedPerson are used to represent a patient or their proxy. Hook definitions typically define a context.userId field and corresponding prefetch token.","title":"Prefetch tokens identifying the user"},{"location":"specification/current/#prefetch-query-restrictions","text":"To reduce the implementation burden on CDS Clients that support CDS Services, this specification RECOMMENDS that prefetch queries only use a subset of the full functionality available in the FHIR specification. When using this subset, valid prefetch templates MUST only make use of: instance level read interactions (for resources with known ids such as Patient , Practitioner , or Encounter ) type level search interactions; e.g. patient={{context.patientId}} Resource references (e.g. patient={{context.patientId}} ) token search parameters using equality (e.g. code=4548-4 ) and optionally the :in modifier (no other modifiers for token parameters) date search parameters on date , dateTime , instant , or Period types only, and using only the prefixes eq , lt , gt , ge , le the _count parameter to limit the number of results returned the _sort parameter to allow for most recent and first queries","title":"Prefetch query restrictions"},{"location":"specification/current/#example-prefetch-token","text":"Often a prefetch template builds on the contextual data associated with the hook. For example, a particular CDS Service might recommend guidance based on a patient's conditions when the chart is opened. The FHIR query to retrieve these conditions might be Condition?patient=123 . In order to express this as a prefetch template, the CDS Service must express the FHIR id of the patient as a token so that the CDS Client can replace the token with the appropriate value. When context fields are used as tokens, their token name MUST be context.name-of-the-field . For example, given a context like: 1 2 3 4 5 { \"context\" : { \"patientId\" : \"123\" } } The token name would be {{context.patientId}} . Again using our above conditions example, the complete prefetch template would be Condition?patient={{context.patientId}} . Only the first level fields in context may be considered for tokens. For example, given the following context that contains amongst other things, a MedicationRequest FHIR resource: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 { \"context\" : { \"encounterId\" : \"456\" , \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"123\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }]}, \"subject\" : { \"reference\" : \"Patient/1288992\" } } } ] } } } Only the encounterId field in this example is eligible to be a prefetch token as it is a first level field and the datatype (string) can be placed into the FHIR query. The MedicationRequest.id value in the context is not eligible to be a prefetch token because it is not a first level field. If the hook creator intends for the MedicationRequest.id value to be available as a prefetch token, it must be made available as a first level field. Using the aforementioned example, we simply add a new medicationRequestId field: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 { \"context\" : { \"medicationRequestId\" : \"123\" , \"encounterId\" : \"456\" , \"draftOrders\" : { \"resourceType\" : \"Bundle\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"123\" , \"status\" : \"draft\" , \"intent\" : \"order\" , \"medicationCodeableConcept\" : { \"coding\" : [ { \"system\" : \"http://www.nlm.nih.gov/research/umls/rxnorm\" , \"code\" : \"617993\" , \"display\" : \"Amoxicillin 120 MG/ML / clavulanate potassium 8.58 MG/ML Oral Suspension\" }]}, \"subject\" : { \"reference\" : \"Patient/1288992\" } } } ] } } }","title":"Example prefetch token"},{"location":"specification/current/#example-prefetch-templates","text":"1 2 3 4 5 6 7 8 { \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" , \"hemoglobin-a1c\" : \"Observation?patient={{context.patientId}}&code=4548-4&_count=1&sort:desc=date\" , \"diabetes-type2\" : \"Condition?patient={{context.patientId}}&code=44054006&category=problem-list-item&status=active\" , \"user\" : \"PractitionerRole?_id={{userPractitionerRoleId}}\" } } Here is an example prefetch field from a CDS Service discovery endpoint. The goal is to know, at call time: Key Description patient Patient demographics. hemoglobin-a1c Most recent Hemoglobin A1c reading for this patient. diabetes-type2 If the patient has an active condition of diabetes mellitus on their problem list. user Information on the current user.","title":"Example prefetch templates"},{"location":"specification/current/#example-prefetch-data","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 { \"prefetch\" : { \"patient\" : { \"resourceType\" : \"Patient\" , \"gender\" : \"male\" , \"birthDate\" : \"1974-12-25\" , \"...\" : \"<snipped for brevity>\" }, \"hemoglobin-a1c\" : { \"resourceType\" : \"Bundle\" , \"type\" : \"searchset\" , \"entry\" : [ { \"resource\" : { \"resourceType\" : \"Observation\" , \"code\" : { \"coding\" : [ { \"system\" : \"http://loinc.org\" , \"code\" : \"4548-4\" , \"display\" : \"Hemoglobin A1c\" } ] }, \"...\" : \"<snipped for brevity>\" } } ] }, \"user\" : \"123\" } } The CDS Hooks request is augmented to include two prefetch values, where the dictionary keys match the request keys ( patient and hemoglobin-a1c in this case). Note that the missing diabetes-type2 key indicates that either the CDS Client has decided not to satisfy this particular prefetch template or it was not able to retrieve this prefetched data. The CDS Service is responsible for retrieving the FHIR resource representing the user from the FHIR server (if required).","title":"Example prefetch data"},{"location":"specification/current/#fhir-resource-access","text":"If the CDS Client provides both fhirServer and fhirAuthorization request parameters, the CDS Service MAY use the FHIR server to obtain any FHIR resources for which it's authorized, beyond those provided by the CDS Client as prefetched data. This is similar to the approach used by SMART on FHIR wherein the SMART app requests and ultimately obtains an access token from the CDS Client's Authorization server using the SMART launch workflow, as described in SMART App Launch Implementation Guide . Like SMART on FHIR, CDS Hooks requires that CDS Services present a valid access token to the FHIR server with each API call. Thus, a CDS Service requires an access token before communicating with the CDS Client's FHIR resource server. While CDS Hooks shares the underlying technical framework and standards as SMART on FHIR, the CDS Hooks workflow MUST accommodate the automated, low-latency delivery of an access token to the CDS service. With CDS Hooks, if the CDS Client wants to provide the CDS Service direct access to FHIR resources, the CDS Client creates or obtains an access token prior to invoking the CDS Service, passing this token to the CDS Service as part of the service call. This approach remains compatible with OAuth 2.0's bearer token protocol while minimizing the number of HTTPS round-trips and the service invocation latency. The CDS Client remains in control of providing an access token that is associated with the specific CDS Service, user, and context of the invocation. As the CDS Service executes on behalf of a user, the data to which the CDS Service is given access by the CDS Client MUST be limited to the same restrictions and authorizations afforded the current user. As such, the access token SHALL be scoped to: The CDS Service being invoked The current user","title":"FHIR Resource Access"},{"location":"specification/current/#passing-the-access-token-to-the-cds-service","text":"The access token is specified in the CDS Service request via the fhirAuthorization request parameter. This parameter is an object that contains both the access token as well as other related information as specified below. If the CDS Client chooses not to pass along an access token, the fhirAuthorization parameter is omitted. Field Optionality Type Description access_token REQUIRED string This is the OAuth 2.0 access token that provides access to the FHIR server. token_type REQUIRED string Fixed value: Bearer expires_in REQUIRED integer The lifetime in seconds of the access token. scope REQUIRED string The scopes the access token grants the CDS Service. subject REQUIRED string The OAuth 2.0 client identifier of the CDS Service, as registered with the CDS Client's authorization server. 'patient` CONDITIONAL string If the granted SMART scopes include patient scopes (i.e. \"patient/\"), the access token is restricted to a specific patient. This field SHOULD be populated to identify the FHIR id of that patient. The scopes granted to the CDS Service via the scope field are defined by the SMART on FHIR specification . The expires_in value is established by the authorization server and SHOULD BE very short lived, as the access token MUST be treated as a transient value by the CDS Service. CDS Clients SHOULD revoke an issued access token upon the completion of the CDS Hooks request/response to limit the validity period of the token. Below is an example fhirAuthorization parameter: 1 2 3 4 5 6 7 8 9 { \"fhirAuthorization\" : { \"access_token\" : \"some-opaque-fhir-access-token\" , \"token_type\" : \"Bearer\" , \"expires_in\" : 300 , \"scope\" : \"user/Patient.read user/Observation.read\" , \"subject\" : \"cds-service4\" } }","title":"Passing the Access Token to the CDS Service"},{"location":"specification/current/#cds-service-response","text":"For successful responses, CDS Services SHALL respond with a 200 HTTP response with an object containing a cards array and optionally a systemActions array as described below. Each card contains decision support guidance from the CDS Service. Cards are intended for display to an end user. The data format of a card defines a very minimal set of required attributes with several more optional attributes to suit a variety of use cases, such as: narrative informational decision support, actionable suggestions to modify data, and links to SMART apps. Note that because the CDS client may be invoking multiple services from the same hook, there may be multiple responses related to the same information. This specification does not address these scenarios specifically; both CDS Services and CDS Clients should consider the implications of multiple CDS Services in their integrations and are invited to consider card attributes when determining prioritization and presentation options.","title":"CDS Service Response"},{"location":"specification/current/#http-status-codes_1","text":"Code Description 200 OK A successful response. 412 Precondition Failed The CDS Service is unable to retrieve the necessary FHIR data to execute its decision support, either through a prefetch request or directly calling the FHIR server. CDS Services MAY return other HTTP statuses, specifically 4xx and 5xx HTTP error codes.","title":"HTTP Status Codes"},{"location":"specification/current/#http-response","text":"Field Optionality Type Description cards REQUIRED array of Cards An array of Cards . Cards can provide a combination of information (for reading), suggested actions (to be applied if a user selects them), and links (to launch an app if the user selects them). The CDS Client decides how to display cards, but this specification recommends displaying suggestions using buttons, and links using underlined text. systemActions OPTIONAL array of Actions An array of Actions that the CDS Service proposes to auto-apply. Each action follows the schema of a card-based suggestion.action . The CDS Client decides whether to auto-apply actions. If your CDS Service has no decision support for the user, your service should return a 200 HTTP response with an empty array of cards, for example: 1 2 3 { \"cards\" : [] } Clients SHOULD remove cards returned by previous invocations of a hook to a service with the same id when a new hook is triggered (see update stale guidance ).","title":"HTTP Response"},{"location":"specification/current/#card-attributes","text":"Each Card is described by the following attributes. Field Optionality Type Description uuid OPTIONAL string Unique identifier of the card. MAY be used for auditing and logging cards and SHALL be included in any subsequent calls to the CDS service's feedback endpoint. summary REQUIRED string One-sentence, <140-character summary message for display to the user inside of this card. detail OPTIONAL string Optional detailed information to display; if provided MUST be represented in (GitHub Flavored) Markdown . (For non-urgent cards, the CDS Client MAY hide these details until the user clicks a link like \"view more details...\"). indicator REQUIRED string Urgency/importance of what this card conveys. Allowed values, in order of increasing urgency, are: info , warning , critical . The CDS Client MAY use this field to help make UI display decisions such as sort order or coloring. source REQUIRED object Grouping structure for the Source of the information displayed on this card. The source should be the primary source of guidance for the decision support the card represents. suggestions OPTIONAL array of Suggestions Allows a service to suggest a set of changes in the context of the current activity (e.g. changing the dose of a medication currently being prescribed, for the order-sign activity). If suggestions are present, selectionBehavior MUST also be provided. selectionBehavior CONDITIONAL string Describes the intended selection behavior of the suggestions in the card. Allowed values are: at-most-one , indicating that the user may choose none or at most one of the suggestions; any , indicating that the end user may choose any number of suggestions including none of them and all of them. CDS Clients that do not understand the value MUST treat the card as an error. overrideReasons OPTIONAL array of Coding Override reasons can be selected by the end user when overriding a card without taking the suggested recommendations. The CDS service MAY return a list of override reasons to the CDS client. If override reasons are present, the CDS Service MUST populate a display value for each reason's Coding . The CDS Client SHOULD present these reasons to the clinician when they dismiss a card. A CDS Client MAY augment the override reasons presented to the user with its own reasons. links OPTIONAL array of Links Allows a service to suggest a link to an app that the user might want to run for additional information or to help guide a decision.","title":"Card Attributes"},{"location":"specification/current/#source","text":"The Source is described by the following attributes. Field Optionality Type Description label REQUIRED string A short, human-readable label to display for the source of the information displayed on this card. If a url is also specified, this MAY be the text for the hyperlink. url OPTIONAL URL An optional absolute URL to load (via GET , in a browser context) when a user clicks on this link to learn more about the organization or data set that provided the information on this card. Note that this URL should not be used to supply a context-specific \"drill-down\" view of the information on this card. For that, use card.link.url instead. icon OPTIONAL URL An absolute URL to an icon for the source of this card. The icon returned by this URL SHOULD be a 100x100 pixel PNG image without any transparent regions. The CDS Client may ignore or scale the image during display as appropriate for user experience. topic OPTIONAL Coding A topic describes the content of the card by providing a high-level categorization that can be useful for filtering, searching or ordered display of related cards in the CDS client's UI. This specification does not prescribe a standard set of topics. Below is an example source parameter: 1 2 3 4 5 6 7 8 9 10 11 12 { \"source\" : { \"label\" : \"Zika Virus Management\" , \"url\" : \"https://example.com/cdc-zika-virus-mgmt\" , \"icon\" : \"https://example.com/cdc-zika-virus-mgmt/100.png\" , \"topic\" : { \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/topics\" , \"code\" : \"12345\" , \"display\" : \"Mosquito born virus\" } } }","title":"Source"},{"location":"specification/current/#suggestion","text":"Each Suggestion is described by the following attributes. Field Optionality Type Description label REQUIRED string Human-readable label to display for this suggestion (e.g. the CDS Client might render this as the text on a button tied to this suggestion). uuid OPTIONAL string Unique identifier, used for auditing and logging suggestions. isRecommended OPTIONAL boolean When there are multiple suggestions, allows a service to indicate that a specific suggestion is recommended from all the available suggestions on the card. CDS Hooks clients may choose to influence their UI based on this value, such as pre-selecting, or highlighting recommended suggestions. Multiple suggestions MAY be recommended, if card.selectionBehavior is any . actions OPTIONAL array of Actions Array of objects, each defining a suggested action. Within a suggestion, all actions are logically AND'd together, such that a user selecting a suggestion selects all of the actions within it. When a suggestion contains multiple actions, the actions SHOULD be processed as per FHIR's rules for processing transactions with the CDS Client's fhirServer as the base url for the inferred full URL of the transaction bundle entries. (Specifically, deletes happen first, then creates, then updates).","title":"Suggestion"},{"location":"specification/current/#action","text":"Each Action is described by the following attributes. Field Optionality Type Description type REQUIRED string The type of action being performed. Allowed values are: create , update , delete . description REQUIRED string Human-readable description of the suggested action MAY be presented to the end-user. resource CONDITIONAL object A FHIR resource. When the type attribute is create , the resource attribute SHALL contain a new FHIR resource to be created. For update , this holds the updated resource in its entirety and not just the changed fields. Use of this field to communicate a string of a FHIR id for delete suggestions is DEPRECATED and resourceId SHOULD be used instead. resourceId CONDITIONAL string A relative reference to the relevant resource. SHOULD be provided when the type attribute is delete . The following example illustrates a create action: 1 2 3 4 5 6 7 8 9 { \"type\" : \"create\" , \"description\" : \"Create a prescription for Acetaminophen 250 MG\" , \"resource\" : { \"resourceType\" : \"MedicationRequest\" , \"id\" : \"medrx001\" , \"...\" : \"<snipped for brevity>\" } } The following example illustrates an update action: 1 2 3 4 5 6 7 8 9 { \"type\" : \"update\" , \"description\" : \"Update the order to record the appropriateness score\" , \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"procedure-request-1\" , \"...\" : \"<snipped for brevity>\" } } The following example illustrates a delete action: 1 2 3 4 5 { \"type\" : \"delete\" , \"description\" : \"Remove the inappropriate order\" , \"resourceId\" : \"ServiceRequest/procedure-request-1\" }","title":"Action"},{"location":"specification/current/#reasons-for-rejecting-a-card","text":"overrideReasons is an array of Coding that captures a codified set of reasons an end user may select from as the rejection reason when rejecting the advice presented in the card. When using the coding object to represent a reason, CDS Services MUST provide a human readable text in the display property and CDS Clients MAY incorporate it into their user interface. This specification does not prescribe a standard set of override reasons; implementers are encouraged to submit suggestions for standardization. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 { \"overrideReasons\" : [ { \"code\" : \"reason-code-provided-by-service\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Patient refused\" }, { \"code\" : \"12354\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Contraindicated\" } ] }","title":"Reasons for rejecting a card"},{"location":"specification/current/#link","text":"Each Link is described by the following attributes. Field Optionality Type Description label REQUIRED string Human-readable label to display for this link (e.g. the CDS Client might render this as the underlined text of a clickable link). url REQUIRED URL URL to load (via GET , in a browser context) when a user clicks on this link. Note that this MAY be a \"deep link\" with context embedded in path segments, query parameters, or a hash. type REQUIRED string The type of the given URL. There are two possible values for this field. A type of absolute indicates that the URL is absolute and should be treated as-is. A type of smart indicates that the URL is a SMART app launch URL and the CDS Client should ensure the SMART app launch URL is populated with the appropriate SMART launch parameters. appContext OPTIONAL string An optional field that allows the CDS Service to share information from the CDS card with a subsequently launched SMART app. The appContext field should only be valued if the link type is smart and is not valid for absolute links. The appContext field and value will be sent to the SMART app as part of the OAuth 2.0 access token response, alongside the other SMART launch parameters when the SMART app is launched. Note that appContext could be escaped JSON, base64 encoded XML, or even a simple string, so long as the SMART app can recognize it. CDS Client support for appContext requires additional coordination with the authorization server that is not described or specified in CDS Hooks nor SMART. autolaunchable OPTIONAL boolean This field serves as a hint to the CDS Client suggesting this link be immediately launched, without displaying the card and without manual user interaction. Note that CDS Hooks cards which contain links with this field set to true, may not be shown to the user. Sufficiently advanced CDS Clients may support automatically launching multiple links or multiple cards. Implementer guidance is requested to determine if the specification should preclude these advanced scenarios.","title":"Link"},{"location":"specification/current/#considerations-for-autolaunchable-and-user-experience","text":"The intent of this optional feature is to improve individual user experience by removing the otherwise unnecessary click of a link by the user. Appropriate support of this feature includes guardrails from both the CDS Service developer and the CDS Client, as well as additional local control by the organization using the service. The CDS Client ultimately determines if a link can be automatically launched, taking into consideration user interface needs, workflow considerations, or even absence of support for this optional feature. If a CDS Hooks response contains guidance in addition to an autolaunchable link, it's the CDS Service's responsibility to ensure that any decision support that exists in the CDS Hooks response's card(s) is communicated via the launched app.","title":"Considerations for autolaunchable and user experience"},{"location":"specification/current/#system-action","text":"A systemAction is the same Action which may be returned in a suggestion, but is instead returned alongside the array of cards. A systemAction is not presented to the user within a card, but rather may be auto-applied without user intervention. 1 2 3 4 5 6 7 8 9 10 11 12 13 { \"cards\" : [], \"systemActions\" : [ { \"type\" : \"update\" , \"resource\" : { \"resourceType\" : \"ServiceRequest\" , \"id\" : \"example-MRI-59879846\" , \"...\" : \"<snipped for brevity\" } } ] }","title":"System Action"},{"location":"specification/current/#example_1","text":"Example response 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 { \"cards\" : [ { \"uuid\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"summary\" : \"Example Card\" , \"indicator\" : \"info\" , \"detail\" : \"This is an example card.\" , \"source\" : { \"label\" : \"Static CDS Service Example\" , \"url\" : \"https://example.com\" , \"icon\" : \"https://example.com/img/icon-100px.png\" }, \"links\" : [ { \"label\" : \"Google\" , \"url\" : \"https://google.com\" , \"type\" : \"absolute\" }, { \"label\" : \"Github\" , \"url\" : \"https://github.com\" , \"type\" : \"absolute\" }, { \"label\" : \"SMART Example App\" , \"url\" : \"https://smart.example.com/launch\" , \"type\" : \"smart\" , \"appContext\" : \"{\\\"session\\\":3456356,\\\"settings\\\":{\\\"module\\\":4235}}\" } ] }, { \"summary\" : \"Another card\" , \"indicator\" : \"warning\" , \"source\" : { \"label\" : \"Static CDS Service Example\" }, \"overrideReasons\" : [ { \"code\" : \"reason-code-provided-by-service\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Patient refused\" }, { \"code\" : \"12354\" , \"system\" : \"http://example.org/cds-services/fhir/CodeSystem/override-reasons\" , \"display\" : \"Contraindicated\" } ] } ] } Example response using autolaunchable 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 { \"cards\" : [ { \"uuid\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"summary\" : \"Lung cancer screening shared decision making\" , \"detail\" : \"Patient is a current smoker with a 20 pack/year history. Consider advising patient to complete lung cancer screening. The Lung Cancer Screening Shared Decision Making App (LCSSDM) has been proven to increase patient followthrough for screening.\" , \"source\" : { \"label\" : \"Lung Cancer Screening Shared Decision Making App\" , \"url\" : \"https://example.com/LCS\" , \"icon\" : \"https://example.com/img/icon-100px.png\" }, \"links\" : [ { \"label\" : \"Github\" , \"url\" : \"https://github.com\" , \"type\" : \"absolute\" , \"autolaunchable\" : true } ] } ] }","title":"Example"},{"location":"specification/current/#feedback","text":"Once a CDS Hooks Service responds to a hook by returning a card, the service has no further interaction with the CDS Client. The acceptance of a suggestion or rejection of a card is valuable information to enable a service to improve its behavior towards the goal of the end-user having a positive and meaningful experience with the CDS. A feedback endpoint enables suggestion tracking & analytics. A CDS Service MAY support a feedback endpoint; a CDS Client SHOULD be capable of sending feedback. Upon receiving a card, a user may accept its suggestions, ignore it entirely, or dismiss it with or without an override reason. Note that while one or more suggestions can be accepted, an entire card is either ignored or overridden. Typically, an end user may only accept (a suggestion), or override a card once; however, a card once ignored could later be acted upon. CDS Hooks does not specify the UI behavior of CDS Clients, including the persistence of cards. CDS Clients should faithfully report each of these distinct end-user interactions as feedback. A CDS Client provides feedback by POSTing a JSON document. The feedback endpoint can be constructed from the CDS Service endpoint and a path segment of \"feedback\" as {baseUrl}/cds-services/{service.id}/feedback. The request to the feedback endpoint SHALL be an object containing an array. Field Description feedback array of Feedback Each Feedback SHALL be described by the following attributes. Field Optionality Type Description card REQUIRED string The card.uuid from the CDS Hooks response. Uniquely identifies the card. outcome REQUIRED string A value of accepted or overridden . acceptedSuggestions CONDITIONAL array An array of json objects identifying one or more of the user's AcceptedSuggestion s. Required for accepted outcomes. overrideReason OPTIONAL OverrideReason A json object capturing the override reason as a Coding as well as any comments entered by the user. outcomeTimestamp REQUIRED string ISO8601 representation of the date and time in Coordinated Universal Time (UTC) when action was taken on the card, as profiled in section 5.6 of RFC3339 . e.g. 1985-04-12T23:20:50.52Z","title":"Feedback"},{"location":"specification/current/#suggestion-accepted","text":"The CDS Client can inform the service when one or more suggestions were accepted by POSTing a simple JSON object. The CDS Client authenticates to the CDS service as described in Trusting CDS Clients . Upon the user accepting a suggestion (perhaps when she clicks a displayed label (e.g., button) from a \"suggestion\" card), the CDS Client informs the service by posting the card and suggestion uuid s to the CDS Service's feedback endpoint with an outcome of accepted . To enable a positive clinical experience, the feedback endpoint may be called for multiple hook instances or multiple cards at the same time or even multiple times for a card or suggestion. Depending upon the UI and workflow of the CDS Client, a CDS Service may receive feedback for the same card instance multiple times. Each AcceptedSuggestion is described by the following attributes. Field Optionality Type Description id REQUIRED string The card.suggestion.uuid from the CDS Hooks response. Uniquely identifies the suggestion that was accepted.","title":"Suggestion accepted"},{"location":"specification/current/#example-suggestion-accepted","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" : [ { \"card\" : \"4e0a3a1e-3283-4575-ab82-028d55fe2719\" , \"outcome\" : \"accepted\" , \"acceptedSuggestions\" : [ { \"id\" : \"e56e1945-20b3-4393-8503-a1a20fd73152\" } ], \"outcomeTimestamp\" : \"2021-12-11T10:05:31Z\" } ] } If either the card or the suggestion has no uuid , the CDS Client does not send a notification.","title":"Example suggestion accepted"},{"location":"specification/current/#card-ignored","text":"If the end-user doesn't interact with the CDS Service's card at all, the card is ignored . In this case, the CDS Client does not inform the CDS Service of the rejected guidance. Even with a card.uuid , a suggestion.uuid , and an available feedback service, the service is not informed (in part, because it may later be acted upon).","title":"Card ignored"},{"location":"specification/current/#overridden-guidance","text":"A CDS Client may enable the end user to override guidance without providing an explicit reason for doing so. The CDS Client can inform the service when a card was dismissed by specifying an outcome of overridden without providing an overrideReason . This may occur, for example, when the end user viewed the card and dismissed it without providing a reason why.","title":"Overridden guidance"},{"location":"specification/current/#example-overridden-guidance-without-overridereason","text":"1 2 3 4 5 6 7 8 9 10 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" : [ { \"card\" : \"f6b95768-b1c8-40dc-8385-bf3504b82ffb\" , // uuid from `card.uuid` \"outcome\" : \"overridden\" , \"outcomeTimestamp\" : \"2020-12-11T00:00:00Z\" } ] }","title":"Example overridden guidance without overrideReason"},{"location":"specification/current/#explicit-reject-with-override-reasons","text":"A CDS Client can inform the service when a card was rejected by POSTing an outcome of overridden along with an overrideReason to the service's feedback endpoint. The CDS Client may enable the clinician to provide an additional overrideReason or to supplement the overrideReason with a free text comment, supplied to the CDS Service in overrideReason.userComment .","title":"Explicit reject with override reasons"},{"location":"specification/current/#overridereason","text":"Each OverrideReason is described by the following attributes, in the feedback POST to the CDS Service. Field Optionality Type Description reason CONDITIONAL Coding The Coding object representing the override reason selected by the end user. Required if user selected an override reason from the list of reasons provided in the Card (instead of only leaving a userComment). userComment OPTIONAL string The CDS Client may enable the clinician to further explain why the card was rejected with free text. That user comment may be communicated to the CDS Service as a userComment .","title":"OverrideReason"},{"location":"specification/current/#example-overridden-guidance-with-overridereason","text":"1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 POST { baseUrl } /cds - services/ { serviceId } / fee dback { \"feedback\" :[ { \"card\" : \"9368d37b-283f-44a0-93ea-547cebab93ed\" , \"outcome\" : \"overridden\" , \"overrideReason\" :{ \"reason\" :{ \"code\" : \"d7ecf885\" , \"system\" : \"https://example.com/cds-hooks/override-reason-system\" }, \"userComment\" : \"A comment entered by the clinician.\" }, \"outcomeTimestamp\" : \"2020-12-11T00:00:00Z\" } ] }","title":"Example overridden guidance with overrideReason"},{"location":"specification/current/#security-and-safety","text":"All data exchanged through the RESTful APIs MUST be transmitted over channels secured using the Hypertext Transfer Protocol (HTTP) over Transport Layer Security (TLS), also known as HTTPS and defined in RFC2818 . Security and safety risks associated with the CDS Hooks API include: The risk that confidential information and privileged authorizations transmitted between a CDS Client and a CDS Service could be surreptitiously intercepted by an attacker; The risk that an attacker masquerading as a legitimate CDS Service could receive confidential information or privileged authorizations from a CDS Client, or could provide to a CDS Client decision support recommendations that could be harmful to a patient; The risk that an attacker masquerading as a legitimate service-subscribing CDS Client (i.e., man-in-the-middle) could intercept and possibly alter data exchanged between the two parties. The risk that a CDS Service could embed dangerous suggestions or links to dangerous apps in Cards returned to a CDS Client. The risk that a CDS Hooks browser-based deployment could be victimized by a Cross-Origin Resource Sharing (CORS) attack. The risk that a CDS Service could return a decision based on outdated patient data, resulting in a safety risk to the patient. CDS Hooks defines a security model that addresses these risks by assuring that the identities of both the CDS Service and the CDS Client are authenticated to each other; by protecting confidential information and privileged authorizations shared between a CDS Client and a CDS Service; by recommending means of assuring data freshness; and by incorporating business mechanisms through which trust is established and maintained between a CDS Client and a CDS Service. As with any access to protected patient information, systems should ensure that they have appropriate authorization and audit mechanisms in place to support transparency of use of the data. For more information, refer to Security Best Practices .","title":"Security and Safety"},{"location":"specification/current/#trusting-cds-services","text":"Prior to enabling CDS Clients to request decision support from any CDS Service, the CDS Client vendor and/or provider organization is expected to perform due diligence on the CDS Service provider. Each CDS Client vendor/provider is individually responsible for determining the suitability, safety and integrity of the CDS Services it uses, based on the organization's own risk-management strategy. Each CDS Client vendor/provider SHOULD maintain an \"allow list\" (and/or \"deny list\") of the CDS Services it has vetted, and the Card links that have been deemed safe to display from within the CDS Client context. Each provider organization is expected to work with its CDS Client vendor to choose what CDS Services to allow and to negotiate the conditions under which the CDS Services MAY be called. Once a CDS Service provider is selected, the CDS Client vendor/provider negotiates the terms under which service will be provided. This negotiation includes agreement on patient data elements that will be prefetched and provided to the CDS Service, the CDS Services used and the hooks that will trigger them, data elements that will be made available through an access token passed by the CDS Client, and steps the CDS Service MUST take to protect patient data and access tokens. The CDS Service can be registered with the CDS Client's authorization server, in part to define the FHIR resources that the CDS Service has authorization to access. These business arrangements are documented in the service agreement. Every interaction between a CDS Client and a CDS Service is initiated by the CDS Client sending a service request to a CDS Service endpoint protected using the Transport Layer Security protocol . Through the TLS protocol the identity of the CDS Service is authenticated, and an encrypted transmission channel is established between the CDS Client and the CDS Service. Both the Discovery endpoint and individual CDS Service endpoints are TLS secured. The CDS Client's FHIR server, using information provided by the authorization server, is responsible for enforcing restrictions on the information available to the CDS Service. Regardless of whether FHIR resources are prefetched or retrieved from the FHIR server, the CDS Client SHALL deny access to a requested resource if it is outside the user's authorized scope. If a CDS Client is satisfying prefetch requests from a CDS Service or sends a non-null fhirAuthorization object to a CDS Service so that it can call the FHIR server, the CDS Service MUST be pre-registered with the authorization server protecting access to the FHIR server. Pre-registration includes registering a client identifier, and agreeing upon the scope of FHIR access that is minimally necessary to provide the clinical decision support required. This specification does not address how the CDS Client, authorization server, and CDS Service perform this pre-registration.","title":"Trusting CDS Services"},{"location":"specification/current/#trusting-cds-clients","text":"The service agreement negotiated between the CDS Client vendor/provider and the CDS Service provider will include obligations the CDS Client vendor/provider commits to the CDS Service provider. Some agreements MAY include the use of mutual TLS, in which both ends of the channel are authenticated. However, mutual TLS is impractical for many organizations. In the absence of mutual TLS, only the CDS Service endpoint will be authenticated because the CDS Client initiates the TLS channel set-up. To enable the CDS Service to authenticate the identity of the CDS Client, CDS Hooks uses digitally signed JSON web tokens (JWT) ( rfc7519 ). CDS Services SHOULD require authentication if invoking the service poses any risk of exposing sensitive data to the caller. Each time a CDS Client transmits a request to a CDS Service which requires authentication, the request MUST include an Authorization header presenting the JWT as a \u201cBearer\u201d token: 1 Authorization: Bearer {{JWT}} Note that this is for every single CDS Service call, whether that be a Discovery call, a single CDS Service invocation, or multiple exchanges relating to a single service. Also note that mutual TLS MAY be used alongside JSON web tokens to establish trust of the CDS Client by the CDS Service. The CDS Client MUST use its private key to digitally sign the JWT, using the JSON Web Signatures (rfc7515) standard. The JWT header contains the following fields (see rfc7515 section 4.1 for further information on these standard headers): Field Optionality Type Value alg REQUIRED string The cryptographic algorithm used to sign this JWT. kid REQUIRED string The identifier of the key-pair used to sign this JWT. This identifier MUST be unique within the CDS Client's JWK Set. typ REQUIRED string Fixed value: JWT jku OPTIONAL url The URL to the JWK Set containing the public key(s). The JWT payload contains the following fields: Field Optionality Type Value iss REQUIRED string The URI of the issuer of this JWT. Note that the JWT MAY be self-issued by the CDS Client, or MAY be issued by a third-party identity provider. aud REQUIRED string or array of string The CDS Service endpoint that is being called by the CDS Client. (See more details below). exp REQUIRED number Expiration time integer for this authentication JWT, expressed in seconds since the \"Epoch\" (1970-01-01T00:00:00Z UTC). iat REQUIRED number The time at which this JWT was issued, expressed in seconds since the \"Epoch\" (1970-01-01T00:00:00Z UTC). jti REQUIRED string A nonce string value that uniquely identifies this authentication JWT (used to protect against replay attacks). tenant OPTIONAL string An opaque string identifying the healthcare organization that is invoking the CDS Hooks request. CDS Services SHOULD limit the CDS Clients they trust by maintaining an allowlist of iss and jku urls. Per rfc7519 , the aud value is either a string or an array of strings. For CDS Hooks, this value MUST be the URL of the CDS Service endpoint being invoked. For example, consider a CDS Service available at a base URL of https://cds.example.org . When the CDS Client invokes the CDS Service discovery endpoint, the aud value is either \"https://cds.example.org/cds-services\" or [\"https://cds.example.org/cds-services\"] . Similarly, when the CDS Client invokes a particular CDS Service (say, some-service ), the aud value is either \"https://cds.example.org/cds-services/some-service\" or [\"https://cds.example.org/cds-services/some-service\"] . The CDS Client MUST make its public key, expressed as a JSON Web Key (JWK), available in a JWK Set, as defined by rfc7517 . The kid value from the JWT header allows a CDS Service to identify the correct JWK in the JWK Set that can be used to verify the signature. The CDS Client MAY make its JWK Set available via a URL identified by the jku header field, as defined by rfc7515 4.1.2 . If the jku header field is ommitted, the CDS Client and CDS Service SHALL communicate the JWK Set out-of-band.","title":"Trusting CDS Clients"},{"location":"specification/current/#jwt-signing-algorithm","text":"The cryptographic signing algorithm of JWT is indicated in the alg header field. JSON Web Algorithms (rfc7518) defines several cryptographic algorithms for use in signing JWTs and should be referenced by CDS Hooks implementers. JWTs SHALL NOT be signed using the none algorithm, referred to in rfc7518 as unsecured JSON Web Signatures, as the lack of a cryptographic signature does not provide any integrity protection. Such JWTs could not be used by a CDS Service to identity the CDS Client preventing an establishment of trust. JWTs SHALL NOT be signed using any symmetric algorithm as these algorithms require the CDS Client and CDS Service to share a private key in order to verify the signature. For example, all HMAC based algorithms rely upon a shared private key and thus SHALL NOT be used to sign a JWT. When choosing an algorithm to sign their JWTs, CDS Clients SHOULD consider not only the algorithms (and key sizes) that are recommended within the security industry, but also how well those algorithms are supported in the various programming languages and libraries that may be used by CDS Services. At publication time of this specification, both ES384 and RS384 are RECOMMENDED for their regard within the larger security industry, strength, and support across popular programming languages and libraries. However, stronger and better algorithms are continually being introduced due to new threats, weaknesses, and increases in computing power. CDS Clients SHOULD continually re-evaluate their choice of an algorithm based upon these ever changing conditions. CDS Services SHOULD consider the algorithms they understand and trust based upon their tolerance for risk.","title":"JWT Signing Algorithm"},{"location":"specification/current/#example_2","text":"An example JSON web token header, payload, and JWK set: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 // JSON Web Token Header { \"alg\" : \"ES384\" , \"typ\" : \"JWT\" , \"kid\" : \"example-kid\" , \"jku\" : \"https://fhir-ehr.example.com/jwk_uri\" } // JSON Web Token Payload { \"iss\" : \"https://fhir-ehr.example.com/\" , \"aud\" : \"https://cds.example.org/cds-services/some-service\" , \"exp\" : 1422568860 , \"iat\" : 1311280970 , \"jti\" : \"ee22b021-e1b7-4611-ba5b-8eec6a33ac1e\" , \"tenant\" : \"2ddd6c3a-8e9a-44c6-a305-52111ad302a2\" } // JSON Web Key Set (public key) // This public key is used by the CDS Service to verify the signature of the JWT { \"keys\" : [ { \"kty\" : \"EC\" , \"use\" : \"sig\" , \"crv\" : \"P-384\" , \"kid\" : \"example-kid\" , \"x\" : \"46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk\" , \"y\" : \"XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI\" , \"alg\" : \"ES384\" } ] } // JSON Web Key (private key) // This private key is used by the CDS Client to sign the JWT { \"kty\" : \"EC\" , \"d\" : \"SeFXUXda8UomZ8GFUl7HH_Oi15rIbfMcsWj9ecIsDR8kLbqsEz2CGNgwy_IcILxy\" , \"use\" : \"sig\" , \"crv\" : \"P-384\" , \"kid\" : \"example-kid\" , \"x\" : \"46SDH7Znh821wblCBglA61sNE9ZrHYKKt3qRtRTmSXyOI_FIGBLWrWa0GPUkDCEk\" , \"y\" : \"XMcRuuoGW7CXjQdy-F5i3FeBE0x9hPLdeFdSoDd3ELmx404tLX0VRRcqzAsPhXcI\" , \"alg\" : \"ES384\" } Using the above JWT values and JWKs, the complete JWT as passed in the Authorization HTTP header would be: 1 Authorization: Bearer eyJhbGciOiJFUzM4NCIsInR5cCI6IkpXVCIsImtpZCI6ImV4YW1wbGUta2lkIiwiamt1IjoiaHR0cHM6Ly9maGlyLWVoci5leGFtcGxlLmNvbS9qd2tfdXJpIn0.eyJpc3MiOiJodHRwczovL2ZoaXItZWhyLmV4YW1wbGUuY29tLyIsImF1ZCI6Imh0dHBzOi8vY2RzLmV4YW1wbGUub3JnL2Nkcy1zZXJ2aWNlcy9zb21lLXNlcnZpY2UiLCJleHAiOjE0MjI1Njg4NjAsImlhdCI6MTMxMTI4MDk3MCwianRpIjoiZWUyMmIwMjEtZTFiNy00NjExLWJhNWItOGVlYzZhMzNhYzFlIiwidGVuYW50IjoiMmRkZDZjM2EtOGU5YS00NGM2LWEzMDUtNTIxMTFhZDMwMmEyIn0.d1WfLjGRKlcWB94l9do4cM8REXeYJLL6SGUBO8VHZhfM8mwKYP70EMxJ67War4TQblEpaQrp11wx5p7oPFm2ETYgCicS84vXWEIYTdjooZdooCSDf2L8-i4awdoUwiEb","title":"Example"},{"location":"specification/current/#cross-origin-resource-sharing","text":"Cross-origin resource sharing (CORS) is a World Wide Web Consortium (W3C) standard mechanism that uses additional HTTP headers to enable a web browser to gain permission to access resources from an Internet domain different from that which the browser is currently accessing. CORS is a client-side security mechanism with well-documented security risks. CDS Services and browser-based CDS Clients will require CORS support. A secure implementation guide for CORS is outside of the scope of this CDS Hooks specification. Organizations planning to implement CDS Hooks with CORS support are referred to the Cross-Origin Resource Sharing section of the OWASP HTML5 Security Cheat Sheet .","title":"Cross-Origin Resource Sharing"},{"location":"specification/current/#update-stale-guidance","text":"In the case that CDS Hooks cards are persisted, clients should take care to ensure that stale guidance does not negatively impact patient care. CDS Services can update their previously returned guidance by returning a new set of cards when the service is invoked based on a different hook . CDS Services indicate this intent by providing multiple CDS Services with the same id in discovery . Clients are recommended to remove cards returned by a previous invocation with the new cards . STU NOTE: We are seeking implementer feedback on how best to balance the needs of performance for implementations with the critical patient safety issues raised by the potential for stale guidance. Note that CDS Services will need to negotiate with CDS Clients to ensure that hooks that are required to ensure patient safety are supported by the CDS Client.","title":"Update stale guidance"},{"location":"specification/current/#extensions","text":"The specification is not prescriptive about support for extensions. However, to support extensions, the specification reserves the name extension and will never define an element with that name, allowing implementations to use it to provide custom behavior and information. The value of an extension element MUST be a pre-coordinated JSON object. Extension structures SHOULD use a strategy for naming that ensures global uniqueness, such as reverse-domain-name notation, as in the examples below. The intention here is that anything that has broad ranging value across the community enough to be a standardized extension has broad ranging value enough to be a first class citizen rather than an extension in CDS Hooks. STU Note: We seek implementer feedback on whether the recommendation to use namespace-based unique naming in the extension specification should be made mandatory or that we consider adding a mandatory field to extensions that indicates the source/type of the extension (as is done with FHIR). For example, an extension on a request could look like this: 1 2 3 4 5 6 7 8 9 10 11 12 { \"hookInstance\" : \"d1577c69-dfbe-44ad-ba6d-3e05e953b2ea\" , \"fhirServer\" : \"http://fhir.example.org:9080\" , \"hook\" : \"patient-view\" , \"context\" : { \"userId\" : \"Practitioner/example\" }, \"extension\" : { \"com.example.timestamp\" : \"2017-11-27T22:13:25Z\" , \"com.cds-hooks.sandbox.myextension-practitionerspecialty\" : \"gastroenterology\" } } As another example, an extension defined on the discovery response could look like this: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 { \"services\" : [ { \"title\" : \"Example CDS Service Discovery\" , \"hook\" : \"patient-view\" , \"id\" : \"patientview\" , \"prefetch\" : { \"patient\" : \"Patient/{{context.patientId}}\" }, \"description\" : \"clinical decision support for patient view\" , \"extension\" : { \"com.example.clientConformance\" : \"http://hooks.example.org/fhir/102/Conformance/patientview\" } } ] }","title":"Extensions"},{"location":"specification/current/#data-types","text":"CDS Hooks leverages json data types throughout. This section defines data structures re-used across the specification.","title":"Data Types"},{"location":"specification/current/#coding","text":"The Coding data type captures the concept of a code. A code is understood only when the given code, code-system, and a optionally a human readable display are available. This coding type is a standalone data type in CDS Hooks modeled after a trimmed down version of the FHIR Coding data type . Field Optionality Type Description code REQUIRED string The code for what is being represented system REQUIRED string The codesystem for this code . display CONDITIONAL string A short, human-readable label to display. REQUIRED for Override Reasons provided by the CDS Service, OPTIONAL for Topic .","title":"Coding"},{"location":"specification/current/#hooks","text":"","title":"Hooks"},{"location":"specification/current/#overview_1","text":"As a specification, CDS Hooks does not prescribe a default or required set of hooks for implementers. Rather, the set of hooks defined here are merely a set of common use cases that were used to aid in the creation of CDS Hooks. The set of hooks defined here are not a closed set; anyone is able to define new hooks to fit their use cases and propose those hooks to the community. New hooks are proposed in a prescribed format using the documentation template by submitting a pull request for community feedback. Hooks are versioned , and mature according to the Hook Maturity Model . Note that each hook (e.g. order-select ) represents something the user is doing in the CDS Client and multiple CDS Services might respond to the same hook (e.g. a \"price check\" service and a \"prior authorization\" service might both respond to order-select ).","title":"Overview"},{"location":"specification/current/#hook-context-and-prefetch","text":"","title":"Hook context and prefetch"},{"location":"specification/current/#whats-the-difference","text":"Any user workflow or action within a CDS Client will naturally include contextual information such as the current user and patient. CDS Hooks refers to this information as context and allows each hook to define the information that is available in the context. Because CDS Hooks is intended to support usage within any CDS Client, this context can contain both required and optional data, depending on the capabilities of individual CDS Clients. However, the context information is intended to be relevant to most CDS Services subscribing to the hook. For example, consider a simple patient-view hook that is invoked whenever the user views a patient's information within the CDS Client. At this point in the workflow, the contextual information would include at least the current user and the patient that is being viewed. The hook declares this as context , and passes it to the CDS Service as part of the request in the context field: 1 2 3 4 \"context\" :{ \"userId\" : \"PractitionerRole/123\" , \"patientId\" : \"1288992\" } Prefetch data, on the other hand, is defined by CDS Services as a way to allow the CDS Client to provide the data that a CDS Service needs as part of the initial request to the service. When the context data relates to a FHIR resource, it is important not to conflate context and prefetch. For instance, in the hook described above for opening a patient's chart, the hook context includes the id of the patient whose chart is being opened, not the full patient FHIR resource. In this case, the FHIR id of the patient is appropriate as the CDS Services may not be interested in details from the patient resource but instead other data related to this patient. Therefore, including the full patient resource in context would be unnecessary. Alternatively, a CDS Service may need the full patient resource in certain scenarios, in which case they can fetch it as needed from the FHIR server or request it to be prefetched using a prefetch template in their discovery response, such as: 1 2 3 \"prefetch\" : { \"patientToGreet\" : \"Patient/{{context.patientId}}\" } See the section on prefetch tokens for more information on how contextual information can be used to parameterize prefetch templates. Consider another hook for when a new patient is being registered. In this case, it would likely be appropriate for the context to contain the full FHIR resource for the patient being registered as the patient may not be yet recorded in the CDS Client (and thus not available from the FHIR server) and CDS Services using this hook would predominantly be interested in the details of the patient being registered. Additionally, consider a PGX CDS Service and a Zika screening CDS Service, each of which is subscribed to the same hook. The context data specified by their shared hook should contain data relevant to both CDS Services; however, each service will have other specific data needs that will necessitate disparate prefetch requests. For instance, the PGX CDS Service likely is interested in genomics data whereas the Zika screening CDS Service will want Observations. In summary, context is specified in the hook definition to guide developers on the information available at the point in the workflow when the hook is triggered. Prefetch data is defined by each CDS Service because it is specific to the information that service needs in order to process.","title":"What's the difference?"},{"location":"specification/current/#hook-definition-format","text":"Hooks are defined in the following format.","title":"Hook Definition Format"},{"location":"specification/current/#hook-name-expressed-as-noun-verb","text":"The name of the hook SHOULD succinctly and clearly describe the activity or event. Hook names are unique so hook creators SHOULD take care to ensure newly proposed hooks do not conflict with an existing hook name. Hook creators SHALL name their hook with reverse domain notation (e.g. org.example.patient-transmogrify ) if the hook is specific to an organization. Reverse domain notation SHALL not be used by a standard hooks catalog. When naming hooks, the name should start with the subject (noun) of the hook and be followed by the activity (verb). For example, patient-view (not view-patient ) or order-sign (not sign-order ).","title":"hook-name-expressed-as-noun-verb"},{"location":"specification/current/#workflow","text":"Describe when this hook occurs in a workflow. Hook creators SHOULD include as much detail and clarity as possible to minimize any ambiguity or confusion among implementers.","title":"Workflow"},{"location":"specification/current/#context","text":"Describe the set of contextual data used by this hook. Only data logically and necessarily associated with the purpose of this hook should be represented in context. All fields defined by the hook's context MUST be defined in a table where each field is described by the following attributes: Field: The name of the field in the context JSON object. Hook authors SHOULD name their context fields to be consistent with other existing hooks when referring to the same context field. Optionality: A string value of either REQUIRED or OPTIONAL Prefetch Token: A string value of either Yes or No , indicating whether this field can be tokenized in a prefetch template. 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. The table below illustrates a sample hook context table: Field Optionality Prefetch Token Type Description someField REQUIRED Yes string A clear description of the value of this field. anotherField OPTIONAL No number A clear description of the value of this field. someObject REQUIRED No object A clear description of the value of this field. 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.","title":"Context"},{"location":"specification/current/#fhir-resources-in-context","text":"For context fields that may contain multiple FHIR resources, the field SHOULD be defined as a FHIR Bundle, rather than as an array of FHIR resources. For example, multiple FHIR resources are necessary to describe all of the orders under review in the order-sign hook's draftOrders 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, imagine a hook, order-select that is invoked when a user selects a medication during an order workflow. The context data for this hook would contain draft FHIR resources representing the medications that have been selected for ordering. In this case, the CDS Client 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.","title":"FHIR resources in context"},{"location":"specification/current/#examples","text":"Hook creators SHOULD include examples of the context. 1 2 3 4 5 6 7 8 9 \"context\" :{ \"someField\" : \"foo\" , \"anotherField\" : 123 , \"someObject\" : { \"color\" : \"red\" , \"version\" : 1 }, \"moreObjects\" :[] } If the context contains FHIR data, hook creators SHOULD include examples across multiple versions of FHIR if differences across FHIR versions are possible.","title":"Examples"},{"location":"specification/current/#hook-maturity-model","text":"The intent of the CDS Hooks Maturity Model is to attain broad community engagement and consensus, before a hook is labeled as mature, that the hook is necessary, implementable, and worthwhile to the CDS Services and CDS Clients that would reasonably be expected to use it. Implementer feedback should drive the maturity of new hooks. Diverse participation in open developer forums and events, such as HL7 FHIR Connectathons, is necessary to achieve significant implementer feedback. The below criteria will be evaluated with these goals in mind. 1 Hook maturity | 3 - Considered The Hook maturity levels use the term CDS Client to generically refer to the clinical workflow system in which a CDS Services returned cards are displayed. Maturity Level Maturity title Requirements 0 Draft Hook is defined according to the hook definition format . 1 Submitted The above, and \u2026 Hook definition is written up as a github pull request using the Hook template and community feedback is solicited on the zulip CDS Hooks stream . 2 Tested The above, and \u2026 The hook has been tested and successfully supports interoperability among at least one CDS Client and two independent CDS Services using semi-realistic data and scenarios (e.g. at a FHIR Connectathon). The github pull request defining the hook is approved and published by the CDS Hooks Project Management Committee. 3 Considered The above, and \u2026 At least 3 distinct organizations recorded ten distinct implementer comments (including a github issue, tracker item, or comment on the hook definition page), including at least two CDS Clients and three independent CDS Services. The hook has been tested at two Connectathons. 4 Documented The above, and \u2026 The author agrees that the artifact is sufficiently stable to require implementer consultation for subsequent non-backward compatible changes. The hook is implemented in the standard CDS Hooks sandbox and multiple prototype projects. The Hook specification SHALL: Identify a broad set of example contexts in which the hook may be used with a minimum of three, but as many as 8-10. Clearly differentiate the hook from similar hooks or other standards to help an implementer determine if the hook is correct for their scenario. Explicitly document example scenarios when the hook should not be used. 5 Mature The above, and ... The hook has been implemented in production in at least two CDS Clients and three independent CDS Services. An HL7 working group ballots the hook and the hook has passed HL7 STU ballot. 6 Normative The above, and ... the responsible HL7 working group and the CDS working group agree the material is ready to lock down and the hook has passed HL7 normative ballot","title":"Hook Maturity Model"},{"location":"specification/current/#changes-to-a-hook","text":"Each hook MUST include a Metadata table at the beginning of the hook with the specification version and hook version as described in the following sections.","title":"Changes to a Hook"},{"location":"specification/current/#specification-version","text":"Because hooks are such an integral part of the CDS Hooks specification, hook definitions are associated with specific versions of the specification. The hook definition MUST include the version (or versions) of the CDS Hooks specification that it is defined to work with. 1 specificationVersion | 1.0 Because the specification itself follows semantic versioning, the version specified here is a minimum specification version. In other words, a hook defined to work against 1.0 should continue to work against the 1.1 version of CDS Hooks. However, a hook that specifies 1.1 would not be expected to work in a CDS Hooks 1.0 environment.","title":"Specification Version"},{"location":"specification/current/#hook-version","text":"To enable tracking of changes to hook definitions, each hook MUST include a version indicator, expressed as a string. 1 hookVersion | 1.0 To help ensure the stability of CDS Hooks implementations, once a hook has been defined (i.e. published with a particular name so that it is available for implementation), breaking changes MUST NOT be made. This means that fields can be added and restrictions relaxed, but fields cannot be changed, and restrictions cannot be tightened. In particular, the semantics of a hook (i.e. the meaning of the hook from the perspective of the CDS Client) cannot be changed. CDS Clients 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 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 Major 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 Change of semantics of an existing context field Major Change of semantics of the hook Major When a major change is made, the hook definition MUST be published under a new name. When a minor or patch change is made, the hook version MUST be updated. Hook definers MUST use semantic versioning to communicate the impact of changes in an industry standard way. Note that the intent of this table is to outline possible breaking changes. The authors have attempted to enumerate these types of changes exhaustively, but as new types of breaking changes are identified, this list will be updated.","title":"Hook Version"},{"location":"specification/current/#hook-maturity","text":"As each hook progresses through a process of being defined, tested, implemented, used in production environments, and balloted, the hook's formal maturity level increases. Each hook has its own maturity level, which MUST be defined in the hook's definition and correspond to the Hook Maturity Model . 1 hookMaturity | 0 - Draft","title":"Hook Maturity"},{"location":"specification/current/#change-log","text":"Changes made to a hook's definition MUST be documented in a change log to ensure hook consumers can track what has been changed over the life of a hook. The change log MUST contain the following elements: Version: The version of the change Description: A description of the change and its impact For example: Version Description 1.1 Added new context variable 1.0.1 Clarified context variable usage 1.0 Initial Release","title":"Change Log"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 622e1f3d..4d2eba0b 100644
Binary files a/sitemap.xml.gz and b/sitemap.xml.gz differ