availability of data and safety #506

isaacvetter · 2019-10-09T17:05:43Z

Intended to address --
Fixes: #502, #503

Intended to address -- Fixes: #502, #503

bvdh · 2019-10-10T08:29:23Z

docs/hooks/patient-view.md

-The patient whose record was opened, including their encounter, if applicable.
+The patient whose record was opened, including their encounter, if applicable. 
+
+The FHIR ids referenced in `context` are expected to be available via the FHIR Server (if `fhirServer` is populated in the request) or via prefetch, if supported. However, the specification does not explicitly require this behavior and implementations should be aware that integrations may not fully support this expectation.


Suggest:
If the CDS-Client supports pretech and/or provides a FHIR Server, the CDS-Client SHOULD provide FHIR Resources referenced by FHIR ids in context. As this behavior is optional, CDS-Server implementers need to be aware that not all CDS-Clients will support this behavior.

Is it appropriate to add a statement to the base spec about the nature of context? e.g. if ids are provided, they must be resolvable through some mechanism available to the CDS Service. The point being that if an id is present, in order to be useful, the CDS Service must be able to call the FHIR server to retrieve it, or to have that same data prefetched by the CDS Client.

Hey Bas, does the rewrite address your concerns? I modified your suggestion for readability and consistency in terminology.

First, a few relevant sections of the spec:

On CDS Hooks Anatomy, a hook is

A defined point within the client system's workflow with well-known contextual information provided as part of the request

On the HTTP Request to a CDS Service, context is

Hook-specific contextual data that the CDS service will need.

On Providing FHIR Resources to a CDS Service

Each CDS Service will require specific FHIR resources in order to compute the recommendations the CDS Client requests...this specification defines a process to allow a CDS Service to request and obtain FHIR resources efficiently. Two optional methods are provided....Each CDS Client SHOULD decide which approach, or combination, is preferred.

On Prefetch Template

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.

In summary, the spec emphasizes that:

A CDS Client's purpose in invoking a hook is to communicate well-known and needed information to the CDS Service

CDS Clients SHOULD decide whether to support exposing their FHIR server or implementing prefetch or both.

CDS Services SHALL return a 412 if they do not get the information that they need from either the FHIR Server or prefetch (as opposed to returning something unsafe like an empty array of cards).

It isn't the responsibility of a hook definition to warn CDS Services about CDS Clients that choose to limit decision support by preventing access to needed data (or otherwise). Such CDS Clients will not gain adoption and I don't think statements on a hook definition to address their unusable nature add much value.

If we want to add clarifications to a future version of the spec to comment on the nature of FHIR references in a given context, that or other similar updates may be helpful. In the meantime, I don't think the 1.0 specification precludes the ability to publish the existing patient-view definition (prior to these amendments).

@bvdh, thoughts?

bvdh · 2019-10-10T08:35:07Z

docs/hooks/patient-view.md


 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
 `userId` | REQUIRED | Yes | *string* | The id of the current user.<br />For example, if the user represents a FHIR resource on the given FHIR server, the resource type would be one of [Practitioner](https://www.hl7.org/fhir/practitioner.html), [Patient](https://www.hl7.org/fhir/patient.html), or [RelatedPerson](https://www.hl7.org/fhir/relatedperson.html).<br />If the user was a Practitioner, this value would be `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

+For information on patient safety issues see [Security & Safety](../../specification/1.0/#security-and-safety).


Suggest:
The patient-view hook only allows advice that is based on information provided using prefetch and/or the FHIR-server. As is stated in [Security & Safety], implementers should be aware that using the patient-view hook might result in a decision based on outdated patient data, resulting in a safety risk to the patient. E.g. because the data the advice has been based on has been altered in the current user-session.

Does this addition provide any information that is not already available in the base spec?

Dennis - that's a good question. Bas, how much of the base spec should we be repeating here?

Adding comments about outdated/stale clinical data and a link to the Security and Safety page is redundant since the 1.0 specification already calls this out

Security and safety risks associated with the CDS Hooks API include:
...
6. The risk that a CDS Service could return a decision based on outdated patient data, resulting in a safety risk to the patient.

@bvdh, are you agreeable to removing this language from the hook since it's already covered by the published base spec?

bvdh

@isaacvetter , I tweaked the sentences a bit. Please comment.

dennispatterson

Neither of these additions seems particularly unique to patient-view. Rather than add this sort of language to each new hook up for ballot, perhaps there are additions that can be made to clarify the base specification or stated best practices?

dennispatterson · 2019-10-15T19:53:37Z

docs/hooks/patient-view.md

-The patient whose record was opened, including their encounter, if applicable.
+The patient whose record was opened, including their encounter, if applicable. 
+
+The FHIR ids referenced in `context` are expected to be available via the FHIR Server (if `fhirServer` is populated in the request) or via prefetch, if supported. However, the specification does not explicitly require this behavior and implementations should be aware that integrations may not fully support this expectation.


Is it appropriate to add a statement to the base spec about the nature of context? e.g. if ids are provided, they must be resolvable through some mechanism available to the CDS Service. The point being that if an id is present, in order to be useful, the CDS Service must be able to call the FHIR server to retrieve it, or to have that same data prefetched by the CDS Client.

dennispatterson · 2019-10-15T19:55:51Z

docs/hooks/patient-view.md


 Field | Optionality | Prefetch Token | Type | Description
 ----- | -------- | ---- | ---- | ----
 `userId` | REQUIRED | Yes | *string* | The id of the current user.<br />For example, if the user represents a FHIR resource on the given FHIR server, the resource type would be one of [Practitioner](https://www.hl7.org/fhir/practitioner.html), [Patient](https://www.hl7.org/fhir/patient.html), or [RelatedPerson](https://www.hl7.org/fhir/relatedperson.html).<br />If the user was a Practitioner, this value would be `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

+For information on patient safety issues see [Security & Safety](../../specification/1.0/#security-and-safety).


Does this addition provide any information that is not already available in the base spec?

@bvdh

Rewrite paragraph to better address @bvdh comment

Rewrite safety paragraph per Bas.

isaacvetter · 2020-01-22T16:35:13Z

Hey Guys - @bvdh , @dennispatterson ,

I'm closing this PR in favor of the HL7 patient-view hook ballot.

Isaac

availability of data and safety

2604ade

Intended to address -- Fixes: #502, #503

kpshek deployed to cds-hooks-docs-pr-506 October 9, 2019 17:05 View deployment

isaacvetter mentioned this pull request Oct 9, 2019

Patient-view: encounter access #502

Open

bvdh reviewed Oct 10, 2019

View reviewed changes

bvdh suggested changes Oct 10, 2019

View reviewed changes

bvdh mentioned this pull request Oct 10, 2019

Add guidance on the access of data referred to be id's in hook context. #507

Open

dennispatterson reviewed Oct 15, 2019

View reviewed changes

isaacvetter added 2 commits October 15, 2019 15:03

availability of FHIR resources from ids in context

e34f699

Rewrite paragraph to better address @bvdh comment

safety paragraph - stale clinical data

ae0e88e

Rewrite safety paragraph per Bas.

isaacvetter closed this Jan 22, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

availability of data and safety #506

availability of data and safety #506

isaacvetter commented Oct 9, 2019

bvdh Oct 10, 2019

dennispatterson Oct 15, 2019

isaacvetter Oct 15, 2019

dennispatterson Oct 16, 2019

bvdh Oct 10, 2019

dennispatterson Oct 15, 2019

isaacvetter Oct 15, 2019

dennispatterson Oct 16, 2019

bvdh left a comment

dennispatterson left a comment

dennispatterson Oct 15, 2019

dennispatterson Oct 15, 2019

isaacvetter commented Jan 22, 2020

availability of data and safety #506

availability of data and safety #506

Conversation

isaacvetter commented Oct 9, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bvdh left a comment

Choose a reason for hiding this comment

dennispatterson left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

isaacvetter commented Jan 22, 2020