Skip navigation
All Places > Survey123 for ArcGIS > Blog
1 2 3 Previous Next

Survey123 for ArcGIS

163 posts

You can think of XLSForm repeats like sub-forms: A form within a form that can also be completed multiple times. Repeats are a very powerful feature in Survey123 because they can be configured in many different ways to support different business workflows. This article covers everything from the basics to the more advanced features of repeats. 


Some use cases


Let's first review some common scenarios that scream for a repeat:


  • In a door-to-door population survey, you will want to capture the location of the household and address, but also information about every member of the family. A repeat will help you model the form to be completed for each of the members of the household, including information about their name, age, gender, etc. The household survey will have a household member repeat in it, which will be completed for each person in the household.
  • In an asset inspection form you may want to capture information about each defect found. The defects repeat (or sub-form) will include questions to let you document each defect with its own photo, a description of what needs to be repaired and estimated cost of repair.
  • Repeats are also a great way to handle routine inspections. An asset form can include a repeat for the inspections: one form for the asset with its ID, location, etc and a sub-form (repeat) for every inspection ever made, with its date, issues found, etc. Since repeats can be nested, the inspection repeat form can also include its own repeat or sub-form for every defect found.


The basics


Repeats are supported through XLSForms via Survey123 Connect. If you are familiar with XLSForm groups, you have a lot of ground covered, because a repeat is really a type of group that lets you cycle through the questions in the group again and again.


To add a repeat to an XLSForm you need to enclose a set of questions within a begin group and end group set, as shown in this example:


texthh_idHousehold ID
begin repeathh_membersHousehold Members
textmbr_nameName and last name
select_one gendermbr_genderGender
end repeat
select_one yes_noall_members_presentAll household members present?


In the survey above, the main body of the form is really about the household itself and is used to collect the household ID and address. The repeat block is all about household member information. We expect the enumerator to complete the Household Members repeat, or sub-form, once for each person in the household. The All household members present? question is outside the repeat, so it also belongs to the main form, but it will be presented right after the Household Members repeat.


Below is what the survey above would look like in the Connect preview. Note that the repeat appears as a common question group, except that at the bottom there are multiple options to navigate records within the repeat: a plus button to add a new record as well as next and back buttons (once you have more than one household member).



The user experience for repeats within the Survey123 web app is slightly different, presenting all the repeat records at once. You can navigate through them by scrolling up and down, as shown in the next animation.


Repeat records in the Survey123 web app are shown all at once


You can add one or more repeats to your survey. For example, in a school survey, you could include a repeat to document all classes in the school, and a separate repeat to gather information about teachers, etc. 


Understanding repeat data in your feature layer


Survey123 repeats are modeled in ArcGIS as related tables (or related layers if your repeat includes a geopoint, geoshape or geotrace question). In the example household survey above, the information about the household (id, address...) is kept in the main layer of a feature service, and the data from the household member repeat (name, age, gender) is modeled as a separate, but related table. The relationship between the tables/layers is kept through internally created global IDs.


If you would like to preview what your geodatabase schema looks like you can use the Schema Preview option in Connect, as shown in the animation below. Note that the name of the repeat in XLSForm becomes the name of the related table.


Survey123 Connect lets you preview the geodatabase schema of your survey


Using the Survey123 website, you can quickly explore data from repeats using the Data tab. The table will show records from the main layer of your survey as usual, and also extra tabs for every repeat in your form. You can propagate selections across the tabs for easier exploration of your data.


Use the Survey123 website to explore related records (repeats)


Repeat appearances (minimal and compact)


Through the appearance column in the XLSForm you can control how the repeat initially loads and appears in your form. By default, a repeat with no appearance value set is shown expanded, with one initial record showing. This can be good or bad. The good is that all questions within the repeat are ready for end-users to enter data right away. The bad is that if no data is entered, a new empty record will be added to your related table. I generally avoid using repeats with no appearance unless questions within the repeat are flagged as required.


If you want to avoid the repeat from having an initial record preloaded, use the minimal appearance. This will show your repeat group expanded, but with no records. To initialize data entry in the repeat, the end user will need to explicitly add a new record to the repeat by clicking the plus button.


The compact appearance simply collapses your repeat when the form initially loads. Of course, you can combine the minimal and compact appearances.



XLSForm expressions and repeats


XLSForm expressions allow you to bring sophisticated logic into your forms. Generally, XLSForm expressions are used to auto-calculate values (Calculations), define skip logic (Relevant), and to build data validation rules (Constraints). The XLSForm expression syntax for calculations in repeats is basically the same as with any other question in the form (more details at Formulas—Survey123 for ArcGIS | Documentation), but here are some important things to highlight.


When writing XLSForm expressions for a question within a repeat, you can reference other questions inside the repeat, but also questions outside! A common use is that where you want to bring data into your related table from the parent record. For example, in the example household survey you may want to store, along with every household member, their corresponding household ID. It would look something like this:


texthh_idHousehold ID
begin repeathh_membersHousehold Members
hiddenparent_hh_idParent Household ID${hh_id}
textmbr_nameName and last name
select_one gendermbr_genderGender
end repeat
select_one yes_noall_members_presentAll household members present?


Note how the parent_hh_id question within the repeat is calculated to automatically fetch the value of the Household ID for that person. The Household ID is outside the repeat, but the calculation brings that value into the repeat record. This is a common use of calculations within repeats because it helps bringing more information into the repeat table that would otherwise require a join.




There are a few techniques you can use to style your repeat with custom colors and labels. This can be help users navigate your form more efficiently.


One technique is to dynamically set the label of your repeat to provide some context as to what information should be entered into the repeat. For example, in our household survey, you can include the address of the household in the header of the repeat. Instead of just reading 'Household Members', you can make it read 'Household Members at: <Address of the household comes here>. This is what is known as a dynamic label and it is described in more detail in the Understanding Dynamic Labels in Survey123 for ArcGIS blog post.  This is quite handy when working with long surveys, because it brings additional context for the person filling out the form. Here is what this would look like. Note how the label for the repeat is dynamically generated using a value from a question outside the repeat.


begin repeathh_membersHousehold Members at ${hh_address}


You can also use colors to make your repeats stand out better within the form, like in the following screenshot. The repeat block uses a darker background color than the rest of the form, clearly separating questions within the repeat, from those outside.


The background and border colors of your repeat can be controlled through the body::esri:style column. In the example above, the vale in this column for the begin_repeat question is: backgroundColor='#cbcddb' borderColor='#494a4f'.  The color is expressed in hexadecimal format or HTML color name.  You will generally not want to use bright colors for you repeat backgrounds. Try to be subtle using slight variations of the background color of your form.

The body::esri:style color parameters are only honored by the Survey field app.


Aggregation functions (max,min, count and sum)


XLSForms support a handful of functions specially built to work with repeats. Specifically: count, sum, min, and max. They are all pretty self-explanatory. The design below shows the max and count functions in action.


texthh_idHousehold ID
begin repeathh_membersHousehold Members
textmbr_nameName and last name
end repeat
hiddenmax_ageAge of oldest personmax(${mbr_age})esriFieldTypeInteger
hiddentotal_countTotal persons in housecount(${mbr_name})esriFieldTypeInteger


The count function can get a bit tricky as it will only consider in the count records with a value in the question it references. For this reason, it is best to use the count function against a question within the repeat that is flagged as required.


The sum question is also an interesting one in that it can sum not only numbers, but also text and even geopoint questions as well. If you sum text, it will concatenate all responses to your question within the repeat. If you sum on a geopoint question within the repeat, it will generate a geotrace object.

Check the Repeat Aggregation Survey123 Connect survey sample for an example using aggregation functions.



Aggregation functions (join)


There is one more aggregate function that may be of interest: join. The join function is used to create a single list including all responses to a particular question within the repeat. Its syntax looks as follows:

join (",",${questioname})

The first parameter defines a separator. You can use a comma ",", a hyphen "-", or other character. The second parameter is the question within your repeat from which you want to create the list.


In our household survey example, we could use join to display a list of all people interviewed so far.


texthh_idHousehold ID
begin repeathh_membersHousehold Members: ${interviews}
textmbr_nameName and last name
end repeat
hiddeninterviewsEvery person interviewedjoin(",",${mbr_name})


Note that the hidden question at the end uses the join function in the calculation column. Then the label in the begin repeat takes that value and displays it dynamically. You can see the effect in the next animation:



We can take join a bit further. Let's pretend we need to design a manhole inspection form. We want all six parts of the manhole to be inspected: the cover, chimney, cone, wall, bench and channel. We will use a repeat to document the inspection results of every component, and the join function to help us make sure all components have been inspected. Let's first have a look at what the form's behavior looks like:



Note that a checklist at the bottom of the form keeps track of the components inspected so far. When a new component is selected for inspection within the repeat, the value of the checklist is recalculated accordingly. This checklist at the bottom is set as read-only, so the user cannot manipulate it. A constraint in the checklist is also in place to avoid users from submitting the form unless all components are checked.


A simplified version of the XLSForm, highlighting the use of the join function is shown below:


textmanhole_idManhole ID
begin repeatcomponents_groupComponents
select_one componentscomponentComponent
select_one conditionsconditionCondition
end repeat
select_multiple components
comps_inspectedComponents Inspected


To complete the XLSForm to mimic the behavior shown in the animation, you would also need to:

  • Set the comps_inspected question as read-only, to avoid users from manipulating the checklist manually.
  • Set the constraint of the comps_inspected question to count-selected(${components_tested})=6.


Repeat Count


If you want to control how many records must exist within a repeat, use the repeat_count XLSForm column. If you set the value to 2, then your repeat will be initialized with 2 empty records. If you set it to 5, it will contain 5, etc. You can also set the repeat_count dynamically as shown in the example below.


texthh_idHousehold ID
integerhh_totalHow many people live in this house?
begin repeathh_membersHousehold Members${hh_total}
textmbr_nameName and last nameyes
end repeat


The repeat_count column simply defines how many records are shown in the repeat. All records will be empty until the end user goes through every record to add data. Unless you have required questions within the repeat, Survey123 will allow you to submit records from the repeat with no data, and they will show as what they are: empty records. Generally speaking, you do not want to use repeat_count, unless you want to force people to submit a specific number of records in the repeat. If that is the case, you will want to add required fields within the repeat group. In the household example above, we first ask, "How many people live in this house?" We use that number to define the exact number of records in the household roster that must be completed. By making the questions within the repeat required, we guarantee that data is entered for every person in the house.


In cases where you want users to submit a number of records within a range, you will not want to use repeat_count. Instead, you will want to use constraints and the count function. For example, in an electric panel survey, you include a repeat to document all circuit breakers. Say that the number of circuit breakers is always between 5 and 20. This is what you would want to do:


textcc_idCircuit Panel ID
begin repeatbreakersCircuit Breakers
select_one typebreaker_typeType
select_one statusbreaker_statusStatus
end repeat
integertotalTotal Breakers${total}> 4 and ${total}<21count(${breaker_type})


As described above, for the count function to work effectively, you will want to make the breaker_type question required.


Nested repeats


A nested repeat is a repeat within a repeat. For example, say you are doing a survey of a campground in a National Park. You want a survey for the campground itself (the name, the location of the entrance, etc). Within each campground you have campsites, so that gives you one repeat (location of the campsite, photo, size, etc). Then for each campsite you have equipment, which gives the second repeat (equipment type, condition, etc).


You can nest as many repeats as you want. That is, you can nest 3, 4 even 5 repeats if you like. Technically you could nest even more but for the sanity of your users avoid it whenever possible. 


Nested repeats are only supported in the Survey123 field app.

The Survey123 web app does not support nested repeats.


Repeats in the Inbox


The Inbox is a powerful feature in the Survey123 field app, allowing you to edit existing GIS records in a feature layer. If you are not familiar with the Inbox, I strongly suggest you watch this short video tutorial.



By default, when GIS features are loaded into the Inbox, the repeat records will be empty. That is, the Survey123 field app does not fetch data from related records unless told otherwise. When updating an existing record from the Inbox in this way, you will be able to add new repeat records, but not view or update existing ones from the feature layer.


If you want to look at or update existing related records, you need to specify in your XLSForm what you want to download into the app, and for what purpose. This is all done through the bind::esri:parameters XLSForm column.


For example, let's pretend you are creating an asset inspection form and you want the complete history of inspections to be available in read-only mode. Then you would go with something like this:


textpanel_idElectric Panel ID
begin repeatcircuitsCircuit Breakersquery
datetimeinsp_dateInspection date
select_one statusstatusStatus
end repeat
integertotalTotal Breakers${total}> 4 and ${total}<21count(${breaker_type}


The query value in bind::esri:parameters will force the Survey123 app to download every related record, so all your inspections will show in the repeat of the asset form. The values supported in this column include:


  • query: Used to fetch related records and populate repeats. If query is not used, surveys from the Inbox will not display any repeat information from the existing feature. You can also control which records should be fetched, by defining a where statement for your query. For example: query="status='needs_repair'" will populate the repeat with all related records where the status is set to needs_repair. If no where statement is passed, the query parameter will fetch all related records.
  • allowUpdates: This parameter controls if the existing data in the repeat can be updated by the end user of the Survey123 field app or not. This is extremely useful because often you want end users to have read-only access to historical data (for example previous inspections of an asset) in the repeat, while allowing entering a new inspection to the repeat. allowUpdates by default is always false, but you can turn it on: allowUpdates=true.
  • allowAdds: By default this parameter is always true, allowing the end user to enter new records in the repeat. You can turn it off by passing allowAdds=false.


In the example below, our electric panel survey will display all existing circuit breakers ever recorded for that asset. It will also allow the end user to modify information from those previously recorded breakers because allowUpdates is set to true. The only exception will be the installation_date, which will be shown in the repeat as read-only.


textpanel_idElectric Panel ID
begin repeatbreakers Breakersquery allowUpdates=true
datetimeins_dateInstallation dateyes
datetimeinsp_dateInspection date
select_one statusstatusStatus
end repeat

Spatial analysis is a key component in GIS work, it allows us to understand the relationship between our data and the world around us. ArcGIS Survey123 is a great resource to efficiently capture data in the Esri Field Operations suite and provides tools to easily extract that data using Feature Reports. Survey123 Feature Reports which came out of beta in the 3.5 release of Survey123 is a great service to quickly consume data in a format that is defined and customized by the user. Survey123 Feature Reports are effective in understanding your data and responses obtained, but what about performing spatial analysis on your Survey123 results?


In this blog post, I will describe one workflow that can be used to analyze your Survey123 results using the Business Analyst Online Reporting and Infographic Services to further understand your data and extract additional information that may not easily be apparent in your survey results. With the brainstorming help from James Tedrick and our conversation on the workflow, it seemed appropriate to create a little blog outlining the ideas discussed. 


This blog post will follow an example for city park inspections with the goal of utilizing ArcGIS Survey123 to provide a temporal system of record for the city’s parks that will update every so often tracking historical changes. Using the GIS data collected from the survey the example will further identify community factors around the parks.


Below is a workflow for using Survey123 results to run Business Analyst Online Reports and Infographics:


Once the park data was collected in the hosted feature layer since the GeoShape question type was used to outline the park boundaries, the service was pulled into a Web Map to define areas of interest surrounding the data. Unfortunately, Rings can only be added to center points in Business Analyst Online so the areas of interest needed to be specified using the Create Buffers tool in the Web Map’s Analysis tools.


WebMap with Buffers


A new Business Analyst Online project was created and the Web Map was imported into the project.



After pulling the Web Map into Business Analyst Online areas can be set up to be used in Reports or Infographics.



Once the areas are configured any Reports or Infographics that were created or shared with me can be run with my survey results.


Survey123 website links are a not so widely known. Through this article, I want to bring some visibility to this cool feature. You may already be familiar with the Survey123 field and web app linking capabilities. Links allow you to launch and pre-configure the apps with a single click. Survey123 website links are not much different, allowing you to create links to share with those who need to look at and analyze survey results, or pre-configuring the Survey123 website to target your own instance of ArcGIS Enterprise.


Analyze and Data Tab page links


The Analyze and Data tabs in the Survey123 website are a great way to explore and understand data submitted to your surveys. The Data tab lets you drill down into specific survey records while the Analyze tab lets you explore trends. Both tabs have plenty of options to help you tweak all sort of options. For example, in the Data tab you can control which basemap to use in the map, which features should be selected in the table view or what filters to apply. In the Analyze tab you can control which questions should be shown or hidden, what type of charts to use to summarize each question, etc.


Survey123 website links are a great way to take a snapshot of all these preferences you set and reuse them later. For your own use, or for someone else's!


If you look carefully, you will notice that as you work on your Data and Analyze tabs, the URL in your browser reflects your choices. In the screenshot below, for example, observe that the URL in the browser has a bunch of parameters specifying the currently selected basemap, map extent, filter and other properties in the Data tab.



What this essentially means is that you can now easily copy the URL, bookmark it for later use or even share it with other people that have viewer access to your survey. That is, in short, a Survey123 website link!


For your convenience, you can also grab the link to your survey123 page as shown below.



Survey123 website links are particularly useful with the Analyze tab. Your preferences to use one type of chart or another, hide or show specific questions or even your own filters will all be encapsulated in the page link. In this way, you can save bookmarks to easily return to your preferred survey results view.


Target your own ArcGIS Enterprise with the portalUrl query parameter


If you work with ArcGIS Enterprise, this is a must-have. Through the portalUrl query parameter you can define the target ArcGIS Enterprise instance that will be hit from the Survey123 website. For example:

In the URL Above, the host, domain, and webadaptor are replaced by information about your portal, allowing you to use the Survey123 website against your own ArcGIS Enterprise instance. 


While you can obviously bookmark the URL above to reuse it, it is much better to modify your ArcGIS Enterprise app launcher to include a shortcut to the Survey123 website. That way, anyone in your organization can easily access the Survey123 website without having to remember the syntax of the URL.



You will find step by step instructions to create your own Survey123 website shortcut in the app launcher of ArcGIS Enterprise in this Technical Support Article.

Hans Christian Andersen was born in Odense, near Copenhagen, Denmark, on April 2, 1805. He is famous for his fairy tales, such as "The Little Mermaid", "The Emperor's New Clothes", "The Princess and the Pea" and many others. Fairy tales are short fictional stories for children's entertainment. They generally involve animals, plants, forces of nature or folkloric characters such as elves, witches, fairies... fairy tales often have happy endings, but Andersen never took that very literally.


Coinciding with Andersen's birthday and International Children's Book Day, today we release Survey123 version 3.9. This update also has a touch of magic in it...


Survey update notifications in the Survey123 field app


Many of you have contributed with your comments and voted up ArcGIS Ideas from Mike Bruening and James Botterill on survey update notifications. So far, these are among the most popular of all! 


With this update, the Survey123 field app will let you know if a new version of a survey on the device is available for download. This check happens automatically when the application starts, or when a new user signs in to the app. You can also manually trigger the check by simply dragging down on the survey gallery.


Survey update notifications will appear after you re-publish a survey. For example, if you add additional choices to a list, fix a typo on a label, add new questions or adjust calculations, etc.


As of this release, it is up to the end user of the app to decide if and when a survey update should be downloaded. We are aware that many of you would like to force survey updates in some cases and this is something we are working on implementing in a future release.


We trust this new feature will streamline much of your field work out there!



New Map question in the Survey123 web designer (line/polygon support added)


With this release, we have replaced the geopoint question type in the Survey123 web designer with a new Map question type. The Map question is useful when you want end users to provide the location of an event, just like you did with the geopoint question, but it also supports line and area modes.


Survey123 designer now includes a new map question type


In the screenshot above, for example, the Map question in the form is configured to let end users draw an area (polygon), instead of a single location (point). The new Map question type works well in the Survey123 web and field apps and features vertex-by-vertex and freehand drawing tools.


Since the ArcGIS data model is limited to one geometry field per layer, it is only possible to add a single Map question to a form. Additionally, once a survey is published, it is no longer possible to switch the type of geometry in the Map question. That is, you cannot for example switch from line to area. It is possible to change the drawing tool mode from freehand to vertex-by-vertex, but not the geometry type. If you ever need to make such a change, you can save a new copy of your survey and change the geometry type before publishing your new survey.


We want to thank all of you who provided feedback through the Early Adopter Program and our Holistic Testing sessions during the development of this new question type. In particular to Charlie FitzpatrickJoseph Kerski and Education colleagues.


Custom Survey123 feature report filenames


Many of you have requested more control over the name of the output files created by the Survey123 feature report service. You can now include a question placeholder in the output report file name that you pass into the service. This placeholder value will be dynamically replaced when the report is generated.


In the screenshot below for example, you can see that the name of the output report file generated includes the household id value from the survey record.


Custom report file names (Survey123 report service)

You can use question placeholders when defining the report output filename in the Survey123 website, or from the Integromat module. The placeholder looks as follows: ${question_name}. For example, below I set the placeholder to use the value from the field hhid (Household ID). You can combine if you wish multiple placeholders.



New Survey123 web app JavaScript API


The Survey123 web app JavaScript API is designed to help web developers more easily embed, style and interact with live Survey123 smart forms within their applications. It is a simple, yet powerful way to integrate Survey123 within larger business workflows. Through this API, you can choose at runtime what survey you want to display and how it will fit within your web application. You can bidirectionally send messages between your form and the web application. To learn more about this API check the Introducing the Survey123 Web App JavaScript API blog post.


Survey123 web app Draft mode


In the Survey123 website, if you visit the Collaborate tab, you will find a new Draft mode section. If you choose to use the draft mode, data entered through the Survey123 web app (from a web browser) will be stored locally until your survey is sent or cleared. This is useful for long surveys where people may choose to work on your form for a while, and then come back to it later after having closed the browser. Data will not be lost even if the end user navigates away from the survey or closes the browser; when they go back to your survey URL, all the entered data will be there until submitted.

You will want to turn on this option selectively, as this could compromise the privacy of entered data if used from a shared computer. For example, if someone is working on a form with sensitive information and draft mode is enabled, it is possible that data could be compromised if that person forgets to submit or does not reset the data in the form. Anyone loading the survey URL at a later time from that shared computer will see the data.


Draft mode is only available in surveys published with version 3.9 or above.


When draft mode is on, a link to reset the draft will be shown at the top, as illustrated in the screenshot below.

Other fixes and enhancements


Whilst the new features above are important, many of the fixes and enhancements that follow are just as relevant. I will highlight here a few that could easily get lost amongst the list below:


  • As anticipated in our earlier Upcoming changes to Survey123 web form's query parameters announcement, the mode query URL parameter in the Survey123 web app now supports the use of globalIds.  To facilitate migration of your existing work, we have extended the life of the objectId parameter in 3.9.


3.8 and earlier versionsSupportedNot supported
3.9SupportedSupportedUse this version to migrate!
3.10 and beyondNot supportedSupported


  • We very strongly recommend that you transition away from objectIds as the days for them are counted!  With 3.10 we will completely drop to support and exclusively use globalds.
  • In the Survey123 field app, you will notice that the sign in workflow has been revised. It features a cleaner, more informative and easier to use UX. This was part of a larger effort to accommodate random sign out issues and to incorporate multiple enhancement requests to facilitate login/logout workflows. The UX for connecting the app to your own ArcGIS Enterprise portal has also been revised.
  • In the Survey123 website, the Analyze tab now includes a much improved user experience for navigating long forms.
  • If you work with XLSForms, you should also note that starting with this release, select_multiple questions now support calculations.
  • If PKI authentication is of interest, on top of SAML PKI support, the Survey123 field app now also supports PKI authentication from your ArcGIS Enterprise web adaptor.
  • For Windows users: You can also now download the Survey123 app and Connect directly from the Windows Store.


Survey123 field app and Connect


  • Never get randomly signed-out again: Multiple fixes have been applied to accommodate scenarios where the Survey123 field app would randomly sign users out: BUG-000128933
  • Enhanced PKI authentication support: While support for PKI through SAML has been available in Survey123 for a while, this update brings new enhancements to support PKI authentication at the ArcGIS Enterprise Web Adaptor level. This provides additional flexibility to deploy Survey123 in environments that adhere to this standard. For more information regarding PKI support in Survey123, check this help topic.
  • Windows Store: The Windows 64-bit and 32-bit setup files of the Survey123 field app and Connect can be found from our Survey123 download page. Additionally, starting with this release you can also download Survey123 Connect and the Survey123 app directly from the Windows Store.
  • Addressed multiple issues related to double tap sensitivity: BUG-000124309BUG-000125208BUG-000127278BUG-000109661.
  • Split View on Apple devices: You can now arrange the Survey123 field app in iOS split view.
  • BUG-000125609 ArcGIS Online allows the organization short name to include uppercase characters leading to case sensitive related errors when using the organizations URL.
  • BUG-000127518 Creating a form in Survey123 for ArcGIS with a geopoint question type and esriFieldTypePointZ field type does not allow the feature geometry to update in ArcGIS Online Map Viewer.
  • BUG-000127816 The surveys displayed is changed when multiple languages are set up in the survey.
  • ENH-000125365 Have Survey123 honor the "Remember Me" functionality when using a IWA login from Portal.
  • ENH-000105906 Add functionality for Survey 123 Connect to have a "remember me" option for usernames.
  • ENH-000121154 Support Trimble Rx GPS receivers in Survey123 on iOS devices.
  • BUG-000122130 One page will be automatically added when collecting the survey in the survey123 app created from survey123 web designer with more than one page.

Survey123 website, web app and report services


  • DE-000003535,BUG-000126960 An error is returned when trying to generate a feature report in the Survey123 for ArcGIS website for a survey published using the 'Feature Service' option.
  • BUG-000128390 Surveys created and accessed through the Survey123 for ArcGIS website returns the error message, "Survey does not exist or is not accessible" when special characters exist in question or choice labels.
  • BUG-000128110 GeoPoint question's map for the surveys created using Survey123 web designer (after the recent update) does not appear in Survey123 field app (on both desktop and mobile devices).
  • BUG-000126008 After removing a single choice grid from a group, republishing the survey, and adding it back into the group, any changes made to the single choice grid questions are given identical, generic schema names preventing the user from republishing the survey
  • BUG-000127630 In Survey123 for ArcGIS, when a survey has a geotrace or geoshape question type, the map scale setting is not honored when including a map in the feature report
  • BUG-000126425 Boolean expressions do not work in the Survey123 for ArcGIS web app
  • BUG-000128085 In the Survey123 for ArcGIS website, images in a Note element cause the survey to fail to publish if they are on the same row separated by a space
  • BUG-000128548 The background set for a survey is displayed as distorted in the web form if the “style settings” is set to “pages” and “appearance” for groups is set to “field list”
  • BUG-000124744 HTML markup codes appear at the start of the published survey in Survey123 for ArcGIS
  • BUG-000116598 Survey123 for ArcGIS error 'Privileges of stakeholder role are required to access this page. You're currently in field worker role.' when accessing the survey..
  • BUG-000117843 When using the em dash 'ー' (UTF-8 Enconded \xE3\x83\xBC) in a single line text question, the words are broken up into separate responses in the wordcloud section of the Analyze tab
  • BUG-000125151 The Survey123 for ArcGIS Website does not retain the Layout Element settings (Header and Footer Settings) for a survey if the Survey has been published through Survey123 Connect
  • BUG-000111740 The Survey123 website returns the 404 error message in network traffic when loading a survey in a web browser
  • BUG-000126848 Viewer and Editor roles with the 'feature report' privilege enabled by default are unable to generate a feature report in Survey123 for ArcGIS as the 'create, update, delete content' privilege is also required.
  • BUG-000122896 Surver123 for ArcGIS does not provide a character count on text questions with repeats. 
  • BUG-000129358 Some organizations are unable to publish any surveys in the Survey123 for ArcGIS web app
  • BUG-000125046 A geopoint location is rendered as an empty map image in the exported report from the Survey123 for ArcGIS website when the survey is created from an existing feature service.


Documentation and templates


  • BUG-000128228 Unlisted built-in (reserved) geodatabase field names cause the publishing error with Survey123 for ArcGIS that is returned when using a reserved keyword for a field name, "Error: Dataset not found. Code: 500. Publishing failed."
  • ENH-000127952 Displaying the 'name' field instead of the 'label' field for select_one type questions in Survey123 reports
  • ENH-000128878 Survey123 - Documentation - orderBy Parameter - is missing of examples, case application and a more detailed description for the function
  • ENH-000128477 Improve documentation for Repeats in Survey123 to contain information on the abilities and limitations of nested repeats
  • ENH-000126920 Currently the text for when Configuring Survey123 with a feature service published to ArcGIS...
  • ENH-000127608 Please update Product Life Cycle page for Survey123 to indicate Classic was 2.9 and below and is now retired as of a certain date


Next steps


Survey123 3.10 is already in the making. You can access the latest builds from the Early Adopter Community. Our focus is aimed towards a few critical aspects:


Survey123 field app fix-only update for iOS (for release before end of April 2020):


  • Specifically for iOS, and for specific surveys, you have observed consistent crashes in the Survey123 app. These issues are currently being worked on and we are aiming at releasing an update for iOS to address these issues as soon as possible. BUG-000111086,DE-000003544, BUG-000108085,BUG-000128201,DE-000003543, BUG-000125015,DE-000003368, BUG-000126685. Beta builds with fixes to these issues will be shared through the Early Adopter Community as soon as they are ready.


Survey123 3.10:


  • Mapping enhancements in the Survey123 field app: for quite some time now we have been shipping the Survey123 field app with a Beta feature that lets you bring your own web maps, vector and mobile map packages into the map. We are now finalizing this work, which should be fully supported in the 3.10 release.
  • The Survey123 feature report service is getting ready to see its first major feature update since release. We are working on supporting summary reports where you can bring all or a subset of features in your survey into a single report. As part of this effort, we are also adding new syntax to support statistics within reports.
  • Ranking question: we are working on a new ranking type of question to help you define sortable lists within a form. With the ranking question, end users will be able to express preferences over a predefined list of choices: drag and drop choices to set their order!
  • Finalizing the on-premises setup of the Survey123 website and API.
  • Improving web accessibility in the Survey123 web app.
  • Support for ArcGIS Enterprise in the Microsoft Automate connector.


A complete list of Beta features is available in the Early Adopter Community, as well as user forums and documentation. If you are interested, have a look!

The Survey123 web app JavaScript API is designed to help you embed, style and interact with Survey123 smart forms within your own web applications. At a glance, here is what you can do with this API and a little bit of JavaScript magic:


  • Programmatically embed a Survey123 web form within a web page at run-time.
  • Apply a custom css to the embedded web form to make it look fit within your own web app.
  • Programmatically read and write values into the embedded web form from your own web application.
  • Subscribe to web form events such as onFormLoaded, onFormSubmitted or onValueChanged.


There are many applications for this new API. In the animation below, for example, a form is embedded within a web page used to report the speed of your internet connection. When the page is initially loaded, a big button is shown to help users initiate a quick internet speed test. One the connection speed is estimated, a Survey123 web form is loaded and the output of the speed test is automatically added into the form. At that point, the end user can complete the remaining questions and submit. The whole idea with this is that the logic to measure the internet speed of your connection sits in your web application, but when the time comes to submit data like your location, email contact and internet speed a Survey123 form is used for that. Through the Survey123 web app JavaScript API you can make your web app talk to the form and load the measured internet speed right away to make the process simpler.


Thanks to the Applications Prototype Lab for sharing the above example and making its source code available in GitHub!


You may also want to leverage the Web App JavaScript API to bring Survey123 forms into existing websites. Of course, you can always embed your survey by copying and pasting an embed link, but using the Web App API has the advantage that you can make your form interact with the website and vice-versa. For example, say you want to embed in the website of your city a form to capture incidents or issues that need attention. You can pre-populate certain questions in the form using information gathered from your own website. Similarly, you can feed your website with information entered by the user in the Survey123 while the form is being completed, or when the data is finally sent.



Getting Started (Hello World)


The following is about the simplest code snippet showing the basics of the Survey123 Web App JavaScript API. This sample loads a custom web form into a web page and pre-populates a couple of questions in it.



Lets have a closer look at the code:


  • Line 2: In this line we import the Survey123 web app JavaScript API. The address of the latest version of the API is 
  • Line 5: Your web form needs a container in your web page. Typically, you will want to use a DIV HTML element. You can control the exact size of the the container in your page, although keep in mind that you cannot make it too small or otherwise your web form will not have room to display.
  • Lines 7-14: This is where we create a Survey123WebForm JavaScript object. The constructor requires at least the following attributes:
    • clientId: The client ID is a string that proves that you have explicitly authorized the use of Survey123 web app API from your web page. You need to create the Client ID through the website. Check the Generating a Client ID section later in this article for details.
    • container: This is the HTML element in which you want your web form to be displayed. Typically a DIV.
    • itemID: This is the ArcGIS itemID of your web form. Check the Getting the ItemID of a web form section later in this article for details.

There are a number of optional attributes you can also set. In the example above, we added the defaultQuestionValue attribute to set the default value of a couple of questions.  Check the Web Form attributes section later in this document for a complete list.


Generating a Client ID


To authorize the use of the Survey123 web app JavaScript API within your web application, you must provide a valid Client ID. You can create a Client ID through ArcGIS for Developers  as follows:


  1. Login into ArcGIS for Developers and open the Dashboard.
  2. Create a New Application and switch to the Authentication tab
  3. Add your web application URL and/or domain to the list of Redirect URIs.
  4. Copy the Client ID.



Getting the ItemID of a Web Form


ItemIDs uniquely identify ArcGIS items within your organization. You can find more information about itemIDs in the Where can I find the item ID for an ArcGIS Online item? article. To get the ItemID of your web form:


  1. Login to
  2. Open the Overview or Design tab of your survey
  3. The portion in the URL highlighted in the screenshot below is the itemID.




More details (Web Form attributes)


Here is the list of all attributes supported by the Web Form object.


containerThe HTML element that will contain the web form, typically a DIV.
clientIdA valid Client ID for your domain registered in ArcGIS for Developers
itemIdThe ItemId of the web form you want to load.
portalUrl(Optional) The URL of your ArcGIS portal. If left empty, defaults to
tokenRequired if you work with private surveys.

(Optional) Elements can be set to be hidden, including navbar, theme, header, subHeader.

    For example: ["navbar","header","subheader"]

You can also hide questions within your survey. For example:

    For example: ['field:yourQuestionName']

autoRefresh(Optional) Enable auto refresh the survey after submit successfully. You can set autoRefresh=3 which will refresh the survey after 3 second
defaultQuestionValue(Optional) Lets you populate questions in the form. For example: {field_0: 'value1', field_1: 'value2'}
isDisabledSubmitToFeatureService(Optional) Set this property to true and the web form will not send data to your feature service.
onFormLoaded(Optional) Invokes a callback function when loaded. For example: function({form:Form, contentHeight: number })   
onFormSubmitted(Optional) Invokes a callback function when the form is submitted. For example: function({surveyFeatureSet: SurveyFeatureSet})
onQuestionValueChanged(Optional) Invokes a callback function when values in your form change. For example: function({field: string; value: any; path: string; repeatIndex: number; formId: string})
width(Optional) Takes a number in pixels. Controls the width of the survey although anything smaller than 660 will be ignored.


More details (Web Form methods)


Web Form methods allow you to set the value of questions within your form from a JavaScript function.  You can also use them to programmatically change the style of your form.



Used to set the value of a question, or questions, at run-time. For example:


  'field_1': 'test1',
  'field_2': 'test2'


Used to center the map and set the geopoint value to a given location. For example:







It is commonly used in combination with the Geolocation API.


Used to apply CSS styling to your web form. For example:


  '& .question-label': {
     'color': '#ff0000 !important',
     'font-size': '30px !important'
  '& .form-header': {
     'color': '#ff0000 !important'




  • Hello World: A bare bones sample showing how to embed a web form within a web page.
  • Speed Test: A more elaborate sample written by the Esri Geo Experience Center’s Applications Prototype Lab. It integrates a simple routine to estimate internet speed connection and then uses that estimation to pre-populate a question in a web form.

[Updated March 28, 2020]

[Updated April 3, 2020]

What is changing?


Survey123 version 3.4 introduced the ability in the Survey123 web app (aka web form) to update and view existing GIS features using the mode URL query parameter. Essentially, this query parameter allows you to pass the objectId of an existing GIS feature to preload data into a web form to view or update its contents. More details about use cases and syntax can be found at:



We will be introducing changes to the mode query parameter in version 3.9, replacing the use of objectId with globalId as the means to set the GIS feature record to be updated or viewed. For example:



* [Update March 28,2020] To facilitate migration to the globalId parameter, we will be extending support for the objectId parameter until 3.10.


3.8 and earlier versionsSupportedNot supported
3.9SupportedSupportedUse this version to migrate!
3.10 and beyondNot supportedSupported


Why are we making this change?


The use of globalId to set the GIS feature to be updated is less susceptible to manipulation by end users.


How will this change affect me?


This change can potentially break existing workflows where static or dynamic links are used to update/view existing features using a web form. For example:


  • If you have embedded a web form within a dashboard to edit the selected record from a list element, this change in Survey123 query parameters can break your existing Survey123-Dashboard integration.
  • If you have a custom web map pop-up with a link to a survey web form in edit mode, this change may break your workflow.
  • If you have shared static HTML links in websites, e-mails or by other means, the links may stop loading the data to be updated.


Any survey published prior to 3.9 will continue to work normally and without modification to the query parameter, unless version locking is disabled or the survey is republished with 3.9 or a newer version.  


What should I do about this?


Now that 3.9 is released, it is time to act:


  1. Start now documenting web applications or workflows where you make use of the mode=edit or mode=view URL parameter.
  2. Re-publish your surveys affected and switch your URL calls from using the objectId parameter, to using the globalId parameter.


3.8 and earlier versionsSupportedNot supported
3.9SupportedSupportedUse this version to migrate!
3.10 and beyondNot supportedSupported

We recently applied a minor patch to the Survey123 website, web app and report service. This is a very focused update addressing five issues recently reported.


  1. BUG-000128390 Surveys created and accessed through the Survey123 for ArcGIS website returns the error message, "Survey does not exist or is not accessible" when special characters exist in question or choice labels. Thanks to Jeff Carney and Kanin Sangcharoenvanakul for their Survey 123 web Form Error discussion.
  2. BUG-000128110 A geopoint question added from Survey123 web designer will not render correctly in the Survey123 field app.
  3. Surveys published from Survey123 Connect after January 21 do not render DateTime questions correctly in the Survey123 web app. Thanks to Jônatas Lima Póvoas for reporting the problem.
  4. Surveys published to ArcGIS Enterprise cause the Survey123 Report service to fail if "Include default maps" is enabled in through the Maps settings in Survey123 Connect. Thanks to Kanchana Karthikeyan for reporting this issue.
  5. Surveys published from Survey123 Connect will cause the Survey123 Report service to fail if the target feature layer is missing Editor Tracking fields. Thanks Mervyn Lotter for reporting and helping out with the diagnosis and validation.


For fixes to issues #2 and #3 to take effect, you will need to re-publish your survey.



We have also made available in the Early Adopter Community | Esri Early Adopter Program new updates to version 3.9 via the latest Survey123 3.9 RC builds. 3.9 is scheduled for release in April. We are targeting the inclusion of new features including:


  • Survey update notifications in the field app.
  • Replacement of the Geopoint question type with a new Map question type with support for point, line and polygons.
  • Expanded Survey123 report syntax: Statistics and summary tables.


Check the Early Adopter Community announcements for details.

With every new release of Survey123, we include fixes, enhancements and new features into Survey123.  For the most part, having access to the latest and greatest fixes and features is straight-forward:


  • Survey123 field app: Install the latest Survey123 field app from the app stores.
  • Survey123 website: Reload the Survey123 website in your browser.
  • Survey123 report service: Nothing to do... every time you request a new report, the latest report engine is used.
  • Survey123 Microsoft Automate and Integromat modules: All changes get applied right away in run-time and design modes.


But what about your web forms? Well it depends so that is why I thought it would be worth going in detail over this.


Survey123 web form version locking


Survey123 web forms are version locked by default. That is, a web form (unless specified otherwise) will always use the version of the Survey123 web app that was current when you last published the survey.  This basically means that any new fixes and enhancements we apply to new versions of Survey123 do not take effect over your already published web forms.


We apply version locking by default because we want to make sure your surveys always behave exactly as when you published them, regardless of changes in newer versions of Survey123.  It is true that new versions incorporate fixes and enhancements, but they can also bring unexpected changes that may break your existing surveys. 


Three ways to upgrade your web forms


If you would like to upgrade the version of Survey123 used to render your web forms, you have different options.


  • You can disable version locking in your survey through the Settings tab of your survey. In the screenshot below, you can see that I have a survey that was published with version 3.5. If version locking is enabled, then the 3.5 version of the Survey123 web app will always be used to render the form. By activating the option to 'always use the latest version', the web form will always run on the latest and greatest version.



A handy preview link right by the 'always use the latest version' option is available so you can validate that all looks good before you make a change.  I strongly suggest you always preview your survey to make sure everything behaves as expected.


Choosing to always run your web forms against the the latest version of the Survey123 web app available is tempting, but consider the following:  First, by disabling version locking you are forcing a dynamic upgrade of your published survey to the latest version when the survey is loaded in your browser. We do our best to minimize the impact of upgrading your web forms on the fly, but this could slow down the loading time of your form.  Second, with every new update there is always a chance that something could break. If you disable version locking you lose control over which version of the Survey123 web app will be used to render your form.


  • You can force your web form to use the latest version available of the Survey123 web app by adding the version=latest query parameter to the URL. For example:<your_survey_id_here>?version=latest

Note that version=latest has been added as a query parameter to the URL.  You can combine version=latest with other query parameters as described in Survey123 Tricks of the Trade: Web form URL parameters 


I like to use this technique to thoroughly test out my surveys before I upgrade them to the latest version, but I do not like to share URLs with the version=latest parameter in them because people may accidentally or intentionally remove it.


  • Finally, you can upgrade your survey web form by republishing it.  With this approach, your web form is upgraded to the current version of the publishing tool (Survey123 Connect or Survey123 web designer) you use. By keeping version locking activated, your web form is always cached and ready to go (no on the fly upgrades). You would need to republish it again if in the future you consider that you need to upgrade the web form version.


All in all, I personally prefer to decide when to upgrade a web form. If a web form is working all good, I leave it alone: Don't change anything that works!  In the event that I want to leverage a particular fix, enhancement or new feature in a more recent version, I first validate my web forms with the latest release (using version=latest), and then I republish the survey to upgrade the web form.  Knowing that my web form is version locked and running on the exact version I want gives me extra peace of mind.


Hug Day Release

Posted by ichivite-esristaff Employee Jan 21, 2020

[Updated on January 27, 2020]


Can you tell the difference between a bear hug and a cheek hug? Today is National Hugging Day!  You can't (yet) hug through social media and AI cannot hug (yet). YOU have to hug, you alone. Hugging is good for you. Hugging is good for people you hug. Hug!



Today, we let a new update to Survey123 go free. This release is mostly focused on the reporting capabilities of Survey123. We are adding new functionality to our report service such as report previews, PDF outputs and merging of multiple reports into a single file. This update also brings a good number of fixes for the Survey123 website and web app. Survey123 Connect and the field app have not been updated with this release.


If you are not yet familiar with Survey123 Feature reports, check theUnderstanding Survey123 Feature Reports blog and/or have a look at this 7 minute tutorial video:




Report preview mode


Many of you requested that we add a new preview option so you can generate test reports for free. Authoring good report templates is an iterative process and it is common to generate many test reports before a template is ready. The report preview output consists of a watermarked PDF file. Here is an example:


This new option to generate a preview of the report is only available to the owner of the survey. Once generated, the download of your report preview will start automatically in your web browser.

Please note that selecting content in report PDF previews is disabled.



PDF support added to Survey123 Reports


You can now save your Survey123 reports in PDF format. A new Format drop down has been added, as shown below, so you can choose PDF as your output.



If you plan to generate reports in PDF format, it is highly recommended that you embed fonts within your Microsoft Word template as described in the Embed fonts in Word or PowerPoint - Office Support help topic.  If you do not embed the fonts, your report outputs may not look exactly the same as your template.


[January 27, 2020] The Integromat module has been updated so you can create reports in PDF.


Merge multiple reports into a single file


When creating reports in bulk, you can now also choose to merge all reports into a single file. If the collection of feature reports you want to merge is larger than 512Mb we will automatically split your job into multiple files.



Expanded report template syntax


A number of new functions have been added to the feature report syntax. For example, you can now:


New functionExample
utcOffset. Apply an UTC offset to a DateTime question. This is useful if you want to express time in your reports in local time. Remember that all dates and time values in ArcGIS are always stored in UTC time!${survey_date | utcOffset:"+01:00"}
Apply basic math operators: +, -, * and /.  Use them to perform basic aggregation functions in your report using data from your survey.${boys + girls}
checked. Shows a checkbox to indicate if a particular element has been checked in a single or multiple selection question.  The new checked function replaces the old selected function for this purpose.  The selected function should be used along with conditional (if) statements instead of for showing a checkbox.${defects | checked:"Paint"} Needs paint
selected. In the past this function was often used to add a checkbox into your report when a particular choice in a selection question was checked. While all report templates using selected for that purpose will continue to work, it is strongly recommended you now use this function within conditional statements. Anything shown in between the ${conditional statement}  and ${/} will be shown only if the conditional statement evaluates to true. If you want to add a checkbox to your report, use the checked function instead.  ${if needRepair | selected:"yes"}…${/}
${if favoriteFruits | selected:"apple"}…${/}
countSelected. Count the number of elements checked in a multiple selection question. ${defects | countSelected}
selectedAt: For a multiple selection question, returns a specific selected choice for the given index (zero-indexed). Returns an empty string if the index does not exist.${defects | selectedAt:2}


For more details and additions in this release, check the Feature report templates—Survey123 for ArcGIS | Documentation help topic.


Miscellaneous fixes and minor enhancements


Important note: As described in Understanding web form version locking in Survey123 already published surveys will not benefit from fixes to new releases of the Survey123 web app, unless you upgrade them.  Since this update does not include a new version of Survey123 Connect, use the version=latest URL query parameter to load your survey or disable version locking in your survey.

  • BUG-000126720 Basemap selected for GeoPoint question in Connect for Survey123 is not honored when viewing the survey through
  • BUG-000126537 Non-survey owners cannot edit their submissions through the Survey123 for ArcGIS web App despite documentation stating it is possible to do so. ([Data] Non-owners with both stakeholder and fieldworker privilege cannot edit in Individual Response for Connect surveys).
  • ENH-000117970 The default Admin role in the Survey123 for ArcGIS website does not have the 'Everyone' option available in the Collaborate tab when the organization has the 'members can share content publicly' setting disabled.
  • BUG-000124120 Hide Parameter in Web Form URL fails to hide Survey Fields that are within a group. (Hide questions inside of group of page through URL parameter).
  • BUG-000126428 Adding an image URL link in the Survey Description section causes the survey to fail to publish in the Survey123 for ArcGIS website with an error message, "ObjectStoreException. Unable to add or update item: &lt;item_ID&gt;."
  • BUG-000124617 When the 'appearance' field is set to hide-input for a Geopoint question in a Survey123 for ArcGIS XLSForm, the Easting and Northing values are identical (UTM Coordinates) when the survey is opened from a web browser.
  • BUG-000125399: Time question with value set to now() is not able to render the correct 12PM time in the web form.
  • BUG-000121113 If a select one survey response contains a comma in the name value the value/label will not be printed in a Feature Report.
  • BUG-000115396 The CreationDate method does not include the UTC offset option when generating a report in the Survey123 for ArcGIS website.
  • ENH-000118417 When using the Report (Beta) function on the Survey123 website to display a geopoint, there is no documented method of setting the map extent for the record.
  • BUG-000126329 The Collaborate 'Viewer' settings allowing non survey owners to have the capability to edit their own submitted records are not being honored when attempting to edit in the Data page.
  • BUG-000126582 When entering survey responses for a survey using the Survey123 for ArcGIS website, pressing 'Enter' in a text question launches the computer's camera.
  • ENH-000125299 Add error handling for an extra slash at the end of the Survey123 for Enterprise URL.
  • BUG-000124359 Error "Can not find your location. Please check your browser to ensure that your location is shared." when using the "Find my location" option on iOS devices on publishing a survey using the Survey123 Web Designer.
  • BUG-000122802 Photos missing properties do not display when Custom Report is printed from
  • BUG-000099614 In the Analyze Tab on Survey123 for ArcGIS Hub, DATE values will only be reported if they have same DATE as the initial report.
  • BUG-000121513 Geopoint question device location does not work as expected in Microsoft Edge 41.x and Internet Explorer 11 browsers.
  • BUG-000127348 Submission w/ Attachment fails on SQL Server due to lower case GlobalIDs.
  • BUG-000126959 AttachmentInfos and AttachmentInfo are empty in the Integromat module for Survey123 for ArcGIS when a survey is published or updated in Survey123 Connect for ArcGIS 3.6.127.
  • BUG-000124762 When Creating a Survey using the Survey123 Web Designer with a Note question, the Note does not honor the alignment settings for an image when the survey is viewed online.
  • BUG-000126022 DE-000003375 The USA Topo Maps basemap does not work in Individual Response and Feature Report when location is outside USA.


Next steps


We are finalizing work in the Survey123 Integromat module to incorporate the new Format parameter. This will allow you to automate the creation of PDF reports using Integromat. We are looking at having this ready before the end of the month. We will simply update the Integromat module and add a brief note in this blog post when ready. The Integromat module has been updated with support for PDF output format [January 27, 2020]


From a functional perspective, we also have received requests to expand the report service from feature reports to summary reports. This is also right now in design and we will update our Survey123 Early Adopter Community website as soon as we have something for you to test.  


The next update to Survey123 Connect and the Field app (3.9) is almost ready. We have uploaded the latest Beta builds to the Early Adopter Community website and are looking forward to your feedback before we move to General Release. The main new feature we plan to make available touches on the Notify users a Survey123 form has been updated GeoNet idea.  There are also some quite juicy fixes in this 3.9 release but I leave the details to our Early Adopter documentation on 3.9.


If you are a fan of Survey123 web designer, you should know that we will soon add a new Map question type. The new Map question type will bring support for polygons and lines into the web designer.


For more details on what is cooking for the next updates to Survey123, check the Survey123 Early Adopter Community website.  There are a good number of active projects waiting for your feedback!

I discovered a handy workflow for calling and passing arguments to Python scripts using Survey123’s webhook capability, Integromat, and Google Cloud Functions. The possibilities are endless, but some use cases include:


  • Making scripts available and convenient to users without a Python environment on their machine
  • Calling a script each time a survey is submitted or updated (e.g., perform a field calculation)
  • Update records in a separate feature layer based on survey responses


In this example, I’ve made a simple web form and Python script that checks an ArcGIS Online org for new items and sends a raw list object of these items via email.


This post assumes basic familiarity with Survey123 Webhooks and Integromat. There are great Integromat intro posts from Ismael Chivite here and here.


Step 1: Create a Google Cloud Function to run your script

  1. Go to, log in with your Google account, and follow prompts to begin a Google Cloud Platform trial.
  2. You’ll be provided with a default project titled “My First Project.” From the dashboard of this project, in the Resources pane, click Cloud Functions. You can also go directly to functions at
  3. At the top of the page, click Create Function. Name your function and accept defaults except Runtime, which you’ll change to Python 3.7.
  4. Click the requirements.txt tab, above the code editor pane. This is where you’ll enter any Python modules required by your script that aren’t included in the standard Python distribution. For this example, we will need to add only the arcgis module.Add modules to requirements.txt
  5. Now we add our Python code! Click the tab and paste your code. Be sure to wrap everything in a function, pass ‘request’ as an argument to your function, and assign variables used by the function with request.args.get(‘example’), matching the field names from the Survey123 form you’ll create in the next section. See my example below.
  6. Enter your function name under ‘Function to Execute’ and click Create. It will take a few minutes for your function to deploy.

 Python code for


Step 2: Create and publish Survey123 

Now, let’s create a form to call the Python script.

  1. Open Survey123 Connect and create a new survey with fields for each argument you’ll be passing to the script. These field names must match what you provided to the request.args.get() method in the script – in our case, “startDate” and “toEmail”.Survey123 Connect fields
  2. Publish your survey.


Step 3: Set up a scenario in Integromat and connect a webhook to your Survey123 form

You’ll need to set up two modules in Integromat: The Survey123 module to watch for a new survey submission, and the HTTP module to make a request that calls the script on Google Cloud Functions and passes arguments to it.

  1. Add the Survey123 module to your scenario and connect it to your new survey as described here.
  2. Next, add the HTTP module but leave it alone for now. Connect the two modules:Integromat scenario
  3. Return to your Google Cloud Function, click the Trigger tab, and copy the URL for your function:Google Cloud Function URL
  4. Paste your URL into the HTTP module in Integromat and add a question mark at the end, followed by your first field/argument name and an equals sign, as shown below.http module integromat
  5.  Now grab your first argument from the dynamic fields window by expanding Attributes and clicking the field name:get dynamic field
  6.   Repeat for additional arguments, separating with an ampersand (&). The final URL in our example looks like this:integromat http url

Step 4: Call your script with the survey

  1. Turn on your Integromat scenario (or click Run Once)
  2. Open your survey in a web browser, fill in your arguments, and submit. You just called your script!

The Survey123 Early Adopter Community (EAC) helps you access the latest Beta builds of the software. You can sign in with your existing Esri account and gain access to software downloads, documentation on upcoming features and discussion forums.


The Early Adopter Community is critical to Survey123. It allows the development team to share with you early access to the software for user testing and feedback. This feedback is used to refine new features and fixes before they are made available under general release. EAC offers you a great opportunity to try out your own surveys and workflows with the Beta software and anticipate any issues that may arise in upcoming releases.


We have just updated EAC with new Beta versions of Survey123. Below is a list of some of the Beta features and when we estimate they will be available.

As a general rule, we prefer feedback regarding our Beta releases through the Early Adopter Community Forums. We like to keep discussions in GeoNet for the released version of the software. Keeping things separate avoids potential confusion.


Survey123 Feature Reports (PDF, Previews and Merged Reports)


We released Survey123 Feature Report capabilities back in July 2019. EAC will give you access to the Beta builds of the Survey123 website, which include new options to:


  • Generate outputs in PDF format. We want to make sure this works well with your existing report templates and that you do not have any issues with fonts once you open the PDF on your computer.
  • Preview Report designs, so you can put together your report templates without incurring ArcGIS Online credit costs. The output preview documents will be always generated in PDF format and include a watermark.
  • Merge multiple reports in a single file. This new option is available when you want to generate report files in bulk. When chosen, all your feature reports will be combined into a single PDF or docx output file.

Please note that when generating reports (other than previews) through the Early Adopter Community your account will be charged with credits. Use the preview option if you do not want to be charged.

You can try out all of the above through When testing the new PDF and report preview capabilities, please report your findings (positive and negative) in the new Survey123 website forum in the EAC website. We are targeting late January 2020 for the release of both of these features.


Survey123 Field App (Survey update notifications and more)


Through the Early Adopter Community website you can access Beta builds of the Survey123 field app for iOS, Android, Windows, MacOS and Linux. The Beta build of the Survey123 field app cannot run on the same device as the released version, so you will need extra hardware to test it or remove the released version from the device first.


The latest Beta builds available include support for:


  • Survey update notifications. This work is inspired by our most popular Survey123 Geonet Idea: Notify users a Survey123 form has been updated. This will facilitate having field users more easily refresh their surveys if new updates are available in ArcGIS Online or Enterprise. This feature is planned to be made available in late February or early March 2020. 


  • No more random log outs. This is a fix to an issue some of you have reported where field users would get randomly log out, forcing users to have to type their user credentials again. The fix to this problem is now included with the latest Beta builds.
  • There are also a number of additional features available for testing. Information about the specific bug fixes addressed in each Beta update and new features are detailed in the Announcements section of the EAC website. 


The Beta builds of the Survey123 field app are also useful for you to test your existing surveys. As much as we do our best to ensure backwards compatibility with older versions, your own testing can help highlight issues we may never find on our own.

I work for a local government with an Office 365 subscription that includes Power Automate (aka MS Flow) and I wanted to see what I could do with it. After Zoltan Kovacs posted his 3rd blog on using Power Automate to send an email using HTML from a survey I was talking with my colleague (a developer) who told me that it was possible to generate a PDF from HTML using Power Automate (PA).


Wow! Really? 


It's true. It's possible. There is a convert file action that will convert HTML to PDF. 


convert file


The Survey123 Feature Report generates a nicer output and it includes attachments and its much easier to create a Word doc template than it is to create HTML. My method does not include attachments from Survey123 because it hasn't been exposed to Power Automate by Survey123 yet. My method also requires you to know HTML and CSS because you will need to fiddle with it. You can save a Word document as HTML (two options, more on that later) to get started but I just went old school and typed it out.


Here is the flow. You will notice the second step is cut off. It is a parallel branch that would have been too wide to capture and see it. 


entire flow with renamed steps


I'll explain my steps here and include tips along the way.


Step 1 is where you trigger the flow with your survey. 


Tip: Any step or action you add to your flow can be renamed. Clicking on the 3 dots on the side will show a drop down menu. Rename is one of them. Adding comments is another.


include comments


Step 2: parallel branch where I initialize and set variables inside a switch case operation


This survey records water meter replacements. The choice value is stored with a code. I wanted the report to show the label and not the value. I know that Survey123 has jr:choice-name but I built this survey 3 years ago and I didn't want to change it. I looked at using a SharePoint list to lookup the value but I couldn't figure it out (I felt like I was this close to a solution! but I had to walk away and move on). 


I tried using the If expression as it seemed similar to the If expression in Survey123. However, unlike Survey123 it cannot contain nested expressions.


There is a switch case operation. My solution was to initialize a variable and then use the switch case operation to set the variable to a nice looking label for every value. 



set variable


The reason why I cannot show the entire parallel branch in the screen shot is because I have 4 branches and each branch has 4 switch cases. Two of the switches have multiple cases (17 in one of them!). It is wider than my screen can show when I click into them. 


Tip: Have all of your parallel branches figured out in the beginning because it is currently not possible to add one in later without needing to redo your entire flow. 


Step 3 and 4: Read part 2 from Zoltan Kovacs for how to set this up.


Step 5: Create the HTML file (add step: create file action in OneDrive for Business)


A side note about HTML: It's the trickiest part because … well … it is HTML. While testing I typed the HTML myself because I wanted a simple form.


I did have a Word doc of this form. In Word, if I saved it as web page, opened it in Notepad++ it was over 1300 lines long! If I saved it as a web page filtered it was about 300 lines long. Filtered means it strips out all of the Word tags making it impossible to turn it back into the same Word document again. 


A side note about challenges using the PA user interface: This report I created is not very long. About a half of a letter sized page. However, I was unable to see all of it in the PA interface. One of the challenges with the interface is that the dynamic content is in a floating window all of the way down at the bottom right.


dynamic content


It doesn't follow you as you scroll up. If you want to insert the content you have to mouse click exactly where you want it, scroll down, click on the content and then scroll back up to see if it put it where you want it. If you didn't mouse click exactly (even if you think you did) it will appear at the top of the file content. While it is possible to click on the dynamic content and drag it up through the file it is slow and it may need to be done multiple times to get it where you want it.


The next screenshot is the beginning of the HTML. The folder path is where the HTML file is saved in OneDrive for Business. This is one of the connections you need to set up in advance. I believe you cannot go deeper than one folder off of the root folder.


Tip: I found that it was possible to insert code in the HTML while using Notepad++. For example, the dynamic content for anything from Survey123 is triggerBody()?['feature']?['attributes']?['field name']. In Notepad++ I used

@{triggerBody()?['feature']?['attributes']?['field name']}.  Once it was copied into the PA window it changed into the normal looking green dynamic content.


Tip: I'm using inline CSS but it is possible to reference an external stylesheet. I have not tried this yet.


The file name can be a dynamic value. I was never able to figure out how to do this in Integromat. The green icon with the checkmark is coming from the survey. In this particular case it is the service address.  I added .htm


create html 1


PA uses different colors for dynamic content. So far I've seen green for Survey123, blue for the built-in functions used to generate the time stamp and purple for the variables I set.


dynamic content colors 1

dynamic content colors 2


Step 6: Create the PDF file


When you create the file in Step 5 from above the dynamic content will now include ID. It is all that is needed for this step.


create pdf file


Step 7: Save the file to OneDrive


When the HTML file is created in Step 5 it actually saves the file to OneDrive. That doesn't happen in Step 6. You have to explicitly save it using the Create File operation (I've already renamed it in this screenshot). Choose the folder and add the file name and file content from the dynamic content window. 


save pdf file to onedrive

save pdf to onedrive using dynamic content


Step 8: Send email (V2) preview


I didn't really have to send an email to myself with the attachment as it was saving it to OneDrive. It was part of my testing.


send email


I went through a lot of trial and error and Google searches a couple of weeks ago figuring this out even though I know (through the early adopter program) that a PDF option is coming to Survey123.


I'm a GIS specialist who dabbles in the development world. I'm no Power Automate or webhook expert. There is probably a different way to do this but I wanted to share this with the community. It might inspire others to find a different solution or be inspired to try something new.


p.s. I finally finished writing up this post and I've already found a possible alternative to using HTML!

[Updated Dec 18]


One more update to Survey123 to close out the year! A day like today in 1901 Walt Disney was born. Good opportunity to remember him!


Snow White and the Seven Dwarfs, Pinocchio, Dumbo, Bambi, Cinderella, Peter Pan, Sleeping Beauty, One Hundred and One Dalmatians, Mary Poppins, The Jungle Book... Walter Elias Disney was a visionary. He brought animated cartoons to the next level, introducing new techniques, modernizing classic fairy tales and synchronizing music with his creations. He truly transformed a marginal form of communication into an entire new industry. Nobody has won more Oscars (22) or being nominated so many times (59). A pioneer of the American animation industry.


The 3.7 release is now available across all supported platforms. You can download this update from the iOS and Google Play stores or from our Survey123 Resources page. The build numbers are 3.7.55 for the field app and 3.7.59 for Connect. The Survey123 web app has also been updated.


This is a minor, yet important update, as it brings a handful of critical enhancements and fixes.


Inbox Enhancements


A lot of work in this update went into making sure you can work with the Inbox more reliably, faster and with many more records. The Survey123 field app Inbox allows you to update existing GIS records. If you are not familiar with the Inbox, I suggest you take a quick look at this video:



For more details, see the Prepare for editing existing survey data—Survey123 for ArcGIS | Documentation help topic.


With this release, the performance of the Inbox has been greatly improved, allowing you to more quickly download records onto your device; twice as fast as before! The Inbox can also now handle many more features. With this update you will be able to comfortably work with a few thousand records in your Inbox, even if you are downloading complex lines, polygons or have many related records. Overall, the Inbox is now much faster and less memory intensive. You will note a great improvement making this feature more reliable, particularly on low-end devices.


Based on our own tests, we can define an upper limit for the Inbox around ~40k (for points) and ~8k (for lines or polygons). Having said this, the intended and practical limit of the Inbox is lower; around a few thousand records. The philosophy of the Inbox is that of a 'to do' list where you can download surveys for field-users to process. For example, in an asset inspection workflow, each of the records in the Inbox, would represent an inspection for the end user to complete. You will not want to have the Inbox populated with every asset you have. Instead, you will want to use a filter to have the Inbox show only assets where inspections are due. You can apply Inbox queries using the username of the logged in user to tailor the Inbox contents for every person in your field crew. For the benefit of field users, try to keep your Inbox light, only showing records to be processed. Stay away from using the Inbox to download every record in your dataset, particularly if you have many tens of thousands of records.


Enhanced Numbers and Calculator appearances


Work with the numbers and calculator appearances was initially triggered by data-loss issues reported through GeoNet (Using Numbers Appearance Type Sometimes Will Not Store Value in Field). We addressed this issue and also took our time to revisit the usability of these controls.


The numbers and calculator XLSForm appearances are designed to accelerate data capture, providing specialized keypads that replace the generic screen keyboard provided by the operating system in your device.


As their names suggest, the numbers appearance will show a numeric keypad, and the calculator appearance will show... you guessed it: a calculator. These specialized keypads are also shown close to the question on which the data will be entered, as opposed to the bottom of the screen. This allows for faster data entry.


Throughout this release we performed many usability tests in various representative forms and against multiple form factors and devices. We refined the look, feel and behavior of these keypads with a focus on making data capture more efficient and intuitive.  If you have used these keypads in the past, you will notice a noticeable improvement. If you are new to them, you may want to give them a go!


You can use the numbers and calculator appearances with integer, decimal and text questions. To learn more, see the Appearance—Survey123 for ArcGIS | Documentation help topic.



 Geode sub-meter GNSS receivers are now supported


With this update we are adding support for Geode sub-meter GNSS receivers from Esri Partner Juniper Systems. The Geode receiver is compatible with Windows, iOS and Android devices. You can learn more about how to connect the Survey123 field app to an external GNSS receiver through Marika's Direct GNSS external receiver support in Survey123 3.3 blog post. On top of support for Geode, Survey123 also works nicely with the Juniper Systems Mesa 2 rugged tablet (available with either Android or Windows operating systems).


External GNSS receivers, such Geode, allow you capture sub-meter accuracy location data. Additionally, using XLSForm expressions you can easily use location metadata from the device to power data validation rules as well as to simply store the metadata for further analysis in the back-office.



Check out the Survey123 Tricks of the Trade: XLSForms and location quality blog post or Pulling data from geopoint questions to get the best out of your Geode with the Survey123 field app.


Other fixes and minor enhancements


This update includes a lot more other good fixes and enhancements. I wanted to briefly highlight a few:

Survey123 web app (aka web form)


Fixes to Survey123 web forms apply to newly published surveys. If you have an existing web form already published and want to benefit from these fixes, you can re-publish your form.


  • BUG-000126543 - Encountering error "Failed to submit. - Cannot set property 'z' of null' when attempting to submit survey in edit mode (error occurs when submitting a record to a survey which created on top of a standalone table).
  • BUG-000111892 Location for a Geopoint question can not be selected in a Survey opened in the browser of an iOS 10.3.3/10.3.2 device.

Survey123 Connect and Field App


  • BUG-000127248 - Location Expressions in watermarks display full JSON object [Updated Dec 18]
  • BUG-000115279 Hosted feature layers created from Survey123 Connect, do not produce shapefiles once exported with valid/visible geometry.
  • BUG-000102165 The default values of non-relevant questions are not preserved when the values are configured with a 'relevant' expression in Survey123 Connect for ArcGIS.
  • BUG-000125142 Survey123 for ArcGIS gets stuck at "Getting Service Information" when trying to submit a survey over VPN after the survey had been open for over 10 minutes and the connection to the internet or VPN have been disconnected during this time.
  • ENH-000115846 Review how Survey123 makes query requests from the Inbox to increase performance.
  • BUG-000116741 Survey123 Field App looks like it's frozen when refreshing Inbox with many records (more than 1000).

  • BUG-000123911 After increasing the maximum feature count for a feature service, Survey123 3.5.164 for iOS crashes and can't sync more than 1000 records to Inbox.
  • ENH-000119205 Provide the ability for Survey123 to load more than 1000 records in the Inbox.
  • BUG-000125947 Microsoft Surface Pen is incompatible with the Survey123 field app.
  • ENH-000119711 Add survey version to Survey Summary page.
    • The version number of your survey, as described in the settings worksheet of your XLSForm, will be displayed in the survey details page in the Survey123 field app.
  • ENH-000120747 Use appearance to enable/disable regional formatting (thousand separator) for a question.
    • As of this release, no thousand separators will be automatically added to your integer and decimal questions. The thousands-sep appearance can be used to add thousand separators to decimal questions.
  • Various UX enhancements to the map control when editing the geometry of geotrace and geoshape questions.
  • Survey123 Community pane is now hidden in Connect. A Community tab has been added.



  • BUG-000115321 Survey123 Connect. The Cancel button is not translated in the 'Select your active ArcGIS Portal' window in Survey123 Connect for ArcGIS 3.0 which is installed on German operating system (OS).
  • BUG-000115322 Survey123 Connect. The "Close" button is not translated in the "About Survey123 Connect for ArcGIS" window of the Survey123 Connect 3.0 which is installed on German OS.
  • BUG-000098942 Survey123 Connect: Untranslated "Show Details...", "Hide Details" and "OK" buttons when validating input.
  • ENH-000121448 Survey123 Field ap. For time and dateTime questions, the placeholder words for 'Date' and 'Time' should be displayed in the chosen language.
  • BUG-000126692 Calculation field returns the error message, "Invalid Number" on validation in Survey123 Connect for ArcGIS on French operating system.




  • ENH-000118417 When using the Report (Beta) function on the Survey123 website to display a geopoint, there is no documented method of setting the map extent for the record.
  • ENH-000126633 Addition to the Survey123 documentation: While Survey123 can perform calculations on text fields, they will not be honored in the Survey123 webform; Use concat() or join() instead.


Next Steps


We have a number of new features and enhancements lined up for upcoming releases. If you want to know more about them, join our Survey123 Early Adopter Community (EAC). You will find documentation about on-going work, forums for your feedback and of course, the Beta software.


Available for testing now through EAC:


  • Survey123 Feature Report enhancements: PDF output and a new preview mode to generate free PDF watermarked outputs. 
  • Survey123 Web Form JavaScript API: A straight-forward JS API for web developers to embed, style and interact with Survey123 web forms within their web applications.
  • New map capabilities: Support for mobile map packages, web maps and vector tile packages in the Survey123 field app.
  • Windows setup for the Survey123 website and REST API (for Enterprise users).
  • Support for custom JS functions in the XLSForm pulldata function (Survey123 Connect and Field App): Embed custom JS code in your XLSForm expressions.
Check out Part 1 and Part 2 of the series.

In the final part of this series we'll see how to set up an email template for our webhook containing dynamic elements from the survey data and where to access additional webhook settings.


The steps below build on the webhook started in Part 1 & 2 but can be applied to any other webhook.

1.  Click on Add an action under 'Convert time zone' of the If yes branch of your condition.No alt text provided for this image
2.   Search for ‘send an email’ and select the action from the result list. No alt text provided for this image
3.   Complete the To and Subject fields (you should be able to search for your O365 contacts). No alt text provided for this image

4.   Compose the message


What formats and options do we have to include different content? By default, your message is sent as plain text - no hyperlinks or bold/coloured text, but you can include dynamic content like your converted time and values from your submitted survey data. What if you want more?


At the bottom left of the Send an email step, there is an option called Show advanced options. Hidden here you have the availability to switch your email format to HTML (and include HTML formatting tags to change the look of your email), send the email on behalf of someone else, add attachments, set CC and BCC recipients, set the importance of your message and so on.
No alt text provided for this image
That's general formatting out of the way, so we can now focus on including dynamic content in our message template. The following example will add a hyperlink to a web map that will show the location of the reported close call when it's clicked on. We will use a web map application that is shared with the relevant AGOL group(s), thus notified people can see the reported close call in a map.


The web map application to use may contain many other layers and we only want to show the one that contains the survey data and want to zoom in onto the close call location. How do we do this? Documentation to the rescue! The online help for Web AppBuilder for ArcGIS has a section about using URL parameters - we just need to have a look at the following sections:
  • Open a saved app
  • Set layer's visibility
  • Query a feature


Using the information from the help we can construct the url:


https://<your portal url>/apps/webappviewer/index.html?id=<itemId>&showLayers=<layerID>&query=<layerID>,<queryField>,<queryValue>

Where to find the values required?
  • itemId: Open the item's page in AGOL and look at the end of the URL in your web browser or scroll down to URL on the item's page and copy the hash value.


No alt text provided for this image


  • queryField: this is the field from your layer to use for the query. (We use the OBJECTID in our example.)


  • queryValue: value coming from your survey data, so your link is dynamic and will work with any close calls. (For testing purposes you can use a static value.)


It is highly recommended to test your URL in a web browser to make sure your web map application loads with the layers you need and shows the queried feature. It would look something like this:,OBJECTID,95 


Once the URL is tested and you are happy with the results, it can go in to the email message with the rest of the dynamic content (change to 'Yes' under Is HTML first in advanced options). An example can be seen below.


No alt text provided for this image


The sent email would look like this: 


No alt text provided for this image


Clicking on the hyperlink opens the web map application, pans to the feature and displays a pop-up:

No alt text provided for this image


With using dynamic content in custom functions in the body of your message you can create a template that could be dynamically updated with the correct close call reason for example: No alt text provided for this image


Additional webhook settings on the Survey123 website

Most of your webhook settings can be controlled in your Power Automate (aka MS Flow) account, but there are a few settings that can only be accessed on the Survey123 website.


1.  Open your web browser and go to


2.  Log in and find the survey with the webhook in question


3.  Click on the ellipsis (...) button and select Settings

No alt text provided for this image

4.  Click on Webhooks on the left-hand side to see all webhooks for your survey


5.  Click on Edit (the pencil icon) under Operations to see more details No alt text provided for this image

6.  On the new page you can make changes to your webhook:

  • Edit its name
  • Change when it should be triggered: new records submitted, existing records edited
  • Event data: information included in the payload. Hover over the grey '?' icon after each item to see the information they include
  • Turn the webhook off or back on


No alt text provided for this image

NB: Changing the payload URL can break your webhook, only do it if you are sure you know what you're doing.



In this series of articles you learnt how to

  • Create a new webhook in Power Automate (MS Flow) for a Survey123 survey
  • Add conditions, convert and format the survey time
  • Send a notification email with dynamic content as part of the webhook
  • Find additional settings for your webhook


I hope you enjoyed the series! Feel free to share the articles with your network, leave feedback or message. 

You can download the article series in PDF format from here.

In this blog post I will explore a handful of XLSForm techniques to help you better control the organization and layout of questions within a form. You will learn about groups, grids and pages, but also other tricks to refine the size, placement and look and feel of questions within your form.



Groups: XLSForm Basics

Groups organize questions into sections, helping users more easily navigate complex forms.Our Survey123 for ArcGIS: Using Groups to split your survey into sections - YouTube  video is about the quickest way there is to learn the basics of XLSForm groups. I strongly suggest you watch it, it's only 2 minutes long.



As described in the video, you can create sections in your form by enclosing a set of questions within a begin group/end group block. You need to specify a value in the name column of the begin group row, and this name must be unique. If it helps you navigate the spreadsheet, you can also add a name to the end group row, but it is not compulsory.


texthh_idHousehold ID
begin grouphh_groupBasic Household Information
geopointhh_locationGPS Location
hiddenhh_location_acHorizontal Accuracy
end group


You can add as many groups as you like to a form, and you can nest them too: you can add groups within groups!


On occasion, you may want to display groups collapsed and let the end-user expand them if needed. This can be achieved by setting the appearance column to compact.


It is not possible to dynamically expand or collapse a group with an XLSForm expression.

Use the compact appearance to make your group appear collapsed by default.



Formatting Group Headers


Since groups are fundamentally used to help users navigate long surveys, it is important to take pride in the headers. The group headers, if formatted appropriately, can really make a big difference for people.

The font of group labels by default is a bit bigger and bolder than the labels of questions. This helps the group header stand out. Using HMTL formatting within the label column of the begin group row, you can bring your own style to the group header. For example, you can center the label in the screen, change its color, and size.


In the example to the right, the group headers have been given different background colors to help users navigate more quickly between them. Note that the first two groups, in red and blue, are collapsed but users can choose to expand them.


The Style your survey—Survey123 for ArcGIS | Documentation help topic shows the most common HTML tags that you can use to format your labels. When setting colors, you can use either their HTML code name or their hexadecimal representation. At W3Schools you can use the handy color picker for HTML colors. All the properties described in the documentation are supported in the Survey123 mobile and web apps except for the background color, which is only supported in the field app. 


The next XLSForm sample shows the syntax for defining the background color of the group header.


Body bgcolor is only supported in the field app. Webforms will ignore this property.



texthh_idHousehold ID
begin grouphh_group<body bgcolor="#C00000"><font color="white">Household Information</font></body>
geopointhh_locGPS Location
hiddenhh_loc_acHorizontal Accuracy
end group


Dynamic Labels for your Groups


When working with labels for your groups (and questions, actually), remember that on top of the formatting syntax described above, you can also dynamically change the label content. For example, say you have a health household interview survey where we you need to capture all symptoms detected in each of the household members. You can present the symptoms group with a label that matches the name of the household member for which you are capturing the data. This could help eliminate confusion. Below is the actual example. Look how the group header in black changes depending on the household member name entered.



Check out Understanding Dynamic Labels in Survey123 for ArcGIS to learn more about this technique.


Visibility of Groups

One final note on groups relates to their visibility within the survey, which is controlled through the relevant XLSForm column. If an expression written in the relevant columns evaluates to true, the group is shown, otherwise it is hidden to the user. 


A common bad practice with form design consists on repeating the same relevant statement to a large collection of consecutive questions. This slows down your survey, because the same expression needs to be evaluated again and again for each of the questions. If a sequential set of questions shares the same relevant statement, it is good practice to group them and apply the relevant expression to the begin group row only. If the group is relevant, all questions within the group will show. If the group is not relevant, all questions inside the group will be hidden. There is no need to duplicate the relevant expression again and again.




Introduction to Pages


Pages are particularly useful when working with large forms, helping you logically organize your questions and giving end users a sense of progress across the entire survey.

Even for smaller surveys, pages can be useful. In the example below we have a Special-Use application permit form.  I added a welcome image and text on the first page to create a cover for the form. Note that the first page does not expect any input from the user. It is just a welcome page, or cover page to the survey. Next, I organized the actual questions within my form into pages, giving each page a descriptive title at the top. As users move from page to page, a progress bar at the bottom shows how close they are to the end of the survey.



In the Survey123 field app, users can easily move through pages in the form one by one. Alternatively, a page menu lets users jump to any of the pages in the form with a simple selection. In the example shown below, the page menu helps the user jump from page 3 to 32 with just a couple of taps.



Pages: XLSForm basics


If you want to add pages into your form, firstly you need to set the style of your XLSForm to pages. This is done through the settings XLSForm worksheet as shown below.


Zika Household Surveypages


Once the style is set, add one group for every page you want and set the appearance of the group to table-list. For example


texthh_idHousehold ID
begin grouphh_groupHousehold Informationtable-list
geopointhh_locGPS Location
hiddenhh_loc_acHorizontal Accuracy
end group


When working with the pages style, it is good practice to have all questions within a page. That is: make sure all your questions in the form are within an existing group with an appearance set to table-list. If you leave questions outside of a page, you will get erratic behavior across the web and field apps where a single question may appear on every page.


You can combine groups and pages. That is, you can include groups within a page. Groups do not become pages unless you set their appearance to table-list.


All the header HTML formatting tricks described for groups above, also apply to pages. The same goes for the behavior with the relevant expressions. You can hide pages by using relevant statements, however keep in mind that the behavior across the web and field app is different. In the web app, non-relevant pages will be truly hidden, you will not even see them in the page navigator controls. This will cause the total count of pages in the page navigation control to vary as pages become visible or hidden. In the case of the field app, as of version 3.7, the pages will still show in the page navigation control, but will be shown blank. This is a known issue (BUG) in the field app.

Hidden (non-relevant) pages in the field app will be shown blank. This is a known issue as of version 3.7.





Grids: Introduction

Typically, questions within a form are arranged to take the full width of the screen. It is possible however to arrange multiple questions side by side using custom grids (theme-grid in XLSForm jargon). This is particularly useful when you are designing a form for use on a tablet.


With this type of grid layout, you can maximize the number of questions shown within the width of screen, reducing the need for users to scroll up and down. Grids can also help you mimic more closely the look and feel of legacy paper forms. Copying the layout of paper forms is not necessarily a good idea, but in some cases achieving some level of resemblance can make nostalgic users happier.


In the example shown to the right, you can see how questions can be arranged side by side. Crafting such a survey, defining exactly the placement of questions takes some thought and trial and error, but the experience it provides to the end user is significantly better than with a regular layout. This type of design is generally put together with a specific form factor in mind. That is, you design your survey for a particular minimum screen size. If a grid design like the one shown is loaded in a smart phone, the form is not going to look right. I have seen some people creating two flavors of the same survey: one for tablets and one for smart phones.  It clearly adds an overhead during design, but if your survey questions are not going to change much it is a good thing to consider.


The theme-grid style is not supported in the web form. It is only supported in Survey123 Connect and field app.



Grids: XLSForm Basics


To arrange questions in a grid layout, you first need to set the style of your survey to theme-grid. This is done in the settings sheet of your XLSForm.


My Surveytheme-grid


Once the theme-grid is set, all groups within your survey will contain questions using a four-column grid layout. You can change the number of columns in a grid by simply adding the w (as in width) property to the appearance column of your group. For example, w2 means two columns, w8 means eight columns.


texthh_idHousehold ID
begin grouphh_groupHousehold Informationw2
geopointhh_locGPS Location
texthh_zipZIP Code
end group


Unless specified otherwise, questions within a group will always take one column of the grid. In the example above, the GPS Location and Address will be placed side by side in one row, and the City and ZIP Code will complete a second row.


Using the w property for the individual questions within the group, you can choose how many columns you want each question to take. In the example below, I gave two columns (one full row, since the grid has two columns) to the GPS Location question, and another full row (two columns) to the address. I then arranged the City and ZIP Code questions side by side giving them a w1 appearance.


texthh_idHousehold ID
begin grouphh_groupHousehold Informationfield-list w2
geopointhh_locGPS Locationw2
texthh_zipZIP Codew1
end group



You will also note in the screenshot above that the Household ID question is taking the full width of the screen. That is expected. When using the theme-grid, questions outside of a group always get rendered as usual, taking the full width of the screen.


Grids: A few extra tips and things you should know


  • Survey123 Connect includes a handy XLSForm sample called Grid Style Groups. It shows some advanced techniques, including arranging repeats and geopoint questions side by side, combining pages with grids, etc.



  • Working with grid layouts gives you a lot of flexibility, but mastering it takes time and trial and error. Always test your designs on a mobile device that you are targeting to make sure things look as you expect.
  • Do not expect the grid layout, or questions within a grid, to automatically adjust to the size of the screen. If you do not give enough space to your questions, they will look ugly. For example, in practice, you can't work with more than 2 columns on a smartphone. Even when working with 2 columns you need to be careful when working on small screens: you need to keep the labels of questions and choices short and avoid question types like geopoint or dateTime which tend to take more space. Do not take this the wrong way, you can use 2 columns in a smart phone, but with caution.
  • I know I said this before, but I will say it again: the theme-grid is not supported in the webform. It is only supported in the Survey123 field app.
  • You can combine pages and grids. Simply set the style of your form as follows:


My Surveytheme-grid pages


  • When using theme-grid, questions outside of a group (grid) will always take the full width of the screen.
  • If you do not define a width (w parameter) for a group, the number of columns in the grid will be four (as in w4)
  • If you do not define a width (w parameter) for a question within a group, it will default to w1.
  • Non-relevant questions will still take space in your layout. If a question is non-relevant, you will see an empty space in your grid.
  • Be careful with or_other. If you use a select question with the or_other option, your question will always take one extra cell (column). This is in anticipation that the end-user selects the 'other' choice. In that case, a new free text question appears, taking the extra space.
  • You cannot apply a width parameter to a repeat, but you can apply it to a group within a repeat.  If you want to learn how to arrange repeats side by side, have a look at the Grid Style Groups XLSForm sample in Survey123 Connect.
  • The table-list appearance does not work in combination with theme-grid or pages.
  • The body::esri:style XLSForm column can help you refine the height of questions. This can be useful, particularly when working with the theme-grid. For example, if you put a text and a geopoint question side by side, the layout will show unbalanced, because the text question by default is not as tall as a geopoint question. You can change the height of geopoint, geotrace, geoshape signature and multiline text questions. Learn more at Esri custom columns—Survey123 for ArcGIS | Documentation 



When using the body:esri:style column, keep in mind that some properties are not compatible with theme-grid. For example, borderColor is not supported (do you need border colors? If so Vote for this GeoNet idea), and repeats inside of grid style groups do not support backgroundColor either.