FHIR Chat · docs: issue 4: Strengthen documentation around app links · cds hooks

Stream: cds hooks

Topic: docs: issue 4: Strengthen documentation around app links

---

Github Notifications (Sep 20 2016 at 17:28):

kpshek commented on issue 4

Test Zulip integration...

Josh Mandel (Sep 20 2016 at 17:38):

It works!

Kevin Shekleton (Sep 20 2016 at 17:48):

On the first try too! :-)

Github Notifications (Dec 17 2016 at 15:19):

kpshek commented on issue 4

Originally I was thinking that SMART app links didn't have to be any special type of link in the CDS card. This is because the EHR has a known registry/whitelist of SMART app launch URLs. Thus, by comparing every CDS card link to this registry, if it was found to be contained within, the EHR could modify the link to add the SMART iss and launch parameters.

However, I have the following concerns with this approach:

1. It assumes the EHR has a registry/whitelist of known SMART app launch URLs

While this is true of the EHR I'm intimately familiar with (Cerner), I don't know that this will hold true for all EHRs. Maintaining such a registry/whitelist is not necessary and in the case of Cerner, is done for business reasons (not due to technical or security reasons).

Additionally, in the not too distant future I can see where it may not be possible to maintain such a registry/whitelist for certain use cases (like for instance patient's bringing their own SMART app). While our use case of CDS Hooks has been focused on the practitioners in the EHR, I would not be surprised to see us venture into other venues like patients in their personal EHR or patient portal.

2. It requires the EHR to re-write the card link

Only the EHR knows the appropriate values for the iss and launch parameters during a SMART app launch. As such, a CDS service can never supply a link to a SMART app that is absolute. Instead, the link must be made 'correct' by the EHR re-writing the link to add the appropriate parameters.

---

Based on this, I would like to define a first-class SMART app link within a CDS card. So, either an explicit SMART app launch URL field or some additional attribute on a link indicating that this is a SMART app. The former option is more explicit/clear at the cost of API verbosity where the latter (achieved through something like a type attribute on a link) is terse, but perhaps unnecessarily open-ended.

Right now I'm leaning towards that latter option of including a type attribute on each link (this is in addition the existing label and url attributes) with a value of smart. Non SMART app links could have a type of absolute.

I'd appreciate any thoughts from others on this.

Github Notifications (Dec 30 2016 at 21:43):

kalyaniyerra commented on issue 4

I like the option 2 to add the type attribute on each link to specify smart or absolute. This option adds for future extensibility for other types of apps also.

Github Notifications (Jan 14 2017 at 21:54):

kpshek commented on issue 4

Right now I'm leaning towards that latter option of including a type attribute on each link (this is in addition the existing label and url attributes) with a value of smart. Non SMART app links could have a type of absolute.

After offline conversation with @Isaac Vetter (Epic), @kalyaniyerra (Premier), the RxREVU team (Peregrin, Sean, Joel), and Elsevier (Alex DeJong), we decided to proceed with this proposal. This new type field will be required for each link returned in a card.

When the type is smart, the EHR will be responsible for appending valid and appropriate launch and iss parameters to the URL.

Github Notifications (Jan 14 2017 at 22:23):

kpshek commented on issue 4

I'd appreciate it if another set of eyes could review my proposed documentation changes here: https://github.com/cds-hooks/docs/pull/16

Github Notifications (Jan 14 2017 at 22:29):

jcward10 commented on issue 4

Can we have a recommendedTarget key? Then, the cds tool can recommend opening the link in an iframe modal or a new tab.

Github Notifications (Jan 14 2017 at 22:35):

isaacvetter commented on issue 4

Hey @Jeremy Ward, I'm not sure that the cds tool always knows what the possible targets are for a given EHR. The EHR can be, at least, a desktop, web or mobile app. In two of these three scenario's, an iframe or new tab may not be possible.

Github Notifications (Jan 14 2017 at 22:40):

olbrich commented on issue 4

@Isaac Vetter I can see scenarios in which a hook might behave differently depending on the User agent. For example, a hook might not have enough space to work properly on a mobile browser and thus might suggest that the user should use a desktop web browser to complete their task instead. I suppose that's why @Jeremy Ward's suggestion is just a recommendation.

Github Notifications (Jan 14 2017 at 22:44):

Penumbra69 commented on issue 4

We have a similar card-generation capability in house (non-fhir), and in it we have a few fields for rendering the information to a client (we support mobile, web, and sms). One is Markdown compatible, One is 140 characters of text, one is HTML (we call it the 'div' field which always is a <div></div>). The renderer can then pluck from the card the rendering it is capable of. More work to store, more data to pass - but solved the conundrum for us.

Github Notifications (Jan 14 2017 at 23:18):

kpshek commented on issue 4

Can we have a recommendedTarget key? Then, the cds tool can recommend opening the link in an iframe modal or a new tab.

@Jeremy Ward and I had an offline conversation where I explained my thoughts on this but I want to also document them here. To cut to the chase, I agree with @Isaac Vetter in that the CDS service isn't the best entity to recommend a target. Even though this would be an optional recommendation, it has the high probability to be a crummy recommendation in which case I don't see a need to add this in the spec.

The target of the link is based upon the platform and capabilities of the EHR. Eg: mobile native app vs desktop native app vs pure browser. In the case of the Cerner EHR (of which I'm very familiar), we could launch a link (specifically a SMART app) in the following ways:

- A new browser window
- Within the current browser window
- Navigating the user to a different section of the workflow in which the SMART app has already been configured, outside the confines of the CDS card

In each of these scenarios, the EHR knows best how to open the link and I would ignore any recommendation provided by the CDS service.

I've seen demos/prototypes of embedded SMART apps in other EHRs and each opened them in a variety of ways (new windows, new iframes opened in a slide over panel, etc).

For all of these reasons, I don't think we should add a new recommendedTarget field

Github Notifications (Jan 14 2017 at 23:55):

kpshek commented on issue 4

I just merged #16 which resolves this issue. Note - this is a new breaking change to the API.

If we want to continue the discussion on the sidebar conversation here around link targets we should open a new issue.

Github Notifications (Jan 14 2017 at 23:55):

kpshek closed issue 4

Github Notifications (Jan 15 2017 at 18:18):

kpshek reopened issue 4

Our documentation around app links needs to be clarified. Questions that the documentation should answer:
- Are there any expectations that links should always be TLS protected? (https)
- Do links to SMART apps need any other metadata or identifying information?
- Are links absolute URLs?
- Should EHRs open links in a new window? embedded frame? etc.
- Do we support custom URL schemes? (eg, native links like myapp://)

Github Notifications (Jan 15 2017 at 18:26):

kpshek commented on issue 4

Re-opening this issue. I realized that PR #16 addressed a few aspects of the questions I wanted to answer when I originally logged this issue.

Are there any expectations that links should always be TLS protected? (https)

I plan on updating the documentation to state that TLS protected endpoints are strongly recommended, but not required with absolute links. smart links must be TLS protected as the SMART project requires this.

Do links to SMART apps need any other metadata or identifying information?

Answered this with the new smart type field on links.

Are links absolute URLs?

Answered this with the new absolute type field on links.

Should EHRs open links in a new window? embedded frame? etc.

I plan on putting my thoughts above on this topic into the documentation.

Do we support custom URL schemes? (eg, native links like myapp://)

Right now I want to be silent on this until we actually prototype something out. I _think_ this would work with what we have today (this would be an absolute link).

Isaac Vetter (Jan 15 2017 at 20:59):

Hey @Kevin Shekleton ,

Do we support custom URL schemes? (eg, native links like myapp://)
Right now I want to be silent on this until we actually prototype something out. I _think_ this would work with what we have today (this would be an absolute link).

This seems like an unnecessary limitation. I'm pretty sure that there's nothing in the SMART spec that precludes SMART launch apps with uri schemes other than https. Is this incorrect?

Definitely, it's worth testing out, but we shouldn't preclude it.

Isaac

Kevin Shekleton (Jan 15 2017 at 21:18):

@Isaac Vetter - You are correct. If a SMART app is available over http, it needs to be TLS protected (https). However, SMART apps can be available via custom URI schemes too

Kevin Shekleton (Jan 15 2017 at 21:18):

I'll clarify my issue comment

Github Notifications (Feb 21 2017 at 19:45):

jmandel commented on issue 4

The other requirement to highlight here, I think, is letting an app finish and *return control back to the EHR* — in our test harness for example we use this capability to link to a hypertension management tool where a user can select a drug, and then return to the EHR and have the UI updated with their choice.

Right now we do this using a redirect URL: the app's job is to redirect to that URL if/when the user has finished working with the app (e.g. made a final decision); the EHR gets to host whatever content it needs at this URL (e.g. execute a JS function to communicate back with the EHR host window, or execute a server-side process to mark the session as complete).

Github Notifications (Mar 16 2017 at 15:32):

vadi2 commented on issue 4

Another thing that's unclear in the documentation to me is about this redirect url - is the hookInstance supplied back to the EHR, so the EHR knows which decision is complete?

Github Notifications (Mar 16 2017 at 20:26):

jmandel commented on issue 4

Ah. Once control returns to the EHR, the EHR re-invokes the notification using the same hookId, and it's at that point that the external service returns a user's "decisions". So as currently specified, the external service needs to retain this state (id + decision) long enough to support the return loop.

Github Notifications (Mar 17 2017 at 07:08):

vadi2 commented on issue 4

Hm... but then if multiple hooks are started at once, the EHR wouldn't know which one is it that came back. I guess the EHR would have to re-try them all and see if decisions are available for them?

Github Notifications (Mar 17 2017 at 07:47):

vadi2 commented on issue 4

The other way is - I'm not finding anything saying otherwise in the spec - is that the redirect URL supplied by the EHR to begin with would have this hookInstance within it as a parameter, so when the CDS pings it, it would know which is completed.

I guess I'm looking to see what current implementations, if any, are doing in this regard?

Github Notifications (Mar 17 2017 at 13:27):

jmandel commented on issue 4

So far, I think the only implementation is our test harness. In the current implementation: the redirect URL is a static URL hosted by the test harness; it's just a page whose job is basically "find my window.opener and notify them that i'm done; then close me". But that's an implementation detail...

It would be possible for the main EHR frame to keep track of which apps it has launched in which child windows (e.g. by generating unique redirect URLs, or tracking metadata about its window objects in JS, or some other mechanism), to prevent re-triggering all services. But that's technically an optimization; it should also be safe to re-trigger all hooks any time a user returns from an app.

It's certainly an "open design issue" to determine what's implementable within real-world EHRs, and this is one of the trickier workflow steps to pull off.

Github Notifications (Mar 17 2017 at 14:07):

vadi2 commented on issue 4

Thanks, I suppose I was just looking for someone to say that's an implementation detail as the spec is unclear on this part. Appreciated!

---

Last updated: Apr 12 2022 at 19:14 UTC