Structured Data Capture
2.8.0 - CI Build

Structured Data Capture, published by HL7 International - FHIR Infrastructure Work Group. This is not an authorized publication; it is the continuous build for version 2.8.0). This version is based on the current content of https://github.com/HL7/sdc/ and changes regularly. See the Directory of published versions

Adaptive forms

Adaptive Questionnaire Background

Adaptive Forms follow an architecture where a questionnaire is not pre-defined, rather the questionnaire is dynamically developed based on previous answers to questions chosen from an item bank of questions. This type of administration is also known as Computerized Adaptive Testing (CAT), or administration of Adaptive Questionnaires. In these cases, a set of questions (typically 4 to 12) are administered from a question bank containing numerous questions. The selected questions are based on Item Response Theory (IRT) algorithms which look at the answers provided and select the next question based on IRT algorithms. The questions are selected to quickly obtain the necessary outcomes (e.g. assessing a person's physical function) using fewer questions rather than administer a large question bank. These small set of questions still provide the necessary confidence and scores required to interpret the data appropriately as if the whole questionnaire was administered.

Adaptive Questionnaire Administration Abstract Model and Actors

The section explains the process of administering an Adaptive Questionnaire and the actors (systems) involved. Figure 1 below shows the abstract model of the administration process.

Adaptive Questionnaire Administration Abstract Model

Figure 1: Adaptive Questionnaire Administration Abstract Model

Actors, Definitions and Data Flow

External Assessment Center: The External IRT based Assessment Center is a system that can administer a questionnaire based on IRT algorithms. The data that is necessary for the administration is only the initial item bank. The External Assessment Center does not need to know about the specific patient identity or any other clinical information. The Assessment Center will use algorithms recommended by the Questionnaire designer to determine how to administer the questionnaire.

Patient Facing Administration App: The Patient Facing Administration App is the actual app that is being used to present the questions to the patient. It can be an EHR, a SMART on FHIR App, an Independent PRO Administration App.

Data Flow Description for Adaptive Questionnaires Administration

As shown in Figure 1 above, the Patient Facing Administration App (EHR, Care Delivery System, Independent App or SMART on FHIR App) acts as the client and initiates the administration process.

The following section describes the steps that take place when completing an adaptive Questionnaire and also provides examples of the content sent to and received back from the 'next-question' operation.

  • Step 1: The available adaptive questionnaires are loaded into the Assessment Center.
  • Step 2: The administration is initiated with a specific Adaptive Questionnaire.

    Request
    POST [base]/Questionnaire/$next-question
    Request Body
          { // start body
            "resourceType": "QuestionnaireResponse",
            "meta": {
              "profile": [
                "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse-adapt"
              ]
            },// end of meta
    
            // contained Questionnaire
            "contained": [
              {
                "resourceType": "Questionnaire",
                "id": "q",
                "meta": {
                  "profile": [
                    "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-adapt"
                  ]
                },
                "identifier": {
                 // identifier system and value for "Physical Function 2.0" questionnaire
                },
    
                //no items since initiating the adaptive questionnaire
                ...
              }
            ], // end of contained Questionnaire
    
            // reference to contained Questionnaire
            "questionnaire": "#q",
            "status": "in-progress",
            ...
            //no items since it is just getting started
          } // end body

  • Step 3: The Assessment Center responds to the start request with a Questionnaire and the first item for administration.
    Response Body
          { // start response body
            "resourceType": "QuestionnaireResponse",
            "meta": {
              "profile": [
                "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse-adapt"
              ]
            }, // end of meta
    
            // contained Questionnaire
            "contained": [
              {
                "resourceType": "Questionnaire",
                "id": "q",
                "meta": {
                  "profile": [
                    "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-adapt"
                  ]
                },
                "identifier": {
                 // identifier system and value for "Physical Function 2.0" questionnaire
                },
    
                // First Item being sent back
                "item": [
                  {
                    "linkId": "1.1", // unique id of the question within the questionnaire
                    "code" : [
                      {
                        "system": "http://loinc.org",
                        "code": "12345-6"
                      }
                    ],
                    "text": "Are you able to walk for 30 minutes ?",
                    "type": "choice",
                    "required": true,
                    "answerValueSet": "http://loinc.org/LA1234"
                  } // end of item
                ]
              }
            ] // end of contained Questionnaire
          } // end response body

  • Step 4: The Patient Facing Administration App will then display the question to the user and collect the response.
  • Step 5: The Patient Facing Administration App will then send the answer to the Assessment Center and ask for the next question. The Assessment Center will use the answer to determine the next question based on the algorithm and respond back with the next question until the assessment is done.

    Request
    POST [base]/Questionnaire/$next-question
    Request Body
          { // start body
            "resourceType": "QuestionnaireResponse",
            "meta": {
                "profile": [
                  "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse-adapt"
                ]
            }, // end of meta
    
            // contained Questionnaire
            "contained": [
              {
                "resourceType": "Questionnaire",
                "id": "q",
                "meta": {
                  "profile": [
                    "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-adapt"
                  ]
                },
                "identifier": {
                 // identifier system and value for "Physical Function 2.0" questionnaire
                },
    
                // List items here that have been already administered.
                "item": [
                  {
                    "linkId": "1.1", // unique id of the question within the questionnaire
                    "code" : [
                      {
                        "system": "http://loinc.org",
                        "code": "12345-6",
                      }
                    ],
                    "text": "Are you able to walk for 30 minutes ?",
                    "type": "choice",
                    "required": true,
                    "answerValueSet": "http://loinc.org/LA1234"
                  } // end of item
                ]
              }
            ], // end of Contained Questionnaire
    
            // references the contained Questionnaire
            "questionnaire": "#q",
    
            "status": "in-progress",
            ...
            "item": [
              // First Item being sent back with answer to be used to determine completeness or next question.
              {
                "linkId": "1.1", // unique id of the question within the questionnaire
                "text": "Are you able to walk for 30 minutes ?",
                "answer": [
                  {
                    "valueCoding": {
                      "system": "http://loinc.org",
                      "code": "LA1234"
                    }
                  }
                ]
              } // end of item
            ]
          } // end body

    Response Body
          { // start body
            "resourceType": "QuestionnaireResponse",
            "meta": {
              "profile": [
                "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse-adapt"
              ],
            },// end of meta
    
            // contained Questionnaire
            "contained": [
              {
                "resourceType": "Questionnaire",
                "id": "Id of the Questionnaire Instance on which operation is being invoked",
                "meta": {
                  "profile": [
                    "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-adapt"
                  ]
                },
                "identifier": {
                  // identifier system and value for "Physical Function 2.0" questionnaire
                },
    
                "item": [
                // Item already administered
                  {
                    "linkId": "1.1", // unique id of the question within the questionnaire
                    "code" : [
                      {
                        "system": "http://loinc.org",
                        "code": "12345-6",
                      }
                    ],
                    "text": "Are you able to walk for 30 minutes ?",
                    "type": "choice",
                    "required": true,
                    "answerValueSet": "http://loinc.org/LA1234"
                  }, // end of Item already administered
    
                  // New Item
                  {
                    "linkId": "1.2", // unique id of the question within the questionnaire
                    "code" : [
                      {
                        "system": "http://loinc.org",
                        "code": "23456-7",
                      }
                    ],
                    "text": "Are you able to lift a chair to move it from one room to another ?",
                    "type": "choice",
                    "required": true,
                    "answerValueSet": "http://loinc.org/LA1234"
                  } // end of New Item
                ] // end of items
              }
            ], // end of contained Questionnaire
    
            // References the contained Questionnaire
            "questionnaire": "#q",
    
            "status": "in-progress",
            ...
    
            "item": [
              // First Item that was sent back with answer when requesting next question.
              {
                "linkId": "1.1", // unique id of the question within the questionnaire
                "text": "Are you able to walk for 30 minutes ?",
                "answer": [
                  {
                    "valueCoding": {
                      "system": "http://loinc.org",
                      "code": "LA1234"
                    }
                  }
                ]
              }
            ] // end of item
          } // end body

  • Step 4 is repeated as long as new questions are received and the status is "in-progress"
  • Step 6: If the Assessment Center determines that the assessment is done, it will respond with the final results which will contain all the questions that were answered, along with the answers, the individual scores and the overall score.
    Request
    POST [base]/Questionnaire/$next-question
    Response Body with Completed Status indicating completion of Administration
          { // start body
            "resourceType": "QuestionnaireResponse",
            "meta": {
              "profile": [
                "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaireresponse-adapt"
              ],
            },// end of meta,
    
            // contained Questionnaire
            "contained": [
              {
                "resourceType": "Questionnaire",
                "id": "Id of the Questionnaire Instance on which operation is being invoked",
                "meta": {
                  "profile": [
                    "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-adapt"
                  ]
                },
                "identifier": {
                  // identifier system and value for "Physical Function 2.0" questionnaire
                },
    
                "item": [
                // Items already administered
                  {
                    "linkId": "1.1", // unique id of the question within the questionnaire
                    "code" : [
                      {
                        "system": "http://loinc.org",
                        "code": "12345-6",
                      }
                    ],
                    "text": "Are you able to walk for 30 minutes ?",
                    "type": "choice",
                    "required": true,
                    "answerValueSet": "http://loinc.org/LA1234"
                  }, // end of item
                  {
                    "linkId": "1.2", // unique id of the question within the questionnaire
                    "code" : [
                      {
                        "system": "http://loinc.org",
                        "code": "23456-7",
                      },
                    ],
                    "text": "Are you able to lift a chair to move it from one room to another ?",
                    "type": "choice",
                    "required": true,
                    "answerValueSet": "http://loinc.org/LA1234"
                  }, // end of item
    
                  ...
    
                  // Since the questionnaire is completed, there will be 2 new items with the overall score and confidence.
                  {
                  // Mark the item as hidden (if the score should be hidden from the user)
                    "extension": [
                      {
                        "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-hidden",
                        "valueBoolean": true
                      }
                    ],
                    "linkId": "1.9", // unique id of the question within the questionnaire
                    "text": "Overall Score",
                    "type": "decimal",
                    "required": true,
                    "readOnly": true
                  }, // end of item
                  {
                  // Mark the item as hidden (if the confidence should be hidden from the user)
                    "extension": [
                      {
                        "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-hidden",
                        "valueBoolean": true
                      }
                    ],
                    "linkId": "1.10", // unique id of the question within the questionnaire
                    "text": "Score Confidence",
                    "type": "decimal",
                    "required": true,
                    "readOnly": true
                  } // end of item
                ]
              }
            ], // end of contained Questionnaire
    
            // references the contained Questionnaire
            "questionnaire": "#q",
    
            // completed Status
            "status": "completed",
            ...
    
            "item": [
              // First Item that was previously sent back
              {
                "linkId": "1.1", // unique id of the question within the questionnaire
                "text": "Are you able to walk for 30 minutes ?",
                "answer": [
                  {
                    "valueCoding": {
                      "system": "http://loinc.org",
                      "code": "LA1234"
                    }
                  }
                ]
              }, // end of item
              {
                "linkId": "1.2", // unique id of the question within the questionnaire
                "text": "Are you able to lift a chair to move it from one room to another ?",
                "type": "choice",
                "answer": [
                  {
                    "valueCoding": {
                      "system": "http://loinc.org",
                      "code": "LA3534"
                    }
                  }
                ]
              }, // end of item
    
              ...
    
              // Since the questionnaire is completed, there will be 2 new items with the overall score and confidence.
              {
                "linkId": "1.9", // unique id of the question within the questionnaire
                "text": "Overall Score",
                "answer": [
                  {
                    "valueDecimal": "123.45"
                  }
                ]
              },
              {
                "linkId": "1.10", // unique id of the question within the questionnaire
                "text": "Score Confidence",
                "answer": [
                  {
                    "valueDecimal": "0.95"
                  }
                ]
              }
            ] // end of items
          } // end body