Zandbak/MVPTO: verschil tussen versies

Uit informatiestandaarden
Naar navigatie springen Naar zoeken springen
k (Tekst vervangen - "{{#customtitle:" door "{{DISPLAYTITLE:")
 
(26 tussenliggende versies door 2 gebruikers niet weergegeven)
Regel 1: Regel 1:
 
__NUMBEREDHEADINGS__
 
__NUMBEREDHEADINGS__
{{#customtitle:MedMij FHIR Implementation Guide: Questionnaire and Questionnaire Response (Vragenlijsten)}}
+
{{DISPLAYTITLE:MedMij FHIR Implementation Guide: Questionnaires {{Sjabloon:VersieInfo|V2019.01|Vragenlijsten}}}}
 
{{MedMij:Vdraft_Issuebox_FHIR_IG}}
 
{{MedMij:Vdraft_Issuebox_FHIR_IG}}
  
Regel 17: Regel 17:
 
[[Bestand:Functioneel-02.png|link=MedMij:Vdraft_Ontwerpen |100px|rechts|Functional design|Go to functional design]]
 
[[Bestand:Functioneel-02.png|link=MedMij:Vdraft_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. These questionnaires may take the form of a straightforward flat list of questions, but they can consist of hierarchically organized groups and sub-groups. Likewise, there can be a wide range of question types, varying from simple fill-out forms to multiple choice questions and scales.
+
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 can be communicated using the QuestionnaireResponse resource. To support the logistics of assigning and answering a questionnaire, a Task resource is used.
+
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.
  
 
This information standard is inspired by the international [[MedMij:Vdraft_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 information standard is inspired by the international [[MedMij:Vdraft_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.  
  
'''Note''': this page is part of the [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vdraft_FHIR_IG MedMij FHIR Implementation Guide] and is a technical representation of the functional design published on this [[MedMij:Vdraft_Ontwerpen| wiki page]].
+
This IG is a technical representation of the [[MedMij:Vdraft_OntwerpVragenlijsten|functional design]] and follows the principles of the [[MedMij:V2019.01_FHIR_IG|general MedMij FHIR IG]].
  
 
=Actors involved=
 
=Actors involved=
Table 1 shows the relevant actors, systems and FHIR Capability Statements in MedMij context. The Capability Statements demonstrate the minimum conformance requirements for the described use cases. The role that covers the provision of a Questionnaire MAY be integrated in the XIS or MAY be supported by a separate questionnaire repository. That means the role of XIS in table 1 MAY also be supported by a questionnaire repository.
+
The table shows the relevant actors, systems and FHIR CapabilityStatements. The CapabilityStatements demonstrate the minimum conformance requirements for the described use cases. The role that covers the provision of a Questionnaire MAY be integrated in the XIS or MAY be supported by a separate questionnaire repository.
 
 
'''Note''': according to the MedMij Afsprakenstelsel, the PGO initiates communication with the XIS, not the other way around. Therefore, the healthcare provider needs to inform the patient about the questionnaire offline. The PGO should provide an interface to the user to manually check a specific healthcare provider for questionnaire tasks. (TODO: hoort dit hier thuis of in FO?)
 
  
 
{| class="wikitable"
 
{| class="wikitable"
 
! colspan="2" style="text-align:left;" | Actors
 
! colspan="2" style="text-align:left;" | Actors
 
! colspan="2" style="text-align:left;" | Systems
 
! colspan="2" style="text-align:left;" | Systems
! colspan="2" style="text-align:left;" | FHIR Capability Statements
+
! colspan="2" style="text-align:left;" | FHIR CapabilityStatements
 
|-
 
|-
 
! style="text-align:left;" |Name
 
! style="text-align:left;" |Name
Regel 46: Regel 44:
 
| PHR
 
| PHR
 
| Personal health record
 
| Personal health record
* retreives a task
+
* retreives a Task
* retreives a questionnaire
+
* retreives a Questionnaire
* updates the task
+
* updates the Task
* sends the questionnaire response
+
* sends the QuestionnaireResponse
| [https://simplifier.net/nictizstu3-questionnaires/questionnairereference-clientcapabilities CapabilityStatement: Client]
+
| {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/questionnaires-clientcapabilities|CapabilityStatement: Client}}
 
| FHIR Client requirements  
 
| FHIR Client requirements  
 
|-
 
|-
Regel 57: Regel 55:
 
| XIS
 
| XIS
 
| Healthcare information system
 
| Healthcare information system
* provides a QuestionnaireReferenceTask
+
* provides a Questionnaires-Task
* receives updates to the task
+
* receives updates to the Task
* receives the questionnaire response
+
* receives the QuestionnaireResponse
| [https://simplifier.net/nictizstu3-questionnaires/questionnairereference-servercapabilities CapabilityStatement: Server]
+
| {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/questionnaires-servercapabilities|CapabilityStatement: Server}}
 
| FHIR Server requirements
 
| FHIR Server requirements
 
|-
 
|-
 
| Questionnaire repository
 
| Questionnaire repository
| The healthcare provider provides a Questionnaire.
+
| Organization that provides Questionnaire resources
 
| VRE
 
| VRE
 
| Healthcare information system or third party FHIR server
 
| Healthcare information system or third party FHIR server
 
* provides Questionnaire resource in XML and JSON formats
 
* provides Questionnaire resource in XML and JSON formats
| [https://simplifier.net/nictizstu3-questionnaires/questionnairereference-repositorycapabilities CapabilityStatement: Questionnaire repository]
+
| {{Simplifier|http://nictiz.nl/fhir/CapabilityStatement/questionnaires-repositorycapabilities|CapabilityStatement: Questionnaire repository}}
 
| Questionnaire repository requirements
 
| Questionnaire repository requirements
 
|}
 
|}
<font size = "1">'''Table 1. Actors, systems and FHIR Capability Statements'''</font>
 
  
=Boundaries and Relationships=
+
=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 use of the SDC IG verbatim:
+
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 current use case is more restricted.
* the derived profiles for the MedMij use case reference HCIM based profiles for common resources like Patient, Practitioner, PractitionerRole and Organization
+
* 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.
+
* 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 QuestionnaireResponse.author tells who the person is that provided the answers. For the current MedMij use case it is restricted to a patient. The QuestionnaireResponse.subject tells who the answers apply to. For the current MedMij use case it may be a patient, organization or practitioner.
The QuestionnaireResponse.author tells who the person is that provided the answers. For the current MedMij use case it may be a patient. The QuestionnaireResponse.subject tells who the answers apply to. For the current MedMij use case it may be a patient, organization or practitioner.
 
  
 
=Use case: retrieve questionnaire=
 
=Use case: retrieve questionnaire=
Regel 85: Regel 81:
 
[[Bestand:Afsprakenstelsel-01.png|link=https://www.medmij.nl/afsprakenstelsel/|rechts |100px|Go to Afsprakenstelsel]]
 
[[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:Vdraft_OntwerpVragenlijsten Functional Design]. At first the questionnaire is assigned to the patient by a QuestionnaireReferenceTask resource. The PHR extracts the reference to the Questionnaire resource and retrieves it from the XIS or from an external questionnaire repository.
+
The order of invocations follows the [https://informatiestandaarden.nictiz.nl/wiki/MedMij:Vdraft_OntwerpVragenlijsten functional design]. At first the questionnaire is assigned to the patient by a Questionnaires-Task resource. The PHR extracts the reference to the Questionnaire resource and retrieves it from the XIS or from a questionnaire repository (VRE).
  
 
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'].
 
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 gets Questionnaire reference - PHR===
+
===Client searches Questionnaires-Task - PHR===
Using a [http://hl7.org/fhir/STU3/search.html search operation], the PHR provides a Task resource containing a reference to the patient questionnaire from the XIS. The Task SHALL conform to the MedMij [[#List_of_StructureDefinitions|QuestionnaireReferenceTask profile]] SHALL initially have Task.status set to "requested" (see [[#Task state machine]]). The Questionnaire resource SHALL be referenced using Task.input.valueReference.reference.
+
Using a [http://hl7.org/fhir/STU3/search.html search operation], the PHR retrieves a Task resource containing a reference to the questionnaire from the XIS. The Task SHALL conform to the [[#List_of_StructureDefinitions|Questionnaires-Task profile]] and SHALL initially have <code>Task.status</code> set to "requested" (see [[#Task state machine]]). The Questionnaire resource SHALL be referenced using <code>Task.input.valueReference.reference</code>.
  
  GET [base]/Task/?status=requested&_include=Task:patient&_include=Task:requester
+
  GET [base]/Task/?code=<nowiki>http://loinc.org|74468-0</nowiki>&status=requested&_include=Task:requester
  
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]).
+
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]).
  
===Client gets Questionnaire - PHR===
+
===Client retrieves Questionnaire - PHR===
Upon retreiving the Task, the PHR system retreives the Questionnaire resource referenced in the Task 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 reference.
+
Upon retreiving the Task, the PHR retrieves the Questionnaire resource referenced in the Task 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 a questionnaire repository (VRE).
  
 
  GET ''Task.input.valueReference.reference.value''
 
  GET ''Task.input.valueReference.reference.value''
  
The Questionnaire resource SHALL conform to the MedMij [[#List_of_StructureDefinitions|Questionnaire profile]].
+
The Questionnaire resource SHALL conform to the [[#List_of_StructureDefinitions|Questionnaire profile]].
 
 
'''Note''': for known questionnaires, a PHR may choose to use hardcoded instead of generated forms. However, PHRs implementing this information standard should always be able to generate a form for the minimal Questionnaire subset defined below. Also note that a known questionnaire can only be recognized by its reference in the Task; currently, no coding system exists to identify known questionnaires.
 
  
 
If this operation fails (after repeated attempts), the PHR should close the task with status "failed" (see [[#Updating the Task]]). This closes the Task and ends the workflow (see [[#Task state machine]]).
 
If this operation fails (after repeated attempts), the PHR should close the task with status "failed" (see [[#Updating the Task]]). This closes the Task and ends the workflow (see [[#Task state machine]]).
Regel 117: Regel 111:
 
* Integer
 
* Integer
 
* Date / dateTime / time
 
* Date / dateTime / time
* String
+
* String / text
* Choice / open-choice (TODO: voorkeursweg beschrijven voor gebruik van .option ipv ValueSet-reference)
+
* Choice / open-choice, where the possible answers are defined using <code>option</code> elements
 
* Quantity
 
* Quantity
  
Regel 134: Regel 128:
  
 
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.
 
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 instead of generated forms. However, a PHR implementing this information standard should always be able to generate a form for the minimal Questionnaire requirements. Also note that a known questionnaire can only be recognized by its reference in the Task; currently, no coding system exists to identify known questionnaires. Although the XIS MUST use version specific references, it is up to the PHR to check whether the referenced Questionnaire is the same as the expected Questionnaire.
 +
 +
===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==
 
==List of invocations==
Regel 146: Regel 188:
  
 
===Client provides QuestionnaireResponse - PHR===
 
===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 MedMij [[#List_of_StructureDefinitions|questionnaire response 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 task with status "failed" (see [[#Updating the Task]]). This closes the Task and ends the process (see [[#Task state machine]]).
+
The answers to the questions in the Questionnaire resource are captured using an instance of the QuestionnaireResponse resource, which SHALL conform to the [[#List_of_StructureDefinitions|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 task with status "failed" (see [[#Updating the Task]]). This closes the Task and ends the process (see [[#Task 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 simultaniously:
+
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.
+
* Send the QuestionnaireResponse resource to the XIS.
* update the Task at the XIS to set Task.output.valueReference to the QuestionnaireResponse.
+
* Update the Task at the XIS to set <code>Task.output.valueReference</code> to the QuestionnaireResponse.
* update the Task at the XIS to set Task.status to "completed".
+
* Update the Task at the XIS to set <code>Task.status</code> to "completed".
  
 
A FHIR transaction is a POST command to the XIS endpoint:
 
A FHIR transaction is a POST command to the XIS endpoint:
Regel 158: Regel 200:
  
 
The body of the POST operation SHALL be a Bundle resource with Bundle.type set to "transaction" that SHALL contain
 
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 QuestionnaireResponse resource as a <code>create</code> interaction.
* the original Task resource with the required changes in Task.status and Task.output as an <code>update</code> interaction (see [[#Updating the Task]])
+
* 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 Task]]).
  
 
Example:
 
Example:
Regel 168: Regel 210:
 
         <resource>
 
         <resource>
 
             <Task>
 
             <Task>
                 <id value="ORIGINAL_ID"/>
+
                 <id value="ORIGINAL_ID"/><!-- where ORIGINAL_ID is the Task.id as received from the XIS -->
 
                 <meta>
 
                 <meta>
 
                     <profile value="..."/>
 
                     <profile value="..."/>
Regel 187: Regel 229:
 
         <request>
 
         <request>
 
             <method value="PUT"/>
 
             <method value="PUT"/>
             <url value="Task/ORIGINAL_ID"/>
+
             <url value="Task/ORIGINAL_ID"/><!-- where ORIGINAL_ID is the Task.id as received from the XIS -->
 
         </request>
 
         </request>
 
     </entry>
 
     </entry>
Regel 208: Regel 250:
 
</syntaxhighlight>
 
</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 'transaction-response', 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 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].
 
 
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.
 
  
 
'''Note''': updating the QuestionnaireResponse is not supported in the use case.
 
'''Note''': updating the QuestionnaireResponse is not supported in the use case.
Regel 217: Regel 257:
  
 
==Introduction==
 
==Introduction==
Retreiving 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). To track the status of the prescription fullfillment, a Task resource at the XIS server is used, which transitions through various stages until completion.
+
Retreiving 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 fullfillment, 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 task at the different stages in the life cycle of the questionnaire, using an <code>update</code> operation (see [[#Updating the Task]]). This implies that the the Task resource should be made accessible by the XIS server for these updates, at least for the expected life time of the fullfillment cycle. Additionally, the PHR may perform a <code>read</code> of the Task resource at any time.
+
It is the responsibility of the PHR to update the task at the different stages in the life cycle of the questionnaire, using an update operation (see [[#Updating the Task]]). 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 task to a closed state. However, it is not guaranteed that the required update operation succeeds. If the PHR is unable to bring the task to a closed state, the server may eventually close the task because of business rules.
 
It is primarilly the responsibility of the PHR to bring the task to a closed state. However, it is not guaranteed that the required update operation succeeds. If the PHR is unable to bring the task to a closed state, the server may eventually close the task because of business rules.
Regel 234: Regel 274:
 
           \--> rejected -----------------------/
 
           \--> rejected -----------------------/
 
</pre>
 
</pre>
TODO: uittekenen.
 
  
Only the transactions shown here are allowed. The server should reject any update that attempts to perform an illegal transaction. See [[#Handling errors]].
+
Only the transitions shown here are allowed. The server SHOULD reject any update that attempts to perform an illegal transition. See [[#Task update failures]].
  
 
==Updating the Task==
 
==Updating the Task==
Regel 245: Regel 284:
 
Where ORIGINAL_ID is the Task.id from the Task originally received from the XIS.
 
Where ORIGINAL_ID is the Task.id from the Task originally received from the XIS.
  
'''Note''': apart from the relevant modifications, the Task resource should be sent completely and without changes.
+
'''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 transaction). 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 Task resource on the server to "failed" and stop further processing. If it is not possible to perform this task update, the task effectively remains in a stalled position. The server may eventually close it because of business rules.
 
 
 
=Handling errors=
 
 
 
==Task update failures==
 
The server may be unable to accept an update the Task resource due to errors or business rules (e.g. an illegal status transaction). 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 relevant section]] in the FHIR spec.
 
 
 
The PHR should try to recover from this response. If this is not possible, the PHR should attempt to update the status of the Task resource on the server to "failed" and stop further processing. If it is not possible to perform this task update, the task effectively remains in a stalled position. The server may eventually close it due to business rules.
 
 
 
==Other errors==
 
 
 
TODO: beter uitwerken
 
 
 
* 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 the [[http://hl7.org/fhir/STU3/search.html#errors relevant part of the FHIR spec for more information]].
 
* The read operation to retreive the Questionnaire resource is an ordinary HTTP operation. If this operation fails (after repeated attempts), the PHR should close the task with status "failed".
 
* If the PHR is unable to fully render the Questionnaire to the PHR user, it should close the task with status "rejected".
 
* 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 task with status "failed".
 
* If the server is unable to process the transaction with the QuestionnaireResponse, it SHALL return an HTTP 400 or HTTP 500 type response instead of a 200 OK response. If the response is not 200 OK, the PHR should close the task with status "failed".
 
 
 
=Interactions, operations, search parameters=
 
 
 
===Interactions===
 
 
 
The following logical interactions are needed for the use case of Questionnaire and Questionnaire Response:
 
* [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
 
  
===Operations===
+
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 following operations have been specified for use in SDC. The MedMij use case has no identified requirement for these operations. This specification therefor does not define that system roles implement them.
 
* [http://hl7.org/fhir/STU3/questionnaire-operations.html#populate Populate Questionnaire]
 
* [http://hl7.org/fhir/STU3/questionnaire-operations.html#populatehtml Generate HTML for Questionnaire]
 
* [http://hl7.org/fhir/STU3/questionnaire-operations.html#2.38.13.3 Generate a link to a Questionnaire completion webpage]
 
* [http://hl7.org/fhir/STU3/structuredefinition-operations.html#5.3.13.1 Build Questionnaire]
 
  
===Search parameters===
+
The PHR should try to recover from this response. If this is not possible, the PHR SHOULD attempt to update the status of the Task resource on the server to "failed" and stop further processing. If it is not possible to perform this task update, the task effectively remains in a stalled position. The server may eventually close it because of business rules.
The following search parameter types and search result parameters need to be supported for this use case.
 
  
Search parameter types:
+
=FHIR profiles, interactions, search parameters=
* [http://hl7.org/fhir/STU3/search.html#token token]
 
** Including modifier 'in'
 
* [http://hl7.org/fhir/STU3/search.html#reference reference]
 
  
==List of StructureDefinitions==
+
==FHIR profiles==
The unique FHIR profiles based on HCIM applicable in a broader context than the exchange of Questionnaire and Questionnaire Response.
 
  
 
{| class="wikitable" style="horizontal-align: right"  
 
{| class="wikitable" style="horizontal-align: right"  
!style="background-color: #4AB8A7; color: white; font-weight: bold; text-align:left;  background-color: #E3E3E3 width:400px" | FHIR Profile
+
!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" | FHIR resource
!style="background-color: #4AB8A7; color: white; font-weight: bold; text-align:left;  background-color: #E3E3E3 width:50px" | HCIM NL / Concept
+
!style="background-color: #4AB8A7; color: white; font-weight: bold; text-align:left;  background-color: #E3E3E3 width:50px" | HCIM EN
 
|-
 
|-
| [https://simplifier.net/resolve?canonical=http://fhir.nl/fhir/StructureDefinition/nl-core-patient http://fhir.nl/fhir/StructureDefinition/nl-core-patient]
+
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-patient}}
 
| Patient
 
| Patient
 
| Patient
 
| Patient
 
|-
 
|-
| [https://simplifier.net/resolve?canonical=http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner]
+
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner}}
 
| Practitioner
 
| Practitioner
| Zorgverlener
+
| rowspan="2" | HealthProfessional
 
|-
 
|-
| [https://simplifier.net/resolve?canonical=http://fhir.nl/fhir/StructureDefinition/nl-core-practitionerrole http://fhir.nl/fhir/StructureDefinition/nl-core-practitionerrole]
+
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-practitionerrole}}
 
| PractitionerRole
 
| PractitionerRole
| Zorgverlenerrol
 
 
|-
 
|-
| [https://simplifier.net/resolve?canonical=http://fhir.nl/fhir/StructureDefinition/nl-core-organization http://fhir.nl/fhir/StructureDefinition/nl-core-organization]
+
| {{Simplifier|http://fhir.nl/fhir/StructureDefinition/nl-core-organization}}
 
| Organization
 
| Organization
| Zorgaanbieder
+
| HealthcareProvider
 
|-
 
|-
| [https://simplifier.net/resolve?canonical=http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaire http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaire]
+
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaire}}
| Questionnaire
 
 
| Questionnaire
 
| Questionnaire
 +
|
 
|-
 
|-
| [https://simplifier.net/resolve?canonical=http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaireresponse http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaireresponse]
+
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaireresponse}}
 
| QuestionnaireResponse
 
| QuestionnaireResponse
| Questionnaire Response
+
|  
 
|-
 
|-
| [https://simplifier.net/resolve?canonical=http://nictiz.nl/fhir/StructureDefinition/QuestionnaireReferenceTask http://nictiz.nl/fhir/StructureDefinition/QuestionnaireReferenceTask]
+
| {{Simplifier|http://nictiz.nl/fhir/StructureDefinition/Questionnaires-Task}}
 
| Task
 
| Task
| Questionnaire Reference
+
|  
 
|}
 
|}
 +
 +
==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]

Huidige versie van 20 jul 2020 om 00:59


MedMij:Vdraft Issuebox FHIR IG

Naar medmij.nl
Icoon vragenlijsten
AfsprakenstelselFunctioneelTechnischAfspraken-Functioneel-Technisch

1 Introduction

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.

This information standard is inspired by the international 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 functional design and follows the principles of the general MedMij FHIR IG.

2 Actors involved

The table shows the relevant actors, systems and FHIR CapabilityStatements. The CapabilityStatements demonstrate the minimum conformance requirements for the described use cases. The role that covers the provision of a Questionnaire MAY be integrated in the XIS or MAY be supported by a separate questionnaire repository.

Actors Systems FHIR CapabilityStatements
Name Description Name Description Name Description
Patient The user of a personal healthcare environment PHR Personal health record
  • retreives a Task
  • retreives a Questionnaire
  • updates the Task
  • sends the QuestionnaireResponse
Client@ http://nictiz.nl/fhir/CapabilityStatement/questionnaires-clientcapabilities FHIR Client requirements
Healthcare professional The user of a XIS XIS Healthcare information system
  • provides a Questionnaires-Task
  • receives updates to the Task
  • receives the QuestionnaireResponse
Server@ http://nictiz.nl/fhir/CapabilityStatement/questionnaires-servercapabilities FHIR Server requirements
Questionnaire repository Organization that provides Questionnaire resources VRE Healthcare information system or third party FHIR server
  • provides Questionnaire resource in XML and JSON formats
Questionnaire repository@ http://nictiz.nl/fhir/CapabilityStatement/questionnaires-repositorycapabilities Questionnaire repository requirements

3 Boundaries and relationships

The MedMij use case for questionnaires overlaps partially with the uses cases described in the 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 mustSupport and the use of isModifier in SDC differs fundamentally from other MedMij IG's and are therefore ignored in this IG.
  • The QuestionnaireResponse.author tells who the person is that provided the answers. For the current MedMij use case it is restricted to a patient. The QuestionnaireResponse.subject tells who the answers apply to. For the current MedMij use case it may be a patient, organization or practitioner.

4 Use case: retrieve questionnaire

4.1 List of invocations

Go to Afsprakenstelsel

The order of invocations follows the functional design. At first the questionnaire is assigned to the patient by a Questionnaires-Task resource. The PHR extracts the reference to the Questionnaire resource and retrieves it from the XIS or from a questionnaire repository (VRE).

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 'MedMij Afsprakenstelsel'.

4.1.1 Client searches Questionnaires-Task - PHR

Using a search operation, the PHR retrieves a Task resource containing a reference to the questionnaire from the XIS. The Task SHALL conform to the Questionnaires-Task profile and SHALL initially have Task.status set to "requested" (see #Task state machine). The Questionnaire resource SHALL be referenced using Task.input.valueReference.reference.

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

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 the FHIR documentation on search).

4.1.2 Client retrieves Questionnaire - PHR

Upon retreiving the Task, the PHR retrieves the Questionnaire resource referenced in the Task using a read operation. This reference may live on the same base as the XIS or may be a questionnaire repository (VRE).

GET Task.input.valueReference.reference.value

The Questionnaire resource SHALL conform to the Questionnaire profile.

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

5 Use case: send questionnaire response

5.1 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 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 option elements
  • Quantity

The following elements of the Questionnaire.item element MUST be supported:

  • Questionnaire.item.enableWhen
  • Questionnaire.item.required
  • Questionnaire.item.option

In addition, the following extensions MUST be supported:

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 instead of generated forms. However, a PHR implementing this information standard should always be able to generate a form for the minimal Questionnaire requirements. Also note that a known questionnaire can only be recognized by its reference in the Task; currently, no coding system exists to identify known questionnaires. Although the XIS MUST use version specific references, it is up to the PHR to check whether the referenced Questionnaire is the same as the expected Questionnaire.

5.1.1 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, item.type 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 Questionnaire.item.options 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 Questionnaire.item.option elements, with possible answers defined as valueCode. Note: although the Questionnaire resource defines item.option.value[x] 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 QuestionnaireResponse.item.answer.valueCode:

  • If the user selects one of the predefined answers, it should be captured in the answer using the code (and if present, system) elements of the valueCode.
  • If the question is of type "open-choice" and the user provides an alternative answer, it should be captured using the display element of the valueCode.

Questionnaire example:

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

QuestionnaireResponse example:

<item>
    <linkId value="example"/>
    <answer>
        <valueCoding>
            <code value="EO1"/>
            <display value="Example option 1"/>
        </valueCoding>
    </answer>
</item>

5.2 List of invocations

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 'MedMij Afsprakenstelsel'.

5.2.1 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 Task resource (see #Updating the Task):

  • 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 Task and ends the process (see #Task state machine).

5.2.2 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 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 task with status "failed" (see #Updating the Task). This closes the Task and ends the process (see #Task state machine).

Upon completion of the questionnaire by the user, the PHR system uses a transaction operation to simultaneously:

  • Send the QuestionnaireResponse resource to the XIS.
  • Update the Task at the XIS to set Task.output.valueReference to the QuestionnaireResponse.
  • Update the Task at the XIS to set Task.status 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 create interaction.
  • The original Task resource with the required changes in Task.status and Task.output as an update interaction (see #Updating the Task).

Example:

<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="..."/>
                </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="..."/>
                </meta>
                ...
            </QuestionnaireResponse>
        </resource>
    </entry>
    <request>
        <method value="POST"/>
        <url value="QuestionnaireResponse"/>
    </request>
</Bundle>

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 transaction-response, 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 transaction response.

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

6 Tracking the status using the Task resource

6.1 Introduction

Retreiving 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 fullfillment, 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 task at the different stages in the life cycle of the questionnaire, using an update operation (see #Updating the Task). 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 read operation of the Task resource at any time.

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

6.2 Task state machine

The Task resource can transition through the following states:

          /----------------/-------------------\
          |                |                   |
requested +--+-> accepted -+---> completed ----+---> X
          |  |             |                   |
          |  \-------------\--> failed --------|
          |                                    |
          \--> rejected -----------------------/

Only the transitions shown here are allowed. The server SHOULD reject any update that attempts to perform an illegal transition. See #Task update failures.

6.3 Updating the Task

The Task resource at the XIS can be updated by the PHR using the 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 Task.id from the Task 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 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 Task resource on the server to "failed" and stop further processing. If it is not possible to perform this task update, the task effectively remains in a stalled position. The server may eventually close it because of business rules.

7 FHIR profiles, interactions, search parameters

7.1 FHIR profiles

Canonical URL FHIR resource HCIM EN
http://fhir.nl/fhir/StructureDefinition/nl-core-patient Patient Patient
http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner Practitioner HealthProfessional
http://fhir.nl/fhir/StructureDefinition/nl-core-practitionerrole PractitionerRole
http://fhir.nl/fhir/StructureDefinition/nl-core-organization Organization HealthcareProvider
http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaire Questionnaire
http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaireresponse QuestionnaireResponse
http://nictiz.nl/fhir/StructureDefinition/Questionnaires-Task Task

7.2 Interactions

The following logical interactions are needed for the Questionnaires information standard:

7.3 Search parameters

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

Search parameter types: