hl7 / smart-web-messaging

SMART Web Messaging Specification Development

SMART Web Messaging Implementation Guide

The SMART Web Messaging Implementation Guide content has moved from this README to input/pagecontent/index.md. This document is used to feed the IG autopublisher, which populates: https://build.fhir.org/ig/HL7/smart-web-messaging/

Published Content

The IG autobuilder automatically publishes on pushes to the main branch of this repo via a GitHub Webhook. It typically takes a few minutes for the build to detect changes and run.

Autobuilder

More details on the autobuilder are here: https://github.com/FHIR/auto-ig-builder#fhir-implementation-guide-auto-builder

Latest

You can view the latest published content here: https://build.fhir.org/ig/HL7/smart-web-messaging/

Troubleshooting

If you don't see published content when you view that link, it means the autobuilder may be failing to build and publish the IG.

The IG autobuilder populates a few files as it works. When the IG is failing to publish, you can easily browse to those when visiting the link above. However, you can also view them when the publisher is working normally by visiting the links below.

build.log

The complete output of the autobuilder is saved here: https://build.fhir.org/ig/HL7/smart-web-messaging/build.log

qa.html

The publisher produces an html page containing publication warnings and errors. View it here: https://build.fhir.org/ig/HL7/smart-web-messaging/qa.html

builds.html

You can view all the auto published builds here: https://fhir.github.io/auto-ig-builder/builds.html.

Making Changes

To update the published IG, it is recommended that you test it locally before pushing changes back to the repo.

Prerequisites

You must have sushi to generate the IG. https://github.com/FHIR/sushi#installation-for-sushi-users

To convert the IG into the pulishable HTML content, you will run the latest version of the publisher, which will automatically be downloaded by the build process below. However, to view the content locally, you must have jekyll installed locally. https://jekyllrb.com/docs/installation/

Testing Locally

Please check out this repo and run the build.sh script (see below). This will run sushi locally on the repo files, then apply the latest publisher to the sushi output to confirm that the publisher will work with the IG.

# Check out the repo.
mkdir -p ~/code/HL7
cd $_
git clone [email protected]:HL7/smart-web-messaging.git
cd smart-web-messaging

# Build and test the IG using a local sushi and publisher.jar.
./build.sh

# The script will automatically open the local qa.html and index.html in your
# default browser.

Building on Windows

Prerequisites

1. Install Node
2. Install FHIR Shorthand
   • Global: npm install -g fsh-sushi
   • Local: npm install fsh-sushi
3. Install Java (JDK 14 or later)

Building

1. Run _updatePublisher.bat (answer Y to all questions)
2. Run _genonce.bat

smart-web-messaging's Issues

draft IG uses the wrong template

The draft IG uses a non-standard color scheme (purple) when it should be red & yellow. Perhaps change the template to hl7.fhir.template

Clarify cardinality of EHR Responses

Had some good discussion with @bkaney at the May HL7 Connectathon in Montreal about the cardinality of EHR Responses. That is, if a client sends an EHR a message, is the expectation that the EHR should only return one reply? Or, can two replies come back with the same "responseToMessageId"?

Because the statuses of these replies are modeled after http statuses, it's somewhat implied that there is one reply, but theoretically an EHR could choose to return a 202 initially and then a 200/201 at completion.

Additional scopes for messaging activityTypes?

Had some good discussion with @bkaney at the May HL7 Connectathon in Montreal about the list of activityTypes for the ui.launchActivity.

The Authorization section suggests a SMART scope for 'messaging/ui.launchActivity'. However, does every SMART app with that scope have the ability to navigate to any activityType? If EHRs desire to implement fine-grained control like this, would those be additional or finer-grained scopes? (e.g. messaging/ui.launchScratchpad)

Security using JWS

Can we require that the message has some sort of signature using JWS?

Additionally, can we recommend that whenever the Application has a web server component, signature is created on the web server, so that the signing credential is not available in JavaScript on the App's client side?

@isaacvetter , @jmandel : FYI - I'm writing this issue up. Let me know what thoughts you folks have.

SMART Web Messaging as a way to communicate events happening inside of a SMART App

We're implementing SMART Web Messaging in our Provider Portal (think of it as a CDS focused EHR) and would like to use SMART Web Messaging as a way to communicate events that happen inside of a SMART App back to the portal. We want the user facing elements of our portal to be minimal and delegate as many tasks as possible to SMART Apps and CDS Hooks using SMART Web Messaging as way to help with the orchestration of workflow and information between apps and CDS Hooks cards.

As an example, someone should be able to build a CPOE-type SMART App, register it in our portal, launch the portal, select a patient, launch the CPOE app, fill out an order which then the app uses SMART Web Messaging to notify the portal that the order_sign hook should be triggered. This is in contrast to a SMART app that may want to provide a draft order to the "standard/default" CPOE module and use the ui.LaunchActivity message to navigate and pre-populate an order in that module.

My question is: is that possible/intended with the current ui.LaunchActivity? If not, could we consider adding a new parameter to LaunchActivity to communicate intended/recommended behavior of the EHR/Portal to either "navigate" or "notify"? Or even add a new UI Message Type for this?

Draft implementation?

Did someone already implemented a draft implementation of the smart-web-messaging methods?

Create a history.html which resembles the smart-app-launch history.html.

The history.html links are all dead because they point to https://hl7.org/fhir/smart-web-messaging/history.html, which doesn't exist.

A version of the history page must be published to there.

IG response HTTP status code subset could be specified

The list of expected HTTP response codes could be identified, since not all of them will be relevant.

For example, the following may be the only codes expected to reasonably be encountered.

Code	Meaning
200	OK
500	EHR Error Processing Request
400	Bad Request
404	Request Not Satisfiable (???)
???	???

If there are reasonable status codes for individual request message types, it may be good to specify each of those subsets separately, too.

IG examples include code showing sample usage of the `client-js` client?

It might be helpful to see how the smart_messaging_origin and smart_web_messaging_handle values are injected into the launch context or read on the app side.

https://docs.smarthealthit.org/client-js/

Examples in the IG illustrating application code might include logic that looks like this:

<!-- index.html -->
<script src="./node_module/fhirclient/build/fhir-client.js"></script>
<script>

function launch(context) {
  const targetOrigin = context.smart_messaging_origin;
...
}

FHIR.oauth2.ready()
    .then(launch)
    .catch(console.error);
</script>

draft IG has broken links

Ensure there are no remaining broken links in https://build.fhir.org/ig/HL7/smart-web-messaging/

FHIR-33013

Define scratchpad.read as an operation that accepts an optional location parameter and returns a bundle of content from the EHR scratchpad.

Be sure the messagingHandle is present in all examples

Some examples don't include the messagingHandle - it should be included for correctness and completeness.

| `location` | OPTIONAL | string | Takes the form `ResourceType/Id` when provided. |

| location | OPTIONAL | string | Takes the form ResourceType/Id when provided. |

Should align in case with the text later on, suggest to change it to

| location | OPTIONAL | string | Takes the form resourceType/id when provided. |

Originally posted by @bvdh in #56 (comment)

IG: duplicate content in README.md and index.md

Address the alternatives-considered.md, activity-catalog.md, and README.md in the repo root. There should be only one markdown page. The build.sh script could make a copy of the main markdown file when building, copying over ig-data/input/pagecontent/index.md. Or, the README.md could link to the main content in fsh/ig-data/input/pagecontent/index.md.

Update IG wording for final publication.

Remove the rough edges from the IG wording.

Create an entry in the JIRA-Spec-Artifacts repo

The qa.html log reports a warning that:

The jira specification file appears to be out of date with the versions, artifacts and pages currently defined in the IG. A proposed revised file to be reviewed and, if appropriate, submitted as a pull request against the XML folder in https://github.com/HL7/JIRA-Spec-Artifacts.

Looking at the linked repo, it seems that a new XML file must be added for the spec to silence this warning.

Looking at the SMART example for inspiration, something like this might work:

<?xml version="1.0" encoding="UTF-8"?>
<specification gitUrl="https://github.com/HL7/smart-web-messaging" url="http://www.hl7.org/fhir/smart-web-messaging" ciUrl="http://hl7.github.io/smart-web-messaging" defaultWorkgroup="fhir-i" defaultVersion="1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../schemas/specification.xsd">
  <version code="1.0"/>
  <artifactPageExtension value="-definitions"/>
  <artifactPageExtension value="-examples"/>
  <artifactPageExtension value="-mappings"/>
  <page name="(NA)" key="NA"/>
  <page name="(many)" key="many"/>
  <page name="(profiles)" key="profiles"/>
  <page name="smart-web-messaging" key="smart-web-messaging" url="smart-web-messaging" deprecated="true"/>
</specification>