Zandbak/MVPTO: verschil tussen versies

Uit informatiestandaarden
Naar navigatie springen Naar zoeken springen
(Fixed a number of TODO's)
(Preliminary error handling)
Regel 120: Regel 120:
 
Upon retrieving the Questionnaire resource, the PHR checks if it is able to present a form that ''completely'' covers all the questions and structure and updates the Task resource accordingly, using an [http://hl7.org/fhir/STU3/http.html#update update operation].
 
Upon retrieving the Questionnaire resource, the PHR checks if it is able to present a form that ''completely'' covers all the questions and structure and updates the Task resource accordingly, using an [http://hl7.org/fhir/STU3/http.html#update update operation].
 
* If the Questionnaire can be processed, Task.status SHALL be set to "accepted".
 
* 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. Nu further actions can be taken.
+
* If the Questionnaire cannot be processed, Task.status SHALL be set to "rejected". See [[#Handling errors]].
  
 
<code>PUT [base]/Task/id{?[parameters]{&_format=[mime-type]}}</code>
 
<code>PUT [base]/Task/id{?[parameters]{&_format=[mime-type]}}</code>
Regel 214: Regel 214:
 
</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 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.
+
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 (see [[#Handling errors]]).
  
 
'''Note: updating the QuestionnaireResponse is not supported in the use case.'''
 
'''Note: updating the QuestionnaireResponse is not supported in the use case.'''
 +
 +
=Updating the task=
 +
 +
TODO: discuss
 +
 +
The PHR has to update the task during various stages in the life cycle of the questionnaire, using a HTTP PUT operation.
 +
 +
The PHR should ultimately bring the task to a closed state. However, it is not guaranteed that an update operation succeeds. If the PHR is unable to bring the task to the closed state, the server may eventually close the task because of business rules.
 +
 +
==Task state machine==
 +
The Task resource can transition through the following states:
 +
<pre>
 +
          /---------------/-------------------\
 +
          |              |                  |
 +
requested ----> accepted -----> completed --------> X
 +
          |              |                  |
 +
          |              \--> failed --------|       
 +
          |                                  |
 +
          \--> rejected ----------------------/
 +
</pre>
 +
TODO: uittekenen.
 +
 +
Transaction not shown here, are not allowed. The server should reject any attempt to update the Task resource according to such illegal transactions. See [[#Handling errors]].
  
 
=Handling errors=
 
=Handling errors=
(TODO: kan dit er niet gewoon uit?)
 
If the search fails '''(cannot be executed, not that there are no matches)''', the return value is a status code 4xx or 5xx with an OperationOutcome. An HTTP status code of 403 signifies that the server refused to perform the search, while other 4xx and 5xx codes signify that some sort of error has occurred. The HTTP status code 404 is returned if a XIS did not implement an endpoint used in a request by a PHR. When the search fails, a server SHOULD return an OperationOutcome detailing the cause of the failure. For example, in case of a not implemented FHIR endpoint, the OperationOutcome would state that the resource type is not supported. Note: an empty search result is not a failure.
 
 
Common HTTP Status codes returned on FHIR-related errors (in addition to normal HTTP errors related to security, header and content type negotiation issues):
 
  
* 400 Bad Request - search could not be processed or failed basic FHIR validation rules
+
==Task update failures==
* 401 Not Authorized - authorization is required for the interaction that was attempted
+
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.
* 404 Not Found - resource type not supported, or not a FHIR end-point
 
  
In some cases, parameters may cause an error. For instance:
+
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.
  
* A parameter may refer to a non-existent resource.
+
==Other errors==
* A parameter may refer to an unknown code
 
* A parameter may refer to a time that is out of scope
 
* A parameter may use an illegal or unacceptable modifier
 
* A date/time parameter may have incorrect format
 
* A parameter may be unknown or unsupported
 
Where the content of the parameter is syntactically incorrect, servers SHOULD return an error. However, where the issue is a logical condition (e.g. unknown subject or code), the server SHOULD process the search, including processing the parameter - with the result of returning an empty search set, since the parameter cannot be satisfied.
 
  
In such cases, the search process MAY include an OperationOutcome in the search set that contains additional hints and warnings about the search process. This is included in the search results as an entry with search mode = outcome. Clients can use this information to improve future searches.
+
TODO: beter uitwerken
  
Link to relevant FHIR specification: http://hl7.org/fhir/STU3/search.html#errors
+
* 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, operations, search parameters=

Versie van 26 feb 2020 13:38

{{#customtitle:MedMij FHIR Implementation Guide: Questionnaire and Questionnaire Response (Vragenlijsten)}} 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. 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.

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.

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.

Note: this page is part of the MedMij FHIR Implementation Guide and is a technical representation of the functional design published on this wiki page.

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

Note: in the (TODO: waar is dit vastgelegd?), only the PGO can initiate 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: op een meer prominente plek uitleggen?).

(TODO: de meeste andere standaarden hebben alleen een tabel met actors, niet met transactions) (TODO: de andere standaarden hebben een capabilitystatement per actor, niet per actor/resource. Dat zouden er bij ons drie worden: client, server en repository)

Actors Systems FHIR Capability Statements
Name Description Name Description Name Description
Patient The user of a personal healthcare environment retrieves a QuestionnaireReferenceTask PHR Personal health record CapabilityStatement: Client gets Task FHIR Client requirements
Patient The user of a personal healthcare environment retrieves a Questionnaire and updates the QuestionnaireReferenceTask. PHR Personal health record CapabilityStatement: Client gets Questionnaire FHIR Client requirements
Patient The user of a personal healthcare environment provides a QuestionnaireResponsean and updates the QuestionnaireReferenceTask. PHR Personal health record CapabilityStatement: Client provides QuestionnaireResponse FHIR Client requirements
Healthcare professional The user of a XIS provides a QuestionnaireReferenceTask. XIS Healthcare information system CapabilityStatement: Server provides Task FHIR Server requirements
Healthcare provider / Questionnaire repository The healthcare provider provides a Questionnaire. XIS Healthcare information system CapabilityStatement: Server provides Questionnaire FHIR Server requirements
Healthcare provider The healthcare provider accepts an update the QuestionnaireReferenceTask XIS Healthcare information system CapabilityStatement: Server accepts update to Task FHIR Server requirements
Healthcare provider The healthcare information system accepts creation of a QuestionnaireResponse and an updates the QuestionnaireReferenceTask. XIS Healthcare information system CapabilityStatement: Server accepts QuestionnaireResponse FHIR Server requirements

Table 1. Actors, systems and FHIR Capability Statements

3 Boundaries and Relationships

The MedMij use case for questionnaires overlaps partially with SDC use cases. Where possible, the SDC profiles are re-used. However, the current use case is more restricted than the SDC use cases. Furthermore, the MedMij derived profiles reference HCIM based profiles for common resources like Patient, Practitioner, PractitionerRole and Organization.

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.

4 Use case: retrieve Questionnaire

4.1 List of invocations

Go to Afsprakenstelsel

The order of invocations follows the Functional Design (TODO: link). At first the Questionnaire is assigned to the patient by a QuestionnaireReferenceTask. The PHR extracts the reference to the Questionnaire and retrieves it from the XIS or from an external Questionnaire repository.

4.1.1 Client gets Questionnaire reference - PHR

Using a 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 QuestionnaireReferenceTask profile. A search interaction can be performed by an HTTP GET or command as shown:

GET [base]/Task/{?[parameters]{&_format=[mime-type]}}

The Task.status SHALL be set to "requested", and the Questionnaire SHALL be referenced using Task.input.valueReference.reference.

4.1.2 Client gets Questionnaire - PHR

The PHR system retrieves the Questionnaire assigned to patient using a read operation. The Questionnaire SHALL conform to the MedMij questionnaire profile. A read interaction MAY be based on the reference for the Questionnaire found in the Task.focus element (but MAY also be obtained through other means outside the scope of this specification. TODO: huh?)

GET [base]/Questionnaire/id{?[parameters]{&_format=[mime-type]}}

Upon retrieving the Questionnaire resource, the PHR checks if it is able to present a form that completely covers all the questions and structure and updates the Task resource accordingly, using an update operation.

  • 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". See #Handling errors.

PUT [base]/Task/id{?[parameters]{&_format=[mime-type]}}

4.2 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
  • Choice / open-choice
  • Quantity

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

  • Questionnaire.item.enableWhen
  • Questionnaire.item.required
  • Questionnaire.item.options

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

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

5 Use case: send QuestionnaireResponse

5.1 List of invocations

Go to Afsprakenstelsel

This FHIR implementation guide assumes that the PHR system is able to make a connection to the XIS to send QuestionnaireResponse. 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.1.1 Client provides QuestionnaireResponse - PHR

The answers to the questions in the Questionnaire are captured using an instance of the QuestionnaireResponse resource, which SHALL conform to the MedMij questionnaire response profile.

Upon completion of the questionnaire by the user, the PHR system sends the QuestionnaireResponse resource to the XIS and simultaniously closes the original Task resource on the XIS, using a FHIR transaction.

A transaction interaction is performed by an HTTP POST command to the XIS endpoint:

POST [base]/{?[parameters]{&_format=[mime-type]}}

The content of the post submission should be a Bundle resource with Bundle.type set to "transaction", and containing both the updated Task and the QuestionnaireResponse, according to the following structure (where ORIGINAL_ID is the original Task.id from the Task retrieved from the server):

<Bundle xmlns="http://hl7.org/fhir">
    <type value="transaction"/>
    <entry>
        <resource>
            <Task>
                <id value="ORIGINAL_ID"/>
                <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"/>
        </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 (see #Handling errors).

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

6 Updating the task

TODO: discuss

The PHR has to update the task during various stages in the life cycle of the questionnaire, using a HTTP PUT operation.

The PHR should ultimately bring the task to a closed state. However, it is not guaranteed that an update operation succeeds. If the PHR is unable to bring the task to the closed state, the server may eventually close the task because of business rules.

6.1 Task state machine

The Task resource can transition through the following states:

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

TODO: uittekenen.

Transaction not shown here, are not allowed. The server should reject any attempt to update the Task resource according to such illegal transactions. See #Handling errors.

7 Handling errors

7.1 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 [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.

7.2 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 [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".

8 Interactions, operations, search parameters

8.1 Interactions

The following logical interactions are needed for the use case of Questionnaire and Questionnaire Response:

8.2 Operations

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.

8.3 Search parameters

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

Search parameter types:

8.4 List of StructureDefinitions

The unique FHIR profiles based on HCIM applicable in a broader context than the exchange of Questionnaire and Questionnaire Response.

FHIR Profile FHIR Resource HCIM NL / Concept
http://fhir.nl/fhir/StructureDefinition/nl-core-patient Patient Patient
http://fhir.nl/fhir/StructureDefinition/nl-core-practitioner Practitioner Zorgverlener
http://fhir.nl/fhir/StructureDefinition/nl-core-practitionerrole PractitionerRole Zorgverlenerrol
http://fhir.nl/fhir/StructureDefinition/nl-core-organization Organization Zorgaanbieder
http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaire Questionnaire Questionnaire
http://nictiz.nl/fhir/StructureDefinition/nl-core-questionnaireresponse QuestionnaireResponse Questionnaire Response
http://nictiz.nl/fhir/StructureDefinition/QuestionnaireReferenceTask Task Questionnaire Reference