Hi everyone,
I’d like to introduce a small project that’s been a long time coming: OpenEMR SMART Questionnaires, now at GitHub - openemr/oe-smart-questionnaire · GitHub.
It’s a standalone SMART on FHIR app for completing questionnaires. You launch it from a patient’s chart, fill out the questionnaire, and the answers are saved back to OpenEMR as a FHIR QuestionnaireResponse. Before getting into how it works, I’d like to share how it came about, because it’s really the result of several pieces of work over a number of years, and not all of them mine.
A little history
A few years back I added a questionnaire tool to OpenEMR. The idea was simple: let a practice import a standard FHIR Questionnaire, say a depression screen or an SDOH assessment, and use it as a form without having to build a custom encounter form for each one. We used NLM’s LForms library to render them. It got a lot of practices collecting structured assessments they couldn’t easily collect before. But it also meant depending on a large outside library, and the answers lived mostly inside OpenEMR’s own forms rather than as real FHIR data.
Last year I started on the next step, which became PR #12880. It brought native FHIR Questionnaire and QuestionnaireResponse support to the patient dashboard (Assessments → FHIR Assessments), replaced LForms with a native runtime, and added a SMART launch flow that passes the questionnaire and response in the launch context. Once LForms was removed, questionnaires became a first-class part of the chart instead of a bolt-on.
None of the SMART side would have been possible without Stephen Nielson. Stephen did the heavy lifting on OpenEMR’s OAuth2 and SMART on FHIR infrastructure, the launch and authorization plumbing every SMART app depends on. When I built the questionnaire launch on top of it, it held up. That foundation is why a third-party app can open a patient’s chart in context today. Thank you, Stephen.
The last piece was FHIR writes. Until recently OpenEMR’s FHIR API was mostly read-only, so an outside app could display a questionnaire but had no proper way to save the answers. Building on earlier work by Chris (rollingventures), we recently merged POST and PUT support across a good number of FHIR resources. With that in place, an app can write a QuestionnaireResponse back through the standard API like any other SMART app.
This app is what you get when those pieces come together.
How the workflow goes
- From a patient’s FHIR Assessments list, choose a questionnaire and pick Launch SMART App.
- OpenEMR asks the clinician to approve access, then opens the app on that questionnaire for that patient.
- The app follows what OpenEMR tells it:
- start: a new response;
- continue: picks up the draft where it was left;
- review: shows a finished response read-only, with an option to amend.
- The clinician can save a draft and come back later, or complete it. Required questions are checked before it’s marked complete.
- Everything is saved through OpenEMR’s FHIR API as a QuestionnaireResponse on the patient’s record, and it shows up in the assessment history.
Behind the scenes the app is a confidential client, so the access token never reaches the browser. The app, not the browser, decides which patient and questionnaire a response belongs to. It can also be registered with several OpenEMR sites from one install, and there’s a small admin page for that.
Why I think this matters for clinical workflows
Collecting answers is only half of it. The value of a questionnaire is what happens next. Because the responses are now standard FHIR data written through the standard API, they can drive the next step instead of sitting in a form:
- an SDOH screening that turns into a referral;
- a physical therapy assessment tracked over time;
- a follow-up task when a score crosses a threshold.
That “render, extract, close the loop” idea is laid out in epic #13266. This app is the first working part of it. It also means other SMART apps can do the same thing, since nothing here is specific to this app.
Honest caveats
- The current OpenEMR consent screen has a quirk with SMART v2 read-and-write scopes on the same resource, so the app uses v1 scopes for QuestionnaireResponse for now. It works fine that way. I’ll be working on the OpenEMR side as a separate project, and the app already has a v2 option ready for when that lands.
- It’s new. It has a solid test suite, but real-world use is what finds the rough edges.
Trying it
The README and INSTALLATION guide in the repo walk through setup on XAMPP, Apache or nginx, registering with your OpenEMR, and troubleshooting.
I’d really appreciate testers, especially anyone using questionnaires in a real clinical setting. Tell me what works, what doesn’t, and what the next step after the questionnaire looks like in your practice. That last part will shape where this goes.
Thanks for reading, and thanks again to Stephen and everyone whose work this sits on.
Jerry
