Build the weekly wellness reflection

Create a FHIR Questionnaire for a short non-clinical weekly check-in and save responses with QuestionnaireForm.

What we are building

A short, app-owned FHIR Questionnaire with one self-report question for each domain. Ovok Native renders the Questionnaire, validates required answers and saves a FHIR QuestionnaireResponse for the signed-in Patient.

What you should already have

The implementation

This is an example of an app-owned reflection, not a validated psychological, sleep, nutrition or clinical instrument. Keep it brief and neutral. Create and publish this resource once in the sandbox using an authorized project workflow; the mobile member flow should read the published resource, not create a new Questionnaire on every launch.

const reflectionOptions = [
  "Much less than I wanted",
  "A little less than I wanted",
  "About as I expected",
  "A little more than I expected",
  "Much more than I expected",
];

export const weeklyWellnessQuestionnaire = {
  resourceType: "Questionnaire" as const,
  status: "active",
  title: "Weekly wellbeing reflection",
  subjectType: ["Patient"],
  item: [
    {
      linkId: "sleep",
      text: "How did your sleep feel this week?",
      type: "choice" as const,
      required: true,
      answerOption: ["Very difficult", "Difficult", "Mixed", "Good", "Very good"].map(
        (value) => ({ valueString: value }),
      ),
    },
    {
      linkId: "movement",
      text: "How did your movement compare with what you wanted for yourself?",
      type: "choice" as const,
      required: true,
      answerOption: reflectionOptions.map((value) => ({ valueString: value })),
    },
    {
      linkId: "nutrition",
      text: "How did your eating habits feel this week?",
      type: "choice" as const,
      required: true,
      answerOption: reflectionOptions.map((value) => ({ valueString: value })),
    },
    {
      linkId: "stress",
      text: "How would you describe your stress this week?",
      type: "choice" as const,
      required: true,
      answerOption: ["Very high", "High", "Mixed", "Low", "Very low"].map(
        (value) => ({ valueString: value }),
      ),
    },
    {
      linkId: "recovery",
      text: "How did your energy and sense of recovery feel this week?",
      type: "choice" as const,
      required: true,
      answerOption: ["Very low", "Low", "Mixed", "Good", "Very good"].map(
        (value) => ({ valueString: value }),
      ),
    },
    {
      linkId: "week-note",
      text: "What would you like to discuss with your coach?",
      type: "string" as const,
    },
  ],
};

Load the active Questionnaire from the project, then render it with the SDK-managed persistence path:

import { QuestionnaireForm } from "@ovok/native";

export function WeeklyReflectionForm({
  questionnaire,
  onCompleted,
}: {
  questionnaire: Parameters<typeof QuestionnaireForm>[0]["questionnaire"];
  onCompleted: (responseId: string) => void;
}) {
  return (
    <QuestionnaireForm
      questionnaire={questionnaire}
      onSuccess={(response) => {
        if (response.id) onCompleted(response.id);
      }}
      onError={(error) => console.error("Reflection save failed", error)}
    >
      <QuestionnaireForm.Header />
      <QuestionnaireForm.Content>
        <QuestionnaireForm.Content.Item />
        <QuestionnaireForm.Content.Error />
      </QuestionnaireForm.Content>
      <QuestionnaireForm.Navigation>
        <QuestionnaireForm.Navigation.PreviousButton />
        <QuestionnaireForm.Navigation.NextButton />
        <QuestionnaireForm.Navigation.SubmitButton>
          Save this reflection
        </QuestionnaireForm.Navigation.SubmitButton>
      </QuestionnaireForm.Navigation>
    </QuestionnaireForm>
  );
}

With onSuccess / onError and no app-owned onSubmit, the component creates a QuestionnaireResponse using the active Patient and the Questionnaire. A stable identifier prevents duplicate writes while a submission is pending; after a successful save, a later submission is a new response. Start a clean form for each weekly check-in rather than editing a completed response in place.

The example answer choices are ordinary app-owned reflection options, not a validated scale. The Questionnaire's item text is FHIR content; create a reviewed Questionnaire for each supported language rather than assuming CMS translation automatically rewrites FHIR resource content.

Important Ovok decisions

  • Use stable linkId values so a question can be matched across responses and languages.
  • Keep the Questionnaire resource as the question definition and each QuestionnaireResponse as a distinct historical completion.
  • No score, diagnosis, psychological assessment or recommendation is calculated.
  • $populate and $extract are not required for this simple reflection. Use them only for a workflow that actually needs their documented behavior; see Ovok primitives.
  • App-owned labels and navigation are localized through CMS; Questionnaire content is managed as FHIR data.

Expected result

A member can complete the weekly reflection and the SDK saves a QuestionnaireResponse linked to that Patient and Questionnaire. Failed saves remain visible and can be retried.

Common errors and troubleshooting

SymptomCheck
The form cannot render an itemConfirm the Questionnaire uses item types supported by the current QuestionnaireForm.
Submission says no profile is availableMount the form after sign-in and successful Patient profile loading.
A retry creates duplicate responsesKeep the form instance mounted while the same submission is retried; mount a new instance only for a new check-in.
A language switch changes buttons but not question textPublish a matching localized FHIR Questionnaire resource and load that version.
The form starts to look like a clinical assessmentKeep the questions neutral and clearly identify them as self-reflections.

Previous / next

Last updated on

On this page