diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 0c2e1632..76fcc374 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -2,8 +2,8 @@ - [Overview](#overview) - [Roles](#roles) - - [Project Management Committee](#project-management-committee) - [Committers](#committers) + - [Project Management Committee](#project-management-committee) - [PMC Chair](#pmc-chair) - [Contributors](#contributors) - [Implementers](#implementers) diff --git a/docs/hooks/appointment-book.md b/docs/hooks/appointment-book.md index 8d3ce347..605141a1 100644 --- a/docs/hooks/appointment-book.md +++ b/docs/hooks/appointment-book.md @@ -1,10 +1,16 @@ # `appointment-book` +!!! info "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 | [3 - Considered](../../specification/current/#hook-maturity-model) +| hookMaturity | [1 - Submitted](../../specification/current/#hook-maturity-model) ## Workflow @@ -127,7 +133,7 @@ Field | Optionality | Prefetch Token | Type | Description "userId" : "PractitionerRole/A2340113", "patientId" : "1288992", "encounterId" : "456", - "appointment" : [ + "appointments" : [ { "resourceType": "Appointment", "id": "example", diff --git a/docs/hooks/encounter-discharge.md b/docs/hooks/encounter-discharge.md index d5f81f21..5d6326c7 100644 --- a/docs/hooks/encounter-discharge.md +++ b/docs/hooks/encounter-discharge.md @@ -4,7 +4,7 @@ | ---- | ---- | specificationVersion | 1.0 | hookVersion | 1.0 -| hookMaturity | [3 - Considered](../../specification/current/#hook-maturity-model) +| hookMaturity | [1 - Submitted](../../specification/current/#hook-maturity-model) ## Workflow diff --git a/docs/hooks/encounter-start.md b/docs/hooks/encounter-start.md index f434bb11..9d068a57 100644 --- a/docs/hooks/encounter-start.md +++ b/docs/hooks/encounter-start.md @@ -1,5 +1,14 @@ # `encounter-start` +!!! info "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 diff --git a/docs/hooks/medication-refill.md b/docs/hooks/medication-refill.md new file mode 100644 index 00000000..6f0d16fe --- /dev/null +++ b/docs/hooks/medication-refill.md @@ -0,0 +1,172 @@ +# `medication-refill` + +| Metadata | Value +| ---- | ---- +| specificationVersion | 2.0 +| hookVersion | 0.1.0 +| hookMaturity | [1 - Submitted](../../specification/current/#hook-maturity-model) + + +## Workflow + +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 + +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) + +```json +{ + "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) + +```json +{ + "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 + +Version | Description +---- | ---- +0.1.0 | Initial Release diff --git a/docs/hooks/order-dispatch.md b/docs/hooks/order-dispatch.md index e5216410..f4bc1be2 100644 --- a/docs/hooks/order-dispatch.md +++ b/docs/hooks/order-dispatch.md @@ -3,12 +3,12 @@ | Metadata | Value | ---- | ---- | specificationVersion | 2.0 -| hookVersion | 1.0 +| hookVersion | 1.1 | hookMaturity | [0 - Draft](../../specification/current/#hook-maturity-model) ## Workflow -The `order-dispatch` hook fires when a practitioner is selecting a candidate performer for a pre-existing order that was not tied to a specific performer. For example, selecting an imaging center to satisfy a radiology order, selecting a cardiologist to satisfy a referral, etc. This hook only occurs in situations where the order is agnostic as to who the performer should be and a separate process (which might be performed by back-office staff, a central dispatch service, or even the ordering clincian themselves at a later time) is used to select and seek action by a specific performer. It is possible that the same order might be dispatched multiple times, either because initial selected targets refuse or are otherwise unable to satisfy the order, or because the performer is only asked to perform a 'portion' of what's authorized (the first monthly lab test of a year-long set, the first dispense of a 6 month order, etc.) +The `order-dispatch` hook fires when a practitioner is selecting a candidate performer for a pre-existing order or (set of orders) that was not assigned to a specific performer. For example, selecting an imaging center to satisfy a radiology order, selecting a cardiologist to satisfy a referral, etc. This hook only occurs in situations where the order is agnostic as to who the performer should be and a separate process (which might be performed by back-office staff, a central dispatch service, or even the ordering clincian themselves at a later time) is used to select and seek action by a specific performer. It is possible that the same order might be dispatched multiple times, either because initial selected targets refuse or are otherwise unable to satisfy the order, or because the performer is only asked to perform a 'portion' of what's authorized (the first monthly lab test of a year-long set, the first dispense of a 6 month order, etc.). Note that the order isn't updated to include the performer in this situation, as the authorization of who could theoretically perform the order isn't changed by seeking fulfillment by a specific provider. This "request for fulfillment" process is typically represented in FHIR using [Task](http://hl7.org/fhir/task.html). This resource allows identifying the order to be acted upon, who is being asked to act on it, the time-period in which they're expected to act, and any limitations/qualifications to 'how much' of the order should be acted on. @@ -19,25 +19,26 @@ Decision support that may be relevant for this hook might include information re Field | Optionality | Prefetch Token | Type | Description ----- | -------- | ---- | ---- | ---- `patientId` | REQUIRED | Yes | *string* | The FHIR `Patient.id` of the current patient in context -`order` | REQUIRED | Yes | *string* | The FHIR local reference for the Request resource for which fulfillment is sought E.g. `ServiceRequest/123` +`dispatchedOrders` | REQUIRED | Yes | *array* | Collection of the FHIR local references for the Request resource(s) for which fulfillment is sought E.g. `ServiceRequest/123` `performer` | REQUIRED | Yes | *string* | The FHIR local reference for the Practitioner, PractitionerRole, Organization, CareTeam, etc. who is being asked to execute the order. E.g. `Practitioner/456` -`task` | OPTIONAL | No | *object* | DSTU2/STU3/R4 - Task instance that provides a full description of the fulfillment request - including the timing and any constraints on fulfillment +`fulfillmentTasks` | OPTIONAL | No | *array* | DSTU2/STU3/R4/R5 - Collection of the Task instances (as objects) that provides a full description of the fulfillment request - including the timing and any constraints on fulfillment. If Tasks are provided, each will be for a separate order and SHALL reference one of the dispatched-orders. -### Examples +## Examples +### Example (R4) ```json "context":{ "patientId" : "1288992", - "order" : "ServiceRequest/proc002", + "dispatched-orders" : ["ServiceRequest/proc002"], "performer" : "Organization/some-performer", - "task" : { + "fulfillment-tasks" : [{ "resourceType" : "Task", "status" : "draft", "intent" : "order", "code" : { "coding" : [{ - "system" : "", - "code" : "" + "system" : "http://hl7.org/fhir/CodeSystem/task-code", + "code" : "fulfill" }] }, "focus" : { @@ -54,7 +55,7 @@ Field | Optionality | Prefetch Token | Type | Description "owner" : { "reference" : "Organziation/some-performer" } - } + }] } ``` @@ -63,3 +64,4 @@ Field | Optionality | Prefetch Token | Type | Description Version | Description ---- | ---- 1.0 | Initial Release +1.1 | Adjusted context names and cardinalities based on feedback diff --git a/docs/hooks/order-select.md b/docs/hooks/order-select.md index c5d42e06..23d8a813 100644 --- a/docs/hooks/order-select.md +++ b/docs/hooks/order-select.md @@ -8,18 +8,19 @@ ## Workflow -The `order-select` hook fires when a clinician selects one or more orders to place for a patient, (including orders for medications, procedures, labs and other orders). If supported by the CDS Client, this hook may also be invoked each time the clinician selects a detail regarding the order. -This hook is among the first workflow events for an order entering a draft status. -The context of this hook may include defaulted order details -as it first occurs immediately upon the clinician selecting the order from the order catalogue of the CPOE, or upon her manual selection of order details (e.g. dose, quantity, route, etc). CDS services should expect some of the order information to not yet be specified. -Additionally, the context may include previously selected orders that are not yet signed from the same ordering session. -The `order-select` hook occurs after the clinician selects the order and before signing. +The order-select hook occurs after the clinician selects the order and before signing. -This hook is intended to replace (deprecate) the `medication-prescribe` hook. +This hook occurs when a clinician initially selects one or more new orders from a list of potential orders for a specific patient (including orders for medications, procedures, labs and other orders). The newly selected order defines that medication, procedure, lab, etc, but may or may not define the additional details necessary to finalize the order. + +`order-select` is among the first workflow events for an order entering a draft status. The context of this hook may include defaulted order details upon the clinician selecting the order from the order catalogue of the CPOE, or upon her manual selection of order details (e.g. dose, quantity, route, etc). CDS services should expect some of the order information to not yet be specified. Additionally, the context may include previously selected orders that are not yet signed from the same ordering session. + +This hook is intended to replace (deprecate) the medication-prescribe hook. + +![Ordering Flow Diagram](../images/orderingflow.png) ## Context -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). +Decision support should focus on the 'selected' orders - those that are newly selected or currently 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 @@ -28,9 +29,14 @@ Field | Optionality | Prefetch Token | Type | Description `patientId` | REQUIRED | Yes | *string* | The FHIR `Patient.id` of the current patient in context `encounterId` | OPTIONAL | Yes | *string* | The FHIR `Encounter.id` of the current encounter in context `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 +`draftOrders` | REQUIRED | No | *object* | A Bundle of FHIR request resources with a draft status, representing orders that aren't yet signed from the current ordering session. +### A Note Concerning FHIR Versions +CDS Hooks is designed to be agnostic of FHIR version. For example, all versions of FHIR can represent in-progress orders but over time, the specific resource name and some of the important elements have changed. Below are some of the mosty commonly used FHIR resources for representing an order in CDS Hooks. This list is intentionally not comprehensive. +* DSTU2 - FHIR Bundle of MedicationOrder, ProcedureRequest +* STU3 - FHIR Bundle of MedicationRequest, ProcedureRequest +* R4 - FHIR Bundle of MedicationRequest, ServiceRequest ## Examples diff --git a/docs/hooks/order-sign.md b/docs/hooks/order-sign.md index f0d7852e..a1514c72 100644 --- a/docs/hooks/order-sign.md +++ b/docs/hooks/order-sign.md @@ -12,10 +12,17 @@ The `order-sign` hook fires when a clinician is ready to sign one or more orders This hook is among the last workflow events before an order is promoted out of a draft status. The context contains all order details, such as dose, quantity, route, etc, although the order has not yet been signed and therefore still exists in a draft status. -Use this hook when your service requires all order details, and the clinician will accept recommended changes. +Use this hook when your service requires all order details. + +This hook can also be used when an order or set of orders is being 're-signed' after revision (e.g. change +to status, extending dates, or other changes allowed to signed orders within the system's workflow). In this +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. +![Ordering Flow Diagram](../images/orderingflow.png) + ## Context Field | Optionality | Prefetch Token | Type | Description @@ -23,9 +30,14 @@ 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](https://www.hl7.org/fhir/practitioner.html) or [PractitionerRole](https://www.hl7.org/fhir/practitionerrole.html).
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 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 +`draftOrders` | REQUIRED | No | *object* | A Bundle of FHIR request resources with a draft status, representing orders that aren't yet signed from the current ordering session. +### A Note Concerning FHIR Versions +CDS Hooks is designed to be agnostic of FHIR version. For example, all versions of FHIR can represent in-progress orders but over time, the specific resource name and some of the important elements have changed. Below are some of the mosty commonly used FHIR resources for representing an order in CDS Hooks. This list is intentionally not comprehensive. +* DSTU2 - FHIR Bundle of MedicationOrder, ProcedureRequest +* STU3 - FHIR Bundle of MedicationRequest, ProcedureRequest +* R4 - FHIR Bundle of MedicationRequest, ServiceRequest ## Examples @@ -543,3 +555,4 @@ 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 diff --git a/docs/images/orderingflow.png b/docs/images/orderingflow.png new file mode 100644 index 00000000..f2a6ce52 Binary files /dev/null and b/docs/images/orderingflow.png differ diff --git a/docs/images/orderingflow.svg b/docs/images/orderingflow.svg new file mode 100644 index 00000000..a6ff14bd --- /dev/null +++ b/docs/images/orderingflow.svg @@ -0,0 +1,116 @@ + + + + + + + + + + + Open CPOE + + + + + + + + + + + + + + + + Select product + + + + + + + + order-select + + + + + + + order-select fires at the beginning + + + + + + + + + + + + Select route + + + + + + + + Select frequency + + + + + + + + Select duration + + + + + + + + Link Order & misc + + + + + + + + + + + + + + + + + Sign order + + + + + + + + order-sign + + + + + + + order-sign at the end + + + + + + diff --git a/mkdocs.yml b/mkdocs.yml index 3bc942fd..03dfe897 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,9 +24,10 @@ nav: - 'order-review 🚫' : 'hooks/order-review.md' - 'order-select 4' : 'hooks/order-select.md' - 'order-sign 5' : 'hooks/order-sign.md' - - 'appointment-book 3' : 'hooks/appointment-book.md' + - 'appointment-book 1' : 'hooks/appointment-book.md' - 'encounter-start 1' : 'hooks/encounter-start.md' - - 'encounter-discharge 3' : 'hooks/encounter-discharge.md' + - 'encounter-discharge 1' : 'hooks/encounter-discharge.md' + - 'medication-refill 1' : 'hooks/medication-refill.md' - 'problem-list-item-create 1' : 'hooks/problem-list-item-create.md' - Quick Start: 'quickstart.md' - Cheat Sheet: 'cheat-sheet/Cheat Sheet - Sept 2019.pdf'