Questionnaire to Survey

This project was created to allow surveys defined as Fast Healthcare Interoperability Resources (FHIR^®) Questionnaires to be used with the SurveyJS library. The goal is to broaden the ecosystem of tools for implementing FHIR^® Questionnaires in practice.

Background

Questionnaire to Survey was designed to support clinical decision support (CDS) in the area of alcohol screening and brief intervention (ASBI). That application has shaped the specific features that are currently supported in the underlying standards and technologies described in this section.

FHIR Questionnaire

Questionnaire is one of the many interoperable resources defined by the Health Level 7 (HL7^®) FHIR^® standard. The Questionnaire resource allows a set of questions and allowable responses to be represented in an open and standard way. Each Questionnaire is defined by a set of both required and optional data elements, which are by design general in nature in order to support the capabilities most likely to be found in most healthcare systems. Questionnaire to Survey is currently focused on supporting the Questionnaire elements needed for the ASBI CDS application.

Structured Data Capture (SDC)

The base FHIR^® specification is meant to be an 80% solution for healthcare interoperability. Mechanisms such as extensions, profiles, and implementation guides provide a means in which use cases outside this 80% can be addressed. The Structured Data Capture (SDC) implementation guide defines how more complex Questionnaire functionality and behavior can be expressed. Examples of additional complexity include advanced rendering of Questionnaires and the ability to provide dynamic updates via logical expressions (see "Clinical Quality Language (CQL)" below).

Clinical Quality Language (CQL)

CQL is a domain-specific programming language focused on clinical quality applications, including CDS as well as electronic clinical quality measures (eCQMs). Logical expressions written in CQL are human-readable but can also be compiled to a machine-friendly format to facilitate implementation. Questionnaire to Survey allows CQL expressions referenced in a Questionnaire to be executed by SurveyJS via a function provided by the user.

SurveyJS

SurveyJS is a JavaScript library for rendering surveys and forms in a web browser and capturing user responses. While it provides many capabilities which are similiar to those described by FHIR^® and SDC, it is not currently able to ingest FHIR^® Questionnaires. Questionnaire to Survey is intended to fill this gap by translating FHIR^® Questionnaires into a format acceptable to SurveyJS.

Limitations

There are a number of important limitations potential users should be made aware of before using Questionnaire to Survey.

Supported Front-End Frameworks

As of version 2.0.0, Questionnaire to Survey in theory supports the same front-end frameworks that are supported by SurveyJS:

SurveyJS survey-vue had been included as a direct dependency in earlier versions of Questionnaire to Survey but has been removed in version 2.0.0. So it or one of the other SurveyJS packages (e.g., survey-react) must be included when using Questionnaire to Survey. The following snippet shows example usage with survey-vue:

import converter from 'questionnaire-to-survey'; // converter() is a function that returns another function
import { FunctionFactory, Model, Serializer, StylesManager } from 'survey-vue';
const vueConverter = converter(FunctionFactory, Model, Serializer, StylesManager);
// Create a SurveyJS object from a FHIR Questionnaire
var model = vueConverter(questionnaire);

Supported Elements

The following Questionnaire elements are currently supported:

Element	Mapping to SurveyJS	Notes & Limitations
`item.linkID`	`question.name`
`item.type`	`question.type`	Only items of type `['boolean', 'choice', 'date', 'dateTime', 'decimal', 'display', 'group', 'integer', 'string', 'text', 'time', 'url']` are currently supported. See `typeMap()` in fhirConversionTools.
`item.text`	`question.title`
`item._text`	`question.html`	Any item rendering-xhtml extensions are added to `question.html`.
`item.answerOption`	`question.choices`	`['valueInteger', 'valueDate', 'valueTime', 'valueString', 'valueCoding']` are the currently supported `answerOption` value choices. See `extractAnswers()` and `getAnswerValues()`.
`item.answerValueSet`	`question.choices`	You must provide a `resolver()` function that takes in the Canonical reference to a ValueSet resource and returns an object with the parsed JSON representation of that resource.
`item.enableWhen`	`question.visibleIf`	The FHIR^® specification says "not enabled" can either mean not visible or that answers cannot be captured; we interpret to the former when mapping to SurveyJS. See `extractVisibility()`.
`item.enableBehavior`	`question.visibleIf`	Multiple `enableWhen` conditions are combined into a single `visibleIf` expression using the specified `enableBehavior`. See `extractVisibility()`.
`item.readOnly`	`question.readOnly`
`item.initial`	`question.defaultValue`	Currently only `item.initial.valueString`s are supported.

Supported Extensions

The following FHIR^® and SDC extensions are currently supported:

Name	URL	Notes & Limitations
`sdc-questionnaire-entryMode`	http://build.fhir.org/ig/HL7/sdc/ValueSet-entryMode.html	**NEW** `random`, `sequential`, and `prior-edit` entry modes are all supported. See `./test/conversionTests.js` for a simple example. Default value is `prior-edit`.
`sdc-questionnaire-calculatedExpression`	http://build.fhir.org/ig/HL7/sdc/StructureDefinition-sdc-questionnaire-calculatedExpression.html	Can be an extension on any `item`; only one calculated expression per `item`. Is used to calculate an answer to a question. Currently only CQL expressions are supported.
`ordinalValue`	https://www.hl7.org/fhir/extension-ordinalvalue.html	Used to assign scores or weights question answer options.
`rendering-xhtml`	https://www.hl7.org/fhir/extension-rendering-xhtml.html	Used to inject XHTML into question text (via `question.html`); multiple `rendering-xhtml` extensions on a single `item._text` will be concatenated.
`cqf-calculatedValue`	https://www.hl7.org/fhir/extension-cqf-calculatedvalue.html	Can be on any `item._text`; multiple `cqf-calculatedValue` extensions on a single `item._text` will be concatenated. Used to inject dynamically-generated text into `question.text`. Currently only CQL expressions are supported.
`sdc-questionnaire-enableWhenExpression`	http://build.fhir.org/ig/HL7/sdc/StructureDefinition-sdc-questionnaire-enableWhenExpression.html	CQL expressions can be used to control the visibility of `items` in the survey. These will override any specified `item.enableWhen` and `item.enableBehavior` elements.

Usage

Setup

This project manages dependencies using the Node Package Manager. Questionnaire to Survey can be built locally by typing npm install at the command line. It is published on npm and can be installed in project via: npm install questionnaire-to-survey.

Tests

See the tests folder for a number of automated tests which demonstrate the functionality of Questionnaire to Survey. They are written using the Mocha JavaScript testing framework. After setup the tests can be run from the command line using npm run test.

Example

A working example of using Questionnaire to Survey can be found in the ASBI Screening App.

Generating QuestionnaireResponse resources from completed surveys

As of Version 2.3.0, Questionnaire to Survey exports a function for converting the output of SurveyJS into QuestionnaireResponse resources. Example usage:

import converter, { responser } from 'questionnaire-to-survey'
import { FunctionFactory, ItemValue, Model, Serializer, StylesManager, Survey } from 'survey-react'
import "survey-react/defaultV2.min.css";

export default function SurveyComponent(props) {
  let {fhirQuestionnaire, saveResponses, resolver} = props;
  
  // Create a SurveyJS model that implements `fhirQuestionnaire`
  const reactConverter = converter(FunctionFactory, Model, Serializer, StylesManager, resolver);
  var model = reactConverter(fhirQuestionnaire, null, 'defaultV2');

  // A function for converting SurveyJS outputs into a FHIR QuestionnaireResponse
  const responseConverter = responser(fhirQuestionnaire, ItemValue);

  // A React component for our FHIR Questionnaire
  return (
    <Survey
      id="survey-root"
      model={model}
      showCompletedPage={false}
      onComplete={data => saveResponses(responseConverter(data))}
    />
  )
}

Other FHIR^® Questionnaire / SDC Implementations

An incomplete list of other projects which can implement FHIR^® Questionnaires:

LForms: Capable of importing and rendering FHIR^® Questionnaires and supports many of the SDC extensions. Written using AngularJS and does not support CQL expression evaluation.

License

Unless otherwise noted, this work is available under an Apache 2.0 license. It was produced by the MITRE Corporation for the National Center on Birth Defects and Developmental Disabilities, Centers for Disease Control and Prevention in accordance with the Statement of Work, contract number 75FCMC18D0047, task order number 75D30119F05691.

Some of the test fixtures have been constructed using examples from the FHIR Release 4 (Technical Correction #1) (v4.0.1) specification. (R) (C) HL7.org 2011+.

asbi-cds-tools/questionnaire-to-survey