Skip navigation
All Places > Survey123 for ArcGIS > Blog > Author: ichivite-esristaff
1 2 3 Previous Next

Survey123 for ArcGIS

105 Posts authored by: ichivite-esristaff Employee

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]

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.


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?


In anticipation of the 3.9 release (tentatively planned for April 2) we recommend that you prepare for this change:


  1. Start now documenting web applications or workflows where you make use of the mode=edit or mode=view URL parameter.
  2. Once 3.9 is released, your existing surveys and links should continue to work without change, unless you have disabled version locking in your survey.  You will want to have a plan to adjust your URLs to be using globalId or otherwise things will break as soon you re-publish your surveys. Once 3.9 is released your existing surveys and links will continue to work even if you use the objectId parameter. However, we strongly recommend you switch to using the globalId parameter. This will eliminate any chance of breaking changes once the 3.10 release, where the objectId parameter will no longer be supported, is made available.


To make the change, once 3.9 is released, you will need to change the URLs to use globalId instead of objectId and also republish your surveys from either Survey123 Connect 3.9 or Survey123 web designer.


A Beta version of 3.9 is already available for testing through the Esri Early Adopter Community website. 

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!

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.

[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.

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.

The 2020 Esri International User Conference is still eight months away, but the deadline for submitting presentation abstracts is approaching fast in November 8!   You do not need to have a fully developed story to submit your paper. A brief abstract describing what you intend to present is plenty. We are looking for inspiring stories showing how you are using #Survey123 to make a difference in your organization.


User Presentations


Every year many dozens of users present at the Esri UC. Definitively a great opportunity to share work with your peers. We all learn when information is shared! You can check the Recent Proceedings from Esri events to see what people have shared in the past.


Gidelines to submit your abstract for the 2020 UC can be found at Call for Presentations | Esri User Conference 


In short:


  • Author/Presenter name(s)
  • Author/Presenter name(s)
  • Presentation title (10 words or fewer)
  • Company name
  • Complete address, phone, and email information
  • Brief presenter biography (25 words or fewer)
  • Abstract (500 characters or fewer, including spaces): Do not include information in your abstract that will not be in your presentation.
  • Keyword set (list only 3–5 keywords): Keywords are used to organize presentations into appropriate sessions, so choose words that clearly describe the main ideas of your work.



Become a Sponsor


Be aware that user papers and presentations must be noncommercial. If you plan on advertising a product, service or company, there other venues for you. You can Become a Sponsor or Exhibitor | 2020 Esri Partner Conference As a sponsor, you can have your own booth in the Showcase area, collaborate to put together Special Interest Groups, etc.





The Survey123 Early Adopter Program (EAP) 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 Program is critical to Survey123. It allows the development team to share with you early cuts of the software feedback can be gathered. This early feedback is used to refine new features and fixes before they are made available under General Release. The EAP offers a great opportunity for you to try out your own surveys and workflows with the Beta software to anticipate any issues that may arise in the upcoming releases.


We just updated the EAP with a Beta version of Survey123 3.7, which is planned to be made available in December this year. Not all the new features and work you see in the EAP will make it to 3.7.Only features that have received positive feedback make the cut for general release. Below is a list of some of Beta features for which we want to actively gather your feedback, and some thoughts on when we estimate the features will join the production release of Survey123.


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


Survey123 Feature Reports


We released Survey123 Feature Report capabilities back in July 2019. The Early Adopter Program will give you access to the Beta builds of the Survey123 website, which include:


  • A new option 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.
  • A new option to generate Preview Reports, so you can design your report templates without incurring ArcGIS Online credit costs.

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

When testing the new PDF and report preview capabilities, please report your findings (positive and negative) in the new Survey123 website forum in the EAP website. We are targeting 3.7 for the release of both of these functions.


Survey123 Field App


Through the Early Adopter Program 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 off the device first.


Our 3.7 release is mostly focused on bug fixes and performance improvements. Information about the specific bug fixes addressed in each Beta update are detailed in the Announcements section of the EAP website. Some of the main areas of work include:


  • The numbers and calculator appearances went through an entire overhaul. The main goal of this work is to address data loss issues reported. We also revisited the overall user experience and came up with a new design to accelerate data capture. We believe we got the data loss issue completely resolved. Can you prove us wrong? Your feedback regarding the new look and feel and usability will also be welcomed.
  • Inbox performance improvements. Our own tests show pretty substantial improvements in terms of memory consumption and speed. This means a better user experience and reduced chances of a crash, particularly on low-end devices. We want you to put points, lines and polys to the test in the Inbox, particularly when working with related records. We are not looking at the Inbox as the means to load 10K records ion your device, but working with a few hundred and even 1000 or 2000 should be now much smoother.
  • Added support for Geode external GNSS receivers.


The features above are planned for our 3.7 release. We are actively working to address random logout issues in the field app. It is our goal to upload new Beta builds so this networking issues can also be validated through the EAP.


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 not to break backwards compatibility with older versions, your own tests can highlight issues we would never find on our own.


Survey123 Web Form JavaScript API (New)


  • This is for any JavaScript developer looking to embed Survey123 forms within a web application. Using this API you can easily have the form interact with your own web app. You can apply your own CSS styling, calculate questions and hook to web form events to make your web app and survey work like one.


This is the very first time we expose this feature through the Early Adopter Program. We are initially aiming to release in early 2020, but as usual, the ultimate release date will be dictated by your own feedback through the Early Adopter Program.


On-Premises Survey123 setup (Updated)


  • A Windows-only setup for those of you who want to deploy the Survey123 website and Survey123 REST API locally in your own on-premises environment.


We have had our On-Premises Survey123 setup available in the Early Adopter Program for some time. We are progressively making adjustments and improvements driven by your feedback. Currently, the beta version is ready for anyone who wants to test the website and API locally while keeping a connection to the internet available. If you plan on deploying in a completely disconnected environment (with no access to the internet), keep in mind that Survey123 Connect will not be able to work in that environment (the website and API will).


We are aiming towards a release of this feature (subject to positive feedback) within the first half of 2020.


Standard Map Types


  • Standard map type functionality was introduced in 3.6 as a Beta feature. This is the only Beta feature included in the released builds of the software.  Standard map type functionality needs to be explicitly activated in Connect and the field app, allowing you to work with web maps, mobile map packages and vector tile packages. 
  • Please note that our Beta builds in the Early Adopter Program do not include any new work in this area when compared with the 3.6 release. For this reason, if you are testing this feature you may want to wait for upcoming updates in the Early Adopter Program.



Other topics


You will find other Beta features such as how to use custom JavaScript functions in the field app or how to work with the Survey123 Feature Report service REST API.

Camera systems can help make homes and businesses safer. This technology has become cheaper and more accessible to consumers than ever before. As these systems multiply, they have become an important tool for capturing evidence of criminal activity in our communities. But with so many cameras it can be hard for police to know where these cameras are located or who to contact for access.  


Camera registration programs are a new initiative many police departments are introducing to enlist the communities help in crime fighting activities. These programs allow citizens and businesses to register their surveillance cameras with the local police department. Registration in these programs gives police permission to access footage from these cameras if a crime takes place nearby, which can provide much needed evidence in support of investigations.


Registering a camera does not provide police remote accessed to the camera or a live video feed, but it does give them a good database of security cameras in the area without having to go door to door to solicit this information.


By using the Survey123 for ArcGIS, police departments are easily able to setup a voluntary camera registration form that citizens can use to share the location, characteristics and contact information of private surveillance systems.


There are a number of Voluntary Camera Registration forms built with Survey123 out there. For example:



This article describes how to create your own Voluntary Camera Registration form using Survey123 for ArcGIS. If first explains how to design and publish the form, then provides tips to keep gathered information safe, to prevent unauthorized access. The last sections briefly discusshow you can include a link, or embed the form within a website, social media, etc.


You will need an ArcGIS Online account with publishing permissions (Creator User Type), and about 45 minutes of your time to follow instructions in this article.


Designing your form


To create a new form using Survey123 for ArcGIS, you will need an ArcGIS named user account with permissions to create content and publishing feature services in ArcGIS. If your organization does not have ArcGIS Online yet, you can create an ArcGIS Trial | Free 21-Day Trial subscription for free.


Before you start, it is best to spend some time figuring out what questions you want in your form.  Some of the examples above (St Charles, Redlands or Marietta) can serve you as inspiration.


Try to keep the form simple.  Write down your questions on paper and think carefully about the exact wording you want to use. Once you have your draft form design on paper, run it through a small group of colleagues and incorporate feedback. Once you have some consensus, it is time to build a first iteration with Survey123.


Next, purely as an example, I will provide step by step instructions that you can follow to learn basic techniques to add questions into your form.


  • In a web browser, navigate to and sign in with your ArcGIS Online credentials.  This will open the survey gallery.
  • Click on Create New Survey and select Survey123 Designer. Designer lets you visually create surveys right from within your web browser. It is very easy to use and plenty for what we need.  Survey123 Connect is a more advanced authoring tool, but we will not be using it here.
  • Choose a Name and tag for your project and optionally set a thumbnail. Then click Create.


Tip: If the animation below is too small, click on it to enlarge it.



After your initial survey project setup finishes, the Survey123 designer will open. You can now start adding questions to your form. We are going to organize our form with a header, two question groups, and a closing section for a disclaimer and terms of use acceptance.


  • Lets start by adding and labeling the groups as shown in the animation.



Groups are a great way to break down your form into sections. They can help you make your form more readable. You can add as many groups to your form as you like and even add groups within groups.  For a simple form like this we will keep all questions and groups within a single page.  For larger forms, you may want to break your survey into pages.


  • Add the Name, Email and Phone questions into the Contact Information group. Note that you can use hints to add subtitles into your questions and also mark questions as required. For the Name and Phone questions, use a Singleline Text type of question. For the Email, use the Email type of question, which has built-in email validation.



Tip: You can use the Preview option in the lower-right corner of Survey123 designer to look at your form as you build it. Note that you can preview your form in desktop, tablet and mobile form factors.


In the Security Device Information group we are going to add questions to capture the location of the camera and a few key characteristics.


  • For the location of the camera, we will add a map question (Geopoint question type). Make sure you mark this question as required. Optionally you can use the left panel to select the default basemap and zoom level for your map.



  • In addition to the map, it is a good idea to add a question for users to enter the address where the camera is located (Single Line Text), as extra validation.
  • Add a question of type Single Choice to capture the number of cameras at that location. We could add also a Number type of question, but to keep things simple we will just provide three choices: One, Two and Three or more. You may also want to arrange the choices horizontally to reduce the need for users to scroll up and down.



Next we are going to add a question to find out if it would be possible to have access to the footage and if so, what is the retention policy. We will use a rule to control the visibility of the footage retention question.


  • Add a question of type Single Choice. Change its value to Can the footage of this camera/s be accessed and shared? Then add Yes, No  to the choice list. You may want to also add I do not know.
  • Add a second Single Choice question type. For the label, use Footage retention policy. For the choices set them to: A few hours, One day, One week and More than one week.
  • Select the Yes/No question above in the preview and click on the Set Rule button so you can control when the Footage retention policy is shown.



You can apply rules to choice questions such as Single Choice, Dropdown and Likert.  When defining a rule, you can control visibility on a single question and entire groups.


Tip: Save your work from time to time. It does not hurt! The Save button is on the lower-right corner of Survey123 designer.


Now we are going to add questions for people to optionally provide additional information about the camera. system. On top of the basic types (text, choices, numbers), Survey123 forms also support photos and even documents.  People for example may want to upload a zip file with blueprints of the building highlighting the exact location and coverage of the camera, etc.


  • In the question panel on the right, look for the Image question type and add it to your form. Set the label to Attach a photo of what your camera can see.  You can add multiple Image questions if you want to let users add more than one photo.
  • Add a File Upload question type. Note that you can define what file extensions will be accepted. This question will let users upload documents such as zip files, pdf documents, etc.



The basics of your form are set. We will now work on the disclaimer section and the header.  The disclaimer section is important according to your own lawyer. Make sure you check with her first!  I will use in this tutorial some boilerplate text as an example but do not quote me on this one! The exact Terms of Use and Disclaimer text you will want to use are something between you and your lawyer.


  • Add a Single Choice question to the bottom of your form, outside the group. Use the Title and Hint to paste your disclaimer text.  Reduce all choices to just one: I agree and make sure you mark the question as required. In this way, users will not be able to submit their data unless they agree to the terms.



The header is also important because that is a good place to insert some context about your Voluntary Camera Registration Program. This is where you can tell users why the Police Department is looking to collect camera information, etc. You can also use the header to bring the logo of your organization.


  • Scroll to the very top of your form and click on the Description text in the preview. Then replace the description text on the left panel. Note that you can insert links to other websites, images, change the size and alignment of your text, etc.  Make this look good because it is the first thing people will see.


Your form is complete, but since manners matter, we are going to refine the look & feel and also configure a Thank You screen that will appear after a form is submitted.




  • To the right of the Appearance tab, you will find your survey Settings dialog from which you can customize your Thank You screen. Note that you can include links to other websites and also embed your organization's logo.


Testing your form


The Publish button, in the lower-right corner of the screen lets you publish your form so you can start capturing data with it.  By default, published forms are only available to the author of the survey. That is, you need to login with the credentials of the person that created the survey in order to submit data.  This is by design, so you can test your own form before you share it with other people.


  • Click on the Publish button to publish your form.
  • Open the survey link and submit some test data.



I strongly suggest you give your form a quick test, submitting data and making sure all looks good, before you share it with other people. Once your data is submitted, you can check it through the Data tab in the Survey123 website. You will be presented with both table and map views of your data. Note that you can further edit information submitted. For example, you can update and delete your test records, right from within the Survey123 website.


  • Once data has been submitted, open the Data tab of your survey project and explore the submissions.
  • Learn how to update and delete submitted data.


Do not be shy, run your form by people in your office and get feedback on it. You can make further adjustments to your survey at this point, and then publish the changes again. Once you feel confident with your form design, you are ready to share it.


Sharing your form (to submit data)


Using the Collaborate tab, you can share your survey design for others to submit data. You want to be extremely careful following these steps or otherwise you could be compromising the data that users will submit.


  • In the Survey123 website, click on the Collaborate tab.
  • On the left side of the screen, make sure that the Submitter tab is selected.
  • In the Who can submit to this survey section, select Everyone.
  • Scroll down a bit to the What can submitters do? section and switch the default option to Only add new records.
  • Click on Save to publicly share your form.



The What can submitters do? section is critical. You want to make sure you enable only access to adding features. If you also enable the option to update features, then a malicious person could technically query, download and even modify data submitted through your survey. 


In short, what we have done so far is to make our survey publicly available, so anyone, even without an ArcGIS account can submit data, but we have disable all options for non-authenticated users to query and download the data. That is, we have shared a survey that can only be used to submit data: your data will not be compromised.


Next, you can get the link to your survey and use it within social media, your own website, etc.


  • Scroll up to the top of the Collaborate dialog and copy the link to your survey.



You may notice that you can also get a QR code for your survey and even easily copy and paste HTML code to embed the survey within a website.


Sharing your form (for people to look at survey results)


Data submitted to your survey will only be available to you, the author of the survey, unless you explicitly share your survey results with others. This can also be done through the Collaborate tab.


  • While in the Collaborate tab, open the Viewer section in the left panel.
  • Select the groups within your organization that will have access to the survey data
  • Click Save.



Any person with an ArcGIS account belonging to the groups you select in this dialog will be able to log into the Survey123 website to look at the results of the survey. Viewers will be able to download, filter and map all submitted data.   Think carefully who you want to grant access to this data. You certainly may not want to allow Everyone to access this data. Keep it safe.


Socializing your form


A key aspect to make your Voluntary Camera Registration campaign successful is to promote it within your community. Connect with people in your organization to find the most appropriate way to present your  registration form. Using links provided in the Collaborate tab, you can:


  • Include links to your form in social media: Facebook and Twitter for example.
  • Include a link or the survey itself within an existing website (use the embed option).
  • Include a link to your survey in an e-mail campaign to residents and business owners in your community.
  • Add a QR code to easily open your form from printed marketing materials.


Maintaining your data


All data submitted through your form will be kept secure in ArcGIS Online (or your own ArcGIS Enterprise organization if you happen to run on ArcGIS Enterprise). I am not a big fan of exporting data out into Microsoft Excel or other formats because the export output becomes obsolete as soon as someone adds a new record. Having copies of the data proliferate can also become an issue. Whenever possible, it is best to have everyone work against a single source.


You can use the Survey123 website to visualize, analyze and curate all data submitted. The Data and Analyze tabs within the Survey123 website are pretty easy to use, yet powerful.


I will emphasize here that you can not only view, but also curate all submitted data from the Data tab of your survey in the Survey123 website. All records submitted can be updated and deleted right from the table and individual response dialogs within the Data tab.


We did not talk much about the Analyze tab in this article, but you will find more info in the Understanding Your Results with the Analyze Tab post.


You can also use other tools within ArcGIS to look, analyze and curate your data. ArcGIS Pro, Web AppBuilder, etc are great examples.  All data in Survey123 resides in a standard ArcGIS Feature Layer, so anything you can do with a Feature Layer, you can also do to Survey123 data.


I hope the above was easy to follow. If you have additional questions or feedback, do not hesitate adding your comments below. Thanks!

A minor update to the Survey123 website and field app has just been made available. This new release includes a handful of critical issues:


  • BUG-000125792: Japanese and Chinese keyboards not working in the field app on iOS 13.
  • BUG-000125769: The Survey123 field app image gallery is unsorted on Android devices.
  • BUG-000125687: Attempting to publish or save a survey in the Survey123 website containing a multiple choice question with the choice name containing more than 32 characters fails with the error, "Errors when parse form."
  • Null geometry is submitted by the Survey123 web app if there’s no Geopoint question in the survey or the Geopoint question is left blank.
  • Corrupted characters being displayed in some languages in the field app on iOS 13.


The latest build number for the Survey123 field app on Android and iOS is now 3.6.157. The Windows version of Connect and then field app has not been updated. 


The source code of the Survey123 Enterprise Template in AppStudio for ArcGIS has also been updated to version 3.6.


In preparation for the 3.7 update, which is planned to be released before the end the year, we will shortly make the Beta builds of the Survey123 website and the field app available in the Survey123 Early Adopter Program.

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


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


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


Critical fixes


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


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


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



Lines and polygons


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


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


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


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





Single choice grid in the field app


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


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



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


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


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


Feature report enhancements


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



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


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


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

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

A parenthesis should be added as follows:

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

Or alternatively, you could use:

${if image_field_1}

Another common syntax error is as follows:

{if choiceQuestion1="choice1"}

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

{if choiceQuestion1=="choice1"}

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


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


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


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


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



Web form view-only mode


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


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


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

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



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


Extended XLSForm support in the Survey123 field app


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



Range question


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


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


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


Check out the Range help topic for more details.



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


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


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




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


Pictorial lists


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


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



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


Critical fixes and minor enhancements


Survey123 Field app (XLSForm support)


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


Survey123 Field app (device specific issues)


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


Survey123 Field app (Usability)


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


Survey123 Web app


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


Feature reports


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


Survey123 Designer and website


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




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




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

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


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


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


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


The Basics


The basics: geoshape and geotrace in Survey123 Connect


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


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


datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Area


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


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

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


The basics: geoshape and geotrace questions in the Survey123 apps


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


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



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



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


The basics: Looking at captured data in the Survey123 website


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



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


Beyond the basics


Adding multiple geo type questions in a survey


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


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


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


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


Input Methods: vertex vs sketch


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


The map supports to input methods:


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

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


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


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


datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Areamethod=vertex



XLSForm functions: Calculating perimeter, area and length.


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


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


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


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


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


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


datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Area


More on XLSForm functions:  repeats, sum and count.


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


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


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


Geotrace and geoshape in the Survey123 field app Inbox


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


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


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


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



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


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


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


Including lines and polygons in your Feature Reports


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


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


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

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


Survey123 Connect XLSForm Templates


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


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


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


Formulas and data validation in Survey123 templates and samples


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


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


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


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



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


Yellow tips (and how to hide/disable them)


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



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



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



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


Manipulating XLSForm lists such as appearance, type, etc.


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


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


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


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



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


You should keep in mind two important things:

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

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

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


Creating your own template


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



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


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


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


Microsoft Excel Productivity Tips


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


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


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



Careful with copy paste!


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


Extend values and formulas


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



Keyboard shortcuts


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


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



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