Questionnaire
Introduction #
The Questionnaire model represents a structured set of questions intended to guide the collection of answers from end-users.
The Interview model represents answers to a structured set of questions represented by a Questionnaire.
Basic usage #
To get a questionnaire or interview by identifier, use the get method on the Questionnaire or Interview model managers:
from canvas_sdk.v1.data.questionnaire import Interview, Questionnaire
questionnaire = Questionnaire.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
interview = Interview.objects.get(id="75df6d7f-d58d-443b-9fa0-ce43b4d7b2a0")
If you have a patient object, the interviews for a patient can be accessed with the interviews attribute on a Patient object:
from canvas_sdk.v1.data.patient import Patient
patient = Patient.objects.get(id="1eed3ea2a8d546a1b681a2a45de1d790")
interviews = patient.interviews.all()
If you have a patient ID, you can get the interviews for the patient with the for_patient method on the Interview model manager:
from canvas_sdk.v1.data.questionnaire import Interview
patient_id = "1eed3ea2a8d546a1b681a2a45de1d790"
interviews = Interview.objects.for_patient(patient_id)
Questionnaire questions #
The questions for a questionnaire can be accessed with the questions attribute on an Questionnaire object:
from canvas_sdk.v1.data.questionnaire import Questionnaire
from logger import log
questionnaire = Questionnaire.objects.get(id="b80b1cdc-2e6a-4aca-90cc-ebc02e683f35")
for question in questionnaire.questions.all():
log.info(f"system: {question.code_system}")
log.info(f"code: {question.code}")
log.info(f"name: {question.name}")
Interview responses #
The interview responses for an interview can be accessed with the interview_responses attribute on an Interview object:
from canvas_sdk.v1.data.questionnaire import Interview
from logger import log
interview = Interview.objects.get(id="75df6d7f-d58d-443b-9fa0-ce43b4d7b2a0")
for interview_response in interview.interview_responses.all():
log.info(f"response option: {interview_response.response_option_value}")
Filtering #
Questionnaires and interviews can be filtered by any attribute that exists on the models.
Filtering for questionnaires and interviews is done with the filter method on the Questionnaire and Interview model managers.
By attribute #
Specify an attribute with filter to filter by that attribute:
from canvas_sdk.v1.data.questionnaire import Interview, Questionnaire
questionnaires = Questionnaire.objects.filter(name="Tobacco")
interviews = Interview.objects.filter(progress_status="F")
By ValueSet #
See Value Sets for the library of built-in value sets and how to create your own.
Filtering by ValueSet works a little differently. The find method on the model manager is used to perform ValueSet filtering:
from canvas_sdk.v1.data.questionnaire import Questionnaire
from canvas_sdk.value_set.v2022.assessment import TobaccoUseScreening
questionnaires = Questionnaire.objects.find(TobaccoUseScreening)
Interview also supports find, which returns the interviews whose questionnaire has a code in the value set:
from canvas_sdk.v1.data.questionnaire import Interview
from canvas_sdk.value_set.v2022.assessment import TobaccoUseScreening
interviews = Interview.objects.find(TobaccoUseScreening)
For interviews, find matches against the related Questionnaire through the questionnaires relation. Questionnaires store their code system by name (for example, "LOINC") rather than by URL, and find handles this for you. It also composes with for_patient:
from canvas_sdk.v1.data.questionnaire import Interview
from canvas_sdk.value_set.v2022.assessment import TobaccoUseScreening
interviews = (
Interview.objects
.for_patient("1eed3ea2a8d546a1b681a2a45de1d790")
.find(TobaccoUseScreening)
)
Attributes #
ResponseOptionSet #
| Field Name | Type |
|---|---|
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| status | String |
| name | String |
| code_system | String |
| code | String |
| type | String — one of the question types below |
| use_in_shx | Boolean |
| options | ResponseOption[] |
| questions | Question[] |
Question types #
type holds the code for the kind of question the option set describes. It decides how the question renders in a note and which value an answer carries.
type | Question | Answer |
|---|---|---|
TXT | Free text | Text, on the response’s response_option_value. |
INT | Integer | A whole number. |
DEC | Decimal | A decimal number. |
DATE | Date | A calendar date, on the response’s response_option_date. |
SING | Single select | One ResponseOption. |
MULT | Multi select | One or more ResponseOption records. |
TXT and DATE questions are not scored, so they are skipped when a questionnaire calculates a score. Authoring a questionnaire in a plugin sets this through the question’s responses_type — see Response types.
ResponseOption #
| Field Name | Type |
|---|---|
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| status | String |
| name | String |
| code | String |
| code_description | String |
| value | String |
| response_option_set | ResponseOptionSet |
| ordering | Integer |
| interview_responses | InterviewQuestionResponse[] |
| enablement_conditions | QuestionEnablementCondition[] |
enablement_conditions holds the conditions that test for this response option, which is how you find the questions a given answer unlocks.
Question #
| Field Name | Type |
|---|---|
| id | UUID |
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| status | String |
| name | String |
| response_option_set | ResponseOptionSet |
| acknowledge_only | Boolean |
| show_prologue | Boolean |
| code_system | String |
| code | String |
| enable_behavior | String — all or any |
| interview_responses | InterviewQuestionResponse[] |
| dependent_conditions | QuestionEnablementCondition[] |
| triggers_condition | QuestionEnablementCondition[] |
enable_behavior decides whether all of the question’s enablement conditions must be met for it to be enabled, or only one of them. It is empty on a question authored without an enabled_behavior, so handle an empty value when reading it.
The read-side attribute here is enable_behavior (no “d”). When authoring a questionnaire through the effect or the manifest schema, the matching config field is spelled enabled_behavior (with a “d”). The difference is intentional.
A question sits on both sides of the branching, so it carries a relation for each direction:
dependent_conditions: the conditions that decide whether this question is enabled.triggers_condition: the conditions on other questions that test this question’s answer.
QuestionEnablementCondition #
A QuestionEnablementCondition controls when a Question is enabled, following FHIR’s enableWhen pattern. Import it with from canvas_sdk.v1.data import QuestionEnablementCondition. Here question is the question the condition governs, and dependent_on is the question whose answer is tested.
| Field Name | Type |
|---|---|
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| status | String |
| question | Question |
| dependent_on | Question |
| operator | String — =, !=, exists, or not_exists |
| answer_option | ResponseOption |
| answer_value | String |
operator takes the same comparison operators as a questionnaire’s enabled conditions (see Enablement operators). answer_option references the ResponseOption matched, the read-side counterpart of a condition’s value_code; answer_value holds a literal value matched, the counterpart of a condition’s value_string.
Questionnaire #
| Field Name | Type |
|---|---|
| id | UUID |
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| status | String |
| name | String |
| expected_completion_time | Float |
| can_originate_in_charting | Boolean |
| use_case_in_charting | String |
| scoring_function_name | String |
| scoring_code_system | String |
| scoring_code | String |
| code_system | String |
| code | String |
| search_tags | String |
| questions | Question[] |
| use_in_shx | Boolean |
| carry_forward | String |
| interview_responses | InterviewQuestionResponse[] |
QuestionnaireQuestionMap #
| Field Name | Type |
|---|---|
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| status | String |
| questionnaire | Questionnaire |
| question | Question |
Interview #
| Field Name | Type |
|---|---|
| id | UUID |
| dbid | Integer |
| committer | CanvasUser |
| entered_in_error | CanvasUser |
| status | String |
| name | String |
| language_id | Integer |
| use_case_in_charting | String |
| patient | Patient |
| note_id | Integer |
| appointment_id | Integer |
| questionnaires | Questionnaire[] |
| progress_status | String |
| created | DateTime |
| modified | DateTime |
| interview_responses | InterviewQuestionResponse[] |
| assessment_set | Assessment[] |
InterviewQuestionnaireMap #
The join between an Interview and the questionnaires it covers. Reach them through the interview’s questionnaires attribute rather than querying this model.
| Field Name | Type |
|---|---|
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| status | String |
| interview | Interview |
| questionnaire | Questionnaire |
InterviewQuestionResponse #
| Field Name | Type |
|---|---|
| dbid | Integer |
| created | DateTime |
| modified | DateTime |
| status | String |
| interview | Interview |
| questionnaire | Questionnaire |
| question | Question |
| response_option | ResponseOption |
| response_option_value | String |
| response_option_date | Date |
| questionnaire_state | String |
| interview_state | String |
| comment | String |
Questions? Create an issue.