Updated XLSForm templates for Survey123
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.
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).
- 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: guidance_hint*, body::esri:visible*, body::esri:inputMask, label::language (xx), hint::language (xx), guidance_hint::language (xx)*, body::accuracyThreshold, bind::esri:warning, bind::esri:warning_message, and bind::saveIncomplete. Columns marked (*) are new in 3.12.
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
| survey | Contains all questions, calculations, appearances and other features that make up your survey form design. |
| choices | Choice lists for multiple choice questions (select_one and select_multiple) are stored here. |
| settings | General settings for your survey, like form title and instance name. |
| Version | Information 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 types | List 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. |
| Appearances | List 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 types | List of Esri field types and form bind types you can use in the bind::esri:fieldType and bind::type columns on the survey sheet. |
| Reference | Useful reference information for functions, operators, HTML formatting, and regular expressions. |
| Reserved | A 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:
- You can specify the title that appears in the header at the top of your survey form in the form_title column. We've added a placeholder title of "Survey title not set". Replace this text with your desired title.
- It's recommended to set an instance name for your survey in the instance_name column. The instance name uniquely identifies survey responses in the Inbox, Outbox, Sent, and Drafts. To learn more about instance names, see this blog post https://community.esri.com/groups/survey123/blog/2017/04/24/understanding-the-instancename-setting and refer to Instance name—ArcGIS Survey123 | Documentation.
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:
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:
- 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).
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.