FHIR Chat · docs / Issue #39 Formally document hook definitions · cds hooks/github

Stream: cds hooks/github

Topic: docs / Issue #39 Formally document hook definitions

---

Github Notifications (May 11 2017 at 15:38):

kpshek commented on Issue #39

From some Zulip discussion on this issue, we're proposing that context is always a JSON object. Furthermore, context is defined per hook which each hook defining the individual keys and values (both the JSON value type and the content) within the context JSON object.

For example (these are examples, not absolute/real hook definitions):

hook: patient-view
description: Some very clear description of the hook (answering Isaac's question's above)
context: An empty object ({})

---

hook: medication-prescribe
description: Some very clear description of the hook (answering Isaac's question's above)
context:

{
  "medication": {
    // DSTU2: MedicationOrder FHIR resource of the medication being prescribed
    // STU3: MedicationRequest FHIR resource of the medication being prescribed
  }
}

---

hook: allergy-review
description: Some very clear description of the hook (answering Isaac's question's above)
context:

{
  "allergies": [{}, {}]
}

Github Notifications (Jul 10 2017 at 20:51):

isaacvetter assigned Issue #39

Github Notifications (Oct 12 2017 at 20:31):

kpshek commented on Issue #39

In conversation with @Isaac Vetter, @hstrasbe, and myself on the Argonaut call today, we talked about splitting out the hook definitions from the specification. This will allow us to add additional hooks without updating the spec.

Here's some thoughts:

• http://cds-hooks.org/ ️ Homepage (overview, links to subpages)
• http://cds-hooks.org/hooks ️ Hook definitions
• http://cds-hooks.org/spec/1.0 ️ The 1.0 of the specification
• http://cds-hooks.org/spec/build ️ The next release of the specification

If we ever do a breaking release (eg, 2.0) and this affects the hook definition, then we will need to put the hook definitions at something like http://cds-hooks.org/1.0/hooks and http://cds-hooks.org/2.0/hooks. The thing that I don't like about this is that I don't want to have similar page for intermediate releases (eg, 1.1, 1.2, etc).

This also relates to #100 which is where we'll be doing the actual work to manage our documentation with respect to versioning.

Github Notifications (Oct 13 2017 at 14:06):

kensaku-kawamoto commented on Issue #39

I think this is a good idea. Sort of like an Implementation Guide.
Is there a reason why the URL wouldn't http://cds-hooks.org/hooks/1,0 and http://cds-hooks.org/hooks/2,0 (version number at the end, like for the spec)?

Github Notifications (Oct 13 2017 at 15:53):

kpshek commented on Issue #39

@kensaku-kawamoto - Putting the version number in the hooks URL would be fine. Though, I think the version numbers should be the major releases only (1.x, 2.x, etc).

One of my personal goals is to not have any breaking changes after 1.0. So, another approach we could take is to have the hooks at just /hooks. IF we introduce breaking changes later and need a 2.0, we can then revisit the URL for our hook definitions to include a version in the path. As I type this, I like this option the best.

Github Notifications (Oct 13 2017 at 17:25):

kensaku-kawamoto commented on Issue #39

Makes sense to me.

Github Notifications (Oct 30 2017 at 21:07):

isaacvetter commented on Issue #39

1. Move hook catalog to a separate repository. Optimally each hook is it's own .md file. README indexes the hooks.
1. Spec should only document conventions / requirements for creating a hook - hook naming, dsecription, clearly defined context, etc. Remove med-prescribe, order-review from spec. Change open-patient to example.

Github Notifications (Nov 22 2017 at 13:56):

brettmarquard commented on Issue #39

How do systems differentiate what belongs in context vs prefetch. The definitions seem similar:

context object. Hook-specific contextual data that the CDS service will need.
For example, with the medication-prescribe hook this will include MedicationOrder being prescribed.

prefetch object. The FHIR data that was prefetched by the EHR (see more information below)

My best guess: context is what the hook defines as required. prefetch is just additional data the EHR decided to send?

Github Notifications (Nov 22 2017 at 14:04):

kensaku-kawamoto commented on Issue #39

From a healthcare system perspective, our privacy and security folks are much more concerned about an external system making calls into our FHIR server to pull data, then for us to push out the required data. So we very much like the idea of prefetch. To that end, I would like to see prefetch be able to fully support the data needs of a CDS Hooks service, if the EHR and healthcare system can support it.

Github Notifications (Nov 22 2017 at 14:55):

kpshek commented on Issue #39

It is important that we do not conflate context and prefetch; we could benefit from stronger documentation explaining the difference between the two as I've heard folks confuse the two sometimes.

context is unique to a hook and therefore applies to all CDS Services for a given hook. A given hook will document required and potentially optional context parameters. Each EHR will need to satisfy the context requirements of each hook they want to support. The parameters in the context are expressed as any name/value data -- it is not constrained to simply FHIR resources.

prefetch is unique to a given CDS Service. The CDS Service defines FHIR resources that it would like the EHR to pass along in the request. The EHR is not required to satisfy any/all of the prefetch desires. A CDS Service may decide that if it doesn't received the desired prefetch data, it returns a 412 status; ideally, the CDS Service should be resilient to missing prefetch data.

Github Notifications (Nov 23 2017 at 15:29):

vlindhol commented on Issue #39

@kpshek in my use case it is a conscious design decision that our CDS will never fetch additional data from the caller's FHIR server, i.e. all data must be present in the call. The reasons are similar as @kensaku-kawamoto mentions, but from the CDS end. We want to be able to say to the EHR to not send any data that makes the patient immediately personally identifiable, like a social security number. If they do, the patient data security consequences are up to them. If we have to fetch the data ourselves, there is no way of telling what the contents might be before it's gotten onto our servers. Therefore we are in a legal sense a service that has full access to personal data, with all the legal ramifications that comes with it. Add to that that we are active in multiple countries, and I think it is clear why we are attempting to keep the liability on the EHR side.

Many parts of CDS hooks seem to assume that additional FHIR server fetches are possible. For example, a system like ours is basically bound to use only the resources specified in a global hook definition like medication-prescribe. If we would like to use fancy additional data, say DNA data, and we can't fetch it ourselves, we basically have to define our own hook. I think this will greatly reduce the usability of global hooks for a lot of people.

What you @kpshek said about returning a 412 status if a prefetch is mandatory is exactly what I have been looking for, since we want our service to signal that prefetch is, just like gravity, not just a good idea but the law. Again, this is since we can't fetch the data ourselves. But I haven't seen a single mention of this being the canonical way of signalling an obligatory prefetch in the docs. Granted, I haven't re-read the docs for a while. And wouldn't it be clearer to include this info in the service description? A simple boolean somewhere? Otherwise customers have to actually try sending a request to us before finding out that they have to perform the data fetching themselves.

Github Notifications (Nov 23 2017 at 16:28):

kpshek commented on Issue #39

@vlindhol - Check out our latest prefetch documentation. @isaacvetter updated it a few weeks ago in PR #103 to clarify some things and add the bit about a 412 HTTP status.

Your use case of a CDS Service not being able to fetch any FHIR data is one that we have heard now several times so it is a use case we care about. If you think that CDS Hooks doesn't address your needs around prefetching please let us know by logging an issue.

Currently, your CDS Service can define whatever data it needs upfront in in the prefetch definition. If the EHR doesn't satisfy your request, you can return a 412 to indicate you don't have the necessary data to process the request. We have said before that we expect there to be some personal touchpoint/communication between an healthcare organization and CDS Service Provider before they integrate. For instance, the healthcare administrators/providers will want to know the value the CDS Service will provide, how it should be incorporated in the EHR, security considerations, etc. During this time, I would expect the CDS Service Provider to state any data requirements. Related to this, this has been discussed in #82 so read through that it you haven't already.

Happy Thanksgiving from the US!
:turkey: :man:‍:egg: :poultry_leg: :fork_and_knife: :tada: :smile:

Github Notifications (Nov 24 2017 at 19:29):

isaacvetter commented on Issue #39

Hey Everybody,

I took an additional stab at #39, I think that we still need to clarify:
* optionality of context parameters
* FHIR versioning - can multiple versions of FHIR exist in the same request (I'm pretty sure that this should be no). How does a service know what to expect?
* is context a list of FHIR ids and resources or a list of json key/value pairs ?
* what's the appropriate granularity of a hook?

Secondly, there's some polishing likely needed on the actual hooks
* What DSTU2 or STU3 FHIR resources am I missing from order-review?
* I don't think that patient-view necessarily includes an encounter, but I suspect that this is contentious.

Isaac

Grahame Grieve (Nov 24 2017 at 19:50):

@Isaac Vetter, where to see your 'additional stab'?

Isaac Vetter (Nov 24 2017 at 20:31):

@Isaac Vetter, where to see your 'additional stab'?

Hey Grahame, in PR #109

Github Notifications (Nov 24 2017 at 21:33):

grahamegrieve commented on Issue #39

Agree to not mixing FHIR versions in a request. bad idea. context for order-review is ok. But how many reviews are we going to have? we need at least Patient, Encounter, EpisodeOfCare, DiagnosticReport, QuestionnaireResponse, Composition, CarePlan, ImagingStudy (+ problem list / medication reconciliation)

Github Notifications (Nov 24 2017 at 21:47):

isaacvetter commented on Issue #39

Hey @grahamegrieve ,

Appreciate the feedback on versioning the FHIR payload.

I want to minimize when a cds service is called to only when it has relevant guidance. Generating context and pre-fetch and awaiting a response are expensive compared to native cds. We do this now by executing local rules before remote rules. More discrete hooks lessen the need for local rules.

Further, I suspect that more specific hooks are easier for cds services to identify and develop against.

I imagine an eventual library of 50-100 defined hooks.

Isaac

Github Notifications (Nov 25 2017 at 12:05):

kpshek commented on Issue #39

I don't think that patient-view necessarily includes an encounter, but I suspect that this is contentious.

I agree with you on this; the encounter id should be optional. In our EHR, you can open a patient's chart without an encounter in context.

Github Notifications (Nov 28 2017 at 19:41):

isaacvetter commented on Issue #39

Hey @jmandel , @grahamegrieve ,

Per your comments on #119, want to check out PR #109's heroku build and give feedback?

Isaac

Github Notifications (Nov 29 2017 at 15:29):

grahamegrieve commented on Issue #39

I'm kind of troubled by the choice between id and full resource in context. Do you have to pick on in the definition itself?

btw, the example for patient view is kind of weird in a purely documentary set, having extensions etc. Not wrong; just.... distracting...

Github Notifications (Nov 29 2017 at 17:53):

jmandel commented on Issue #39

I think it's good/important for the definition to pick between ids and full resources, @grahamegrieve. I didn't follow your note about the example having extensions (I don't see any here).

Some notes on my side:

• We shouldn't push FHIR STU differences into this level. It's not going to scale great... (But if we do, we should fix the example typo to say STU3 instead of STU2.)
• When patient id used to be a top-level property, it was easy to explain how this variable became available in prefetch using a variable like {{Patient.id}}. For hooks that define their own context like hte example here, maybe we want to explain how this context can be used in prefetch. Like in the example, we might declare that Observation?patient={{example-patient-id}} would be a valid way to use these params in prefetch.

Github Notifications (Nov 30 2017 at 00:42):

kpshek commented on Issue #39

@isaacvetter - Let's keep any changes related to #119 off of PR #109. This will allow us to resolve #109 and this issue more quickly, as well as keep PRs related to their own distinct issues.

With that being said, the context for our current hooks (eg, patient-view) should be the Patient.id value, not the full Patient FHIR resource.

Github Notifications (Nov 30 2017 at 01:22):

grahamegrieve commented on Issue #39

@jmandel the patient example for patient-view. I don't know that it's always right to pick between id and full resource. Agree we definitely need to solve the pre-fetch issue

Github Notifications (Nov 30 2017 at 01:23):

jmandel commented on Issue #39

If you didn't pick between ID and full resource (specifying your decision in the hook definition), what would you propose instead @grahamegrieve?

Github Notifications (Nov 30 2017 at 01:26):

grahamegrieve commented on Issue #39

I don't know - allow either? I haven't thought this all the way through, but the FHIR operations, we usually provide a range of ways to pass a resource - at least by value or reference. Which is better depends on context. Perhaps pre-fetch takes the pressure off - if, that is, EHRs support it. I just feel there's more to be though about here

Github Notifications (Nov 30 2017 at 01:33):

kpshek commented on Issue #39

@grahamegrieve and @jmandel - Great discussion. I'd suggest logging a new issue if you want to debate whether a given hook (or specifically, patient-view) should use the FHIR Patient.id vs Patient resource as its context. This issue is specific to documenting/landing on a standard process to formally define new (and existing) hooks.

Currently, our current hooks all use just a FHIR Patient.id and unless we decide otherwise in a separate issue, we should proceed with what we have.

This will allow us to continue making progress on this issue so that we can get it wrapped up. :smile:

Github Notifications (Nov 30 2017 at 04:49):

jmandel commented on Issue #39

Fair enough. Let's still try to address my two comments in bullets above.

Github Notifications (Dec 04 2017 at 19:52):

isaacvetter commented on Issue #39

https://cds-hooks-docs-pr-109.herokuapp.com/hook_catalog/

@kpshek - I disagree that patient-view's context should only be the identifier. The content of a patient-view is the patient, just as the content of a med-prescribe is the med. How are you thinking about this, to come to a different conclusion? Also, I didn't add a column for data type. We'd need to enumerate the possible data types to do this, and it's not clear to me what those are.

I also, didn't attempt to implement @grahamegrieve's suggestion for the FHIR reference() type.

Otherwise, I think that I got everything, including accounting for @jmandel 's point about pre-fetch template variable references.

Github Notifications (Jan 28 2018 at 23:15):

kpshek closed Issue #39

---

Last updated: Apr 12 2022 at 19:14 UTC