Summary templates: turning questionnaire answers into text

Modified on Thu, 29 Oct at 10:49 AM

Summary templates turn a patient's answers on a questionnaire into a short piece of written text. When the patient submits the questionnaire, the therapist sees this generated summary at the top of the response instead of the raw list of questions and answers, and can copy it to the clipboard or print it to PDF. This article explains what the tool does, how to get a first summary working in a few minutes, and where to go when you want more control.


Summary templates is an advanced tool. Simple summaries can be set up entirely from the composer described below. Anything beyond that, such as clinical rule tables or conditional wording, involves writing small templates by hand, and we recommend using the Youwell AI assistant or contacting Youwell support to help with the setup.


CONTENTS


What summary templates do

A questionnaire page (a task) can carry a set of summary templates. Each template describes what the summary should say about one question, one answer option, or a piece of composed text, and one of them is the final summary that the therapist reads.


Typical uses:

  • Turning twenty checkbox answers into two readable sentences for the therapist.
  • Producing a draft reply or journal note that the therapist can review, copy and paste into a chat or a journal system.
  • Encoding a clinical checklist ("if the patient reports X, check Y") as content that clinicians can edit themselves.


The text is generated by fixed rules that you define. There is no AI involved when the summary is produced, so the same answers always give the same summary. The same rules are used when a response is printed to PDF or sent to a journal system.


Before you start

Build and save the questionnaire first: the content page, its questions and answer options. Summary templates describe an existing questionnaire, so the questions need to be in place before you begin.


Then give the questions and answer options meaningful, unique keys in the question editor. Keys are how the summary refers to an answer. If you leave them blank, the platform fills in Q01, Q02 and A01, A02 for you. Those work, but answer keys restart at A01 for every question, and the summary cannot tell two A01s apart. Rename answer options to keys that are unique across the whole page, for example evening_alcohol rather than A03, before you start. You can read more about keys here: Question keys and form IDs.


Opening the composer

In the portal, go to Program, open the programme, the module and the content page. In the page's ⋯ menu, choose Summary templates. Once a page has at least one template, a summary icon also appears in the page header as a shortcut.


The composer has two panes:

  • Questionnaire (left): the page's own structure as an outline, with each section, question and answer option. Every question is marked as Described or Not described, and the header shows how many of the questions the summary covers, for example 4 of 6 questions described. Below the questions is a Composed text group for text that is not tied to a single question, and the Final row, which is what the therapist sees. Use the search field to find a row by key on long questionnaires.
  • Editor (right): the text for whatever you have selected on the left, with a Live output preview above it and Test answers below.


The order in which rows are combined is worked out automatically from the questionnaire when you save. Only composed text can be reordered by hand.


The quickest way to a summary

You do not need to write any templates to get a working summary. The composer can generate the standard rows for you.


  1. Open Summary templates on the page.
  2. Choose Add all questions to summary at the top of the outline. To do one question at a time instead, hover over a question in the outline and choose Add to summary.
  3. Pick how each answer should read:
    • The answer on its own: just the value, for example Almost every night.
    • Question text: answer: the question followed by the value, for example How often do you wake up?: Almost every night.
    • A sentence I write myself: your own wording, with {{value}} placed where the answer should go, for example The patient reports waking {{value}}.
  4. The dialog tells you how many rows it will create. Rows that already contain text are always left as they are, so you can run it again later to fill in any gaps.
  5. Choose Add. A final summary row is created automatically if the page does not already have one, listing each described question in questionnaire order.


Free text, single choice, multiple choice, scale and rating questions can be generated. For single and multiple choice, the summary shows the text of the chosen option, not its key. If the dialog says a key names more than one question, two questions share an answer key; give those options unique keys on the question and try again.


Testing the summary

Use Test answers at the bottom of the editor to answer the questions as a patient would. Nothing entered here is saved; it only drives the preview. Live output above shows the result as you type, and can be switched between Whole summary and This row only.


If a template refers to something that does not exist, the preview lists the errors and names the row they are in. Save is not available while an error stands, so a mistyped key cannot reach patients.


You can also open the page's preview (the eye icon in the page header). This shows the page as the patient sees it, with a live summary panel alongside that updates as you answer.


Adjusting the wording

Select any row in the outline to edit its text:

  • On an answer option, the field is Text used when this option is chosen. Change this to reword what the summary says when the patient picks that option.
  • On a question, the field is When answered, output. This is the line the summary produces for that question.
  • Under Composed text, you can add free-standing text that combines other rows, for example a heading, a fixed reminder, or a paragraph that only appears when a particular option was chosen.
  • The Final row is the summary itself. Any composed text that uses variables can be promoted to become the summary with Make this the summary.


Below the text, Uses lists the rows the text reads. This is filled in from the template automatically and rarely needs editing.


The summary is formatted with Markdown. **bold**, ### headings and - lists work; HTML tags do not.


Writing templates by hand

Templates use the Handlebars language. The generated rows are ordinary templates, so you can open any of them to see the pattern and adapt it. The most useful building blocks are:


{{answer}}The answer to this row's own question or option.
{{item.label}}The question text, or the answer option's text.
{{aa.key}}The answer to any question or option on the page. For an answer option it is true when that option was chosen.
{{ao.key}}The text produced by another template row.
{{#if aa.key}} … {{/if}}Show the text only when that question was answered or that option was chosen.
{{#eq answer 'key'}} … {{/eq}}Show the text only when a single-choice answer equals a particular option.
{{csv o sep=', '}}Join the chosen options of a multiple choice with commas, skipping the ones not chosen.


A common pattern is a checklist that depends on an answer:

{{#if aa.nocturnal_lows}}Check overnight basal rate, sensor alarms and late boluses.{{/if}}{{#if aa.exercise_lows}}Check the temporary basal rate around exercise.{{/if}}


The buttons along the top of the editor paste a skeleton of each helper for you. If you find yourself writing more than a few of these, this is where the Youwell AI assistant earns its keep: describe the summary you want and let it draft the templates against your questionnaire, then check the result with Test answers.


What the therapist sees

When a patient submits the questionnaire, the therapist opens the response from the patient page as usual. The generated summary appears at the top. Show questionnaire reveals the underlying questions and answers, Copy to clipboard copies the summary text for pasting into a chat message or journal system, and Print to PDF produces a document with the same text.


The summary is a suggestion for the therapist to judge. It does not send anything to the patient on its own, and any free text the patient wrote will appear in it as written.


Conditional visibility

A related tool, Conditional visibility, sits next to Summary templates in the page's ⋯ menu where it is enabled. It lets you show or hide a section, question or answer option depending on the patient's other answers, for example showing a follow-up section only when one specific option was chosen. It works both in the patient app and in the therapist's view of the response. Because it shares its storage with summary templates, a rule may appear as a row without text in the composer; leave those rows alone.


Common pitfalls

  • Two answer options with the same key. The most common cause of a summary that shows the wrong option text or nothing at all. Give options unique keys before adding templates.
  • Nothing appears for a question. Check the outline: the question is probably marked Not described. Use Add to summary on it.
  • The whole summary is empty. No row is marked Final, or the final row has no variables in it. Add all questions to summary creates one, or promote a composed row with Make this the summary.
  • A choice question shows a code instead of text. The template uses the answer's key directly. Use the generated pattern for the question instead, which resolves the option text.
  • Formatting shows as tags. Use Markdown, not HTML, in templates.
  • Templates are not copied to a new content version. Publishing a new version of the page copies the questions but not the summary templates. Check the summary after publishing.


Getting help

For anything more than a straightforward summary, we recommend either using the Youwell AI assistant, which can read your questionnaire and draft the templates for you, or contacting Youwell support with a description of what the summary should say. Include the programme and page name and, if possible, an example of the finished text you have in mind.

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article