Brontekst bekijken van MedMij:V2019.01 FHIR Questionnaire and Questionnaire Response (Vragenlijsten)

{{MedMij:V2019.01_Vragenlijsten1_Uitgefaseerd}}
__NUMBEREDHEADINGS__
{{DISPLAYTITLE:MedMij FHIR Implementation Guide: Questionnaires {{Sjabloon:VersieInfo|V2019.01|Vragenlijsten}}}}
{{MedMij:V2019.01_Issuebox_FHIR_IG}}

[[Bestand:MedMij2.png |link=https://www.medmij.nl/|rechts|Naar medmij.nl]]
[[Bestand:vragenlijstenIcoon.png|link=|87px |links||media|Icoon vragenlijsten]]
<imagemap>Bestand:Leeswijzer-technisch-banner 03 white.png|center|400px|alt=Afspraken-Functioneel-Technisch   
circle 241 216 211 [https://www.medmij.nl/afsprakenstelsel Afsprakenstelsel]                
circle 1013 224 212 [[MedMij:V2019.01_OntwerpVragenlijsten|Functioneel]]                
circle 1787 230 212 [[MedMij:V2019.01_FHIR_IG|Technisch]]                
desc none                    
</imagemap>

__TOC__

=Introduction=
[[Bestand:Functioneel-02.png|link=MedMij:V2019.01_Ontwerpen |100px|rechts|Functional design|Go to functional design]]

This page describes the exchange of questionnaires and questionnaire responses within MedMij. A questionnaire is an organized collection of questions intended to solicit information from patients, providers or other individuals involved in the healthcare domain. A questionnaire may take the form of a straightforward flat list of questions, but may also be hierarchically organized in groups and sub-groups. Likewise, it can contain a wide range of question types, varying from simple fill-out fields to multiple-choice questions, scales and questions with dependency's to previous answers.

These questionnaires are captured using the FHIR Questionnaire resource, which defines the questions to be asked, their ordering and grouping, instructional text and the constraints on the answers. The results of a Questionnaire are communicated using the QuestionnaireResponse resource. To support the logistics of assigning and answering a questionnaire, a Task resource is used. In this IG, it will be referred to as "QuestionnaireProvisioningTask".

This information standard is inspired by the international [[MedMij:V2019.01_OntwerpVragenlijsten#sdc|Structured Data Capture (SDC)]] implementation guide and tries to follow it where possible. However, the first version of this information standard is more restricted than SDC; specifically, the possibility for a XIS to pre-populate the questionnaire response is omitted in this first version. Also, contrary to most other use cases for MedMij, no specific HCIM models have been identified for prescribing and answering questionnaires. 

This IG is a technical representation of the [[MedMij:V2019.01_OntwerpVragenlijsten|functional design]] and follows the principles of the [[MedMij:V2019.01_FHIR_IG|general MedMij FHIR IG]].

=Actors involved=
The table shows the relevant actors, systems and FHIR CapabilityStatements. The CapabilityStatements demonstrate the minimum conformance requirements for the described use cases.

A XIS may choose to host the Questionnaire resource or may refer to an external repository, as long as this Questionnaire doesn't contain any personally identifiable information and this external repository adheres to the [[MedMij:V2019.01_FHIR_IG#Use_case_overarching_principles|overarching principles]] in the MedMij IG.

{| class="wikitable"
! colspan="2" style="text-align:left; background-color: #4AB8A7; color: white; font-weight: bold;" | Actors
! colspan="2" style="text-align:left; background-color: #4AB8A7; color: white; font-weight: bold;" | Systems
! colspan="2" style="text-align:left; background-color: #4AB8A7; color: white; font-weight: bold;" | FHIR CapabilityStatements
|-
! style="text-align:left; |Name
! style="text-align:left; |Description
! style="text-align:left; |Name
! style="text-align:left; |Description
! style="text-align:left; |Name
! style="text-align:left; |Description
|-
| Patient
| The user of a personal healthcare environment
| PHR
| Personal health record
* retrieves a QuestionnaireProvisioningTask
* retrieves a Questionnaire
* updates the QuestionnaireProvisioningTask
* sends the QuestionnaireResponse
| {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/questionnaires-clientcapabilities|nictiz.fhir.nl.stu3.zib2017|pkgVersion=1.3.12|title=CapabilityStatement: Client}}
| FHIR Client requirements 
|-
| Healthcare professional
| The user of a XIS
| XIS
| Healthcare information system
* provides a QuestionnaireProvisioningTask
* hosts a Questionnaire (optional)*
* receives updates to the QuestionnaireProvisioningTask
* receives the QuestionnaireResponse
| {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/questionnaires-servercapabilities|nictiz.fhir.nl.stu3.zib2017|pkgVersion=1.3.12|title=CapabilityStatement: Server}}
| FHIR Server requirements
|}

=Boundaries and relationships=
The MedMij use case for questionnaires overlaps partially with the uses cases described in the [http://hl7.org/fhir/us/sdc/ Structured Data Capture (SDC) IG]. Therefore, this IG tries to align as close as possible to the SDC IG. However, there are key differences that prevent the verbatim use of the SDC IG:
* The current use case is more restricted.
* The profiles for the MedMij use case reference HCIM based profiles for common resources like Patient, Practitioner, PractitionerRole and Organization.
* The interpretation of <code>mustSupport</code> and the use of <code>isModifier</code> in SDC differs fundamentally from other MedMij IG's and are therefore ignored in this IG.
* The <code>QuestionnaireResponse.author</code> tells who the person is that provided the answers. For the current MedMij use case it is restricted to a patient. The <code>QuestionnaireResponse.subject</code> tells who the answers apply to. For the current MedMij use case it may be a patient, organization, practitioner, medical device or a payer.

=Use case: retrieve questionnaire reference=
==List of invocations==
[[Bestand:Afsprakenstelsel-01.png|link=https://www.medmij.nl/afsprakenstelsel/|rechts |100px|Go to Afsprakenstelsel]]

The order of invocations follows the [https://informatiestandaarden.nictiz.nl/wiki/MedMij:V2019.01_OntwerpVragenlijsten functional design]. At first the questionnaire is assigned to the patient by a QuestionnaireProvisioningTask. The PHR extracts the reference to the Questionnaire resource from the "Questionnaire" slice in <code>Task.input</code> and retrieves it from the XIS or from an external server.

This FHIR implementation guide assumes that the PHR system is able to make a connection to search Task resources at the XIS. It does not provide information on finding the right XIS nor does it provide information about security. These infrastructure and interface specifications are described in the [https://www.medmij.nl/afsprakenstelsel/ 'MedMij Afsprakenstelsel'].

===Client searches QuestionnaireProvisioningTask - PHR===
Using a [http://hl7.org/fhir/STU3/search.html search operation], the PHR retrieves a QuestionnaireProvisioningTask containing a reference to the questionnaire from the XIS. The Task resource SHALL conform to the [[#FHIR_profiles|vl-QuestionnaireProvisioningTask profile]] and SHALL initially have <code>Task.status</code> set to "requested" (see [[#QuestionnaireProvisioningTask state machine]]). The Questionnaire resource SHALL be referenced using <code>valueReference.reference</code> of the "Questionnaire" slice in <code>Task.input</code>.

 GET [base]/Task/?code=<nowiki>http://loinc.org|74468-0</nowiki>&status=requested

If the search operation fails (cannot be executed, not that there are no matches), the return value is a status code 4xx or 5xx with an OperationOutcome (see [http://hl7.org/fhir/STU3/search.html#errors the FHIR documentation on search]).

=Use case: retrieve questionnaire=
==List of invocations==
===Client retrieves the Questionnaire resource - PHR===
Upon retrieving the QuestionnaireProvisioningTask, the PHR retrieves the Questionnaire resource referenced in the QuestionnaireProvisioningTask using a [https://www.hl7.org/fhir/stu3/http.html#read read operation]. This reference may live on the same base as the XIS or may be an external server.

 GET ''Task.input:Questionnaire.valueReference.reference''

The Questionnaire resource SHALL conform to the [[#FHIR_profiles|Questionnaire profile]].

If this operation fails (after repeated attempts), the PHR should close the QuestionnaireProvisioningTask with status "failed" (see [[#Updating the QuestionnaireProvisioningTask]]). This closes the QuestionnaireProvisioningTask and ends the workflow (see [[#QuestionnaireProvisioningTask state machine]]).

=Use case: send questionnaire response=

==Client renders questionnaire form - PHR==
The PHR should present the questions defined in the retrieved Questionnaire resource to the user, in accordance with their type, overall structure of the questionnaire, and restrictions on the answers. MedMij defines the following minimal subset of [https://www.hl7.org/fhir/stu3/valueset-item-type.html Questionnaire item types] that a PHR MUST support:
* Group
* Display
* Boolean
* Decimal
* Integer
* Date / dateTime / time
* String / text
* Choice / open-choice, where the possible answers are defined using <code>option</code> elements
* Quantity

The following elements of the <code>Questionnaire.item</code> element MUST be supported:
* <code>Questionnaire.item.enableWhen</code>
* <code>Questionnaire.item.required</code>
* <code>Questionnaire.item.option</code>

In addition, the following extensions MUST be supported:
* [http://hl7.org/fhir/stu3/extension-minvalue.html minValue]
* [http://hl7.org/fhir/stu3/extension-maxvalue.html maxValue]
* [http://hl7.org/fhir/stu3/extension-minlength.html minLength]
* [https://www.hl7.org/fhir/stu3/extension-maxdecimalplaces.html maxDecimalPlaces]
* [https://www.hl7.org/fhir/stu3/extension-questionnaire-unit.html unit]

A PHR MAY support other Questionnaire item types as well. However, if a PHR is unable to process any one part in the Questionnaire, it MUST reject the Questionnaire altogether, see below.

'''Note''': for known questionnaires, a PHR may choose to use hardcoded over generated forms. However:
* A PHR implementing this information standard should always be able to generate a form for the minimal Questionnaire requirements.
* Currently, no coding system exists to identify known questionnaires. Known questionnaires might be recognized by the reference in the QuestionnaireProvisioningTask or by the Questionnaire.url field, which presents the canonical URL for the Questionnaire resource (even if it served elsewhere). Although the URL in the XIS reference or Questionnaire.url MUST be version specific, the PHR MUST check whether the referenced Questionnaire resource matches the one it has hardcoded
===Multiple-choice questions in FHIR===

Unfortunately, the FHIR core documention for the Questionnaire and QuestionnaireResponse resources is somewhat confusing and actually contains an error in the topic of multiple-choice questions. This section is meant to clarify the use of multiple-choice type questions in FHIR STU3.

In FHIR STU3 there are two scenarios for multiple-choice questions: in the first scenario, the answer MUST come from a list of predefined options, while in the second scenario, the user MAY alternatively provide a custom answer. In a Questionnaire resource, to define a multiple-choice question, <code>item.type</code> MUST be set to "choice" for the first scenario, or "open-choice" for the second scenario. The answer options MUST be defined using either:
* The <code>Questionnaire.item.options</code> element, which contains a reference to a ValueSet with the possible answers. '''Note''': support for this mechanism is not required for this information standard.
* Using one or more <code>Questionnaire.item.option</code> elements, with possible answers defined as <code>valueCode</code>. '''Note''': although the Questionnaire resource defines <code>item.option.value[x]</code> as a polymorphic element with multiple types, ''only coding is actually allowed''. In the relevant profile, this element is therefore restricted to the coding type.

Likewise, the QuestionnaireResponse resource should capture the answer using <code>QuestionnaireResponse.item.answer.valueCode</code>:
* If the user selects one of the predefined answers, it should be captured in the answer using the <code>code</code> (and if present, <code>system</code>) elements of the <code>valueCode</code>.
* If the question is of type "open-choice" and the user provides an alternative answer, it should be captured using the <code>display</code> element of the <code>valueCode</code>.

Questionnaire example:
<syntaxhighlight lang="xml">
<item>
    <linkId value="example"/>
    <text value="Example question"/>
    <type value="choice"/>
    <option>
        <valueCoding>
            <code value="EO1"/>
            <display value="Example option 1"/>
        </valueCoding>
    </option>
    <option>
        <valueCoding>
            <code value="EO2"/>
            <display value="Example option 2"/>
        </valueCoding>
    </option>
</item>
</syntaxhighlight>

QuestionnaireResponse example:
<syntaxhighlight lang="xml">
<item>
    <linkId value="example"/>
    <answer>
        <valueCoding>
            <code value="EO1"/>
            <display value="Example option 1"/>
        </valueCoding>
    </answer>
</item>
</syntaxhighlight>

==List of invocations==
[[Bestand:Afsprakenstelsel-01.png|link=https://www.medmij.nl/afsprakenstelsel/|rechts |100px|Go to Afsprakenstelsel]]

This FHIR implementation guide assumes that the PHR system is able to make a connection to update the Task resource at the XIS and send the QuestionnaireResponse resource to the XIS. It does not provide information on finding the right XIS nor does it provide information about security. These infrastructure and interface specifications are described in the [https://www.medmij.nl/afsprakenstelsel/ 'MedMij Afsprakenstelsel'].

===Client accepts or rejects the Questionnaire===
Upon retrieving the Questionnaire resource, the PHR SHOULD check if it is able to present a form that ''completely'' covers all the questions and structure and subsequently update the QuestionnaireProvisioningTask resource (see [[#Updating the QuestionnaireProvisioningTask]]):
* If the Questionnaire can be processed, Task.status SHALL be set to "accepted".
* If the Questionnaire cannot be processed, Task.status SHALL be set to "rejected". This closes the QuestionnaireProvisioningTask and ends the process (see [[#QuestionnaireProvisioningTask state machine]]).

===Client provides QuestionnaireResponse - PHR===
The answers to the questions in the Questionnaire resource are captured using an instance of the QuestionnaireResponse resource, which SHALL conform to the [[#FHIR_profiles|QuestionnaireResponse profile]]. If the PHR is unable to process the user response or in some other way is unable to create a QuestionnaireResponse resource, it should close the QuestionnaireProvisioningTask with status "failed" (see [[#Updating the QuestionnaireProvisioningTask]]). This closes the QuestionnaireProvisioningTask and ends the process (see [[#QuestionnaireProvisioningTask state machine]]).

Upon completion of the questionnaire by the user, the PHR system uses a [https://www.hl7.org/fhir/stu3/http.html#transaction transaction operation] to simultaneously:
* Send the QuestionnaireResponse resource to the XIS.
* Update the QuestionnaireProvisioningTask at the XIS to set <code>Task.output.valueReference</code> to the QuestionnaireResponse.
* Update the QuestionnaireProvisioningTask at the XIS to set <code>Task.status</code> to "completed".

A FHIR transaction is a POST command to the XIS endpoint:

 POST [base]

The body of the POST operation SHALL be a Bundle resource with Bundle.type set to "transaction" that SHALL contain
* The QuestionnaireResponse resource as a <code>create</code> interaction.
* The original Task resource with the required changes in <code>Task.status</code> and <code>Task.output</code> as an <code>update</code> interaction (see [[#Updating the QuestionnaireProvisioningTask]]).

Example:
<syntaxhighlight lang="xml">
<Bundle xmlns="http://hl7.org/fhir">
    <type value="transaction"/>
    <entry>
        <resource>
            <Task>
                <id value="ORIGINAL_ID"/><!-- where ORIGINAL_ID is the Task.id as received from the XIS -->
                <meta>
                    <profile value="http://nictiz.nl/fhir/StructureDefinition/vl-QuestionnaireProvisioningTask"/>
                </meta>
                <status value="completed"/>
                ...
                <output>
                    <type>
                        <text value="QuestionnaireResponse"/>
                    </type>
                    <valueReference>
                        <reference value="urn:uuid:e607a55c-194d-447a-8cc7-7ab90e3660c3"/>
                        <display value="Response to questionnaire XXX">
                    </valueReference>
                </output>
            </Task>
        </resource>
        <request>
            <method value="PUT"/>
            <url value="Task/ORIGINAL_ID"/><!-- where ORIGINAL_ID is the Task.id as received from the XIS -->
        </request>
    </entry>
    <entry>
        <fullUrl value="urn:uuid:e607a55c-194d-447a-8cc7-7ab90e3660c3"/>
        <resource>
            <QuestionnaireResponse>
                <meta>
                    <profile value="http://nictiz.nl/fhir/StructureDefinition/vl-QuestionnaireResponse"/>
                </meta>
                ...
            </QuestionnaireResponse>
        </resource>
    </entry>
    <request>
        <method value="POST"/>
        <url value="QuestionnaireResponse"/>
    </request>
</Bundle>
</syntaxhighlight>

If the server is able to process both resources, it SHALL return a HTTP 200 OK status code and SHALL also return a Bundle of type <code>transaction-response</code>, that contains one entry for each entry in the request, in the same order, with the outcome of processing the entry. If the server is unable to process either of the resources, it SHALL not process any one of them and SHALL return an HTTP 400 or HTTP 500 type response. Also see the FHIR specification on [https://www.hl7.org/fhir/stu3/http.html#transaction-response transaction response].

'''Note''': updating the QuestionnaireResponse is not supported in the use case.

=Tracking the status using the QuestionnaireProvisioningTask=
==Introduction==
Retrieving the questionnaire and sending the answers are two separate use cases, but they are meant to be used back-to-back; the XIS that prescribes the questionnaire ultimately expects a response to it (and a questionnaire response is only sent in response to a prescription, at least in the current version of this information standard). To track the status of the prescription fulfillment, a Task resource at the XIS server is used, which transitions through various stages until completion.

It is the responsibility of the PHR to update the QuestionnaireProvisioningTask at the different stages in the life cycle of the questionnaire, using an update operation (see [[#Updating the QuestionnaireProvisioningTask]]). This implies that the the Task resource should be made accessible by the XIS server for these updates, at least for the expected lifetime of the fullfillment cycle. Additionally, the PHR may perform a [https://www.hl7.org/fhir/stu3/http.html#read read operation] of the Task resource at any time.

It is primarilly the responsibility of the PHR to bring the QuestionnaireProvisioningTask to a closed state. However, it is not guaranteed that the required update operation succeeds. If the PHR is unable to bring the QuestionnaireProvisioningTask to a closed state, the server may eventually close it because of business rules.

==QuestionnaireProvisioningTask state machine==
The Task resource can transition through the following states:
<pre>
          /----------------/-------------------\
          |                |                   |
requested +--+-> accepted -+---> completed ----+---> X
          |  |             |                   |
          |  \-------------\--> failed --------|
          |                                    |
          \--> rejected -----------------------/
</pre>

Only the transitions shown here are allowed. The server SHOULD reject any update that attempts to perform an illegal transition. See [[#Updating the QuestionnaireProvisioningTask]].

==Updating the QuestionnaireProvisioningTask==
The Task resource at the XIS can be updated by the PHR using the [https://www.hl7.org/fhir/stu3/http.html#update FHIR update operation]. To perform this operation, the modified Task resource should be sent using a PUT operation: 

 PUT [base]/Task/''ORIGINAL_ID''

Where ORIGINAL_ID is the <code>Task.id</code> from the QuestionnaireProvisioningTask originally received from the XIS.

'''Note''': the Task resource SHOULD be sent completely and without changes, apart from the relevant modifications.

The server may be unable to accept an update the Task resource due to errors or because of business rules (e.g. because of an illegal status transition). In this case, the server SHOULD respond with a 400 type status code, accompanied by an OperationOutcome resource providing additional details (see [https://www.hl7.org/fhir/stu3/http.html#2.21.0.10.1 the FHIR documentation on rejecting updates]).

The PHR should try to recover from this response. If this is not possible, the PHR SHOULD attempt to update the status of the QuestionnaireProvisioningTask on the server to "failed" and stop further processing. If it is not possible to perform this update, the QuestionnaireProvisioningTask effectively remains in a stalled position. The server may eventually close it because of business rules.

=FHIR profiles, interactions, search parameters=

==FHIR profiles==

{{NoteBox|MedMij uses the FHIR packaging mechanism. This allows you to conveniently download examples, profiles and other conformance resources for the current standard and all packages it depends on. For more background information see the [[MedMij:V2019.01_FHIR_IG|the FHIR implementation guide]]. The latest Questionnaires package can be found [https://simplifier.net/nictizstu3-questionnaires/~packages at Simplifier]. It depends on [https://simplifier.net/NictizSTU3-Zib2017/~packages Nictiz package {{VersieInfo|package|release=V2019.01}}] and [https://simplifier.net/packages/hl7.fhir.uv.sdc/2.0.0 SDC package version 2.0.0].}}

{| class="wikitable" style="horizontal-align: right" 
!style="background-color: #4AB8A7; color: white; font-weight: bold; text-align:left;  background-color: #E3E3E3 width:400px" | Canonical URL
!style="background-color: #4AB8A7; color: white; font-weight: bold; text-align:left;  background-color: #E3E3E3 width:50px" | FHIR resource
!style="background-color: #4AB8A7; color: white; font-weight: bold; text-align:left;  background-color: #E3E3E3 width:50px" | HCIM EN
|-
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-patient|nictiz.fhir.nl.stu3.zib2017|pkgVersion=1.3.12}}
| Patient
| Patient
|-
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner|nictiz.fhir.nl.stu3.zib2017|pkgVersion=1.3.12}}
| Practitioner
| rowspan="2" | HealthProfessional
|-
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-practitionerrole|nictiz.fhir.nl.stu3.zib2017|pkgVersion=1.3.12}}
| PractitionerRole
|-
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-organization|nictiz.fhir.nl.stu3.zib2017|pkgVersion=1.3.12}}
| Organization
| HealthcareProvider
|-
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/zib-Payer|nictiz.fhir.nl.stu3.zib2017|pkgVersion=1.3.12}}
| Coverage
| Payer
|-
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/zib-MedicalDevice|nictiz.fhir.nl.stu3.zib2017|pkgVersion=1.3.12}}
| DeviceUseStatement
| MedicalDevice
|-
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/vl-Questionnaire|nictiz.fhir.nl.stu3.questionnaires|pkgVersion=1.0.2}}
| Questionnaire
| 
|-
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/vl-QuestionnaireResponse|nictiz.fhir.nl.stu3.questionnaires|pkgVersion=1.0.2}}
| QuestionnaireResponse
| 
|-
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/vl-QuestionnaireProvisioningTask|nictiz.fhir.nl.stu3.questionnaires|pkgVersion=1.0.2}}
| Task
| 
|}

==Interactions==
The following logical interactions are needed for the Questionnaires information standard:
* [http://hl7.org/fhir/STU3/search.html Search] -- Task
* [http://hl7.org/fhir/STU3/http.html#update Update] -- Task
* [http://hl7.org/fhir/STU3/http.html#read Read] -- Questionnaire
* [http://hl7.org/fhir/STU3/http.html#create Create] -- QuestionnaireResponse

==Search parameters==
The following search parameter types and search result parameters need to be supported for this use case.

Search parameter types:
* [http://hl7.org/fhir/STU3/search.html#token token]
** Including modifier 'in'
* [http://hl7.org/fhir/STU3/search.html#reference reference]

=Release notes=
Release notes can be found on the [[MedMij:V2019.01_OntwerpVragenlijsten#Release_notes| functional design page]].
{{EindUitgefaseerd}}