This page is part of the Argonaut Questionnaire Implementation Guide (v1.0.0: Release) based on FHIR R3. This is the current published version. For a full list of available versions, see the Directory of published versions 
Adaptive Forms
Introduction
The Argonaut Questionnaire Implementation Guide defines a series of interactions which cover the basic workflow for the creation, discovery and retrieval of “computer adaptive forms” using FHIR Questionnaire and QuestionnaireResponse and the FHIR API. The reader is encouraged to familiarize herself with the capabilities of the Questionnaire and QuestionnaireResponse Response resources by reviewing the guidance given in the FHIR specification and the guidance in Static Forms Use Case.
Argonaut Questionnaire Adaptive forms are dynamic forms that adjust what questions are asked based on previous answers. This is also known as Computerized Adaptive Testing (CAT). The logic to determine the questions are defined external to the Questionnaire resource.1 Responses to questions are iteratively submitted to a FHIR operation endpoint and the contained Questionnaire and QuestionnaireResponse resources are updated on the fly. A score based on responses may calculate and recorded separately (e.g., a FHIR Observation) or as part of the QuestionnaireResponse.
See the HealthMeasures website for further background, theory and use cases for adaptive forms.
Assumptions and Precondition
- The Adaptive Questionnaire Service is treated as a “Black Box”. It contains the logic for determination of next question and scoring. Form Fillers make RESTful FHIR transactions on Service using a FHIR operation and pass QuestionnaireResponse with contained Questionnaire as the payload to capture the data needed between the Form Filler and Service
- Transactions are Stateless. The Form Filler constructs a record of the transaction which is passed to service and the service adds to record and passed it back to Form Filler. The Form Filler and service are free of keeping track of the session and a previously disrupted session can be restored if the session token expires.
- The Questionnaire may expire and the form may not be valid. Time limits for completion of a questionnaire or individual question can be defined and the Form Filler Application can record the start and stop date-times using the Argonaut Questionnaire Time Limit Extension and Argonaut QuestionnaireResponse Response Period Extension. Note that either Form Filler or Service could determine if the response is within a time limit. How this information modifies the behavior of the Form-filler or interpretation of results is an implementation detail outside of scope of this Implementation Guide.
- The assessment are short - e.g., PROMIS forms have up to 12 transactions (on average 4-12).
- The service may calculate and record scores in the QuestionnaireResponse resource as “answers” to a “score” question item in the Questionnaire. The score item is flagged as
readOnlyand may be marked as hidden using the Questionnaire Hidden Extension to direct the Form Filler that the item should not be displayed to the user.- To assist in calculating scores the standard ValueSet Ordinal Value Extension and Questionnaire Ordinal Value Extension may be used on items. NOTE: This implementation guide extends the context of the Questionnaire Ordinal Value Extension to elements beyond that defined in the FHIR Specification.
- How and when scoring is done is an implementation detail and outside the scope of this guide.
- The Argonaut Questionnaire Item Order Extension and conceptOrder extension may be used by the service to ensure the relative order of Questionnaire items is maintained between transactions.
- There are no constraints on the nesting of item groups and there are several possible items and item groupings including:
- a single question (‘what is the capital of Assyria?’) or
- a single display (‘Answer these questions three!!’) or
- a single item group of multiple display + multiple questions ( ‘what is you favorite color?’, ‘what is the capital of Assyria?’, ‘what is average flight speed of a laden swallow?’)
- or a group containing the question-score pairs when transmitting an individual score for each item.
- a single item group of: multiple item groups (‘Answer these questions three!!’, ‘what is you favorite color?’, ‘what is the capital of Assyria?’, ‘what is average flight speed of a laden swallow?’)
Workflow Steps
The following sections provide a detailed description of workflow and API guidance for the Adaptive Forms Use Case.
Discovery of Adaptive Questionnaire
The discovery process yields a url that identifies the the set of questions for a particular adaptive questionnaire. The url is included in the contained Questionnaire data so that the Adaptive Questionnaire Service is able to identify which set of questions are being requested.
How the discovery and preview of the service’s adaptive questionnaire is done is out of scope. It may be done out of band or using the standard FHIR RESTful search API.
Initiate Adaptive Questionnaire
To launch the adaptive questionnaire the Form Filler POSTs the operation $next-question to the Adaptive Questionnaire Service (“Black Box”) instance endpoint. A QuestionnaireResponse with a contained Questionnaire representing only the resource metadata is provided as payload data.
The Service updates the contained Questionnaire with the first item and returns the QuestionnaireResponse in the payload.
APIs
The following Argonaut Questionnaire artifacts are used in this transaction:
Usage
To initiate an adaptive questionnaire:
POST [base]/Questionnaire/$next-question
Note that these json examples are annotated with nonstandard comments and snipped for brevity.
request
POST [base]/Questionnaire/questionnaire-example-adaptive-sampler/$next-question
payload
{
"resourceType": "QuestionnaireResponse",
"id": "questionnaireresponse-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-adap-questionnaireresponse"
],
//COMMENT - contained Questionnaire
"contained": [
{
"resourceType": "Questionnaire",
"id": "questionnaire-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
]
},
"url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler",
"title": "Argonaut Questionnaire Sampler",
"status": "draft",
//COMMENT - no items since initiating the adaptive questionnaire
...[snipped for brevity]....
}
]
},
//COMMENT - references the contained Questionnaire
"questionnaire": {
"reference": "#questionnaire-example-adaptive-sampler"
},
"status": "in-progress",
..[snipped for brevity]....
//COMMENT - no items since is just getting started
}
}
response
{
"resourceType": "QuestionnaireResponse",
"id": "questionnaireresponse-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-adap-questionnaireresponse"
],
//COMMENT - contained Questionnaire
"contained": [
{
"resourceType": "Questionnaire",
"id": "questionnaire-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
]
},
//COMMENT - the 'url' element identifies the adaptive questionnaire - the set of questions for a particular adaptive questionnaire
"url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler",
"title": "Argonaut Questionnaire Sampler",
"status": "draft",
...[snipped for brevity]....
//add first item group which is a display only not a questions
"item": [
{
"linkId": "g1",
// unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score) this could also be a GUID
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1"
"text": "Header Text",
"type": "group",
"required": true,
"item": [
{
"linkId": "g1.d",
// unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score)
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1.d1"
"text": "The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3 integer\n4 dateDate\n5 dateTime\n6 timeTime\n7 string\n8 textText\n9 urlUrl\n10 choice\n11 open-choice\n12 quantity\n",
"type": "display",
"required": true
}
]
}
]
}
]
},
//COMMENT - reference to contained Questionnaire
"questionnaire": {
"reference": "#questionnaire-example-adaptive-sampler"
},
"status": "in-progress",
...[snipped for brevity]....
//COMMENT - no items since is just getting started
}
Get Next Question
The Form Filler renders the item, presents it to the end-user and records the response in the QuestionnaireResponse. The Form Filler POSTs the operation $next-question to the Service to retrieve the next question.
As result of the operation, the Service updates the Questionnaire and returns it to the Form Filler. It identifies the adaptive questionnaire items by their definition or linkID elements and determines the next question based on the responses. It may also calculate intermediate and/or cumulative scores. The Service updates the contained Questionnaire with the next question and scores if scoring is done and returns it within the QuestionnaireResponse.
This step is repeated until the adaptive questionnaire is done or the Questionnaire has timed out or another error has occurred.
APIs
The following Argonaut Questionnaire artifacts are used in this transaction:
Usage
To retrieve the next question:
POST [base]/Questionnaire/$next-question
Note that these json examples are annotated with nonstandard comments and snipped for brevity.
request
POST [base]/Questionnaire/questionnaire-example-adaptive-sampler/$next-question
payload
{"resourceType": "QuestionnaireResponse",
"id": "questionnaireresponse-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-adap-questionnaireresponse"
],
//COMMENT - contained Questionnaire
"contained": [
{
"resourceType": "Questionnaire",
"id": "questionnaire-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
]
},
//COMMENT -the 'url' element identifies the adaptive questionnaire - the set of questions for a particular adaptive questionnaire
"url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler",
"title": "Argonaut Questionnaire Sampler",
"status": "draft",
...[snipped for brevity]....
//COMMENT -first item group is a display only
"item": [
{
"linkId": "g1",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score) this could also be a GUID.
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1"
"text": "Header Text",
"type": "group",
"required": true,
"item": [
{
"linkId": "g1.d",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score)
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1.d"
"text": "The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3 integer\n4 dateDate\n5 dateTime\n6 timeTime\n7 string\n8 textText\n9 urlUrl\n10 choice\n11 open-choice\n12 quantity\n",
"type": "display",
"required": true
}
]
}
]
}
]
},
//COMMENT -references the contained Questionnaire
"questionnaire": {
"reference": "#questionnaire-example-adaptive-sampler"
},
"status": "in-progress",
...[snipped for brevity]....
//COMMENT -first group is display only so no scoring or processing by the Server
"item": [
{
"linkId": "g1",
"item": [
{
"linkId": "g1.d"
}
]
}
]
}
}
response
{
"resourceType": "QuestionnaireResponse",
"id": "questionnaireresponse-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-adap-questionnaireresponse"
],
//COMMENT - contained Questionnaire
"contained": [
{
"resourceType": "Questionnaire",
"id": "questionnaire-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
]
},
//COMMENT -the 'url' element identifies the adaptive questionnaire - the set of questions for a particular adaptive questionnaire
"url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler",
"title": "Argonaut Questionnaire Sampler",
"status": "draft",
...[snipped for brevity]....
//COMMENT -first item group is a display only
"item": [
{
"linkId": "g1",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score) this could also be a GUID.
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1"
"text": "Header Text",
"type": "group",
"required": true,
"item": [
{
"linkId": "g1.d",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score)
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1.d"
"text": "The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3 integer\n4 dateDate\n5 dateTime\n6 timeTime\n7 string\n8 textText\n9 urlUrl\n10 choice\n11 open-choice\n12 quantity\n",
"type": "display",
"required": true
}
]
},
//COMMENT -add next item group as next question
{
"linkId": "g2",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2"
"type": "group",
"item": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-ordinalValue",
"valueDecimal": 17
}
],
"linkId": "g2.q1",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2.q1"
"text": "Check the box if the following statement is true. The average air speed velocity of a laden European swallow is greater than a laden African swallow.",
"type": "boolean",
"required": true,
"repeats": false
}
]
},
]
}
]
},
//references the contained Questionnaire
"questionnaire": {
"reference": "#questionnaire-example-adaptive-sampler"
},
"status": "in-progress",
...[snipped for brevity]....
//first group is display only so no scoring or processing by the Server
"item": [
{
"linkId": "g1",
"item": [
{
"linkId": "g1.d"
}
]
}
]
}
Note that these json examples are annotated with nonstandard comments and snipped for brevity.
request
POST [base]/Questionnaire/questionnaire-example-adaptive-sampler/$next-question
payload
{"resourceType": "QuestionnaireResponse",
"id": "questionnaireresponse-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-adap-questionnaireresponse"
],
//COMMENT - contained Questionnaire
"contained": [
{
"resourceType": "Questionnaire",
"id": "questionnaire-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
]
},
//COMMENT -the 'url' element identifies the adaptive questionnaire - the set of questions for a particular adaptive questionnaire
"url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler",
"title": "Argonaut Questionnaire Sampler",
"status": "draft",
...[snipped for brevity]....
//COMMENT -first item group is a display only
"item": [
{
"linkId": "g1",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score) this could also be a GUID.
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1",
"text": "Header Text",
"type": "group",
"required": true,
"item": [
{
"linkId": "g1.d",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score)
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1.d",
"text": "The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3 integer\n4 dateDate\n5 dateTime\n6 timeTime\n7 string\n8 textText\n9 urlUrl\n10 choice\n11 open-choice\n12 quantity\n",
"type": "display",
"required": true
}
]
},
//COMMENT -second item group is a question
{
"linkId": "g2",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2",
"type": "group",
"item": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-ordinalValue",
"valueDecimal": 17
}
],
"linkId": "g2.q1",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2.q1",
"text": "Check the box if the following statement is true. The average air speed velocity of a laden European swallow is greater than a laden African swallow.",
"type": "boolean",
"required": true,
"repeats": false
}
]
}
]
}
]
},
//COMMENT -references the contained Questionnaire
"questionnaire": {
"reference": "#questionnaire-example-adaptive-sampler"
},
"status": "in-progress",
...[snipped for brevity]....
//COMMENT -first group is display only so no scoring or processing by the Server
"item": [
{
"linkId": "g1",
"item": [
{
"linkId": "g1.d"
}
]
},
//COMMENT -second group is question-answer pair added by client to be processed by the Server to determine the next question
{
"linkId": "g2",
"item": [
{
"linkId": "g2.q1",
"answer": [
{
"valueBoolean": false
}
]
}
]
}
]
}
}
response
{
"resourceType": "QuestionnaireResponse",
"id": "questionnaireresponse-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-adap-questionnaireresponse"
],
//COMMENT - contained Questionnaire
"contained": [
{
"resourceType": "Questionnaire",
"id": "questionnaire-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
]
},
//COMMENT -the 'url' element identifies the adaptive questionnaire - the set of questions for a particular adaptive questionnaire
"url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler",
"title": "Argonaut Questionnaire Sampler",
"status": "draft",
...[snipped for brevity]....
"item": [
{
"linkId": "g1",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score) this could also be a GUID.
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1",
"text": "Header Text",
"type": "group",
"required": true,
"item": [
{
"linkId": "g1.d",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score)
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1.d",
"text": "The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3 integer\n4 dateDate\n5 dateTime\n6 timeTime\n7 string\n8 textText\n9 urlUrl\n10 choice\n11 open-choice\n12 quantity\n",
"type": "display",
"required": true
}
]
},
{
"linkId": "g2",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2",
"type": "group",
"item": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-ordinalValue",
"valueDecimal": 17
}
],
"linkId": "g2.q1",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2.q1",
"text": "Check the box if the following statement is true. The average air speed velocity of a laden European swallow is greater than a laden African swallow.",
"type": "boolean",
"required": true,
"repeats": false
}
]
},
//COMMENT - add third item group as next question
{
"linkId": "g3",
"type": "group",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g3",
"item": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-ordinalValue",
"valueDecimal": 7
}
],
"linkId": "g3.q1",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g3",
"text": "What is the average air speed velocity of a laden swallow in m/sec?",
"type": "decimal",
"required": true,
"repeats": false
}
]
}
]
}
]
},
//COMMENT -references the contained Questionnaire
"questionnaire": {
"reference": "#questionnaire-example-adaptive-sampler"
},
"status": "in-progress",
...[snipped for brevity]....
//COMMENT -first group is display only so no scoring or processing by the Server
"item": [
{
"linkId": "g1",
"item": [
{
"linkId": "g1.d"
}
]
},
//COMMENT -second group is question-answer pair so processed by the Server to determine the next question
{
"linkId": "g2",
"item": [
{
"linkId": "g2.q1",
"answer": [
{
"valueBoolean": false
}
]
}
]
}
]
}
Adaptive Questionnaire is Complete
The Form Filler and Service repeat the process to get the next questions and answers as described above.
When the Service determines that the adaptive questionnaire is complete, instead of updating the Questionnaire with the next question, it updates the QuestionnaireResponse status to ‘completed’. The status of ‘completed’ signals to the Form Filler that the adaptive Questionnaire is done. If scoring is done by the Service, the scores may be reported and updated for each transaction or reported once at the end as is shown in diagram below.
APIs
The following Argonaut Questionnaire artifacts are used in this transaction:
Usage
To retrieve the finished adaptive questionnaire:
POST [base]/Questionnaire/$next-question
Note that these json examples are annotated with nonstandard comments and snipped for brevity.
request
POST [base]/Questionnaire/questionnaire-example-adaptive-sampler/$next-question
payload
{"resourceType": "QuestionnaireResponse",
"id": "questionnaireresponse-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-adap-questionnaireresponse"
],
// contained Questionnaire
"contained": [
{
"resourceType": "Questionnaire",
"id": "questionnaire-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
]
},
//the 'url' element identifies the adaptive questionnaire - the set of questions for a particular adaptive questionnaire
"url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler",
"title": "Argonaut Questionnaire Sampler",
"status": "draft",
...[snipped for brevity]....
"item": [
{
"linkId": "g1",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score) this could also be a GUID.
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1",
"text": "Header Text",
"type": "group",
"required": true,
"item": [
{
"linkId": "g1.d",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score)
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1.d",
"text": "The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3 integer\n4 dateDate\n5 dateTime\n6 timeTime\n7 string\n8 textText\n9 urlUrl\n10 choice\n11 open-choice\n12 quantity\n",
"type": "display",
"required": true
}
]
},
{
"linkId": "g2",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2",
"type": "group",
"item": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-ordinalValue",
"valueDecimal": 17
}
],
"linkId": "g2.q1",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2.q1",
"text": "Check the box if the following statement is true. The average air speed velocity of a laden European swallow is greater than a laden African swallow.",
"type": "boolean",
"required": true,
"repeats": false
}
]
},
//COMMENT - third item group is the current question
{
"linkId": "g3",
"type": "group",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g3",
"item": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-ordinalValue",
"valueDecimal": 7
}
],
"linkId": "g3.q1",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g3",
"text": "What is the average air speed velocity of a laden swallow in m/sec?",
"type": "decimal",
"required": true,
"repeats": false
}
]
}
]
}
]
},
//COMMENT -references the contained Questionnaire
"questionnaire": {
"reference": "#questionnaire-example-adaptive-sampler"
},
"status": "in-progress",
...[snipped for brevity]....
//COMMENT -first group is display only so no scoring or processing by the Server
"item": [
{
"linkId": "g1",
"item": [
{
"linkId": "g1.d"
}
]
},
{
"linkId": "g2",
"item": [
{
"linkId": "g2.q1",
"answer": [
{
"valueBoolean": false
}
]
}
]
},
},
//COMMENT -third group question-answer pair updated by client to be processed by the Server to determine the next question and the score
{
"linkId": "g3",
"item": [
{
"linkId": "g3.q1",
"answer": [
{
"valueDecimal": 12.38
}
]
}
]
}
]
}
}
response
{
"resourceType": "QuestionnaireResponse",
"id": "questionnaireresponse-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-adap-questionnaireresponse"
],
//COMMENT - contained Questionnaire
"contained": [
{
"resourceType": "Questionnaire",
"id": "questionnaire-example-adaptive-sampler",
"meta": {
"profile": [
"http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/argo-questionnaire"
]
},
//COMMENT -the 'url' element identifies the adaptive questionnaire - the set of questions for a particular adaptive questionnaire
"url": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler",
"title": "Argonaut Questionnaire Sampler",
"status": "draft",
...[snipped for brevity]....
"item": [
{
"linkId": "g1",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score) this could also be a GUID.
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1",
"text": "Header Text",
"type": "group",
"required": true,
"item": [
{
"linkId": "g1.d",
//COMMENT - unique url for the Server to identify the adaptive questionnaire question for processing (figure out what is the next question and/or calculating the score)
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g1.d",
"text": "The Argonaut Questionnaire Sampler is designed to show all the question types that can be used in the Argonaut Questionnaire Project:\n\n1 boolean\n2 decimal\n3 integer\n4 dateDate\n5 dateTime\n6 timeTime\n7 string\n8 textText\n9 urlUrl\n10 choice\n11 open-choice\n12 quantity\n",
"type": "display",
"required": true
}
]
},
{
"linkId": "g2",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2",
"type": "group",
"item": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-ordinalValue",
"valueDecimal": 17
}
],
"linkId": "g2.q1",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g2.q1",
"text": "Check the box if the following statement is true. The average air speed velocity of a laden European swallow is greater than a laden African swallow.",
"type": "boolean",
"required": true,
"repeats": false
}
]
},
//COMMENT - third item group is the current question
{
"linkId": "g3",
"type": "group",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g3",
"item": [
{
"extension": [
{
"url": "http://hl7.org/fhir/StructureDefinition/questionnaire-ordinalValue",
"valueDecimal": 7
}
],
"linkId": "g3.q1",
"definition": "http://fhir.org/guides/argonaut/questionnaire/Questionnaire/questionnaire-example-adaptive-sampler#g3",
"text": "What is the average air speed velocity of a laden swallow in m/sec?",
"type": "decimal",
"required": true,
"repeats": false
}
]
},
//COMMENT - add a readOnly hidden score question to a final item group.
{
"linkId": "g4",
"type": "group",
"item": [
{
"extension": [
{
"url": "http://fhir.org/guides/argonaut/questionnaire/StructureDefinition/extension-hidden",
"valueBoolean": true
}
],
"linkId": "g4.q1",
"text": "The total score is:",
"type": ,
"required": true,
"repeats": false,
"readOnly": true
}
}
]
}
]
}
]
},
//COMMENT -references the contained Questionnaire
"questionnaire": {
"reference": "#questionnaire-example-adaptive-sampler"
},
//COMMENT - status of ‘complete’ is a signal to the Client that the adaptive Questionnaire is done!
"status": "complete",
...[snipped for brevity]....
"item": [
{
"linkId": "g1",
"item": [
{
"linkId": "g1.d"
}
]
},
{
"linkId": "g2",
"item": [
{
"linkId": "g2.q1",
"answer": [
{
"valueBoolean": false
}
]
}
]
},
},
{
"linkId": "g3",
"item": [
{
"linkId": "g3.q1",
"answer": [
{
"valueDecimal": 12.38
}
]
}
]
},
//COMMENT - add a readOnly hidden score question to a final item group.
{
"linkId": "g4",
"item": [
{
"linkId": "g4.q1",
"answer": [
{
"valueQuantity": {
"value" : 24,
"unit" : "points",
"system" : "http://unitsofmeasure.org",
"code" : "\{score\}"
}
}
]
}
]
}
]
}
QuestionnaireResponse and Scoring
When the adaptive questionnaire is complete, the Form Filler processes the QuestionnaireResponse with a contained Questionnaire based on the questions it was returned by the service. The Form Filler may represent the cumulative or intermediate scores as answers as separate Observations. The Form Filler may post the responses to an Answer Bank and perform searches on the QuestionnaireResponse as described in the Static Forms Use Case.
Examples and Reference Implementation
Examples of completed Adaptive QuestionnaireResponses which demonstrate use of all the extensions and support elements as well as many of the question types can be found on the Argonaut Adaptive QuestionnaireResponse Profile page. In addition, the Argonaut Questionnaire Test Renderer simulates the adaptive form workflow.
Amending and Revising Adaptive Forms
End User wishes to go back and revise an answer to Question
For adaptive forms it needs to be emphasized that it is a stateless process for both the “black box” Service and the Form Filler. That means that the Service processes the entire question-answer tree each time from the beginning and the Form Filler re-renders the informations each time. So any question-answer pair or calculated results can change until the form is completed. The Service may mark some question-answer pairs as readOnly which instruct the Form Filler that they can not be subsequently altered. If not marked as readOnly, any response can be changed at any time by the Form Filler and the Service will process normally and may remove subsequent question-answers as necessary based on its logic. The Form Filler will be presented with the question-answer pairs and render it anew as well - i.e., it shall not retained the previous information.
Answer in Error and Needs to be Reentered
For adaptive forms refer to the API on FHIR operation. An OperationOutcome with the location of the error represented in the ‘expression element’ and a human readable error message should be returned.
Technical Error
Technical errors are typically handled by lower level protocols or manual processes. Typically the Form Filler or Service would simply resubmit the QuestionnaireResponse.
-
How to implement Questionnaire to design forms that adjust what information is displayed and/or that perform calculations based on user input is covered in the SDC (Structured Data Capture) implementation Guide. ↩
