Questionnaire/Assessment feature implementation instructions

sjpadgett · July 30, 2022, 12:04am

Warning see Questionnaire/Assessment feature implementation instructions - #30 by sjpadgett

New encounter questionnaire instructions: Questionnaire/Assessment feature implementation instructions - #5 by sjpadgett

Though many will be creative in different ways to develop a questionnaire, I’ll show a couple ways to get started using NIH tools.
Note the following websites:

LHC-Forms Questionnaire App Is an available application populated with many test patients and questionnaires.
NLM Form Builder Can be used to import existing questionnaires to modify from a couple FHIR server sources or simply use form as is.

Both sources allow either a file download as a json FHIR Questionnaire where the file can then be used to import into OpenEMR from the Portal Dashboard->Manage Templates or a clipboard copy/paste into your own file.

So I’ll start with picking a PHQ-9 questionnaire with scoring using NLM Form Builder and selecting from a LOINC search.

Select on left Export then Export to file and save the R4 version using a file name the patient will understand as that will be the name used after file import. The file should contain only the resource json and be give a .json extension.

Using the dashboard Template Manager you may import as a questionnaire template for the portal or import just the questionnaire to be stored in the questionnaire repository for use by the FHIR API/SMART app or future self created templates using the Questionnaire directives available in the template editor drag/drop menu.

When importing as a normal template import, OpenEMR will auto create the necessary document template and assigned the json resource which is stored in questionnaire repository and the template to the Document Template repository which can then be assigned to a Profile and patients/groups.

After Template import

Then drag and drop to a profile.

Next ensure profile is enabled for the portal here:

Once this is done go to portal for an assigned patient and select questionnaire from My Documents->Select Documents pull down.

That’s all there is to it. I hope this hasn’t been to brief however, please ask any questions if any clarifications are needed and I’ll respond ASAP.

Thanks

adunsulag · July 30, 2022, 5:50pm

To use the NLM tool, here are a couple more screenshots to get you the phq9 form.

First on the NLM page:

Hit the Imports button

Then select the Import a LOINC form:

Put in a search term for the type of form you want to import.

In this case we will do phq9:

Hit the import button once you’ve selected the form you want and it shows up on the screen

Now as Jerry mentioned hit the export button with export to file

Select R4 option and hit continue

Now follow the rest of Jerry’s steps to complete the process.

sjpadgett · July 30, 2022, 5:56pm

Thanks Stephen! Ifin I wasn’t so darn lazy!

sjpadgett · July 30, 2022, 6:01pm

Just a note to all. I’m now working on adding a dialog to allow dropping/pasting a questionnaire json into a text box and a name input instead of having to create a file to import.
Also adding the questionnaire repository items to a new table for deleting/edit or general management of questionnaires.

sjpadgett · August 6, 2022, 5:23am

Creating an encounter questionnaire from questionnaire/assessment lookup.

First select the new encounter form New Questionnaire menu:

image1788×531 86.3 KB
Type to search and select 2. Name the form or leave the default 3. Edit and Save the form or Register the form which will make the questionnaire available to all encounters and users.

image1788×865 150 KB
If populated and saved then form is available in encounter the same as any other encounter form.

image1919×542 34.3 KB
If you register the questionnaire:

image1788×651 117 KB

That’s it and should have this finish by Monday 8/9

lgalarce · August 12, 2022, 5:03pm

I was looking for LHC-Forms and OpenEMR, and I came across this post. When will this be added (in which patch)? I’m really exited for this feature.

sjpadgett · August 12, 2022, 5:14pm

Hi and welcome.
I plan at minimum to include the encounter implementation in patch 2.
I still have work to do on the portal and demographics implementation so currently I’m not sure about their inclusion.

sjpadgett · October 8, 2022, 3:49pm

For all of you interested and tracking this thread I have finished Questionnaire/Assessments up to creating the endpoints. Feature is now in the master branch as well as I’ve created a pre-patch for upcoming v7 patch 2.

This file contains all fixes in v7 production branch up to today 10/8/22 including patch 1.

You may also test the feature on one of our development demos at:
https://www.open-emr.org/wiki/index.php/Development_Demo

To test you may want to go to the LHC Forms builder: NLM Form Builder, import say the GAD7 or PHQ9 assessment and import to openemr via the Portal Dashboard Template Maintenance Import.

For scoring type forms export/import the LHC Forms version and not the R4 because the current public builder does not export the required questionnaire resource extensions for scoring(SDC). There’s other ways to do this.

Or as an admin privileged user you may also import and register forms with encounter New Questionnaire.

You may also use the Manual Import in Dashboard import to cut and paste form json from a tool that will allow you to grab SDC type questionnaires at: LHC-Forms select a patient, select or upload a form from left panel then use the Show As button to pop up the form json to copy and paste.

Doing a little research on the various ways to generate forms will help you out greatly in understanding the power of this feature.

On file selection for import, a tool will pop up to verify and do conversion to both form types then allow import to repository. You may also test both version types(Questionnaire and LHC Form) of form. The default for rendering in encounter is LHC Form if available otherwise form render will revert to the Questionnaire version.

If you cancel you still have opportunity to import

I have created and support several ways to implement this feature with the hope the user has every opportunity to leverage this capability in their practices. Hopefully I haven’t been to overzealous in my
madness!

Let me know what you think and thanks.

ruth · October 14, 2022, 2:27pm

just to say i think this is going to be really useful, so much easier than writing a form in php. I’m still exploring and getting my head round how everything works, so the question below might be redundant as i get deeper into it. I think ‘several ways to implement this feature…’ sounds great - thanks!

the link to LHC-Forms is v. useful - following it’s links takes one to lots of information about how the forms are formatted and the json definitions for forms etc.

a question - if a form is imported in json format, is it saved as a file in the system - and if so does one have to import it each time OpenEMR is upgraded to a new version/patch? and if so can one submit one’s form as a PR?

sjpadgett · October 14, 2022, 2:47pm

All Templates and Assessment/Questionnaire forms are persistent and stored in a database repository for the reason of exposing to anywhere one wishes to use the form. E.g. encounters can use the repository for new registered encounter form and the API.
I stopped saving files to the file system back in v6.0.0. So upgrades and backups are not an issue.

I’m thinking we can use contrib forms directory for sharing if one wishes to share with community.

ruth · October 21, 2022, 2:46pm

hi @sjpadgett - i’m developing a form that has required answers. To test this feature I used the LOINC phq-9 form, imported into NLM form builder. I made all but one question ‘required’, i then exported the lhc version (to also do scoring), saved the .json file, uploaded it into openemr using the miscellaneous/portal dashboard. (i didn’t get a list of templates, as illustrated above, but no worries ) - i then went to an encounter of a patient, selected questionnaires/new and got up an instance of the questionnaire.

the required questions were marked with an asterix, but if they weren’t answered this was just accepted, i.e. no warning was given (as an example when i use the phq-9 or gad7 forms the user is given an error message if the form is saved with any questions not answered). In the jason file this is indicated by
"answerCardinality": { "min": "1", "max": "1" },
but i’ve also seen "required": true,
used.

is there something extra or different that I need to do to get a warning if a required answer is not given, or preferably an inability to save the completed questionnaire ?

many thanks.

sjpadgett · October 21, 2022, 3:48pm

Hi @ruth
I completely forgot to implement the form validation! That’s almost as bad as forgetting to put the toilet seat down!

I’ll get it done in the next day or two and in patch 2 with the rest of feature.
Thanks for catching.

ruth · October 21, 2022, 3:57pm

no worries, thanks for adding it in. By the way, will both indications in the json file work? i.e. ‘required’ as well as ‘cardinality’ ?

and i just found out how to get the list in the template repository window, so that’s sorted (for me) too.

sjpadgett · October 21, 2022, 4:08pm

Unsure Ruth. I think the cardinality is mostly for Questionnaire FHIR resource. lForms has it’s own datatypes and parsing schema,
Again, I’m not sure how renderer is using it but will know better once I get into validation.

I’ll let you know when I’m done with validation and I update this thread.

I do want to note again that whenever using scoring type forms from IHE builder, import as lforms and not questionnaire R4 json. For some reason the builders conversion from lforms to questionnaire R4 does not convert the scoring fields to FHIR extensions needed by SDC spec to render correctly.

ruth · October 21, 2022, 4:54pm

thanks Jerry. Yes, i did get the message about scoring type forms, and the phq-9 I imported is doing scoring nicely!

sjpadgett · October 22, 2022, 5:55pm

Hi @ruth
Fix is here Missing form validation Questionnaires by sjpadgett · Pull Request #5868 · openemr/openemr · GitHub

Here is source with the fix to save ya some time. Again thank you for taking the time to test and report on issues you find. Very helpful to us!
Place in interface/forms/questionnaire_assessments/questionnaire_assessments.php
questionnaire_assessments.php (23.3 KB)

ruth · October 22, 2022, 6:10pm

thanks jerry, that works . I’ll be doing more testing over the next couple of days…

ruth · October 23, 2022, 3:29pm

Hi @sjpadgett - I felt the formatting of the alert message was difficult to read if there were more than one question that needed answering, also I was thinking how a non technical user, or a patient, might react to the message. I added in some code to improve the message, but i expect it’s not the right place or method to use - but it illustrates what I mean.

I failed to locate the code further back that generates the error message, which is perhaps where the changes should go? I’m only gradually understanding how this works!! Also i’m aware that there might be other kinds of questionnaire errors at this point in the code. Any way the code I added into the function saveQR() is as follows, and i’m using that at the moment for further testing.

 function saveQR() {
            if (!isPortal) {
                top.restoreSession();
            }
            let formElement = document.getElementById("formContainer");
            let notValid = LForms.Util.checkValidity(formElement);
            if (notValid) {
                let formatText = xl('Form failed validation?') + "<br />" + jsText(notValid) ;
                const rav =  'requires a value' ;
                if (jsText(notValid).indexOf(rav) >= 0){
                    /* unanswered required questions */
                    /* format the error message */
                    let errmsg = jsText(notValid);
                    errmsg = errmsg.replaceAll(rav,' : **' + rav);
                    // mop up the extra commas
                    errmsg = errmsg.replaceAll(rav + ',',rav+' <br />');
                    formatText = xl('Please answer all the following questions') + "<br /> <br />" + errmsg ;
                    }
                dialog.alert(formatText).then(returned => {
                    dialog.close();
                    return false;
                });
            } else {

ruth · October 24, 2022, 10:07am

good morning @sjpadgett
has skip logic been implemented - as described in section 8 on this page? LForms Demos

also, in the summary of the completed questionnaire in an encounter, boolean values are displayed as ‘1’ or ‘0’ - I was wondering if this could be changed to ‘yes’ and ‘no’ as for many people ‘1’ and ‘0’ will not be so meaningful here? many thanks

sjpadgett · October 24, 2022, 1:39pm

Yes, and I’ve tested on one form.

You have to create the answer options how you want them when building the forms.

Remember, I have no control over LForms rendering because it is a outside project. I don’t want to at this time, customize and take ownership of our own implementation of LForms.