Skip navigation
All Places > Survey123 for ArcGIS > Blog > 2015 > August
2015
ichivite-esristaff

Surveys with style

Posted by ichivite-esristaff Employee Aug 23, 2015

Here are 6 quick tips to make your surveys look better using Survey123 Connect for ArcGIS: Thumbnails, Titles, Images, Styles, Label HTML Formatting and Emojis.

1) USING A THUMBNAIL

The thumbnail is important to visually differentiate your surveys in the Survey123 mobile app gallery.  This is particularly important if field crews download more than one survey.

 

How you do this?

 

1- Preview your own survey in Survey123 Connect
2- Switch to the Settings Tab and tap on the Thubmnail image. This will open a browse dialog so you can select a png image. For best results use images 200x133 pixels in size. Remember. for the thumbnail you can only use png files.

 

The thumbnail image is stored in the Survey directory and always has the same name as your Survey. If you go back to the Gallery and your Survey is not displaying the image you selected, close Connect and open it again.

 

2) SETTING A SURVEY TITLE

The survey title shows once it is open. In the next image for example, you can tell that in the Gallery we have a survey named 'Health Facilities Survey'... but when the actual survey is opened, the title reads 'Liberia Health Facility Survey'... Names and Titles are two separate things.

 

caption2

This is done in your excel file. Simply go to the Settings Worksheet and change the form_title cell

caption3

3) USING IMAGES IN YOUR SURVEY

It is not just a matter of making your surveys look good, which is important... images in your Survey can help people make the right calls when filling out information.

For example, say you are creating a Wolf Reporting survey. Well... you will want to make sure people can tell the difference between a wolf and a coyote. You may think you know the difference, but lots of people don't.

Here is an example of Survey123 Connect previewing a Survey where an image will help people make the right call.

 

Wolf

Here is how it was done:

1- Preview your own survey in Survey123 Connect
2- In the toolbar on the side, select the yellow folder button as highlighted in the next image.

3- Now add your images into the media files directory

media

4- Look for the 'media::image' column and reference images placed in the media folder by name.  Be aware that iOS devices are case sensitive!

coyote

By now you will notice that you can also add audio files to your Survey too. Simply use the media::audio column. You can associate images and audio with questions, groups and notes in the survey worksheet. You can also associate them with choices in the choices worksheet with results as in the next screenshot.

bird

4) USING STYLES

Styles help you control the colors of basic elements in your Survey. The Style tab can be found under Settings.

 

Untitled

Have fun with this...

 

Untitled

5) LABEL HTML FORMATTING

 

I saved the best for last! You can use HTML formatting to highlight words in your questions, display warning notes as red and much more. Here is one example where we use a note to hint that values in questions above are not adding to 100. Note that we use HTML formatting to display the warning in red.  We also bold some words in the questions.

 

HTMLFormatting

Here is a list of common HTML tags supported in Survey123:

 

 

<a href="http://www.esri.com">Link to esri web site</a>

<a href="tel:9093624397">Call Esri</a>

 

<font color="red">Text in red</font>

<b>This text is bold</b>

<i>This text is in italics</i>

<H1>Header 1</H>

<H2>Header 2</H>

Add a line break<p>into a label

<center>This text is centered</center>

<blockquote>Blockquote (indented)</blockquote>

<u>underlined</u>

<tt>typewrite</tt> font

<s>strikethrough</s> font

<ul><li>Unordered list,</li><li>with two items</li></ul>

<ol><li>Ordered list,</li><li>with two numbered items</li></ol>

 

6) Emojis

 

I bet you did not know this one. You can use emojis in your forms. In the example below, I took weather emojis from EmojiMedia and pasted them into the Labels of choices in a select_one question.

 

Last updated July 24, 2018

 

When you create a new survey using Survey123 Connect, a new feature service is created on the fly on your behalf. Some of you wonder how the different XLSForm types of questions in your form are mapped into esri field types in the feature service.   In this post I will describe how XLSForm types are mapped into esri fields by default, but we will also describe how you can take control and tell Survey123 how to best do the mapping and even add fields in the database that are not shown as questions in your form.

 

Default mappings:

 

The type of XLSForm question is defined in the Type column in your Choices worksheet. Here are the default mappings to esri field types.

 

XLSForm Question

Esri Field Type (default mapping)

integer

esriFieldTypeInteger

decimal

esriFieldTypeDouble

text

esriFieldTypeString

select_one

esriFieldTypeString

select_multiple

esriFieldTypeString

note

Not applicable

geopoint

esriFieldTypeGeometry (point, WGS84, 4326)

geotrace

Not implemented

geoshape

Not implemented

date

esriFieldTypeDate

time

esriFieldTypeDate

dateTime

esriFieldTypeDate

image

Attachment

audio

Attachment

barcode

esriFieldTypeString

video

Not implemented

calculate

esriFieldTypeString

acknowledge

Not implemented

 

Controlling mappings:

 

Survey123 Connect v.1.0.1.135 and newer include support for the bind::esri:fieldType and bind:esri:fieldLength columns in the survey worksheet.  Adding values in these columns is optional, but extremely useful when you want to control exactly the type of field to be created in ArcGIS for your survey questions.

 

Some question types are a no brainer. For example, if you have an integer or decimal question, Survey123 Connect will automatically translate them into esriFieldTypeInteger and esriFieldTypeDouble respectively.  You will probably not want to overwrite that behavior.

 

However, select_one questions are trickier. Up until v 1.0.135 Connect would always map select_one questions as esriFieldTypeString. If you happen to use a choice list that stores integers then you will want to be explicit, and force your select_one to be mapped into a geodatabase column of type integer.

 

The same applies to other questions such as select_multiple and calculates. So far Survey123 Connect would always map them to esriFieldTypeString columns, but now you can have more control.

 

The list of values supported in the bind::esri.fieldType column are:

  • esriFieldTypeString  
  • esriFieldTypeDate    
  • esriFieldTypeIntegerr
  • esriFieldTypeSingle
  • esriFieldTypeGUID
  • esriFieldTypePointZ
  • esriFieldTypeDouble
  • null

 

One important warning is that Survey123 Connect will not be able to validate your choices. For example, if you have a calculation expression that returns a string and you set the calculate question to esriFieldTypeInteger… well… things will not go well when the end user tries to submit the data.  The same applies to select_ones: say that among all your choices one of them is a string and you mapped the question to esriFieldTypeInteger… that is a perfect recipe for a disaster because ArcGIS will not be able to cast the selected string into an integer value.

 

The null value was added in version 2.4 and allows you to add a question to your survey that has no representation in the feature service. There are multiple scenarios where this could be handy. For example, say you want to ask for the year in which a building was built (date type of question with a year appearance), but you want to actually store the age of the building. Well, then you set the yearbuilt question as null in the esriFieldType column, and then you use a hidden type of question with a calculation to persist in the feature service the age.  Check out The Power of Nothing blog post for a more detailed discussion on the null type.

 

The second column that Connect now supports is called bind::esri:fieldLength. This column is useful to restrict the length of fields as you can imagine.  It really has a double effect. First, it sets the maximum length of the field in the geodatabase, but additionally, it will limit the number of characters that the user will be able to input in the question. For example, say that you want people to input a US ZIP code. We know that ZIP codes are made out of 5 numeric values. So if you set the length of the field to 5, then users will not be able to input 6 or more characters in the app. You may also want to use bind::esri:fieldLength to expand the number of characters allowed in a text question. By default text fields are mapped into esriFieldString columns with 255 characters, but what it you want users to enter up to 1000? You would simply set the value in this column to 1000.

 

The bind:esri.fieldLength column is optional as well and makes more sense to use when using questions that will be stored as esriFieldTypeInteger , esriFieldTypeString  or esriFieldTypeDouble.

 

Adding columns without adding questions in the form:

 

Say you want to add fields in your feature service, but not show them in the form. Say, even, that you want to add fields and put values in them without the user having to do anything.

 

There are a few techniques for this:

 

  • Calculate: You can use a calculate type of question. Calculate questions are never shown in the form, but we will create a field in the feature service for them. A calculate always requires you to set an expression in the Calculation column.  The advantage of calculates is that you can pre-populate values and these values can be dynamic depending on answers in the form. By default, all calculates are mapped as esriFieldTypeString columns, but you can use the bind::esri:fieldType column to use your own mappings.
  • Hidden: Like calculates, it is a type of question. Hidden questions are in fact very close to calculates, except that they do not require you to fill the calculation column. You could for example leave the value of the field blank, or use a default.  Like with Calculates, Hidden questions are by default mapped to esriFieldTypeString, but you can overwrite that.
  • Relevant: Use a relevant expression that always evaluates to false and your question will not show up in the form. However, Survey123 will always create the corresponding field in the feature service. This is easy to do, but has two disadvantages: you cannot pre-populate values in the field and it adds an overhead to the form because we need to evaluate the expression in the relevant column.  One unique use case that you can satisfy with relevant expression is when you want to create a new field and associate a coded value domain with it in ArcGIS. In this case, using a relevant is your only choice. Lets be clear, this is a hack. A bad hack!

 

When using a Calculate or a Hidden question, the bind::esri:fieldType column described in this post will come very handy.  Even when using relevants, setting your own mapping may make sense when using Select_One questions.

Who is capturing data?


Survey123 will always store the username used to capture data. This is achieved through Editor Tracking, which is enabled by default in every Survey you publish.  We use this information to generate the Participation charts in the survey123 web site, but you can also look at who created an individual entry by simply looking at the attribute table (Data Tab in the survey123 web site)

 

If someone in your organization were to edit the data submitted after the fact, the Editor field will reflect the name of that person as well. You will know who captured the data in the field and who, if anyone, edited the data once submitted.  The Edit date field also comes automatically and refers to the time when the data was edited.

 

If you are interesting in capturing the email of the person that submitted the data handy, you can also add in your form a question of type email as described in the metadata section of the XLSForm help.

 

 

When is data captured? 

 

This one is a bit tricky. When you enable Editor Tracking, ArcGIS will keep track of when the data is received. Although we hide the field in the Survey123 web site, you will be able to see that field if you load the survey data (the feature service) into ArcGIS Pro, or the ArcGIS Map Viewer in your browser. But do not get fooled: the Creator_Date field will not tell you when the data was captured… it simply tells you when it made it into ArcGIS… when it was written into the feature service.

 

If you really want to know when the data was captured, you will need to add a new type of question into your survey spreadsheet. This question will actually not be visible to the end user. The XLSForm spec describes it as part of the Metadata section of your survey and is called ‘start’.

 

It is actually quite simple: just add a start question as in the next screenshot:

 

 

You can add this question at the beginning, the end or pretty much anywhere in between. Again, the question will actually not show up in your form… but the survey123 app will capture the time when the user started the survey and that bit of information will be persisted when submitted. If you use the question type ‘end’, we will always capture when the user finished the survey.  Having both can be useful if you want to measure how much time it took to fill out the form.

 

When using the start and end type of questions, your feature service will immediately become time-aware. Simply take your survey data into the ArcGIS.com Map Viewer and a slider bar will show at the bottom so you can animate data over time.

 

 

 

 

Where is data captured?

 

By now you know that you can add geopoint questions to your survey. By default the Survey123 app tries to capture the location of your device. If your device in fact provides a location, it will be used as the default location. Typically, a user can overwrite that location by tapping on the map.   Sometimes you may not want the end user to be able to change the location and go with what the device provides.  If that is the case simply flag the question in your spreadsheet as readonly.  The map control will still show up, but the user will not be able to move the location.   Alternatively you may want to decide to hide the map control all together. That is possible too… simply create a survey with no geopoint questions at all.    Survey123 will still capture the location for you… if provided by the device.

Formulas supported in Survey123 include the following operators:

 

SymbolFunctionExample

+

Addition

2 + 2

-

Subtraction

2 - 2

*

Multiplication

2 * 2

div

Division

2 div 2

=

Equal

.=10

!=

Not equal

.!=10

<

Less than

.<10

<=

Less than or equal to

.<=10

>

Greater than

.>10

>=

Greater than or equal to

.>=10

or

or

.=10 or .=20

and

and

.>10 and .<20

 

Formulas can be used in Survey123 when building your forms in the following columns:

 

Constraint

Adding a constraint to a survey question will restrict the accepted inputs for a response. This could include a specific range of numbers, combinations of letters and numbers or general pattern matching. In your spreadsheet, the constraint expression is entered into the constraint field and helpful text is entered into the constraint_message field. In the constraint expressions, the input for the question is always represented by a full stop.

For example, the following formula can be used to restrict the input of an integer field to positive numbers only:

 

.>=0

 

Regular expressions can also be used for pattern matching to constrain valid responses. This regular expression can constrain the input of a string field to a well-known email address format:

 

regex(., '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,4}')

 

See here for more information on regular expressions...

See here for more information on using constraints...

 

Relevant

A question, or a sets of questions, can be hidden and revealed based on previous answers using relevant expressions. These expressions are entered into the relevant column and the answers to previous questions are always referred to as follows: ${field_name}. You can apply a relevant expression to a single question, or group questions together and set the relevant expression for the entire group. For example, this expression will reveal a question if the answer to the previous question is true:

 

${previous_question} = 'true'

 

This example will hide questions if the answer to the previous question was greater than 100:

 

${previous_question} <= 100

 

This example combines multiple operators and questions:

 

${previous_question} + ${other_previous_question} <= 100

 

When using mathematical operators, be aware that sometimes you may need to cast values into numbers. In the previous examples we assumed that previous_question and other_previous_question where integers or decimals... but what if the question types were strings? Then you cast them as follows:

 

int(${previous_question}) + int(${other_previous_question}) <= 100

 

See here for more information about using relevant clauses...

 

Calculations

Calculations are performed in the calculation field of a question. Calculations are often associated with calculate type of questions, but can also be applied to integer, text etc type of questions. The outcome of the calculation can be used to populate relevant or constraint expressions by referring to the field name of the calculate question. They can be used to hold values that do not need to be displayed on the form, but are included in the feature service.

 

For example, you can create a question of type calculate and name it calc, then insert the following expression int its calculation column:

 

${question_1} + ${question_2} + ${question_3}

 

And then use the result to set the relevance for the next question:

 

${calc} <= 100

 

See here for more information on calculations...

ichivite-esristaff

Signatures!

Posted by ichivite-esristaff Employee Aug 23, 2015

With Survey123 for ArcGIS you can configure smart forms to capture signatures. This feature is supported  in the Survey123 field app, allowing you to add a handy signature pad. Once a signature is captured, it will be stored as an image attachment in ArcGIS.

To add a signature question into your form, you need to use Survey123 Connect or ArcGIS and author your survey using an XLSForm file.  Add an image question and set the appearance to signature as shown in the screenshot below.

 

 

You can add one or more signature questions into your form. You can in fact even add signature questions within repeats.