Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

See Questionnaire for introduction and use of the resources and its elements.

Creating and Maintaining Questionnaire

Questionnaire are created and updated through Questionnaire Create and Questionnaire Update, respectively.

Later finding appropriate Questionnaire resources depends on the quality and granularity with which the Questionnaire elements are populated when created/updated. Consequently, effort should be made to ensure these elements are populated.

Filtering applied on finding appropriate Questionnaire could involve the following elements of Questionnaire:

  • useContext

  • ehealth-intendedAudience

  • ehealth-recommendation

  • status

  • juristiction

Possibly, the following elements (and others) could be used as well:

  • title

  • description

  • version

  • publisher

  • identifier

Preparing a Questionnaire for Infrastructure Rule Use

The description here applies for Questionnaire resources where processing of corresponding QuestionnaireResponse involves extraction of answer(s) to certain questions in the Questionnaire.

In the eHealth Infrastructure, such processing is performed through rules captured in Library resources. In order to make the rules robust and allow for change of question order and additional questions and answer options, the Questionnaire shall utilize defined questions in the form of DefinedQuestion resources. See DefinedQuestion for further details.

When a question in Questionnaire.item is eligible for extraction in a rule, a DefinedQuestion shall be either found or created and subsequently referenced in Questionnaire.item.definition.

The Questionnaire.item.definition shall be a business versioned reference on the form url|(business) version.

An example:

 Questionnaire.item.definition Example

A Questionnaire containing a question suitable for calculating a Medical Research Council (MRC) score is to processed by a MRC score rule. Therefore the particular question must be identifiable in order to extract the answer value from a QuestionnaireResponse in a robust way.

In the following it is given that the MRC score question has been defined (see #Managing-DefinedQuestion) as a DefinedQuestion with:

  • url set to http://ehealth.sundhed.dk/DefinedQuestion/d3db2ad6-b45e-4d21-81db-bcd0ce5d15a3

  • version set to, say, 1

Preparing for robust extraction, the Questionnaire is defined with:

  • Questionnaire.item.definition set to http://ehealth.sundhed.dk/DefinedQuestion/d3db2ad6-b45e-4d21-81db-bcd0ce5d15a3|1

As noted in DefinedQuestion, despite any reference through Questionnaire.item.definition and the values the DefinedQuestion may have, it is the answer list and other values of the Questionnaire.item that take precedence.

Preparing a Questionnaire with Embedded, Simple Calculations

A Questionnaire defined with the eHealth profile ehealth-questionnaire-advanced (see https://docs.ehealth.sundhed.dk/latest-released/ig/StructureDefinition-ehealth-questionnaire-advanced.html) can contain zero, one or more expressions performing a calculation based on answers to questions in the Questionnaire. The expression can make use of zero, one or more variables which identify the particular question/answers more concisely.

A Questionnaire defined with eHealth profile ehealth-questionnaire (see https://docs.ehealth.sundhed.dk/latest-released/ig/StructureDefinition-ehealth-questionnaire.html) cannot contain expressions nor variables.

Defining a Variable

A variable intended for use in an expression (see below) is defined using the extension variable. An example of a variable is shown below as an excerpt of a Questionnaire (in profile ehealth-questionnaire-advanced) in JSON:

 {
  "url": "http://hl7.org/fhir/StructureDefinition/variable",
  "valueExpression": {
    "name": "Count",
    "language": "text/fhirpath",
    "expression": "QuestionnaireResponse.repeat(item).where(linkId='1.2.208.176.1.5.1,7a481674-9016-46bb-8dd8-2ee49f5bbd53,Sundhedsdatastyrelsen').answer.valueInteger"
  }
}

The variable here is defined at Questionnaire root level referencing a particular question through its Questionnaire.item.linkId. On evaluation in a QuestionnaireResponse, the variable will hold the integer value of the answer (presumably, the referenced Questionnaire.item has integer answer type).

A variable is supported for a question with answer type choice, integer and decimal provided that:

  • the question is not a calculated expression

  • a question of type choice is single-choice only

  • all answer options for question of type choice have an ordinalValue (see ordinalValue)

An example of a variable evaluating to an ordinal value is shown below as an excerpt of a Questionnaire (in profile ehealth-questionnaire-advanced) in JSON:

 {
  "url": "http://hl7.org/fhir/StructureDefinition/variable",
  "valueExpression": {
    "name": "BreathingDifficulty",
    "language": "text/fhirpath",
    "expression": "iif(QuestionnaireResponse.repeat(item).where(linkId='1.2.208.176.1.5.1,6e6bb131-debd-4675-803b-7d783a75acc6,Sundhedsdatastyrelsen').answer.valueString = 'Severe', 2,
                   iif(QuestionnaireResponse.repeat(item).where(linkId='1.2.208.176.1.5.1,6e6bb131-debd-4675-803b-7d783a75acc6,Sundhedsdatastyrelsen').answer.valueString = 'Normal', 1, {}))"
  }
}

The expression above relies on the definer to ensure consistency between the actual answer values (in Questionnaire.item.answerOption.value[x]) and ordinal values possibly assigned in Questionnaire.item.answerOption.ordinalValue.

Defining a Calculation Expression

An expression is defined in a separate Questionnaire.item (or recursively, Questionnaire.item.item) which shall have:

  • Questionnaire.item.readOnly set to true

  • Questionnaire.item.type set to decimal

The expression itself is defined in the extension sdc-questionnaire-calculatedExpression (see calculatedExpression) which is an Expression FHIR element type containing:

  • language - the expression language. The supported language is a subset of FHIRPath described below. The expression language is specified as "text/fhirpath".

  • expression - the expression

An example calculation expression is shown below as an excerpt of a Questionnaire (in profile ehealth-questionnaire-advanced) in JSON:

  "extension": [
    {
      "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-calculatedExpression",
      "valueExpression": {
        "language": "text/fhirpath",
        "expression": "%Animal * %Count"
      }
    },
    "linkId": "1.2.208.176.1.5.1,25d40dde-f91c-4f11-9477-c6cca71d4178,Sundhedsdatastyrelsen",
    "text": "Total",
    "type": "decimal",
    "required": false,
    "readOnly": true
}

The following runtime behavior is not performed when maintaining the Questionnaire but provides background. On evaluation in a QuestionnaireResponse, the QuestionnaireResponse.item corresponding to the Questionnaire.item above shall contain the calculated value in its QuestionnaireResponse.item.answer.valueDecimal. Provided that values are available in the variables Count and Animal (in the evaluation context of the QuestionnaireResponse), the calculated result can be determined.

In case the expression is defined using one or more Questionnaire.item that are not guaranteed to be present in a well-formed QuestionnaireResponse, it should be defined as not required.

A Questionnaire.item is not guaranteed to be present when either:

  • it is not required

  • it depends on other answer(s) (with Questionnaire.item.enableWhen)

  • it is placed in a group nesting structure which has enableWhen itself

Expression Language

The supported expression language is the following subset of FHIRPath:

  • Arithmetic: multiplication, division, addition & subtraction only

  • Parentheses ‘(' and ')'

  • Constants

  • The equals operation (=) for primitive types

  • The iif function

Releasing a Questionnaire

Once a Questionnaire has been finalized it is eligible for use in PlanDefinition/ActivityDefinition telemedicine packages. Finalizing is performed by setting the Questionnaire status to value active through a Questionnaire Update.

The Questionnaire cannot be changed once having status set to active, except for retiring it by changing status to retired.

Retiring a Questionnaire

Retire a Questionnaire by setting the Questionnaire status to value retired through a Questionnaire Update.

Retiring a Questionnaire does not impact current or past use in resources referencing it. It signals that further use in new PlanDefinition/ActivityDefinition telemedicine packages should not happen.

Managing Defined Questions/Answers

See DefinedQuestion for introduction and use of the resource and its elements.

A DefinedQuestion serves multiple purposes:

  • Allows for establishing a versioned set of reusable questions, possibly with answer lists, that can be copied when defining Questionnaire resources.

  • Enables robust identification of a question in a Questionnaire. By adding the DefinedQuestion elements url and version with a pipe as separator to a particular question through Questionnaire.item.definition as described above, a rule can process a QuestionnaireResponse to the Questionnaire and reliably identify the answer to that question. The QuestionnaireResponse already uses the linkId from the Questionnaire.item.linkId to identify the particular question, but by traversing this link and doing lookup on any Questionnaire.item.definition, a rule can work irrespective of linkId values.

 Example DefinedQuestion for MRC question (question text in Danish)
{
    "resourceType": "StructureDefinition",
    "id": "80557",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2020-12-16T09:25:25.068+00:00",
        "profile": [
            "http://ehealth.sundhed.dk/fhir/StructureDefinition/ehealth-definedquestion"
        ]
    },
    "url": "http://ehealth.sundhed.dk/DefinedQuestion/d3db2ad6-b45e-4d21-81db-bcd0ce5d15a3",
    "version": "1",
    "name": "Hvilket af nedenstående udsagn beskriver din situation bedst? \n\nAngiv dit svar:",
    "title": "Hvilket af nedenstående udsagn beskriver din situation bedst? \n\nAngiv dit svar:",
    "status": "active",
    "publisher": "IT Telecare Nord",
    "purpose": "Genbrugeligt spørgsmål til spørgeskema",
    "kind": "logical",
    "abstract": true,
    "type": "StructureDefinition",
    "differential": {
        "element": [
            {
                "id": "StructureDefinition",
                "path": "StructureDefinition.type",
                "definition": "Hvilket af nedenstående udsagn beskriver din situation bedst? \n\nAngiv dit svar:"
            }
        ]
    }
}

Upload an External Questionnaire Definition to the Infrastructure

See Relationship between FHIR Questionnaire/QuestionnaireResponse and External Representations for overview and details on how a FHIR Questionnaire in the eHealth Infrastructure can be related to an external document representation as a Questionnaire Forms Definition Document (QFDD).

As described in Prerequisites for document registering of QuestionnaireResponse resources to national document sharing infrastructure, the corresponding questionnaire definition must be available as format Questionnaire Forms Definition Document (QFDD) and accessible to external systems in general. In addition, the QFDD must be available within the eHealth Infrastructure and it must be referenced from a Questionnaire that represents the same definition of the questionnaire.

The steps involved are:

  1. Upload the QFDD representation of the questionnaire

  2. Associate a Questionnaire with the uploaded QFDD representation

Uploading the QFDD

The QFDD must be represented in a DocumentReference and uploaded to the Document-transformation service by the operation $upload-qfdd.

The requirements for the DocumentReference:

  • DocumentReference.status must be current.

  • DocumentReference.type must be Coding for QFDD (system = "http://loinc.org" and value = "74468-0").

  • DocumentReference.description should contain the title of the questionnaire. If not assigned, the title from the QFDD document is used (in the service operation $upload-qfdd).

  • DocumentReference.content.attachment.data must contain the QFDD (as its xml representation).

See Uploading and Associating a QFDD for how to associate a questionnaire with a QFDD in the Clinical Administration Application.

Associating a Questionnaire with the QFDD

There must be a FHIR Questionnaire that represents the same questionnaire definition as defined in the QFDD.

To associate a Questionnaire with a QFDD, the Questionnaire.identifier must contain the unique document id of the QFDD:

  • Identifier.system set to “urn:oid:<Attribute root in /ClinicalDocument/id of the QFDD>"

  • Identifier.value set to “<Attribute extension in /ClinicalDocument/id of the QFDD>"

The QFDD must be uploaded to the eHealth Infrastructure and associated with a FHIR Questionnaire before a FHIR QuestionnaireResponse can be document registered as a Questionnaire Response Document (QRD).

The Questionnaire.identifier can contain multiple identifiers but only the identifier for QFDD is allowed to have an Identifier.system starting with prefix: “urn:oid:”.

See Uploading and Associating a QFDD for how to associate a questionnaire with a QFDD in the Clinical Administration Application.

Maintaining Questionnaire Terminology (Danish: Spørgeskemakodebank)

When creating FHIR Questionnaires for the purpose of document sharing, it is required that various questionnaire elements (groups, questions, answers etc.) are configured with coded values and ids.

A coded value used in the questionnaire elements must be maintained as a concept of a CodeSystem in the Questionnaire Terminology Service. The system used for an id (in Identifier.system) must exist as a NamingSystem resource created in the Questionnaire Terminology Service.

The CodeSystem and NamingSystem resources in the Questionnaire Terminology Service can be maintained by users with the Questionnaire Editor role, which has the required permissions.

The Questionnaire Terminology Service is based on the generic Terminology Service and can therefore be interacted with in the same way. Likewise, it is also registered as a standalone FHIR server in the Terminology Administration Application (see https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/2063892483/eHealth+Applications#Terminology-Administration-Application). Administration of questionnaire terminology can be performed in the Terminology Administration Application by choosing the Questionnaire Terminology Service as a backend, as described in the user manual (in Danish, see https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/2063892483/eHealth+Applications#Terminology-Administration-Application).

  • No labels