Stream: smart
Topic: Launching SMART app with parameters
Lloyd McKenzie (Jul 29 2020 at 15:47):
Da Vinci has a use-case where we have a CDS Hook that's passing back a card suggesting the launch of a SMART App (specifying the URL of the app to launch). The app being launched is 'generic', but the URL being passed back needs to be specific - it needs to include the URL of a form to be filled out and a token that will allow the app to access that form. There are two mechanisms we could use to construct the URL:
https://base.com/somesmartapplaunchurl?questionnaire=escapedsomeurl&token=sometoken
or
https://base.com/somesmartapplaunchurl/escapedsomeurl/sometoken
The latter approach kind of sucks because it requires web server magic to turn the extra stuff on the end of the URL into parameters internally. However, it's not clear if it's allowed to pass additional parameters on the smartapp. Is it?
Lloyd McKenzie (Jul 30 2020 at 01:26):
And a follow-up: Is there any standard way to provide the same sort of context information to the SMART App that gets provided when invoking the CDS Hook that returned the SMART app card?
Lloyd McKenzie (Jul 30 2020 at 14:50):
@Josh Mandel @Isaac Vetter
Isaac Vetter (Jul 30 2020 at 17:24):
Hey Lloyd!
Is there any standard way to provide the same sort of context information to the SMART App that gets provided when invoking the CDS Hook that returned the SMART app card?
Yes, definitely. The link.appcontextis provided to do exactly this. See: https://cds-hooks.hl7.org/1.0/#link
Isaac Vetter (Jul 30 2020 at 17:26):
Let me know if I'm misunderstanding your question. Note that CRD/DTR do already make use of this field in the CDS Hooks response to coordinate the card and the app, see: https://build.fhir.org/ig/HL7/davinci-crd/hooks.html#launch-smart-application
Isaac Vetter (Jul 30 2020 at 17:27):
What's different between the stated need, above, and this appContext field is that information is not provided to the app as a url querystring, but rather, is provided to the app following the OAuth "handshake", alongside the access_token.
Lloyd McKenzie (Jul 30 2020 at 20:40):
@Isaac Vetter I should have looked in the CDS Hooks spec rather than the SMART spec (the latter seems to have no reference). I'm trying to understand how the link.appcontext is used by the EHR. Is the link.appcontext passed as part of the initial call to the app via the URL? A header? If the URL, can an app be launched using POST (because the content might well be too big to go in the URL). If it's not passed from EHR to app as part of the launch, is there a diagram somewhere showing where it's exchanged?
Isaac Vetter (Jul 30 2020 at 21:51):
This little field does assume a super-high level of familiarity with both specs, a diagram could be useful here as background material (interested in logging a gh or jira issue? :wink: ). Here's what the CDS Hooks spec says in the definition of Link.appContext:
The appContext field and value will be sent to the SMART app as part of the OAuth 2.0 access token response, alongside the other SMART launch parameters when the SMART app is launched.
"as part of the OAuth2.0 access token response" is the key part. It means that the appContext is passed during the final bit of the OAuth2 exchange. From this SMART diagram -- it's part of the "access token response" --
image.png
Isaac Vetter (Jul 30 2020 at 21:52):
so,
- not as part of the launch (initial call) of the app
- not as part of a querystring (nor a urlencoded POST body)
rather, as a json key/value element in the authorization server's HTTP response to the app's calling of the AS's /token endpoint.
Further, I personally always recommend that contextual information about the app launch be passed in this same location. SMART allows implementation to extend the list of fields here and it's nice and secure and doesn't have length restrictions, etc. (For example, FHIRcast standardizes the passing of some additional values here as well).
Lloyd McKenzie (Jul 31 2020 at 01:37):
How does the auth server get it? It's given to the EHR, not the auth server and my understanding is that auth server and EHR can be distinct @Isaac Vetter
Grahame Grieve (Jul 31 2020 at 02:27):
wouldn't it have to be a scope for the the authserver?
Lloyd McKenzie (Jul 31 2020 at 13:50):
How could a bundle of arbitrary JSON data be a scope?
Isaac Vetter (Jul 31 2020 at 19:10):
Hey Guys, For the system I'm most familiar with, there isn't a hard line between the auth server and resource server. More generally, SMART implies a tight relationship between these two systems. Another way to answer your question is -- the auth server knows about the appContext in the same way that the EHR knows about the launch token.
Ultimately, for off-the-shelf CDS Clients and auth servers, there would need to be some additional mechanism of communicating the appContext that's not described in the CDS Hooks or SMART specs.
Lloyd McKenzie (Jul 31 2020 at 20:01):
There's actually 3 different notional systems - the Hooks Client/SMART client, the Auth Server and the resource server. This would require out-of-band communication between the Hooks client and the Auth Server. For the launch parameter, I don't think there would necessarily need to be out-of-band communication from SMART client to Auth Server to share the parameter - though there would need to be coordination about the content. Needing to actually "pass the data" from the Hooks Client to the Auth Server so the Auth Server can then pass it to the app is a significantly higher bar. Not an impossible one, but certainly one that should be made explicit.
https://jira.hl7.org/browse/FHIR-28178
Last updated: Apr 12 2022 at 19:14 UTC
