Updated XLSForm templates for Survey123

1780
1
08-06-2020 06:36 PM
Esri Regular Contributor
7 1 1,780

The XLSForm templates for ArcGIS Survey123 have been updated with a fresh new look in version 3.10. The new templates are available in Survey123 Connect in the New Survey dialog under Templates.

XLSForm templates in the New Survey dialog in Survey123 Connect

It's important to note that your existing XLSForms will continue to work as normal! This blog post provides an overview of Survey123's templates and what's new in 3.10, as well as some best practices for working with the templates. But first, a quick XLSForm recap...

 

XLSForm and Survey123

 

Survey123 is based on XLSForm, a standard specification for authoring survey forms. Survey123 Connect takes an XLSForm and converts it into a format that respondents can fill out. Surveys authored in the Survey123 web designer also rely on XLSForm; when you publish a survey in the web designer an XLSForm is created automatically behind the scenes.

 

An XLSForm can be any .xls or .xlsx file that satisfies the minimum XLSForm requirements. For more information on the required sheets and columns, refer to XLSForm essentials—Survey123 for ArcGIS | Documentation. Beyond the required sheets and columns, the Excel file can include any other worksheets you like. You can also change the formatting on any of the sheets (for example, cell shading or font size) and remove any unused columns (with the exception of the required columns) without affecting the function of the XLSForm. So long as the right values are in the right columns on the right sheets, your design should convert to a survey form in Connect without issue. While it's possible to make your own XLSForm from scratch, Survey123's templates provide everything you need to get started with your survey designs.

 

The templates you download in Survey123 Connect are designed to help you conform to the XLSForm specification. The templates contain the required sheets and columns, and include data validation rules and drop-down lists to help you fill out your XLSForm correctly.

 

While we've progressively added new columns, question types and appearances to the template with each release of Survey123, we thought it was time to give the look and feel of the templates a refresh and also introduce a new Standard template.


What's new?

 

Prior to version 3.10 Survey123 had two templates: Advanced and Basic. At 3.10, Advanced has been updated and Basic has been replaced by Standard.

 

Advanced template

 

The updated Advanced template is very similar to the previous one, in that it includes all of the XLSForm question types, appearances, and columns supported in Survey123. Here are the key changes to the new version:

 

  • The types worksheet has been replaced by a set of six supplementary sheets (more details in the worksheets table, below).

 

Excel worksheet tabs in the updated XLSForm templates

 

  • Columns on the survey sheet have been rearranged into a more logical order. The most commonly used columns are closer to the left of the worksheet, where they're easier to access. Because the order of columns has changed, please take extra care when migrating existing surveys to the new template (see more on this, below).
  • Colours, fonts and styles have been refreshed to give the template a more modern look and feel. Arial is so 2004!
  • In the drop-down for the type column on the survey sheet, the square brackets around "list_name" for select_one select_multiple questions have been removed. These brackets should not be included when specifying the list name, and their inclusion in the previous templates was the source of some confusion! As an example, to use a choice list named "fruits" for a select_one question, enter select_one fruits in the type column.

 

Standard template

 

The new Standard template replaces the Basic template, which was deemed to be, well, a bit too basic! The Standard template is essentially a "cut-down" version of the Advanced template that includes only those question types and appearances that are supported in both the Survey123 field app and Survey123 web app. The Standard template is useful for surveys intended to be used in both apps, where you want a comparable experience in the field app and on the web.

 

Some columns have also been omitted to further simplify the Standard template. The language columns have been removed from the choices and settings sheets and a handful of the more specialised columns have been omitted from the survey sheet, as follows: body::esri:inputMask, label::language (xx), hint::language (xx), body::accuracyThreshold, bind::esri:warning, bind::esri:warning_message, and bind::saveIncomplete.

 

Worksheets

 

The following table outlines the contents of each worksheet in both the Advanced and Standard templates. The green shading denotes a required XLSForm sheet and the blue shading denotes a new supplementary sheet:

 

Worksheet Description
surveyContains all questions, calculations, appearances and other features that make up your survey form design.
choicesChoice lists for multiple choice questions (select_one and select_multiple) are stored here.
settingsGeneral settings for your survey, like form title and instance name.
VersionInformation about when the template was last revised. In the Advanced template, the compatibility information on the Question types and Appearances sheets might change with each revision, so it's important to refer to the revision date to determine the currency of this information.
Question typesList of question types you can use in the type column on the survey sheet. In the Advanced template, columns C and D indicate if the question type is supported in the field app and web app, respectively.
AppearancesList of appearances you can use in the appearance column on the survey sheet. In the Advanced template, columns D and E indicate if the appearance is supported in the field app and web app, respectively.
Field typesList of Esri field types and form bind types you can use in the bind::esri:fieldType and bind::type columns on the survey sheet.
ReferenceUseful reference information for functions, operators, HTML formatting, and regular expressions.
ReservedA list of reserved keywords that cannot be used in the name column on the surveys sheet.

 

Settings worksheet

 

Two things to note about the settings worksheet:

 

 

Best practices

 

Here are some best practices for getting the most out of the Survey123 templates and avoiding common headaches. For a more detailed resource of excellent Excel tips, see Ismael Chivite's blog post https://community.esri.com/groups/survey123/blog/2019/09/15/survey123-tricks-of-the-trade-microsoft-....

 

  • Do not modify the contents of the supplementary sheets. These sheets contain tables and named ranges that are used in the data validation on the survey and settings sheets, so it's best to leave them alone.
  • When copying and pasting cells or rows, always use the paste values option to preserve data validation:

 

Paste values in an Excel worksheet

 

This is especially important when copying cells or rows from another workbook; unless you paste the values only, you will likely retain a link to the data validation in the other workbook, which can lead to errors:

 

Warning message for links in Excel workbook

 

  • If you're a dab hand with XLSForm you can simply remove the data validation if it's annoying you. Survey123 Connect will validate your form as it's updated, so your syntax will be checked in any case. To remove data validation in Excel:
    • Select a cell, range, row or entire sheet.
    • On the Data ribbon, click Data Validation.
    • Click the Clear All button to remove all data validation rules for the selected cell(s).

 

Clear data validation in Excel

 

Migrate an existing survey to a new template

 

While using the new templates is not essential, you might want to update an existing survey to the new look and feel. Here are some tips for migrating an existing survey to the new template:

 

  • Download a template from one of the following links: Advanced or Standard.
    • Alternatively, create a new survey in Connect to get a copy of the template.
  • In your existing Excel file, column-by-column, copy the contents of the survey, choices and settings sheets and paste into the corresponding column in the new template. As mentioned, the column order has changed so a straight copy-paste of the entire sheet isn't going to work. Remember to use the paste values option!
  • If your survey uses external selects, copy the external_choices sheet from your existing Excel file to the new one using the Move or Copy Sheet command. The contents of the external_choices sheet should remain unchanged.
  • Replace the existing .xlsx file in the survey's folder in your C:\Users\UserName\ArcGIS\My Survey Designs directory with the new version, ensuring the file name is identical to the original.
  • Republish your survey.


For those with a keen eye, here's a list of other changes:

 

  • Added the file question type, which is supported in the field app as of 3.10.
  • Modified the data validation rules in places to make it more user-friendly.
  • Removed the yellow input messages (tool tips) on the survey and choices sheets.
  • Example select_one question added to survey sheet.
  • A new allow_choice_duplicates column has been added to the settings sheet. This column doesn't do anything yet, but it will become useful in a future release of Survey123. It can be disregarded for the time being.
  • All of the samples in Connect have been updated to the new Advanced template.

 

We hope you enjoy the new templates and look forward to your feedback! Please leave a comment below, or drop us a line at survey123@esri.com.

1 Comment
Occasional Contributor II

The Standard template is a huge improvement over the Basic template - will check out the other items as time allows, too. Thank you!