Branching and Piping Rules

Overview

PiLR EMA supports branching and piping in surveys. Branching allows portions of a survey to be shown or hidden depending on how questions are answered, and piping allows an answer from a previous question to be inserted or ‘piped’ into the text of an upcoming question.

Basic Survey Concepts

Surveys consists of questions that can be organized into sections.  Sections are important to consider for 3 reasons:

  1. They can help keep the survey presentation neat.  Each section is displayed together, so it might make sense to break a survey into logical pieces (sections).  Each section will be displayed by itself in order, and the user will be prompted to go to the next section.
  2. If you are going to pipe data from one question to another, it is a requirement that the questions be in separate sections.
  3. Branching rules can apply to a whole section.  This can be a nice way to manage what the user sees.  You only present the detailed questions that make sense given how they answer previous sections.  In the Example Screen Shot (left), the user is presented with a question about which Health Areas they might like to assess.  The blue highlighting on Activity and Mood indicate that these are the choices that the user has made.  Using branching, we can skip any questions related to Nutrition by putting them in a single section.Screenshot_2015-07-02-13-16-33.png

Sections are handled as a single entity.  This means that if a user is on section 1, and question 3 does not fit on the screen of the mobile device, the user can see that question by scrolling down.  On Android this is accomplished by a vertical swipe gesture.

If a user want to progress to question 4(which is in a different section), they will have to use the navigation arrow provided by their phone.  On Android this will be a right facing arrow.     The arrow will be displayed beneath the section (see the example screenshot below).

Branching rules can apply to either an individual question within a section, or to all questions in a section.  The survey author can choose to display or hide multiple related questions based on a participant's answer to a single question by nesting multiple questions in a section, and then applying the hide or show command to the section, and not individual questions.

Branching

By default, all survey sections and question cards will be shown to a participant. We can add branching logic to remove or skip some of the cards or sections depending on how a participant answers a particular question.

Branching is configured through set of rules that specify a condition, and then one or more actions to perform if that condition is met.  

When you are considering using a branching flow in your survey, we suggest that you create the survey in the following order:

  1. Create your questions and cards.
  2. Create the branching rules.

We recommend this, because the branch rules use the question or section reference codes that are assigned when these objects are created.  

Example:pilr_health_survey_flow_example (1).png

On a card with possible answers of ‘1’ , ‘2’, or ‘3’

If the participant selects answer ‘1’

Then skip, or ‘hide’ the follow up questions in section 2.

If we create the first question with a ‘Multiple Choice – Select One’ card, the screen will look like this:

pilr_health_survey_question.PNG

We’ll need to note the card’s reference code and the ‘value|text’ options for each answer.  The ‘value’ is what is returned to PiLR Health as the question answer, and the ‘text’ is what is shown to the participant when they are viewing the survey in the mobile application.

Note: you can set your own reference code, provided it is unique, but only when the card is first created. Otherwise, we will receive a number, like 42677.  

After saving the new card, we will also create two more follow up questions. For our demo, we’ll assume their codes are 36951 and 03546.  These additional questions are in the section with the ‘Protective Equipment, title and the number of ‘2’.


Creating branching rules

After saving the cards, click the Edit Survey Rules button on the left side of the survey editor.  Here we will add our branching rules using the codes from our new question cards.  Clicking the Edit Rules Button will open the Survey Rules Editor.  The screen should look something like this:pilr_health_survey_rules_editor.PNG

The left hand side of the view is the Rules Editor workspace, and the right hand side provides a reference view of the cards and sections you created in the survey editor.  The rules use a format described on the edit window. Incorrectly setting the rules will result in an error when you try to save. To begin a new set of rules, it may be helpful to start by copying and pasting the example rules located on the edit window.

Using our question codes, we will set up a rule to skip or ‘hide’ the question about using a respirator question (36951) if the participant selects answer 1.

We’ll also need to remember that our Answer ‘A’ has a value of 1, and ‘B’ = 2.

[

{"expr": { "question_code"  "42677", "response_value": "1" }, "hide_cards": [ "36951" ]}

]

There are two parts to this rule

  1. Anything inside the brackets that follow the ‘expr’ property will be the IF part of your conditional statement:

    IF question code 42677 has a response value of 1
  2. Everything else outside of the “expr”: { } bracket will be our action(s), or what occurs after the THEN part of our conditional statement:

    THEN hide question 36951

By default, all cards are shown to the participant. This includes cards that were previously hidden by a rule. In our example, if the participant selects the option that hides the card, and then changes their answer, the card will be shown again, as the rule no longer applies.

Branching to sections

A section in a survey is a collection of one or more cards that a participant sees at a time.  Think of it as a page.  After answering the questions on section 1, a participant presses the Next arrow and the following section, or page is displayed.

By setting a rule using hide_sections, we can skip entire sections the same way we skip individual cards:

[

{ "expr": { "question_code": "42677", "response_value": "1" }, "hide_sections": [ "2"]}

]

In this case, the whole section will be hidden, which has the effect of hiding both questions in section 2.

Conditions

Conditions, or the IF part of our rule, are how we determine if a particular action is to be performed.  Consider:

{ "expr": {"question_code": "66828", "response_value": "1"}, "show_cards": ["43913"]}

Everything inside “expr”: {…} is our condition. The ‘expr’ (short for expression) format is actually based on MongoDB query syntax.  We read it as:

On question code = 66828, if the response value is 1…

We’ll always want to use a question_code, but the other parts of our condition can change, depending on the card we are using, and what we want to check.

Working with Different Card Types

So far, we have only discussed the Multiple Choice, select 1 card, which uses response_value = 1, or 2 or whatever value we entered when creating the card.

Other card types can have different values that we’ll need to check.  

Yes/No

With yes/no cards, we don’t specify a value|text for each option, we just have a ‘Yes’ or a ‘No’. So we check it like this:

{ "expr": {"question_code": "123", "response_value": "Yes"}, "hide_cards": ["456"]}

Multiple Choice Select 1

As with our first example at the beginning of the guide, we create a value|text set for each option, and then check the response value as part of the value

{ "expr": {"question_code": "123", "response_value": "1"}, "hide_cards": ["456"]}

Multiple Choice Select Multiple (Multi select)

Multi select cards allows for more than one answer to be supplied, and of course, more combinations of answers to be given as well.  This calls for some change, notably the response value is called ‘response_values’ (with an ‘s’), and the values are contained in what is called an Array.  

Arrays are ways to store a set of related answers. While a single response in other cards looks like “1”, an array, assuming just a single answer was given, would look like: [“1”]

As shown in the example below, multiple answers are separated by a comma. More info on multi select changes are described in the Queries section.

{ "expr": {"question_code": "123", "response_values": ["1", “3”]}, "hide_cards": ["456"]}

Queries

Queries are advanced functionality, and are recommended only for use with multi-select cards, and even then only sparingly.

With Yes/No or Select 1 cards, we only have two possible answers: the first one or the second one.  With Multi Select cards, there is no real limit to the number of possible answers, and the number of answer combinations increases with each additional answer possibility.

Consider a multi select with possible values of 1, 2 or 3.  We can have combinations of:

1

2

3

1 and 2

1 and 3

2 and 3

1,2 and 3

And creating one or more rules for each possible combination could get complicated, which is why we use query operators for comparison.  

Supported Comparison Operators

If these operators look familiar, it is because they are based on MongoDB query operator syntax.

$in – Match any of the values specified.

{ "expr": {"question_code": "123", "response_values": {“$in”:["1", “3”]}}, "hide_cards": ["456"]}

Using the example of a multi select with possible values of 1, 2 or 3, the above rule would equate to true if any of the following values were selected:

1

3

1 and 3

However, If 2 were selected, or even 1 and 2, or 2 and 3, then the comparison would equate to false, and the rule would not be run.

$nin – Match none of the values specified.

{ "expr": {"question_code": "123", "response_values": {“$nin”:["1", “3”]}}, "hide_cards": ["456"]}

This rule would run if only 2 were selected, but would not under any other combination.

$all – Match all of the values specified

{ "expr": {"question_code": "123", "response_values": {“$all”:["1", “3”]}}, "hide_cards": ["456"]}

Selecting both 1 and 3 is the only combination that would run the rule.

Actions

So far, we’ve only covered the conditions in which our branching rule will be run. Now, we will discuss the actions to perform when the conditions are met. In other words, the then in our if/then statement

We have gone through examples where we hide cards, and have discussed the possibility to hide sections. We also have the possibility to show cards and sections

"hide_cards": ["456"]

"show_cards": ["123", “789”]

"hide_sections": ["2", “4”]

"show_sections": ["6"]

By default, all cards and sections are shown to the user.  That being the case, we will mostly need to hide cards or sections.  The need for showing cards and sections really only comes up if there is a need for a follow up question to reverse the action of a previous question’s ‘hide’ action.

The cards and sections to be shown or hidden are stored in an Array, which should look familiar after discussing multi-select responses.  This allows for multiple cards/sections to be acted upon for a rule.

Additionally, multiple actions can be applied to a single rule. For instance:

{ "expr": {"question_code": "123", "response_value": "1"}, "hide_cards": ["456"], “hide_sections”[“6”, “7”]}

Hides both cards and sections if the rule’s conditions are met.

Take care when trying to show cards/sections or group multiple actions in a rule. More complex rules provide more possibility for mistakes.

Action Notes

Piping

Piping allows for answer given on a previous question to be inserted, or ‘piped’ into the text of a future question.  Only text information can be piped (we don’t currently support piping things like images, video, or sound).

Notes:

Format

The piping token format is as follows:

[[1234]]

Where the number is the reference code of the answer to be piped.

Optionally, default text can be added in case no answer was given:

[[1234:Default text]]

To add a pipe, simply insert the token in the text where you want the answer inserted.

Example:

Change Log

Description of Change

Date

Version

Update screen shots, clarified examples, changed font to be consistent with the wordpress site, included change log

04-22-2016

v1.3

Original release

07-17-2015

v1.2