CDS Hooks website & specification
Home Page: http://cds-hooks.org
License: Apache License 2.0
This repository is unused by archived here for posterity.
Instead, please visit:
From @jmandel on May 11, 2016 15:45
Providing "trigger guards" for CDS Service Invocation: We’ve encountered several CDS services that are only relevant for a particular set of patients. For instance, a bilirubin CDS service would only be of interest to newborns, so it would be optimal if the EHR would only call the service for that subset of qualifying patients. It would be great to have a discussion around this topic and see if we can at least define conventions for how this is documented in CDS services.
Copied from original issue: cds-hooks/cds-hooks#17
I would like to suggest that Prefetch (in CDS Request) be defined as a Parameters resource. This way we can include any kind of resource, including OperationOutcomes, esp. for those pre-fetch requests that fail (to possibly address a comment by @jmandel in #5 ). This would also increase the flexibility in specifying the type of parameter value (i.e., value[x], resource
or part), including not limiting the parameter value to a resource.
I have a service that should lower the dosage of a given medication.
On the test harness (http://demo.cds-hooks.org/) this doesn't affect the CDS context in any way, only changes in the medicationCodeableConcept seems to trigger refreshes and actually update the medication.
The following services try this scenario can be found at:
The I am using the following structure for the suggestions JSON:
{
...
"suggestions": [
{
"label": "Lower to suggested",
"uuid": "00001",
"create": [
{
"resourceType": "MedicationOrder",
"dateWritten": "2017-05-07",
"status": "draft",
"patient":
{
"reference": "Patient/1288992"
},
"dosageInstruction": [
{
"doseQuantity":
{
"value": 1,
"system": "http://unitsofmeasure.org",
"code": "{pill}"
},
"timing":
{
"repeat":
{
"frequency": 1,
"period": 1,
"periodUnits": "d",
"boundsPeriod":
{
"start": "2017-05-07",
"end": "2017-06-07"
}
}
}
}
],
"medicationCodeableConcept":
{
"text": "Aspirin 325 MG / butalbital 50 MG / Caffeine 40 MG / Codeine Phosphate 30 MG Oral Capsule [Ascomp]",
"coding": [
{
"display": "Aspirin 325 MG / butalbital 50 MG / Caffeine 40 MG / Codeine Phosphate 30 MG Oral Capsule [Ascomp]",
"system": "http://www.nlm.nih.gov/research/umls/rxnorm",
"code": "994239"
}
]
}
}
]
}
]
}
It is my understanding that decisions are not meant to direct the EMR to perform the decision action (create/delete). Instead they're meant to be a notification to the EMR after the action has already been executed (out of band) by the CDS vendor.
The documentation needs to reflect this understanding, as it is easy to misunderstand and assume that decision should cause the EMR to perform the requested updates.
In discussion with @brynrhodes and @kpshek regarding aligning Clinical Reasoning and CDS Hooks, one of the topics of discussion was around the functionality of the FHIR Clinical Reasoning RequestGroup resource. Overall, FHIR's RequestGroup is very powerful, but it also introduces a lot of complexity as well as a dependence upon STU3.
How to pragmatically and simply incorporate the best parts of RequestGroup into CDS Hooks, while also allowing for compatibility with this FHIR resource? Here's the direction that @brynrhodes, @kpshek, and myself landed on:
An array of actions should be added to the CDS Hooks suggestion, such that a card can return multiple suggestions, of which the user can select one. Each suggestion contains a list of actions. When a user selects a suggestion that contains multiple actions, the user is selecting all of the actions within that suggestion. Here's what this looks like in json:
“suggestions”: [
// EHRs should render suggestions to the user as
// ANY suggestion can be selected
{
“uuid”: “abc1238hdf87sh”,
“label”: “Add & remove”,
“actions”: [
// Actions are ANDed together
{
“type”: “create”,
“description”: “Add this new order for X”,
“resource”: { resource X }
},
{
“type”: “delete”,
“description”: “Cancel the existing order”,
“resource”: “MedicationRequest/123”
}
]
},
{
“uuid”: “n9d89hsdg8h”,
“label”: “Modify warfarin”,
“actions”: [
{
“type”: “modify”,
“description”: “Change warfarin dosage to 10mg/day”,
“resource”: "MedicationRequest/abc"
}
]
}
]
Note that each suggestion is implicitly OR’d and that the actions within a suggestion are AND’d. This intentionally does not support the additional feature and complexity of Clinical Reasoning’s RequestGroup selectionBehavior. Additionally each suggestion is implicitly a “visual-group” in the same way as Clinical Reasoning's RequestGroup’s groupingBehavior.
From @jmandel on March 12, 2016 3:28
If you've successfully exposed a CDS Service, write up your experience as a developer tutorial. Explain the toolset you used, and describe the integration process in a set-by-step fashion.
Bonus points if you can provide an easy way for developers to "follow along at home"!
Copied from original issue: cds-hooks/cds-hooks#2
CDS Services will undoubtably be coded to a particular version of FHIR. Should they expose the expected FHIR version as part of the discovery endpoint?
Production EHR vendors will likely support multiple versions of FHIR. If an EHR knows what FHIR version the CDS Service excepts, it can invoke the service with the appropriate FHIR URL.
This is analogous to what Cerner is doing today with their support of SMART apps. The Cerner system stores the FHIR version the SMART app expects and uses this information when launching SMART apps to send it the desired FHIR URL for the expected FHIR version. Note that this is not part of the SMART specification but an out-of-band step that is being done. However, with our discovery endpoint in CDS Hooks, we have an opportunity to formally define this.
(Logging this here for discussion at the HL7 Connecthaton in Baltimore Sept 17-18, 2016)
Our documentation needs to clearly define the prefetching expectations of both the EHR and CDS Service. Ultimately, the question that needs to be answered is:
When a CDS Service requested prefetched data, is this a hint to the EHR or a requirement?
If prefetching is a requirement, should the EHR communicate to the CDS Service that it cannot fulfill the prefetch request?
Is it OK if the EHR can prefetch some of the requested data but not all?
Also see the past discussion over on this defunct issue.
@mjhenkes pointed out that for sources we use name but links and suggestions use label for effectively the same thing. I propose we rename source.name to source.label for API consistency.
👍 👎 requested from @jmandel & @isaacvetter before I start implementing this change
In discussion with @brynrhodes and @isaacvetter regarding aligning Clinical Reasoning and CDS Hooks, one of the topics of discussion was around how hooks are defined today.
For instance, the medication-prescribe hook is very loosely defined today with just a brief mention of the context data that is sent on this type of hook request.
We should do the following:
context in the CDS Service request.From @jmandel on March 17, 2016 20:14
Two main use cases for authentication / authorization
For (1), we could use a signed JWT in a header. Or an OAuth flow.
For (2) we have a current solution (passing OAuth tokens in the input parameters to $cds-hook). Is this good enough?
Copied from original issue: cds-hooks/cds-hooks#12
The examples in our current documentation are trivial and lack any clinical relevance. We should add more complex, clinically relevant examples of JSON data (especially in the CDS service response) to our documentation. This will help illustrate what is possible with CDS Hooks.
Related to this, @robs16 made a great suggestion over in #19 to leverage Choosing Wisely when determining appropriate clinically relevant sources.
Reposting from Zulip to gather feedback:
In looking over the proposed security model I have a few questions that are somewhat inter-related:
I may be missing something in the documentation on SMART and in the proposed security model, but I do not understand how the app pointed at by link.url authenticates to the CDS service. There is no requirement that they are the same, yet the app will generally need to access the CDS service (probably more often than the FHIR service) and will need to reference the session created by the request that provided the link.url. This applies equally to the non-SMART app. I am assuming that authentication would need to be part of the URL?
How will the analytics endpoints be authenticated by the service? How will the service know which hookInstance an analytics request is about?
Depending on the answers from 1 and 2, both link.url and the analytic endpoints have a fixed string which may contain authentication credentials. To maintain security, these must have a timeout and may be one-time in nature. How do we inform the EMR of this? I mean there is nothing that says that a displayed card needs to be acted on within an hour, a day, a week, month, etc.
Proposed JWT aud. What does this refer to? The specific endpoint, a prefix to it, or a token request endpoint? ie: 'https://example.com/cds-services', 'https://example.com/cds-services/medication-echo', 'https://example.com/cds-services/medication-echo/analytics/C919155B-2138-4177-A316-524CB48B4EC9', 'https://example.com/token'
The JWT issuer is based on the associated FHIR server. I think there is an implicit assumption that this issuer will contain the client/practice for cloud EHR providers. I am unsure if this solves all of the nuances of working with a cloud EHR vs a single EHR. Are there cases where an EHR and a FHIR server are not 1 to 1?
The link at the bottom of http://cds-hooks.org/#calling-a-cds-service doesn't work.
An EHR might allow users to take actions on CDS cards outside of clicking suggestion buttons or links. For example, the EHR could allow users to dismiss a card so that it no longer appears, ignoring any suggestions on the card. There is currently no mechanism in the CDS-hook spec that allows for the EHR to notify the CDS service that such an action has taken place.
The existing CDS-Hooks specification provides suggestion with only a label to describe them to the consuming EMR. However it is very common to have different types of suggestions which may be displayed or utilized differently by the EMR. Other than ‘accept’ suggestions which may add, remove, or modify the order, it is useful to capture the reasons a user decided not to accept the suggested changes.
Please consider adding a Suggestion.type required field with values of ‘accept’, ‘override’, ‘prompt’, ‘dismiss’:
The suggestions structure with these changes might look similar to the following:
"suggestions": [
{
"type": "dismiss",
"label": "Dismiss",
"uuid": "27b525a4-71d7-4b01-b796-294178da5544"
},
{
"type": "accept",
"actions": [
{
"type": "delete",
"resource": "DiagnosticOrder/117262"
}
],
"label": "Remove Orders",
"uuid": "b0fefb6a-406b-4efb-b416-29a88118a066"
},
{
"type": "override",
"label": "Rapid eye movement sleep disorders",
"uuid": "f0a30281-d0cd-4eff-b105-d9a47c2ce324"
},
{
"type": "prompt",
"label": "Other (please specify)",
"uuid": "1e770724-3342-4b5c-802b-cc3e48880e44"
}
]
A 'prompt' type suggestion analytic post might include a body of the form:
{
"response": "End-of-life care"
}
Currently the CDS-Hooks specification uses the field ‘indicator’ in a card to describe two different concepts: the urgency/importance of the card, and how the workflow within the EMR should process the card. While these two concepts are somewhat similar and may appear to overlap, they are distinct. The urgency/importance indicates to the EMR how to display the card to the end-user. The workflow processing indicates if the user can dismiss/ignore the card, must explicitly accept a suggestion or provide a reason for not accepting a suggestion, or has no choice but to accept a suggestion.
We would like to suggest modifying Card.indicator to remove ‘hard-stop’ as it explicitly is indicating a workflow processing approach, and add Card.workflowImpact required field with values of ‘no-stop’, ‘soft-stop’, ‘medium-stop’, and ‘hard-stop’:
Note that these workflowImpact values tell the EMR how the CDS service believes the EMR should behave. It is up to the EMR to determine how that impacts the user's actual workflow. In other words, it is a suggestion, not a demand.
When it comes to service discovery, it may make sense for the CDS service discovery endpoint to interrogate the CapabilityStatement of the EHR that is attempting service discovery.
This would allow a service discovery endpoint to be able to determine if the EHR in question supports the necessary FHIR resources and is of an appropriate version to successfully interact with the CDS service and filter out responses as necessary.
This might require calls to /cds-services to include an iss parameter.
In discussion with @brynrhodes and @kpshek regarding aligning Clinical Reasoning and CDS Hooks, one of the topics of discussion was around the ability of a user to "unsubscribe" from a card.
It would make a lot of clinicians happy if they were able to unsubscribe from a card. This information would also be valuable to CDS services.
It would make sense to enhance the analytics-endpoint to support this additional information.
Overall, the analytics-endpoint that's currently defined in the CDS Hooks specification has not yet seen significant adoption, although it's clearly a useful feature to CDS services.
Copying over from cds-hooks/cds-hooks#14:
@jmandel said:
Should include:
http://cds.medapptech.com
http://hooks.fhir.me:8082
In discussion with @brynrhodes and @isaacvetter regarding aligning Clinical Reasoning and CDS Hooks, one of the topics of discussion was around ServiceDefinition.date.
ServiceDefinition is comparable to an individual CDS Service defined within the Discovery endpoint. ServiceDefinition supports an optional field, date, which allows the developer to indicate when changes are made to the underlying service. The intended use of this field is for tooling utilized by organizations to configure CDS services within their workflow, providing users with visibility to changes within the service.
When discussing whether a similar concept made sense to support within CDS Hooks, we looked at existing concepts with the HTTP spec which may fill this gap. We landed upon the Last-Modified (see also rfc2616) HTTP response header which can be used to indicate when changes were made to a resource.
Using the Last-Modified header doesn't provide a direct corollary to ServiceDefinition.date as it is more coarse-grainted. The Last-Modified value would apply to all CDS Services within the Discovery endpoint whereas ServiceDefinition.date is specific to an individual CDS Service. However, using Last-Modified allows us to take advantage of native HTTP features and there wasn't a strong opinion the fine-grained model was necessary.
In order to move forward with this, we would document that CDS Server providers can optionally populate the Last-Modified header and update it when changes are made to their CDS Services. EHRs can then use this value to know when changes have occurred.
As always, feedback from the community is welcome!
In discussion with @brynrhodes and @kpshek regarding aligning Clinical Reasoning and CDS Hooks, one of the topics of discussion was around use of CDS Hooks in infobutton-type scenarios.
The HL7 Infobutton (Context aware knowledge retrieval) is a widely implemented standard for an EHR or other system to query an external clinical knowledgebase in realtime in a clinician's workflow. Contextual information (patient demographics, specific diagnosis, allergy, observation, etc) is included in the EHR's HTTP request. The knowledgebase's response is displayed to the clinician.
This is a specific use case of the CDS Hooks info card. Knowledgebases would benefit from having access to the caller's FHIR server, by receiving the OAuth access_token in the CDS Hooks request, the ability to return a full-featured SMART app, as well as the option of the more advanced remote CDS Hooks functionality .
We should consider building dedicated support of Infobutton in CDS Hooks. One approach would be to define an "infobutton" hook, that includes the existing key/value pairs defined by the HL7 Context aware knowledge retrieval (aka Infobutton) standard within the CDS Hooks request's context attribute. This could provide a straightforward path for platforms and knowledgebases to enhance their existing integrations to take advantages of the additional clinical data offered by an EHR's FHIR server, and other features.
API Docs say suggestion.create is a string, but swagger doc says it's an array of objects.
Our documentation around app links needs to be clarified. Questions that the documentation should answer:
Guideline appropriate ordering scoring cds services generate a score that rates the appropriateness of a particular order as well as a unique identifier that can be used to reference the advice after the fact.
In some cases, this score can be used to bypass prior authorization or in billing claims.
In the case where an alternate order (or perhaps even the same order?) is being recommended, a suggestion could be used and the existing uuid can identify the advice.
There's not a clear-cut location for the external GAO cds-service to return the score as a discrete piece of data.
This could be a significant use-case. It would be nice to accommodate it.
In discussion with @brynrhodes and @isaacvetter regarding aligning Clinical Reasoning and CDS Hooks, one of the topics of discussion was around how both projects handle the concept of prefetching data.
Prefetching aims to address the following:
In Clinical Reasoning, this concept is defined in the ServiceDefinition.dataRequirement using the DataRequirement type. Compared to our prefetch definition, DataRequirement is a much more constrained model. Based upon @brynrhodes implementation experience, the constraints of DataRequirements allow for the calculation of an optimal set of FHIR queries to satisfy multiple DataRequirements. Our current prefetch definition (any FHIR query) would not actually allow EHRs to achieve our 2nd goal above.
To help with this discussion, it would be good to take an inventory on the current prefetch FHIR queries for a variety of CDS Services that have been prototyped at Connectathons. With their feedback, we can see if constraining prefetch to the functionality of DataRequirements would still meet their needs.
In discussion with @brynrhodes and @isaacvetter, we had some questions that we should answer in the spec/documentation:
Markdown Support
Is Markdown required or an optional feature that EHRs can support? If Markdown is optional, it would be nice for EHRs to advertise their support for it so that CDS Services can return cards accordingly.
Markdown Flavor
What flavor of Markdown should CDS Hooks support? Eg, CommonMark? Github Flavored Markdown? etc.
Risks with Embedded HTML in Markdown
Markdown allows for any embedded HTML. Should this be allowed? If so, we need to document how EHRs must mitigate against risks of cards that now contain executable code (JS) or conflicts with CSS classes/names.
Risks with embedded HTML is actually no different than risks posed by embedding SMART apps in an EHR. However, we should probably call out good practices (like usage of iframes).
A potential difference between integrating SMART apps and CDS cards into the EHR is the level of integration we expect with CDS cards. The intention is that since the majority of a CDS card is structured data rather than UX (or entirely if there is no embedded HTML), then the rendering of the card should be close or indistinguishable from the native EHR.
Another point of consideration is that allowing for embedded HTML in the Markdown starts to veer CDS cards in the direction of mini SMART apps.
And finally, another option could be allowing for embedded HTML but only a subset of HTML functionality/tags (a whitelist). This would offer CDS cards the ability to style themselves somewhat but perhaps disallow them from incorporating app-like functionality.
Thoughts & discussions from the community is welcome!
The source within the Card structure is defined as:
the source of the information displayed on this card.
This is ambiguous as there are likely multiple sources which could be related to a card. This could refer to:
We believe that the source referenced in the Card structure should be the primary source of guidance and the documentation should clearly state this.
In discussion with @brynrhodes and @kpshek regarding aligning Clinical Reasoning and CDS Hooks, one of the topics of discussion was around the ability of the cds service to know when a suggestion was rejected by the end user.
Currently, our analytics endpoint accepts a uuid when "a button is clicked", as we necessarily complicate the suggestion model, this may not be sufficient to describe the actual suggestion accepted by the user and does not capture a concept of rejection.
This issue is related to, but not necessarily the same as #41. Overall, I think that we need to re-design the analytics endpoint, so that the cds service is able to improve its behavior and so that the end-user has a positive and meaningful experience with the cds.
Passing parameters between CDS Hook and SoF app launch (when hook provider and app provider are same and would like to use the state/context
Couple of use cases
Couple of straw men (Thx to @kpshek and @isaacvetter ) to start with.
A link in CDS card has params data
{
"summary": "Example Card",
"indicator": "info",
"detail": "This is an example card.",
"source": {
"label": "Static CDS Service Example",
"url": "https://example.com"
},
"links": [
{
"label": "Google",
"url": "https://google.com",
"type": "smart",
"params": "foo=a&bar=c"
}
]
}SMART launch URL param
EHR appends the params value to the SMART app launch URL. This is a change we’d want to put into SMART (to call out launch params by the SMART app) and take advantage of here in CDS Hooks.
http://&foo=a&bar=c&iss=xx&launch=xx
OAuth claim alongside access token during SMART launch
Similar to above, but the EHR passes the custom value in the CDS card SMART link alongside the access token during a SMART launch. In this case the value doesn’t have to be URL encoded
{
"need_patient_banner":true,
"patient":"123",
"encounter":"456",
"token_type":"Bearer",
"access_token":"....",
"id_token":"...",
"scope":"patient\/Patient.read patient\/Observation.read launch online_access openid profile",
"expires_in":570,
"params":"foo=a&bar=c"
}Other ideas / thoughts?
One of the issues we are contending with is the fact that occasionally the data we would need to provide complete decision support doesn't exist in neatly structured objects, and probably sits in some unstructured text or somewhere outside the reach of an EHR's FHIR server.
A way we were considering to get around this is a Suggestion card that is basically asking the user to 'make an observation', or more accurately 'structure this Observation in FHIR so we can use it for decision support'. The intention is to suggest this when the service becomes aware that some data should be available - a surgery is complete or a diagnostic report has returned. But this is an extension of the functionality of a suggestion card as we are requesting the user input data, not just select the card. "What was the distance to the closest surgical margin in that excision surgery", or "which histology was noted for the lesion in the biopsy" are examples. Some of these Observations might already be encoded (I'm not sure on how widespread CAP cancer protocols are in EMRs), but from what I understand they usually will not be.
We discussed the idea of sending a 'DataRequirement' in a suggestion card, but I suspect it this would be complicated for the EHR and require some pre-arranged agreement on the interpretation of a DataRequirement, removing the vendor agnostic aspect that is so attractive about CDS-Hooks.
Has anyone else thought about this sort of issue? Of course with SMART app interaction we can simply prompt the user and then return the structured Observation with the decisions. But for a situation where the doctor is viewing the pathology report and we have the opportunity to structure otherwise unstructured data, a suggestion card might be ideal. Structuring unstructured data is an issue in health informatics in general, and CDS-Hooks might allow a minimally intrusive way to ask a user to do so.
Each hook is specific to a FHIR version. (The prefetch URLs are version-specific.) Therefore a property should be added to "#/definitions/CDS Service" that specifies the FHIR version for that hook.
In discussion with @brynrhodes and @isaacvetter regarding aligning Clinical Reasoning and CDS Hooks, one of the topics of discussion was around how Clinical Reasoning allows the EHR to include to the CDS service that it should evaluate it's rules at the specified date/time (evaluteAt field). This is used for testing or debugging purposes in Clinical Reasoning.
rfc7089 defines an Accept-Datetime HTTP request header to accomplish this same functional goal. In our case, the EHR would send the Accept-Datetime HTTP header in the CDS Service request. The CDS Service would evaluate it's decision support logic as of this given datetime.
Per rfc7089, the CDS Service should also return a response header in this scenario with the Memento-Datetime HTTP header set to the datetime the decision support was evaluated at.
It is worth mentioning that in order for the decision support rules to be evaluated at an arbitrary datetime, all services and systems used by the CDS Service must be capable of supporting this concept. This includes both the EHR and FHIR server who must be capable of querying FHIR resources at the given datetime.
I added a comment to Issue #37 that led me to creating this issue.
There doesn't seem to be any documentation for how a service should respond when an invalid (or more generally, an unexpected) value is provided as a prefetch resource.
It has become apparent that CDS Service vendors/developers want to include a logo or image of some sort in their cards. Today, these developers are doing this with an image tag in the Markdown of the card details. This is fraught with UX issues as the CDS Service developer doesn't know how big to make the image since how it is rendered varies by EHR.
Perhaps we should add first-class support for a logo/icon either in the card itself (via a first-class attribute) or in the CDS service definition in the Discovery endpoint.
We should be prescriptive on the size and format of the logo/icon. Additionally, we should be clear if this is a logo or an icon (there is a difference from a UX perspective).
I'd like to explore first if we can put this in the Discovery endpoint for each service rather than an attribute on the card.
Can we include a relevant clinical scenario in the documentation, such that those who are reviewing the Introduction wiki page, or the sandbox demo page (a doc link on the top right of each main page for that hook), then they can see the use of the cds-hooks spec?
ie.
Today, our documentation does not describe what a CDS Service should do when no decision support is necessary.
My assumption was that the service returns a 200 response with an empty cards array. However, we should make this explicit and call this out in the documentation.
The documentation on the decision structure is somewhat lacking. And I think needs to be advanced a bit, as we are attempting to implement this right now.
In the case the decision indicates an item to be deleted, it makes sense to have the value be a string identifier.
In the create case, the resource doesn't yet exist. Using an identifier could be confusing and also implies that the CDS service would have to host this resource. It is more convenient if the resource to be created is inlined within the decision payload (similar to how this happens with the context).
Don't change delete, continue to specify an array of strings. These identifiers are existing FHIR resources on the specified fhir-server (from the initial service call).
Change create to be an array of (inlined) objects (e.g. FHIR resources) instead of strings.
How should a cds-service let an EHR know about errors?
Following RESTful best practices, HTTP error statuses returned by a cds-service to an EHR when appropriate:
For business-logic type errors, it might make sense for the service to return a 500 containing a FHIR OperationOutcome with values from the FHIR IssueType valueset, but further constrained.
Ken Kawamoto pointed out that in our documentation for the medication-prescribe hook we state that the context is "The set of proposed medication prescriptions".
This makes sense that we would support multiple medication prescriptions as context. However, in our example and in prototype implementations, I know we've only ever sent a single medication prescription as the context.
We need to think through this. I think that it does make sense for the context in this case to contain multiple medication prescriptions.
Currently, the CDS-hooks specification does not provide a mechanism associating the CDS card to the order(s), or other resources, that it is in response to. For example, if a CDS information card came back from a CDS service indicating that a prescription dosage was too high given the patient’s age, it would be beneficial for the EHR to know the particular order the information card was referring to so that it might apply special formatting on the order (or other actions) when the user interacts with the card.
Ideally the card should have an additional relatedResources field which can contain this set of resources. These resources would generally be a subset of resources provided in the context.
Right now our suggestions and decisions share a lot of structure. We should formalize this to
include uuid, label, create and delete, as well as two new
optional elements (assessment and about). This gives us a pretty goood base structure
that can be used for suggestions, decisions, and top-level feedback. Here's the rough idea:
feedbackAt the top level of CDS Hooks response, we define a new array-valued feedbaack property, where
each feedback item follows the augmented suggestion structure. For example:
{
"decisions": [],
"cards": [],
"feedback": [{
"uuid": "c91554be-a7ec-4067-b544-33efabffe9d6",
"about": ["ProcedureRequest/123"],
"assessment": {
"rating": {
"value": 4,
"unit": "Rating Scale",
"system": "https://acr.org"
},
"radiation": {
"value": 3,
"unit": "Relative Radiation Level",
"system": "https://acr.org"
}
}
}]
}The specific assessement properties ("ratings", "radiation") would be hook-specific,
so here I'm imagining a "radiology imaging order" hook...
suggestions can be decorated with assessments, tooSame structure applies to any given suggestion in a suggestion card:
{
"suggestions": [{
"uuid": "c91554be-a7ec-4067-b544-33efabffe9d6",
"delete": ["ProcedureRequest/123"],
"create": [{"resourceType": "ProcedureRequest", "code": {}}],
"assessment": {
"rating": {
"value": 4,
"code": "appropriateness-scale",
"system": "http://acr.org"
},
"radiation": {
"value": 3,
"code": "relative-radiation-scale",
"system": "http://acr.org"
}
}
}]
}decisionsThe items in a decisions array could also be decorated with this same structure.
I won't repeat here, for brevity...
{
"cards": [],
"decisions": [{
"uuid": "c91554be-a7ec-4067-b544-33efabffe9d6",
"delete": ["ProcedureRequest/123"],
"assessment": {
"rating": {
"value": 4,
"unit": "Rating Scale",
"system": "https://acr.org"
},
"radiation": {
"value": 3,
"unit": "Relative Radiation Level",
"system": "https://acr.org"
}
}
}]
}I would like to suggest that context be explicitly documented as a list of FHIR Resources, in order to more accurately interpret what is included in the list.
Is there a plan to define a controlled terminology for EHR triggers of CDS Hooks? Options like “medication-prescribe” and “order-review” are strikingly similar to the HL7 ActTaskCode value set (https://www.hl7.org/fhir/v3/ActTaskCode/vs.html) within the HL7 ActCode code system. For example, "order-review" is "OREV" and "medication-prescribe" is "MEDOE". Why not just adapt the ActTaskCode value set for CDS Hooks?
For a CDS service provider, it is necessary to know which organization (or client) and potentially sub-organization is requesting the service. For example, it may be that a given client purchased only a subset of CDS Service’s capabilities and CDS Service needs this information to properly handle the request. Another example is that the client could be a cloud-based EMR, which encompasses many practices, each with their own organizational structure.
We believe it would be beneficial to add a required organization field to the the CDS service request which would provide the FHIR id of the organization (or sub organization) requesting CDS.
There are at least a few other ways to provide this information, but each has a downside:
FhirServer Url can include an identifier that indicates which organization (or hospital or practice, etc) is requesting the service. The primary issue with this approach is that the CDS service has to parse out the relevant identifier, thereby hardcoding assumptions about how the Url is structured. If those assumptions are ever violated, the process breaks down.
Context could reference the relevant FHIR resources, such as Organization to establish the context. However, the spec and examples currently focus the context on the triggering orders.
Service URL could include a prefix which identifies the organization. However with sub-organizations and sub-sub-organizations this could become unwieldy.
Several CDS service implementations have gotten stuck on CORS. We should add documentation on CORS and that services should implement support for this
The documentation for Suggestion.create states:
string. new resource(s) that this suggestion applies within the current activity (e.g. for medication-prescribe, this holds the updated prescription as proposed by the suggestion).
The .yml in Swagger shows:
Suggestion:
type: object
properties:
label:
type: string
create:
type: array
items:
type: object
delete:
type: array
items:
type: object
A string is not sufficient to hold the resource, so the docs need updating for consistency. Should this be an array of resources, a Bundle.entry (like prefetch), or a Bundle? Should Suggestion.delete be a simple list of strings or consistent with create?
In discussion with @brynrhodes and @kpshek regarding aligning Clinical Reasoning and CDS Hooks, Bryn pointed out that FHIR consistently uses an attribute "name" for a "computer friendly name" and "title" for a "human friendly name"; yet, CDS Hooks is currently using "name" as a human friendly string.
We should change this to avoid confusion for FHIR developers.
CDS Hooks uses the term "name", which should be "title" in the service discovery response.
The documentation does not make it clear what a card with an indicator of 'success' signifies. Does it signify that CDS was executed and there are no suggestions/warnings/information/etc? Or does it just mean that the CDS ran (i.e. it should be returned with basically every response and probably simply ignored by the consumer). What is the proper way to tell the consuming system that there were no suggestions/warnings/information? Note that this may be required and include extra information for supporting PAMA/etc.
One of the issues we have be grappling with is how to let our consumers know in detail what our CDS Service needs from the EHR to ensure integration is as smooth as possible. This is relevant to the FHIR resources found in the context, preload, or requested from the FHIR Server. For example, what fields in ProcedureRequest do we utilize and are they required? What code systems are supported by the CDS service? The FHIR way of doing this is a CapabilityStatement (Conformance in DSTU2) with associated profiles. While CapabilityStatements are not perfect, they go a long way towards ensuring compatibility in an integration.
At the beginning of an integration with a CDS Service, the EHR provider (or other consumer) might ask ‘What data do we need to provide to your service?’. As it stands, the CDS Hooks spec does not address this, so this specification must be provided out-of-band and will probably be inconsistent between various service provider. We propose that on a per-hook basis in the discovery endpoint, the CDS Service may provide a CapabilityStatement (or link/url to one) which better describes the data expected by the service. It should include all resources utilized, fields used, required fields and/or cardinality modifications, code system constraints, and potentially documentation where the CapabilityStatement/profile cannot adequately constrain the solution.
With this, the EHR Provider could request the CapabilityStatement from the CDS Service and run validation against their own FHIR server to identify any gaps to be addressed. The CDS Service provider could similarly run the validation against the EHR’s FHIR server during the integration process to determine gaps. This will also help during maintenance and upgrades to ensure that the service and the EHR remain compatible.
From @jmandel on March 17, 2016 15:53
These can live in a standalone github repo, and should include "valid but tricky" cards with:
And also should include invalid cards, with:
Copied from original issue: cds-hooks/cds-hooks#4
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.