Skip navigation
All Places > ArcGIS Survey123 > Blog > 2019 > September

According to The Hobbit and The Lord of the Rings trilogies written by J.R.R. Tolkien, Bilbo and Frodo were born during the Third Age in the years 2890 and 2968 (of the Shire calendar) respectively. Translated to our Gregorian calendar, Bilbo was born in 1290 and Frodo in 1368. Bilbo and Frodo share the same birthday on September 22 and that makes this day a very special one: Hobbit Day.


Go back?” he thought. “No good at all! Go sideways? Impossible! Go forward? Only thing to do! On we go!”
Bilbo Baggins, The Hobbit, Riddles in the Dark.


Survey123 version 3.6 is now available to all, even the Elves!


Critical fixes


This update includes over 30 critical bug fixes in the Survey123 web app and field apps. An area or particular focus has been ensuring a more correct and consistent behavior of your XLSForm expressions. For example, dealinig with relevant statements and submitted data. The general rule is that data should not be submitted from non-relevant questions. That is, the output of your calculations or default values set, will never be sent to ArcGIS for questions where the relevant expression evaluates to false. In addition, with this update relevant statements apply to hidden and calculate questions. Thus, the use of relevant expressions is reinforced not just as the means to hide questions, but also to better control what data is submitted to the target feature layer.


You will also find a list of device-specific fixes in this release. Barcode scanning capabilities have been greatly improved on Android devices, as well as other improvements to keyboard and input behavior. Others fixes relate to the new iOS 13 update, which introduced some changes affecting the Survey123 field app.


A list of critical BUGs (and relevant enhancements) addressed in this release can be found at the end of this doc.



Lines and polygons


You can now work with line and polygon GIS features within the Survey123 apps. This is possible through the new geotrace and geoshape XLSForm question types, which you can incorporate into your surveys through Survey123 Connect for ArcGIS.  


Geotrace and geoshape questions are similar to geopoint questions in that they are shown in your form as a map. The only difference is that with geotrace and geoshape you can create and update lines and polygons respectively.


Support for geotrace and geoshape is available in both the Survey123 field and web apps. That is, you can work with lines and polygons from a web browser and also from the native app. The website has also been updated so you can view, filter, analyze and even create feature reports with line and polygon data.


There is quite a lot to know when working with lines and polygons in Survey123. You can find more details in our Survey123 Tricks of the Trade: Lines and Polygons post.





Single choice grid in the field app


We introduced single choice grid in the Survey123 web designer and the web app at version 2.8. We are now expanding support to Survey123 Connect and the field app. Single choice grid allows you to compact series of choice list questions, reducing the need for end-users to scroll up and down the form. They can also help you make your forms more easily readable. The key to using single choice grid is a sequence of more than 2 or 3 questions sharing the same list choices. In XLSForm jargon: A sequence of select_one questions sharing the choice list. This new appearance is ideal when you plan on using forms with a tablet, although keeping labels short and choices limited can give you good results even in smart-phones.


In the next animation you can see a single choice grid compacting a set of 5 building condition questions. Note how the choices are labeled just once for the entire set. 



In XLSForm, you can add a single choice grid by simply enclosing your select questions within a group and setting the appearance of the group to table-list.


begin groupassessment_groupReport building conditiontable-list
select_one evaluationassess_collapseCollapse
select_one evaluationassess_leaningBuilding leaning
select_one evaluationassess_structuralStructural damage
select_one evaluationassess_fall_hazFalling hazards
select_one evaluationassess_group_movGround slope movement
end group


Please note that groups using the table-list appearance will take the whole width of the form when your form uses the theme-grid style.


Feature report enhancements


Survey123 feature reports allow you to create high quality printable documents from your Survey123 data. The layout, content and look and feel of your reports are defined in a Microsoft Word document template. For a basic introduction to Survey123's feature reports, refer to the Understanding Survey123 Feature Reports blog post.



This update includes a few refinements to the feature report syntax. You can now:


  • Control how many decimals should be shown in a number.  ${myNumber | round:2}
  • Extract the elevation of a geopoint question. ${myGeopoint | getValue:"z"}
  • Get the x/y coordinates of a geopoint in a particular spatial reference: ${myGeopoint | getValue:"x":26865}.


The template syntax validator has also been improved to handle some logical errors that were not handled before.  In the past, these invalid expressions would pass the syntax validation and then be ignored at run-time.  Starting with this release, you will get a validation error when you attempt to upload the template. For example, the following expression is incorrect:

${if image_field_1 | getValue:"size">0}

A parenthesis should be added as follows:

${if (image_field_1 | getValue:"size")>0}

Or alternatively, you could use:

${if image_field_1}

Another common syntax error is as follows:

{if choiceQuestion1="choice1"}

The equal sign above is used as an assignment. A double = sign should be added  for a comparison:

{if choiceQuestion1=="choice1"}

A side effect of this more strict template syntax validation is that existing templates you may have uploaded will start triggering 'parsing errors'.


The complete feature report syntax is described at: Feature report templates—Survey123 for ArcGIS | ArcGIS 


If you happen to be using Survey123 web hooks and Integromat with ArcGIS Enterprise, you will notice that you can now configure the Survey123 Integromat module to create Feature Reports with your own ArcGIS Enterprise instance.


Finally, be aware that coinciding with the upcoming ArcGIS Online update in October 2019, each feature report generated will consume 2.5 ArcGIS Online credits. Refer to Understanding Survey123 Feature Reports for more information.


Note to ArcGIS Online users: Coinciding with the upcoming ArcGIS Online update in October, Survey123 Feature Reports will consume ArcGIS Online credits.



Web form view-only mode


In most cases, you want to use a Survey123 form to help people capture data. Using web form URL parameters, your survey can be launched with some predetermined responses. You can also use URL parameters to load data from existing records into a survey and let people update that information. With this update, you can also open a survey in read-only mode. This can be done in two steps:


  • Go into the Collaborate tab in the Survey123 website and share your survey results (Viewer tab) as appropriate.


  • Build a URL setting the mode parameter to view, and pass the objectid of the record you want to display.

If you get an error like shown below, make sure  you share your survey results through Collaborate as described in step 1 above.



As the mode=view parameter is only introduced with 3.6, you will need to republish old surveys to take advantage of this feature with them. Alternatively, you could also add the version=latest parameter to dynamically upgrade your survey when it loads in the user's web browser. However, it is generally best to republish the survey with the latest version.


Extended XLSForm support in the Survey123 field app


With this update, we are introducing a handful of very specific enhancements to our XLSForm support in the Survey123 field app. These new features are currently not supported in the Survey123 web app. Demand for these types of capabilities is much more general among Survey123 field app workflows, so we are introducing them in that context exclusively for now.



Range question


The range question is designed to restrict integer or decimal user input to a well defined range. If you setup your survey on top of an existing feature layer, range questions are a perfect fit for fields with a range geodatabase domain. Range questions display in your form as a horizontal slider, ideal for touch screens, although when the control has the focus you can also change its values using the left and right arrow keys.


In the screenshot on the right, you can see a range question being used to help users document pH values on a water sample. Values can be easily set between the pH range of 0 (acidic) and 14 (alkaline).


Through the XLSForm spec, you can dictate different aspects of the slider such as the minimum and maximum accepted values and the colors of the control. Like other XLSForm questions, you can apply calculations, data validation constraints, default values, etc.


Check out the Range help topic for more details.



Custom height for signature, text (multiline), and geo questions


You can now set a custom height for multiline text, signature and geo (geopoint, geotrace, geoshape) questions. This is particularly helpful when you arrange multiple questions in a single row using the theme-grid style, allowing you to adjust the height of different controls to keep your design more symmetric. In the case of text input, expanding the default height also helps signifying to the end-user that large amounts of text can be inputted.


The height is set using the body::esri:style column, which has been added to the far right of the XLSForm survey sheet. You can also manually add this column to old XLSForms you may have.




The height value unit is expressed as lines by default, where a line is the height of the current input text font. Alternative units include % (height=25%), where the height is calculated as a percentage of the current window height, and pixels (height=300pixels). Remember not to add spaces between the unit and the value!


Pictorial lists


There are a few common ways to represent a list of choices: a drop-down list, horizontally, vertically... etc. Carefully choosing the best style for a list, is important. A horizontal arrangement is a good choice for short lists, reducing the need for users to scroll the form up and down. Vertical lists present options in a very clean way, but if you have many choices, a drop-down list will save users time, particularly if you enable auto-complete.


There are some cases, where a pictorial representation of a list is by far the best option. Brett Stokes put together a nice collection of examples, which you can see in the animation below. In all these examples, making selections over the images comes more naturally than making the selection over a traditional list of choices. It is more intuitive, can be less prone to errors and quicker for the user to make their selection.



To learn about including selectable images in your smart form, refer to the Using the image-map appearance in Survey123  post by Brett. Well worth a read!


Critical fixes and minor enhancements


Survey123 Field app (XLSForm support)


  • BUG-000097105 Default values are present in fields that are not relevant.
  • BUG-000124014 Non-relevant repeats are being submitted with values, if the default values or calculations are applied within the repeat.
  • BUG-000123547 Unable to calculate geopoint locations when repeating a survey in the same survey form.
  • ENH-000123296 Hidden and Calculate fields should support relevant expressions.
  • ENH-000105822 Provide ability to create surveys using geometry types other than points in Survey123 (lines, polygons).
  • BUG-000124284 Survey123 Connect for ArcGIS 3.5.x and Survey123 Field App 3.5.x do not hide questions accurately if a relevant column value is calculated on a complex pulldata expression.
  • BUG-000124360 When manually entering Lat/Long for a geopoint location on a 'repeat' question, the 'device location' preview window does not show the device's location until the second repeat and onwards.
  • BUG-000124121 If the spatial filter is enabled for a survey with a 'Query expression' in the 'Inbox Filter', records are omitted even if the records are within the map extent before clicking Refresh.


Survey123 Field app (device specific issues)


  • BUG-000125295 The Survey123 Field App freezes/crashes when attempting to attach an image from the local device on iOS 13.1 Beta.
  • BUG-000121080 Barcodes cannot be scanned in the Survey123 application on Samsung Galaxy Tab E.
  • BUG-000123872 Survey123 Field app crashes upon launch on Android 5.1.1.
  • BUG-000123228 The keyboard of Android devices with 5.2 inches or lesser screen size disrupts the Survey123 for ArcGIS app sign in page.
  • BUG-000123572 Unable to connect error in Survey123 Field App 3.5.164 on iOS 12.3.1 device when Allow Location Access setting is set to "Never" or "While Using the App".
  • BUG-000115243 The final page in Survey123 for ArcGIS App 3.0 installation wizard on Windows 10 German OS contains an action text that does not match the text indicated on the button below the text.


Survey123 Field app (Usability)


  • BUG-000105325 Survey123 for ArcGIS maps do not automatically open to the Home extent as default behavior.
  • BUG-000120565 In Survey123 for ArcGIS, Inbox icons in the Map View randomly turn orange or disappear after a point has been edited and sent, or when the Inbox is refreshed within the Map View.
  • ENH-000107453 When using the Tab key to move through text questions in Survey123 field app on the Desktop, the survey does not scroll automatically.
  • BUG-000124636 Editing the Signature field submitted using the Survey123 for ArcGIS field app creates a permanent black bar over the response.


Survey123 Web app


  • ENH-000113292 Allow the pulldata(@property, utcoffset) function to be used in Survey123 web forms.
  • BUG-000124448 Survey123 webapp version 3.5 fails to return addresses from geopoint using the pulldata() function when geopoint and address questions are in repeat.
  • BUG-000122210 Reverse geocode fails to return results in the Survey123 web app when using a custom geocoder.
  • BUG-000123616 In Japanese language, the data does not show correctly for multiple choice questions in the Survey123 for ArcGIS web app.
  • BUG-000122892 When submitting the form several times in Survey123 for ArcGIS, the sentence mentioned for submitting another survey is misleading in French.
  • BUG-000123376 The setting 'Show message to prompt the user to submit another record' is not honored when the survey is created from Survey123 Connect for ArcGIS.
  • BUG-000118801 An existing secured ArcGIS Server feature service added to ArcGIS Online with credentials saved is not be able to attach images when using the web browser to submit the survey (the data is submitted, but not the attachments).
  • ENH-000118845 Survey123 GeoPoint questions should have the option "Explore" on the Web Map, which activates zoom/pan on the Map.
  • Multiple usability enhancements added to the map control, including an option to enlarge the map when working in a desktop computer and making map navigation easier.


Feature reports


  • BUG-000111657 Photos submitted in landscape orientation in the Survey123 field app, result in poor quality when individual responses are printed or saved to PDF from the Survey123 website.
  • BUG-000125306 Conditional statements for images with the relevancy setup are not honored in a feature report in Survey123 for ArcGIS.


Survey123 Designer and website


  • BUG-000123663 The Data tab fails to zoom to the point extent initially for Survey123 for ArcGIS website.
  • BUG-000124275 Ordnance survey basemaps that are specific to the UK act fuzzy within the Survey123 website.
  • You can now manually set choice names for multiple choice questions in the the Survey123 designer.
  • BUG-000125107 The Analyze tab at does not show the correct Bar Chart reports and percentages for surveys with multiple choice-questions configured with the Batch Editor option when the language for ArcGIS Online Organization is set to 'Japanese - 日本語'.




  • BUG-000124114 In an organization that does not allow HTTPS only, if a Survey123 for ArcGIS form is accessed via the item details page, the error message, "Request needs to be made over HTTPS" is returned.
  • BUG-000122890 Survey123 for ArcGIS sends a query that is logically correct but appears as a potential SQL injection attack to firewalls.




  • ENH-000124633 Update Survey123 documentation to inform that 'Hints' are not supported within 'Repeats'.
  • BUG-000124657 Update Survey123 with ArcGIS Enterprise documentation to provide more details on the limitations of creating feature reports with feature services hosted in Portal.

Starting with version 3.6, Survey123 supports working with line and polygon GIS features within your smart forms. There are many common scenarios for creating new, or working with existing, line and polygon GIS features in Survey123. For example:


  • To support a noxious weed control program, you need a form to report areas where certain chemicals are being applied. You will want your form to include a question for users to delineate the exact area (polygon) where treatment occurred.
  • You want to create a digital form following the SCAT methodology for assessing the impact of an oil spill along a shoreline. Your form must be able to let users highlight the segment (line) of the shoreline, or path, that was assessed.
  • Let's pretend you want to expedite the completion of ATC building inspection forms against an existing collection of building GIS features. In this case, you will want users to open an inspection form for the selected building (polygon) and let them complete all other details.


This blog describes how you can add support for line and polygon GIS features in your Survey123 smart forms using Survey123 Connect and XLSForm.  If you are not familiar with Survey123 Connect and XLSForm, please have a look at our Survey123 video tutorials, our XLSForm essentials—Survey123 for ArcGIS | ArcGIS help topic, or the Survey Customers to Gain Marketing Insight | Learn ArcGIS Learn lesson.


Support for configuring map questions in the Survey123 web designer to capture line and polygons is planned for a future release.


The Basics


The basics: geoshape and geotrace in Survey123 Connect


Hopefully by now you are familiar with the XLSForm geopoint question type. It allows you to bring a map question into your survey, so end users can define a point location of interest as part of your form. The geotrace and geoshape XLSForm question types will also be shown as a map within your form, allowing users to work with line and polygon shapes respectively.


To get started, I suggest you build a new test survey with Survey123 Connect and add the following questions:


datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Area


If the geoshape question does not render correctly when previewing your survey, make sure you download and install the latest version of Survey123 Connect.  Geoshape and geotrace questions are only supported with version 3.6 and above.


Next, publish your survey to test your geoshape question within the Survey123 field app or web app. If using the field app, make sure you have version 3.6 or later installed on your device. You should be able to delineate a treatment area and submit. Using the Survey123 website Data tab, you will be able to look at your newly created features.

If you attempt to use geoshape or geotrace questions in forms authored prior to 3.6, keep in mind that the geoshape and geotrace options will not show in type column choice list. If you want to make these new question types appear in your old form, have a look at the Survey123 Tricks of the Trade: Microsoft Excel blog post.


The basics: geoshape and geotrace questions in the Survey123 apps


You can use geoshape and geotrace questions in both the Survey123 field app and web app. The user experience in the native app and web browser are very similar: A map is presented to the end user with tools to sketch or digitize the corresponding shape (line or polygon).


Here is what using a geoshape question looks like from a web browser (Survey123 web app):



And here is the experience for capturing a line in the Survey123 field app using a geotrace question:



You will notice that the map control shows an info bar describing the length and area of the shape digitized. The units in this info bar are set by your device locale. If your locale is set to the United States, imperial units will be used. Otherwise, metric units will be shown.


The basics: Looking at captured data in the Survey123 website


You can view and perform QA/QC operations on all Survey123 captured data using the Survey123 website. Through the Data tab you can visualize data captured through the geotrace and geoshape question types in a map and individual response views.



You can also bring your line and polygon data into your own custom Survey123 feature reports.


Beyond the basics


Adding multiple geo type questions in a survey


Values for geo type questions (geopoint, geoshape, geotrace) are stored in the SHAPE column of your surveys feature layer. The ArcGIS geodatabase model only allows for one single SHAPE (geometry) column per feature layer, so this restricts the number of geo questions you can add to a survey to one: either one geopoint, or one geoshape or one geotrace question. The only exception is when you add repeats to your survey: each of your repeats can also include its own geo question.


For example, with our SCAT survey, lets pretend you want to use a geotrace question to document the segment of shoreline surveyed and then you want to flag locations where severe oil damage has been found. You could create a survey as follows:


datesurvey_dateSurvey Date
geotraceshoreline_surveyedShoreline segment surveyed
begin repeatsevere_damageSevere damage observations
geopointissue_locationLocation of damage
end repeat


Note that the survey includes two geo questions: one in the main body of the survey, and one inside a repeat. This is allowed because questions within the repeat will be stored in a separate (and related) layer.


Input Methods: vertex vs sketch


When using geoshape or geotrace questions, you can optionally define the input method of your map.That is, you can control which style of tools will be presented in the map to help users delineate a shape.  You can do this through the body::esri:style column in the survey XLSForm sheet.


The map supports to input methods:


  • sketch: Enables drawing tools in the map. This is meant to help users quickly draw, or sketch, a line or polygon in one single take.
  • vertex: This input method is more appropriate when you want users to digitize shapes more accurately. The vertex input method provides tools to add vertices one at at time by:
    • Tapping on the map.
    • Centering the map at a target location.
    • Getting the coordinates through the built-in or external GPS.

The vertex method also lets users switch between edit and navigation modes, update and delete existing vertices.


You will want to experience on your own each of these two input methods and decide what is best for your particular workflow. In some cases you want a simple and quick way for people to sketch a geometry. In others you want to give them more control, even if that implies some initial trial and error with the tools until they get familiar with them.


The following example shows how you can set the vertex input method using the body::esri:style column:


datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Areamethod=vertex



XLSForm functions: Calculating perimeter, area and length.


Along with the geotrace and geoshape question types, we have also extended XLSForm support, so you can create expressions to work with these geometries. Two common functions we anticipate you using are area and length. Back to our noxious weed abatement scenario, the area function could be used to automatically compute the area treated.


datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Area
hiddentreatment_sqmCalculated Area in sqmarea(${treatment_area})esriFieldTypeDouble


Note that in the example above, the calculated area is stored in a hidden field. This is optional, as you could be using a decimal question type instead. You can use a hidden question to keep the output value without presenting it to the end user.  Hidden questions are mapped automatically to text questions in the geodatabase but since I want to store the area as a number, I added esriFieldTypeDouble value to the bind:esriFieldType XLSForm column.


The output of the distance and area functions is always in meters (or square meters), but you can easily apply conversions and rounding as needed.


round(area(${treatment_area}),2)Extracts the area in square meters of a geoshape and rounds the value to 2 decimals
distance(${treatment_area})Calculates the perimeter of a geoshape or the length of a geotrace. Output in meters.
distance(${shoreline_surveyed}) div 1000Gets the distance of a geotrace geomery in meters and divides by 1000 to get the distance in kilometers.
distance(${pipe_to_install}) * ${price_per_meter}Estimates the installation cost of a pipe.


The distance and area functions can also be used in other contexts. In the example below, we use the function to control if a particular question will be required or not. If the area treated is less than 100 square meters, then a justification text question will be shown, but it will not be compulsory. If the area is larger than 100 square meters, then a justification must be provided.


datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Area


More on XLSForm functions:  repeats, sum and count.


With some creative thinking, there are some more advanced XLSForm techniques you could leverage when working with geotrace and geoshape questions. In the next example, a repeat is used to capture the exact location of electric poles. For each pole, type, observations and some GPS metadata for the pole location is collected. Using the sum function, a line feature representing the electric line joining all the poles is automatically generated.


datesurvey_dateSurvey Date
begin repeatpolesPoles
geopointpole_locationPole Location
hiddenpole_haAccuracy (m)pulldata("@geopoint", ${location},"horizontalAccuracy")
select_one typespole_typePole Type
end repeat
geotracepole_lineElectric Linesum(${pole_location})
hiddenpole_count# Poles in Linecount(${pole_location})


While not included in the example above, it would make sense to set the geotrace question as readonly, to ensure that the electric line is truly following all the pole locations within the repeat. Otherwise the end user could open the map for the pole_line question and manually alter its geometry. Depending on your workflow, the desired behavior is up to you and can be configured either way.


Geotrace and geoshape in the Survey123 field app Inbox


So far, we have explored how to use the geotrace and geoshape questions to enter new line and polygon features. In some scenarios however you may want to simply reference existing line and polygon features and help drive data capture workflows within Survey123.


A classic example is that of building inspections. For example if you need to score a set of buildings to assess fire risk, or to evaluate damage after a hurricane or earthquake. Your intent in this scenario is not to create or update the polygon footprints. Instead, what you want is to update attributes in these existing buildings based on your own on-site assessment.


In this case, you will want to build your survey on top of the existing building (polygon) layer. The geoshape question will help you drive the whole user experience in the Survey123 field app, allowing the selection a building from the Inbox map and opening the assessment form for the selected building right away. When submitting your survey, the polygon shape of the building will remain untouched, but the attributes reflecting the assessment will change.


The next animation shows the whole workflow: 1) Bring features (polygons) into the Inbox, 2) Select a feature from the map to open its corresponding form, and 3) Submit changes to update the feature:



If this pattern interests you, keep in mind that the Survey123 field app Inbox is meant to work with a small number of features. When enabling the Inbox in Connect, I strongly recommend you set a filter to query and filter the features based on attributes (buildings pending inspection, or buildings assigned to the logged-in user, for example). From a practical perspective, with 3.6, you will not want to load more than 200 or 300 surveys in the Inbox. You will see some new performance improvements for the Inbox coming in future releases, but as of version 3.6, you will need to keep the number of records loading in the Inbox as low as possible.


Performance improvements to the Inbox are coming with version 3.7. As of 3.6, keep the number of records in the Inbox under a couple of hundred by applying spatial and attribute queries to the Inbox in Survey123 Connect.


For a more detailed description on the Inbox, check our Prepare for editing existing survey data—Survey123 for ArcGIS | ArcGIS help topic.


Including lines and polygons in your Feature Reports


Using Survey123 Feature Reports you can create high quality printable documents for any of your Survey123 records. TheUnderstanding Survey123 Feature Reports blog post describes in more detail how to use this feature. The Feature Report syntax has been extended to allow you to dynamically include in your report the perimeter and length and area properties of a survey record. For example:


  • ${segment_surveyed | getValue:"length":"meters":"geodesic"}
  • ${treatment_area} | getValue:"area":"hectares":"geodesic"}


The length property returns the length of a line and the perimeter of a polygon. The area property only applies to polygon features. The length unit options are feet, kilometers, meters, miles, nautical-miles and yards, for length. For area: acres, hectares, square-miles, square-kilometers, square-meters, square-feet and square-yards. The last property defines if you want to get the planar or geodesic measurement. If your data is in WGS 84 Web Mercator Auxiliary Sphere, which is going to be the case with Survey123 unless you set your own custom projection on the data, you should always use geodesic. If your data uses a local projection, typically planar will be the best option.

vehicle damageStarting with Survey123 3.6, the field app now supports a new appearance of image-map. This new appearance allows Scalable Vector Graphics (SVG) files to be rendered in your survey form and provides a clickable image for both select_one and select_multiple questions. Choice list selections can now be made by simply selecting different parts of the image. The image-map appearance is currently not supported in the Survey123 web app.


So what is an SVG? An SVG file is an XML-based vector image format for two-dimensional graphics, that has support for interactivity and animation. SVGs also have the ability to have raster image formats such as .png and .jpg embedded within them.


The image-map appearance provides a powerful way to customise the UI of your survey without having to write a single line of code. This enables fast and intuitive data collection with the underlying user selections stored in the feature service. The 'Image-map Sample' survey, available in Survey123 Connect, shows a variety of use cases including Risk Assessment, Body Parts, USA States and Soil Texture.


The animation on the right shows a Vehicle Damage Inspection survey that combines the image-map appearance with the photo watermark feature. This enables the inspection photos to be stamped with the corresponding vehicle part for easy identification later. 


These examples involve relatively complex shapes and highlight what is possible, but the most simple of SVG files can also provide real improvements to survey usability. The ‘big button’ experience is easily set up with a basic SVG file. Also included in the 'Image-map Sample' survey is a ‘Level of Difficulty’ example that is essentially just an SVG file containing 4  clickable <path> elements (plus some text and symbols for ease of use).



Implementing the image-map appearance

The following steps relate to the 'Level of Difficulty' example in the 'Image-map Sample' survey. You can follow this process using the 'difficulty.svg' file attached to this blog.


1) Add a select_one or select_multiple question to your XLSForm (more information on this step).


2) Set up your survey choice list. Each entry needs a list_name, name and label. The values in the name column are the ones that link the choices to parts of your image.



Create an SVG file or assess an existing file for compatibility with Survey123. The second half of this blog goes into more detail on creating SVG images, for now just open 'difficulty.svg' (attached) in a text editor to assess it's compatibility.

  • Ensure that your file has <path> elements with id values that match the name values in your choice list. The <path> elements with id values become the clickable areas of the image.
       d="M 5.4998702,5.4998718 H 129.50013 V 194.50013 H 5.4998702 Z"
       id="beginner" />

       d="M 135.48042,5.4804192 H 259.51959 V 194.51958 H 135.48042 Z"
       id="intermediate" />

       d="M 265.48041,5.4804192 H 389.51956 V 194.51958 H 265.48041 Z"
       id="advanced" />

       d="M 395.48041,5.4804192 H 519.51959 V 194.51958 H 395.48041 Z"
       id="expert" />
  • Non-clickable areas are <path> elements without id values and other element types eg <rect>, <circle>, <text> etc.
  • See below for more detailed SVG requirements and tips for using with Survey123.


4) Copy your SVG file into the media folder of your survey. The media folder is located in the survey folder  (~\ArcGIS\My Survey Designs\{survey name}) which can be quickly accessed using the Files button in Survey123 Connect. If the media folder does not exist, you need to create it inside the {survey_name} folder.


5) Add image-map to the appearance column, and the name of your SVG file (include the .svg file extension) to the media::image column of your select question.


select_one difficultydifficultyLevel of Difficultyimage-mapdifficulty.svg


That's all there is to it!


Using SVG files in Survey123

While implementing the image-map appearance in Survey123 is simple, the contents of the SVG file itself can get confusing. SVG files can be created in a multitude of ways and each method may introduce issues when trying to use within Survey123. The remainder of this blog post will look at the most common ways of creating an SVG file and the associated tips and tricks for getting them to work in Survey123.


Minimum SVG requirements for Survey123:

  • Must contain a <path> element that has an id value. Non-<path> elements such as <rect>, <ellipse>, <circle>, <image> and <text> will not be clickable. Likewise, <path> elements without an id value will not be clickable.
  • No empty groups. Having empty groups ie <g> </g> within your SVG makes all <path> elements become un-clickable.
  • Can only have 1 group per nest level. You can have as many nested levels as you like, but if you have more than one group at a particular level (including the parent level), all of the <path> elements become un-clickable.
  • SVG height and width (Viewport) must be defined. While your image will likely display properly in Survey123 without these, your clickable areas may become offset from the underlying image.
  • Viewbox must match Viewport (if specified). You don't need to specify a 'viewBox' parameter in your <svg> element. However, if you do specify a viewBox that differs from your height and width values, your clickable areas will be offset from the underlying image.

Other tips for SVG files:

  • Transform functions. It is possible to have SVG elements with transform functions work perfectly in Survey123. However, we must understand that transforms have a cumulative effect when applied to nested elements. It is often best to avoid transform functions if possible.
  • Number of clickable areas. Although most web browsers can render SVG files with up to 5,000 elements without  any issues, these are obviously not practical for use in Survey123. Be mindful that each clickable <path> element needs to be large enough on the screen for the user to select. You'll need to consider what platforms, devices and screen sizes you're using Survey123 on, to decide on a practical limit that suits you.


Downloading the perfect SVG from the web!

So you’ve found the perfect SVG online and have downloaded it for use with Survey123. While the image you found online may look perfect, it needs to include the required <path> elements to be clickable in Survey123.


There are numerous desktop vector graphics programs like Adobe Illustrator, Corel Draw and Inkscape as well as online SVG editors like Vectr, BoxySVG and DrawSVG. Most of these have tools that will convert different types of objects (eg <rect> or <circle>) to <path>, so perhaps your downloaded image can be easily tweaked to suit Survey123.


There are online resources that have SVG files for download that are designed in a way that suits Survey123, particularly those with geography content like and Most SVGs you'll find online have not been designed in this way so open your file in a text editor to quickly assess the contents.


Converting an existing raster image into an SVG

You may have the perfect .png or .jpg raster image that you would like to use with the image-map appearance in Survey123. The image-map appearance only supports SVG files, so you will need to convert your raster to SVG first. Vector graphics programs have tools that basically trace your raster and create SVG objects which can be very effective. Alternatively, online converters such as or can help you achieve this. Results can vary, but some experimentation with the settings and thresholds can yield usable SVGs in no time.


It is best if your raster image contains filled shapes with a limited range of colours. The 'Pipe Fittings' example was created using to first convert a .jpg to SVG. Then the unwanted light grey <path> elements were deleted using a text editor:



Creating an SVG from scratch

lawn varietiesThis option gives you the greatest control over your SVG file. While it is possible to write an SVG entirely in a text editor, vector graphics programs like the ones listed above are the easiest way to create an SVG from scratch. If you're completely new to digital graphics then perhaps the online SVG editors are your best bet. Otherwise, desktop programs often have a larger toolset without limitations on importing and exporting your finished SVG. Inkscape is a free and open source vector graphics editor and was used for some of the SVGs in the sample survey.


The main advantage of using a vector graphics program is that you can easily embed raster images too. Embedding a photo into your SVG can be very useful, for example when the user needs to identify the selection they're making. Here is an example that includes photos of different lawn varieties:


TIP: Having a raster image in the background of your SVG and drawing some simple shapes over areas you would like the user to click is often the quickest and easiest way to create your SVG for use with Survey123. The 'Stranded Oil Distribution' example was created using a .png file as the background image. Then 24 x squares were drawn as <path> elements over the top of the background image. They were given no stroke or fill properties so they are invisible, but they define the clickable areas that correspond to the underlying parts of the background image.


oil distribution


More Information

The image-map appearance type is included in the Survey123 documentation here: Select one and Select multiple.


Detailed information on the SVG specification can be found here: Scalable Vector Graphics (SVG) 1.1 (Second Edition) and Scalable Vector Graphics (SVG) 2

If you use Survey123 Connect to author forms you are surely to become a regular of Microsoft Excel and the Survey123 XLSForm templates and samples. In this blog post, you will find some tips to help you be more productive with all of that. The first half of the post focuses on the Survey123 XLSForm templates and samples, describing how you can manipulate them to your liking. The second half compiles a handful of general productivity tips for Microsoft Excel.


Survey123 Connect XLSForm Templates


Some context first: XLSForm, .xls files and Microsoft Excel


Before jumping into the actual tips, I want to provide some clarification about Microsoft Excel and how it relates to XLSForm and Survey123. The XLSForm specification describes the syntax you need to follow in order to define a smart form in an .xls spreadsheet file. Survey123 adheres to the XLSForm specification. The foundation of Survey123 forms is ultimately an XLSForm document (.xls file).


Xls files were introduced in 2007 by Microsoft. Initially it was a proprietary format, but it was ultimately shared as an Open Specification. Technically, you can use any means to create Survey123 forms as long as you follow the XLSForm syntax and the output is stored in a proper .xls binary file. You do not need to use Microsoft Excel, other programs such as Open Office, Libre Office, Numbers can create xls files.


Formulas and data validation in Survey123 templates and samples


Survey123 Connect includes a number of samples and templates to help you get started with XLSForms. These .xls files (technically .xlsx) have been created using Microsoft Excel, and while we know they can be used and manipulated outside Microsoft Excel, we do not test them outside of this program.  On top of the compulsory XLSForm sheets (survey, choices and settings), our templates and samples include a number of formulas and data validation rules meant to facilitate the authoring of XLSForm compliant documents.  For example:


  • Several XLSForm columns in the survey spreadsheet include choice lists: type, appearance, bind: esriFieldType, etc.  This is to make it easier for you to pick a valid XLSForm choice.
  • A data validation rule in the name column of the survey sheet will highlight cells that have duplicated values. It also ensures that the value you enter will be accepted by ArcGIS as a field name. It checks for reserved keywords, length and special characters.
  • A yellow tip briefly describes the intent of each XLSForm column.
  • etc.


The formulas and data validation rules included in the Survey123 templates and samples are for your convenience, but they are not strictly necessary. If you feel these validation rules and formulas are in your way, you can manipulate and even eliminate them.


The next animation shows how you can access the data validation rules of a cell in Microsoft Excel.



Virtually every cell in our samples and templates has data validation. At this moment, I just want to make sure you know how to open the data validation rules for a particular cell.


Yellow tips (and how to hide/disable them)


When you select a cell in the survey sheet, you always get a yellow tip.  We added them to describe the purpose of the different columns in the survey sheet.  Below is the tip for the bind::esri:fieldAlias for example.



The yellow tips provide good info, but they also can get on your way obstructing the view of your form design. If you simply hit the Esc key, the tip goes away until you select another cell.



The yellow tip, in Microsoft Excel jargon, is an Input Message. To disable it, you need to go into the data validation dialog as shown in the next animation. 



If you feel ready for it, you can also disable all the Input Messages in one go. First, select all cells in the survey sheet using Ctrl-A, then open the Data Validation dialog and disable the Input Message for all.


Manipulating XLSForm lists such as appearance, type, etc.


As described above, some specific columns in the survey sheet limit inputs to values within a list. This is the case, for example, for the type, appearance, bind::esri:fieldType, required and readonly columns. It is important to know how to manipulate these lists.


Take the type and appearance lists, for example. They define, respectively, the XLSForm question types and question appearances that Survey123 supports. As support for new question types and appearances grows, lists in old surveys  you may have created could become obsolete.  For example, support for geotrace and geoshape question types came with version 3.6.  If your survey used a template downloaded with 3.5, these question types will be missing.


If you look at the data validation of a cell in the type column, you will see that it limits input to a list. The list is defined as a range of cells coming from the types sheet.  The types sheet is not part of the XLSForm spec.  It was spcifically added to the Survey123 Connect templates to help build data validation rules like this. It also serves as a nice quick reference for XLSForm syntax, listing the different question types, appearances, operators  and other things you can use.


If you want to add a missing entry to a list, you will do it in the types sheet. The next animation shows how you can add the geotrace and geoshape question types into a pre-3.6 template.



The same technique described above can be used to add new appearances. 


You should keep in mind two important things:

You must add new entries in the types sheet one by one. That is: You insert one new row, and you add values in it. Then you add the next row and so on and so forth. If you insert more than one row without values, your list range will not be happy.

You must enter new entries somewhere in the middle of the list. That is, never add a new entry at the very beginning (first position) or end (last position) of the list.

In the case of the lists for the required and readonly columns, you may want to delete the data validation rule completely if you want to enter an XLSForm expression in them.  The list included by default only has one value: yes. If you want to enter expressions you may want to delete the data validation rule to eliminate the drop-down list.


Creating your own template


By now you may be wondering if you can create your own template. To some extent, the answer is: yes. You can first create a new survey from the Advanced Template and make your own modifications to the Excel file. You can then use the Create a new survey option to derive new surveys out of your own template.



What I like about this approach is that not only you can create a new survey with all the modifications in your Excel file, your new survey will also inherit other properties of your template, such as the thumbnail, summary and description of your own template. Style, Inbox and Image settings in your template will also be matched, as well as custom content in your media folder if you ever add it to your template form.


If you publish your template from Survey123 Connect and share it with groups within your organization, other people will be able to use it  too.  Your survey, once published, will appear in the My Organization category of the New Survey dialog in Connect.


The real advantage here, again, goes well beyond tweaks to the data validation rules and formulas. It is other things in your template, like settings or even common lists you may have added in the choice sheet that would benefit anyone in your organization using your template.


Microsoft Excel Productivity Tips


So far, I have described specific tips to handle the Survey123  templates and samples that come with Survey123 Connect. Next, I want to compile a few general Microsoft Office tips for all of us who spend time designing Survey123 forms using XLSForms, Microsoft Excel and Connect. It is likely that you will already know many of the tips listed, but if just a single one you don't, that may make this read worthwhile.  If you have other tips you want to share, please add them as a comment below, so we can keep the list growing.


Inserting new rows, the quick way: Ctrl-Shift-+.


It is no secret that you can insert a new row by selecting a row, right-clicking and then using the insert option in the context menu. If you want to do that same thing much more quickly, select a row and then hit Ctrl Shift +.



Careful with copy paste!


Copy-pasting is often our friend. Nothing wrong with it... unless you copy too much. In Excel, when you do a standard copy-paste, you actually are copying way more than you think: you are copying the cell values, but also formatting style and formulas.  It is the formula bit that can get you in trouble, particularly when you copy cells from one xls file to the next.  To avoid any issues, I like to copy just the values.  This is described well in this Microsoft article.


Extend values and formulas


This tip is particularly valuable when constructing lists in the XLSForm choice sheet. Simply double-click on a cell's bottom right corner to extend that value and formula down to the end of the list. In the animation below this technique is used to apply a list name to over 250 list choices.



Keyboard shortcuts


In Microsoft Excel, using the mouse is often the slowest approach to get anything done. There are keyboard short-cuts for anything you can imagine. I use keyboard shortcuts for selections quite a bit: Ctrl + A to select all cells in a sheet and  Ctrl + Shift + Down Arrow to expand a selection to the bottom of a list.


But there are way too many shortcuts to describe and only a few that you will truly take advantage of. If you hit Alt, Microsoft Excel will describe keyboard shortcuts to open a ribbon. For example, Alt + A opens the Data ribbon but you do not have to remember that, because if you simply hit Alt, the Data ribbon will be highlighted with A as a reminder. Even better, if you hit Alt + A not only the Data ribbon opens, but also every function within it is also highlighted with its shortcut. For example, Alt + A + V opens the Data Validation menu.



Again, just a few tips. If you want to share a few more, please do so below!

Filter Blog

By date: By tag: