Understand choice lists

This document is for choice lists as implemented in checkflows, a legacy flow type. If you do not have existing checkflows, we recommend you disregard this document and visit Working with backtracks and choice lists instead, which discusses the new version of this functionality.

In checkflows, by default the user is presented with a series of observable symptoms one after another. It's often better to let the user speed things up by choosing between several symptoms at once. This can be done using choice lists. (For the steps to create and work with choice lists within the assistant builder, see Create choice lists.)

How choice lists work

When an observable symptom is added to a choice list, this changes how the symptom is shown to the user in the assistant. Instead of being its own card with "yes" and "no" options, it is shown as an option in a list alongside any other observable symptoms that have been added to that same choice list.

When the user selects a symptom from the list, they are taken to the symptoms that are connected to the selected symptom, just like if the user had navigated to that individual symptom and indicated that it was their problem. They can thus jump straight to the relevant portion of the flow without having to go through each symptom one by one.

Note that when an observable symptom is presented to a user outside of a choice list, it will display its "QUESTION" field, but when presented as an option in a choice list, it will display its "SYMPTOM" field.

As such, the "SYMPTOM" value should always be a declarative statement that the problem is occurring rather than an ambiguous statement or question. For example, for an observable symptom about a door being stuck shut, "Is the door stuck shut?" can be used as the "QUESTION" while "Door can not be opened" can be used as the "SYMPTOM".

When to use choice lists

It is almost always helpful to have an initial choice list of common issues so that most users can quickly find what they need from the start.

Beyond that, choice lists are most useful when differentiating between symptoms of similar likelihood or in cases where symptoms are clearer when presented together. For example, suppose you are building a flow for troubleshooting a device that can make a few different kinds of noises if something is wrong with it. You may have several observable symptoms such as "Thumping noise", "Clanging noise", and "Scraping noise". If these symptoms are presented to the user one after another, the user will have to consider whether the noise they are hearing matches this description without knowing what the other options are, which can easily result in an incorrect choice. If instead they are presented all three options together in a choice list, it's easier to determine which kind of noise they are hearing and choose correctly.

Choice lists should not be used with symptoms that are rare or which should not be suggested to the user early. Such symptoms can still be quickly available via free text search when appropriate, but don't need to be presented proactively to all users.