Understanding Notes in Survey123

[IsmaelChivite]

Surveys are for the most part about questions, but often you need to provide some context before users can actually give you a good answer. And that is where notes come into play.

Notes allow you to insert text and images in between questions in your Survey123 smart form

Here are the main three reasons why you may want to use notes in your form:

1. Information: Notes are useful when you want to provide users with information that will help them capture data more appropriately. In an invasive species survey, for example, a note could warn the user that the inventory should be performed in a radius of 100 meters from a given sampling point. In a population census enumeration survey, notes can also include certain tips for the enumerator to introduce questions to respondents. 
2. Warnings: Notes can be used to warn users about inconsistencies in the data captured, before it is  submitted. For example, if we do not want people to capture the location of an observation while on the move, we can make a warning note visible whenever we detect that the geopoint object has a speed larger than 0 meters per second. We could also use a warning note if we detect some  logical inconsistencies in the captured data.  Of course, we could use constraints in Survey123 to prevent all this bad  data to be submitted, but notes provide a nice way to bring the user's attention into these  problems early.
3. Look&Feel: Finally, notes are a great way to display banners and logos into your form to make them look exactly as you want.

The Basics

The use of notes is supported in both the Survey123’s web designer as well as Survey123 Connect. The easiest way to create a note is to use web designer, where you can easily format your text using custom font sizes, colors, bullets for your paragraphs and even embedded images and links. You can also control the alignment of your text in the notes: centered, right aligned and left aligned.

Here is how you can add notes to your survey in Web Designer:

Notes in XLSForms

In XLSForms, notes are modeled as a note type of question.  The most important rule when using notes is that they do not require any value in the name column of your XLSForm. That is right: unlike other types of questions in XLSForms, the name column is not mandatory. In fact, it is typically better that you leave it empty.

The reason for this is simple: When you publish a survey with Survey123 Connect, the values in the name column of the survey worksheet define the attribute columns in the feature layer where we will persist your data.  Since notes do not expect any user input, there is no need to  give them a name.

Other than the above, notes behave like most other XLSform questions:

• HTML formatting is supported in notes. You can use  HTML formatting for way more than cosmetic reasons. You can for  example add links. In the next example, I added a link that will trigger a phone call to the Water Department.

type	name	label
note		<center><a href="tel:9091234567">Call Water Department</a></center></p>

• Media: You can associate media to a note question. Use the media:audio and media::image columns for this. In the next example, a note is used to allow the user to play an audio file from the survey.  Images and audio files referenced must be stored in the media folder of your survey.

type	name	label	media::audio
note		Play this audio before counting <i>Gubernatrix cristata</i> calls	gcristata.mp3

• Relevant: Relevant expressions can be used to make notes appear and hide. In the next example, A warning is shown to the user if the location is fixed while on the move. When adding warnings, I like to use HTML formatting to display the notes in red or other color.

type	name	label	relevant	calculation
geopoint	location	Location
calculate	speed	Speed		pulldata("@geopoint", ${location}, "speed")
note		Do not move while fixing location!	0.2 < ${speed}

• Calculations: You can use calculations to display text in the main body of a note. In the following example, a note is used to indicate the number of choices selected in a select multiple question.

type	name	label	calculation
select_multiple violations	violations	Code Violations
note		Violations observed	count-selected(${violations})

When calculating a note, you may want to have  your text all be shown in one single line, rather  than split in two like above. If that is the case, you can do something like the following:

type	name	label	calculation
select_multiple violations	violations	Code Violations
note		</b>	concat("Violations: ", count-selected(${violations}))

The only reason I use </b> in the label is because the label column is mandatory for a note. <b> will not render any text, so the main body of the note will read a a single  line of text, which is what  I want.