Understanding Notes in Survey123

11-14-2017 02:54 AM
Esri Frequent Contributor
8 12 9,412

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.


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.


note Play this audio before counting <i>Gubernatrix cristata</i> callsgcristata.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.


calculatespeedSpeed 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.


select_multiple violationsviolationsCode Violations 
note Violations observedcount-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:


select_multiple violationsviolationsCode 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.

Tags (3)
New Contributor II

Hi Ismael Chivite‌!

How would you do a calculation Note that pulls the responses from a repeated group?

Not, or not limited to, sum() count().... More like a summary/digest of some of the fields in all responses in a repeated set of questions.



New Contributor III

Is there any possibility of allowing notes to have name values without Connect trying to add fields for each one? I've found it very useful on several surveys to name them for easy identification when writing/editing. It's particularly useful when there are several conditional notes that include a lot of html formatting, making them hard to quickly read and identify at a glance in the spreadsheet. Should I just start marking every named note "null" in the bind::esri:fieldType column, or give up trying to include a quick identifier in the name field altogether?

Esri Esteemed Contributor

Hi Nick,

Yes, if you want to provide a quick identifier for the note, set the fieldType to null to prevent field creation.

New Contributor II

Hi James‌!,

Do you have any idea on how to deal with my previous question?

I need to insert a Note with the individual responses (to some fields) from a repeated set of questions...

Best regards,


Esri Esteemed Contributor

Hi Luciano,

What are you looking for in terms of a summary digest?  In general, you are limited to what you can generate with aggregation functions (sum, count, min, max), so it sounds like it might be a bit beyond the current calculation capabilities.

New Contributor II

Thanks James!

Yes, that is what I need.... Unfortunately, I think I've hit a wall here.

Thanks again,


New Contributor


Do you know of any examples of municipalities in North America using Survey123 for census enumeration. Can you point us to a case study or example configuration?

thank you.

New Contributor II


Is it possible to use HTML code to create an email link so people using the survey can click the link and it opens their email application with an auto populated subject and to field.This is so feedback about the survey can easily be submitted.

Thanks ahead of time!

Esri Esteemed Contributor

It's quite possible to make a link - look at mailto - Wikipedia for how to construct the link properly.

Occasional Contributor III

Hi James Tedrick

I looked at the Wiki page, but am running into an issue using the below in a calculate for a note:

concat("<a href='mailto:Andrew.Hargreaves@xxxxxxx.com", "?Subject=", ${AGO_USER}, "%20needs%20help%20",  "%20'%20", ">CLICK HERE TO EMAIL ANDREW DIRECTLY</a>")

For your info ${AGO_USER} is a note calculated using 'property('username')'. I keep getting told:

Any advice is gratefully received.


Occasional Contributor II


Your note example above has bullet points to assess fire severity.  How did you get bullet point in the note...I am having trouble emulating that.



Esri Esteemed Contributor

Hi Chris,

Ismael used the HTML unordered list (<ul>) to format the list.