Interface Guide

Questionnaire Mapping

CareEvolution RKStudio surveys can map to FHIR Questionnaire resources. There are a few special considerations when performing this mapping.

Survey Data

Survey data is stored in the CareEvolution system in the form of observations.

An Observation Context is used to represent the task/survey. The type term corresponds to the study name.

An Observation is used to represent each survey question. The value is the name of the step.

Each survey question Observation contains a child Observation representing the answer to each qeuestion. The value is the answer to the question. If the question has multiple answers (multi-select), the answer has child observations for each answer.

Additional child Observations are used to track the start/stop times of the tasks/questions and the UUID of the task. The Observation Date is always the date/time the survey was uploaded.

Finding Questionnaires

Questionnaires are found by searching for all Observation Contexts that have a Document Type in the FHIR Questionnaire term subset (e.g., FhirQuestionnaireDocumentTypeTerms). When a ResearchKit task is uploaded, a term corresponding to that task would be added to this subset.

Each Questionnaire has one and only one top-level group (as defined by the FHIR spec). The group’s name matches the Document Type term of the Observation Context.

Groups vs Questions

The FHIR specification permits a Questionnaire group to contain questions or sub-groups, but not both. When mapping CareEvolution Observations to FHIR Questionnaires, the system must determine whether to render the Observations as questions or sub-groups.

The primary consideration is whether at least one of the Observations qualifies as a group. This is determined based on whether the Observation type belongs to the FHIR Questionnaire Group term subset (e.g., FhirQuestionnaireGroupObservationTypeTerms).

If one or more of the Observations qualify as a group, then they will all be treated as sub-groups. Otherwise, they will all be treated as questions.


Some Observations can be exposed as extensions instead of sub-groups or questions. Whether an observation qualifies as an extension depends on whether its type is a member of one of the following term subsets:

  • FHIR Questionnaire Extension (e.g., FhirQuestionnaireExtensionObservationTypeTerms)
  • FHIR Questionnaire Group Extension (e.g., FhirQuestionnaireGroupExtensionObservationTypeTerms)
  • FHIR Questionnaire Question Extension (e.g., FhirQuestionnaireQuestionExtensionObservationTypeTerms)