Creating and Maintaining a Questionnaire

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

...

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.

...

...

A Questionnaire defined with the eHealth profile ehealth-questionnaire-advanced (see https://docs.ehealth.sundhed.dk/latest-released/igfhir/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.

...

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:

...

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

...

Managing Defined Questions/Answers

...

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.

{
    "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

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).

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>"

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.

...

Maintaining and Using Codes for Questionnaire Groups, Questions and Answer Options

The eHealth Infrastructure has a Questionnaire Terminology Service for terminology used in certain elements of a Questionnaire.

Coded values maintained in one or more CodeSystem resources in the Questionnaire Terminology Service can be used for the following Questionnaire elements:

• question group (in Questionnaire.item.item.code where Questionnaire.item.item.type=group)

• question (in Questionnaire.item.item.item.code where Questionnaire.item.item.item.type=subtype of question)

• answer option (in Questionnaire.item.item.item.answerOption.valueCoding where Questionnaire.item.item.item.type=choice)

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

• Creation of CodeSystem and adding of concept (code) - This can be performed by the Questionnaire Editor role in the Terminology Administration Application (see https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/2063892483/eHealth+Applications#Terminology-Administration-Application).

  • For a CodeSystem with status draft concepts can be modified and removed. Special care should be made the user to ensure use in any Questionnaire is not influenced.

• Adding of concept (code) - This can also be performed in the questionnaire editor of the Clinical Administration Application.

Maintaining and Using Registries for Questionnaire Ids

The eHealth Infrastructure has a Questionnaire Terminology Service for terminology used in certain elements of a Questionnaire.

For a Questionnaire where QuestionnaireResponse resources are intended for registering as documents, additional ids are required in:

• question group (in Questionnaire.item.item.externalIdentifier where Questionnaire.item.item.type=group, that is, for an inner question group corresponding to a entry/organizer in QRD)

• question (in Questionnaire.item.item.item.externalIdentifier where Questionnaire.item.item.item.type=subtype of question)

• enableBehavior (in Questionnaire.item.item.item.enableBehavior.conditionId ). The conditionId is a string so the identifier must be encoded using the technique described in https://ehealth-dk.atlassian.net/wiki/spaces/EDTW/pages/390168637/Guidelines#Format-of-Questionnaire-linkId.

The system used for an externalIdentifier (in Identifier.system) must exist as a NamingSystem resource in the Questionnaire Terminology Service.

The same goes for a system encoded in a conditionId.

Managing Defined Questions/Answers

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.

{
    "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

Upload of a questionnaire definition represented as a Questionnaire Forms Definition Document (QFDD) to the eHealth Infrastructure is relevant as a preparation for either or both of:

• supporting transformation of a FHIR QuestionnaireResponse to a Questionnaire Response Document (QRD)

• supporting document registration of a FHIR QuestionnaireResponse as a QRD (implicitly, this involves the before-mentioned transformation as well)

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 its document id must be referenced from a FHIR Questionnaire that is a near approximation (see Relationship between FHIR Questionnaire/QuestionnaireResponse and External Representations ) of the QFDD, that is, essentially represents the same questionnaire definition.

The steps involved are:

1. Upload the QFDD representation of the questionnaire definition

2. Associate a FHIR 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 described in https://ehealth.sundhed.dk/fhir/OperationDefinition--s-upload-QFDD.html .

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 description. If not assigned, the title within the QFDD document is used (in the service operation $upload-qfdd).

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

Associating a FHIR Questionnaire with the QFDD

As described in Relationship between FHIR Questionnaire/QuestionnaireResponse and External Representations the FHIR Questionnaire must be or ultimately made to be a near approximation of the QFDD for the association to be correct.

To associate a FHIR 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>