Skip navigation
All Places > ArcGIS Survey123 > Blog > 2018 > November

[Last updated March 4, 2019]


On November 6, 2018, Esri introduced the concept of User Types in ArcGIS. User Types will be available with the upcoming ArcGIS Online December 2018 update.   ArcGIS User Types are an evolution of the ArcGIS Named User licensing model, bringing more granularity into how capabilities and apps are made available to users.


In this blog post, I want to describe how these upcoming new ArcGIS User Types relate to the different capabilities and components of Survey123 for ArcGIS.


An Overview of ArcGIS User Types


A great resource to learn more about the upcoming ArcGIS User Types is Kelly’s What is coming in ArcGIS Online: Introducing User  Types blog post. I recommend that you read her post as a foundation for the details described here.


ArcGIS User Types define what capabilities and apps are available to ArcGIS users within an organization. The image below describes the different User Types that will be made available in the December release of ArcGIS Online.



From a practical perspective, your existing Level 1 Named Users will become Viewers and your Level 2 Named users will become Creators.  What this means from a Survey123 perspective is that whoever was assigned a Level 2 or Level 1 Named User will continue to be able to do exactly the same things as before. For the existing Named Users you may already have, you can consider the new User Type model as simply a name change. End-user workflows and available functionality will not change.


What is more interesting is that a set of 3 new User Types will now be available for purchase.  This is great news, as these new User Types will give you extra flexibility to add new ArcGIS users into your organization to perform specific tasks with Survey123.

ArcGIS User Types from a Survey123 perspective.


Let’s look in more detail at what each of these new User Types can do with Survey123.


Creator (formerly known as Level 2)


The Creator User Type is designed for those in your organization who create maps and apps for others to use. A Creator User Type (formerly known as Level 2), is what you need if you want to publish new surveys into ArcGIS. A creator, for example, can log into the Survey123 website and use Web Designer to create and publish a new survey. Similarly, creators can download and use Survey123 Connect to publish surveys using the XLSForm specification.

Other Survey123 actions that are unique to the Creator User Type include: Uploading new survey report templates, generating batch survey reports or managing survey webhooks.


You will always need at least a Creator User Type (or other User Types above such as GIS Professional) in order to get things going with Survey123.  You need Creators to publish and manage the surveys that people will use in an organization.


With a Creator User Type you can also design dashboards to display data captured from Survey123, or put together Workforce for ArcGIS projects to coordinate Survey123 field work.


 Creators also include all the capabilities and apps licensed for the Field Worker, Editor and Viewer user types.


Field Worker


This is a new User Type for those in your organization who want to use ArcCGIS mobile apps to perform field work. Field Workers get the Field Apps Bundle, which includes Workforce, Collector and Survey123 for ArcGIS.   The Field Worker User Type is a step down from the Creator User Type in that Field Workers do not have the ability to create new content such as surveys, maps and apps, but includes what is needed to submit surveys from the Survey123 field app. I am particularly excited about the Field Worker User Type because for the longest time many of you have been asking for a more affordable way to equip field crews with a complete suite of mobile GIS apps to do their job. A user type including what a field user needs, but nothing else. That's the Field Worker User Type.


This is the User Type you will want for those who are required to capture data with the Survey123 field app.  Think field crews performing asset inventories or inspections, damage assessments, etc.


Field workers also include all capabilities and apps licensed for the Editor and Viewer User Types.




The Editor User Type is designed for people who need to make simple feature edits (adds, updates, deletes) in ArcGIS.  The Editor User Type does not include the Field Apps Bundle, meaning that Editors cannot use the Survey123 field app, however, Editors can submit surveys from a web browser. The Editor User Type can also be a good choice for people who perform, QA/QC workflows or simple edits from web applications against data captured from Survey123.


If it is your preference, you can complement an Editor User Type with add-on app licenses. That is, you can buy ArcGIS apps a-la-carte and assign the licenses to your existing Editor User Types.  For example, if you feel like your field crews do not need Collector, Workforce and Survey123, instead of purchasing a Field Worker User Type license, you can buy Editor User Types and assign the Survey123 field app to them.


Editors also include all capabilities and apps included in the Viewer User Type.


Viewer (formerly known as Level 1)


Viewers, formerly known as Level 1 Named Users, are designed for people who need to look, but not update, information in ArcGIS. Viewers can for example look at real-time dashboards built on top of Survey123 data, use web apps built with Web AppBuilder to visualize information.  The Viewer User Type also grants read-only access into the Survey123 website. That is, Viewers can look at the Overview, Data and Analyze pages of surveys to inspect the results of surveys


Features in the Survey123 website that require permissions to create content, such as publishing new surveys, export reports in batch or configuring web hooks, will not be available to Viewers. Again, Viewers just can look at data.


GIS Professional


The GIS Professional User Type sits above all the User Types I described so far. It includes everything in Creator plus a license to use ArcGIS Pro.  I list GIS Professional last because it does not add any specific Survey123 capabilities that would be missing in Creator. Adding GIS Professionals into the mix for your Survey123 deployments could be of interest when you plan to further process or analyze data captured with Survey123 for example.


Using Survey123 without an ArcGIS Account


For completeness, I would also add that any person, even without an ArcGIS account,  can submit data using the Survey123 field and web apps if the survey has been shared  publicly. The new User Types bring no changes to public surveys.


Other important facts


To add more clarity to the different User Types and what you can do in Survey123, here is a summary of what each User Type can do. 





Design, Publish and Manage surveys
Automate workflows with survey webhooks
Configure survey custom report templates
Generate custom survey reports in bulk
Export survey results to CSV, Excel, File Geodatabase…
Submit surveys from the Survey123 Field App
Submit surveys from a web browser
View and analyze survey results through the Survey123 website


Please note that through the use of ArcGIS Roles, administrators define the specific privileges that a particular ArcGIS member has access to. ArcGIS Roles can be used to restrict privileges initially included with a User Type and described in the table above. For example, if a user  with a Creator User Type is assigned a User role (which revokes privileges to publish feature layers), then that user will not be able to perform the operations above that are unique to the Creator User Type. Similarly, if a user with a Field Worker User Type is assigned a Viewer role, then its  privileges will be similar to that of a Viewer User Type.

Once a User Type is assigned, can it be changed? Certainly. As an ArcGIS Administrator you can switch User Types. For example, a person can be initially assigned an Editor role to submit surveys over the web and eventually be upgraded to a Field Worker to also be able to use the Survey123 Field app. Conversely, a Creator can be demoted to a Field Editor, Editor or Viewer. Now, in that case, you will want  to make sure any items owned by the Creator are  transferred to some other user with a Creator User Type, so the maps, surveys and other items can be maintained.


A user granted a particular User Type can also be granted access to additional apps not originally included with the User Type. For example, a Field Worker user can also be granted a license of Navigator for ArcGIS, and a Creator can be granted access to Insights for ArcGIS or other add-on apps.


What you cannot do is to break apart a User Type. For example,  you cannot take away from a  Field Worker the Survey123 license and give to an Editor.


Will User Types be available in ArcGIS Enterprise? Yes. Starting at version 10.7, which is scheduled for release around March 2019.


What is the price of these User Types? It varies. My suggestion is that you contact an Esri representative. There are programs for personal use, students, non-profit, small and large organizations.




ArcGIS User Types are simply an evolution of the ArcGIS Named User licensing model.  As a Survey123 user, you should not fear the transition from the existing ArcGIS User Levels we use now, to the new ArcGIS User Types coming in the December 2018 release. Your existing Level 1 and Level 2 users will be automatically transitioned to the Viewer and Creator User Types with absolutely no impact to end users.   The transition of existing Named Users will have minor impact from an ArcGIS administrative perspective: Some minor UX changes as described in this blog post.


New User Types including Editor and Field Workers are of particular interest for the deployment of Survey123 within organizations. They both provide lower entry points to people who need to use the Survey123 field app (Field Workers) or submit surveys over the web (Editors).  


Overall, the new User Types include capabilities progressively:

  • The Viewer can view maps and the results of surveys
  • The Editor can do everything a Viewer can do and also submit data through survey123 smart forms in a web browser
  • The field worker is like an Editor but also includes licenses for the Survey123, Collector and Workforce mobile apps
  • Finally, the Creator does everything a Field Worker can do, plus also create new content, including designing and publishing surveys. 


Understanding all User Types, will help you maximize your investment in ArcGIS. Carefully choose the number of User Types to add into your organization, based on what people will typically do. 

A minor update to the Survey123 field app in the Google Play and Amazon stores has just been made available. This new build, addresses BUG-000117493, which affected Android 7.0 (and newer) devices when attempting to connect to an ArcGIS Enterprise portal using non-CA-signed certificates.


BUG-000117493 "SSL Handshake failed (6)" error is generated in Survey123 app when attempting to connect from Android 7.0 or higher to an ArcGIS Enterprise portal using non-CA-signed certificate.


The new build number for the Survey123 field app on Android is 3.1.159.

St Kilda is a beachside suburb of Melbourne, Australia.  Among the various attractions in St Kilda is Luna Park, a theme park featuring the worlds oldest operating roller coaster. It is also known for its Sea Baths established in the19th century and of course, its beach, which is a popular summer spot for melbournites, tourists and backpackers.  My personal favorite at St Kilda is its pier, which holds a small colony of penguins.  There is only one place in the world where you can step out of a tram, walk down a pier and watch penguins, and that is St Kilda.  


In late October, while giving the final touches to this release, the Survey123 team gathered in Melbourne for a one-week team meeting.  We enjoyed visiting the pier at night and watching the penguins as they swam around and hide between the rocks.   We thought we would be devote this update to the St Kilda penguins, so here you go...


Overall, this update to Survey123 is mostly focuses on quality. We took our time going back through issues reported, sorting the most relevant and fixing them.   While fixes are a big part of this release, you will also find a handful of enhancements inspired by your feedback.



Custom Themes in Web Designer


With Survey123 Web Designer you can visually create smart forms, right from your web browser. Survey123 Web Designer grows with every release, incorporating new question types, validation rules and other improvements. Smart forms published with Survey123 Web Designer can be used from the Survey123 Field and Web Apps.


With the introduction of custom themes, you can now tightly control the look and feel of your web surveys.  Below are some examples illustrating the type of things you can do. Header colors, page and survey backgrounds, the color of the submit button... all of that can be now set so you can more closely reflect the feel and brand identity of your own organization or project.  Custom Themes are of particular interest to those of you interested in publishing surveys for use over the web.



The new themes are under the Appearance tab in Web Designer and can be applied to any survey authored in Web Designer. Custom Themes in Web Designer cannot be used with surveys published from Survey123 Connect.


Check this blog post for more details: Introducing Custom Themes in Survey123 Web Designer 


User Input Validation Rules in Multiple Choice questions (Web Designer)


The validation section for Multiple Choice questions in Web Designer has been expanded so you can easily define the minimum and maximum number of choices that can be selected from the list. For example, you can now configure a Multiple Choice question so users will not be able to check more than 3 options, or at least 2, etc.



Validation rules set in Web Designer will be honored by both the Survey123 Field and Web apps. More details around multiple choice questions can be found at:  Understanding Multiple-Choice Questions in Survey123 for ArcGIS 



Character counter in text questions (Web and Field app)


Multi-line questions now display a character count, helping users keep track of how much text they can add before reaching the maximum limit set by the survey owner.



The character counter is implemented in both the Survey123 Web and Field apps and can be set from Survey123 Web Designer as well as through Survey123 Connect.



Dynamic Question Labels


As of 3.1, you can include XLSForm variables within the label of a question or note.  In the example on the side, the Type of Violation and Offender Name entered by the user are embedded in the labels of questions in the survey.



If used appropriately, Dynamic Question Labels will help you make questions in your survey more meaningful to end-users and facilitate navigation.





For more details around dynamic labels refer to this blog post:  Understanding Dynamic Labels in Survey123 for ArcGIS 












For a complete list of enhancements in the Survey123 Website, Field App and Connect, refer to the What is New Help topic.


Main Fixes and Enhancements to Survey123 Website and Web App


  • BUG-000116143 The Survey123 for ArcGIS website works slowly when generating a report and generates an error while downloading custom reports exceeding 10 MB in size.
  • BUG-000112528 Custom Reports fail to load with an error indicating the parser failed to execute if a field it cannot read or does not exist has a formatting set.
  • BUG-000116436 In Survey123 web Design, Rule Setting disappear when you log out if “Show” questions are in a Group. The settings, however, is still honored in the App or Web when submitting surveys.
  • BUG-000116368 Getting error when trying to export to KML on Survey123 Portal website "Error executing function. failed to execute (export service). failed."
  • BUG-000110646 When publishing a survey from Survey 123 for ArcGIS online website to Survey 123 connect for ArcGIS then publish the survey back to online the survey loses the background image
  • BUG-000115084 When utilizing a choice filter in Survey123 for ArcGIS, if images are used against filtered questions, the label fails to display properly on the Data and Analyze tabs
  • BUG-000113561 The Survey123 for ArcGIS web app does not allow user to enter decimal '.' values when using Dutch language in ArcGIS Online
  • BUG-000114313 The survey background sets in Survey123 Connect for ArcGIS is not honored if the survey is accessed using web browser
  • BUG-000114658 A publicly shared Survey123 survey hosted on a federated Portal for ArcGIS or ArcGIS Server is not accessible from a public ArcGIS Online web map when signed in to ArcGIS Online
  • BUG-000115903 In Survey123 website, a question configured using pulldate ("@geopoint") does not get populated even when the Geopoint question is filled (reverse geocode)
  • BUG-000115045 Surveys created in the website fails to open in the Safari browser of iOS devices, where the iOS version is below 11.0.0
  • Added support for the XLSForm version() function in the Survey123 Web App.
  • ENH-000113657 Question visibility settings are now persisted across multiple sessions
  • ENH-000105733: You can now apply filters to data displayed in the Analyze page
  • Image questions in Web Forms now let users leverage the built-in camera or webcam attached to laptops and computers.
  • Major architectural changes have been made in the Feature Report Service to accommodate user load and also to make the rendering of maps in your reports more robust.  Many of the map rendering issues that we have targeted are summarized in this GeoNet thread: Am I the only one having issues with Survey123 Reports?  We also have enhanced the error descriptions to help you debug report template syntax. Our goal is to move the Feature Report functionality into general release around May 2019. We greatly appreciate the feedback that all of you are providing, please keep your comments coming.


Main Fixes and Enhancements to Survey123 Field App and Connect


The build number for the Survey123 Field app is 3.1.158 and it is available for download in the App Stores and our  Survey123 for ArcGIS | ArcGIS Download page. The Survey123 Connect build is 3.1.126.


  • Apple Transport Security supported on iOS.
  • Two new appearances have been added: predictivetext  and nopredictivetext. They are meant to be used with text type of questions and allow the survey owner to enable or disable the predictive text functionality included with the Android and iOS operating systems.
  • BUG-000105983: Survey123 Connect will hang while attempting to publish if the survey includes a repeat block with no questions in it.
  • BUG-000110646 Website background images not maintained when survey republished in connect.
  • BUG-000116622 An error message is thrown when submitting from Survey123 for ArcGIS if the survey contains a geopoint question within nested repeats
  • Fixes for the autocomplete appearance:
  • BUG-000106380 Default Value set in Survey123 Connect is not applied when survey includes cascading select and autocomplete
  • BUG-000097421 In Survey123 Connect for ArcGIS, if a time field has a calculation all time field's defaults are ignored
  • Fixes to repeat_count:
  • Survey123 surveys not showing in app despite being downloaded 
  • BUG-000117394 "The INSERT statement has conflicted with the FOREIGN KEY constraint" error is thrown when Survey123 is pointing to an existing feature service that contains multiple tables all relating back to one parent layer
  • Coordinates passed via custom_url through the center parameter are ignored
  • Under certain conditions, map returns to current location after an address is entered in geosearch
  • On certain iOS6 devices, taking a photo using the Survey123 built-in camera causes an application crash
  • On iOS devices with auto-orientation locked down, images captured using the front-facing (selfie) camera are upside down when the phone is rotated in landscape mode
  • BUG-000116932 When an image is set as a default value for an annotate question outside of a repeat in Survey123 for ArcGIS, the annotate option fails to appear.



What is coming next


Survey123 3.2 is already on the works and our plan is to make it available in January 2019 across all supported platforms.  Version 3.2 will focus on quality, addressing specific software defects that we could not accommodate into the 3.1 update.


Through the Early Adopter Program, we regularly offer early cuts of the software, which you can use to test your existing surveys as well as new features on the works. The main new Early Adopter Program feature in the Survey123 Field App is support for direct connection to external GNSS receivers (scheduled to be generally available around March 2019.  We strongly encourage you to read the Early Adopter documentation, test the latest available builds and report your findings.

Using the Survey123 web designer, you can tightly control many visual aspects of your online surveys.  This includes everything from defining the look of your survey header, the style of its background, the alignment, color and size of text used in questions, the placement of logos, etc.


Of course, all of this is important because people are expecting visually compelling surveys from you. Crafting surveys with great visual appeal is particularly critical for public surveys. By having good control over the look and feel, you will be able to more closely reflect the feel and brand identity of your own organization or project.


Before we start, I want to emphasize that in good survey design, the looks are just half of the story. Carefully crafting the questions to be included in a survey, their order, wording, grouping and the best fit for the available question types, is the other half.  Trying to detail all of this at once would make a very lengthy post, so this time I will focus strictly on the visual aspects of surveys: the looks.


Below you have a few examples illustrating different techniques to make your surveys shine: Custom banners, backgrounds, in-line photos and a few other tricks. 



In this blog post, I will describe a handful of techniques to give your surveys a unique touch, making them look more professional.  While some of the features I am about to describe will be honored by the Survey123 field app, I will mostly focus on the design of web forms. 


For a quick tour of custom themes, I highly recommend you watch this short video-tutorial. In just three minutes, it covers the most important aspects  of custom themes.



Basic Layout Elements: Header, Description and Footer


The basic elements around questions in your survey are the Header, Description and Footer.  Right from the Appearance tab, you can choose to show them, or hide them. For example, the Description element is typically used to describe what your survey is all about.  It is generally made out of text or a combination of text and images. If you feel like the title shown in your header is descriptive enough, you can choose to hide the Description element all together.



By simply clicking on the Header, Description and Footer in the design preview, their properties will be made editable in the right panel of Web Designer.


Survey Header


The header typically holds the title of your survey, but it is also a great location to display an organization logo.  You can choose a Text Header, for which you can control its background color and text alignment, or an Image Header. 


If you choose an Image Header, your image will be adjusted so it fits the entire width of the survey, which will not be larger than 680 pixels. For this reason, as a general rule, your header images do not need to be wider than 680 pixels. The height will be set so your image aspect ratio is preserved. It is best to go with a wide image to avoid taking too much vertical space.  The header is taking the top most part of the display, so with such prime real estate on your screen, you do not need a big, tall header to make a point.



Images used in your survey are not allowed to exceed a size of 1Mb.

    Always try to optimize the size of your images.


Survey Description


The Survey Description element, in Survey123 jargon, is a Note question type. Just like with the Survey Header, you can easily hide the Survey Description element from the Appearance tab.  To set the content of the Description, simply click on the element in the preview, and all the settings will appear in the right panel.



Note that the contents of the Description element accept rich text, so you can add entire paragraphs controlling the font color, size, text alignment, images, links, etc. This makes the Description very flexible, allowing you to provide context about the survey itself.


To support recovery effort after hurricane Michael, the Florida Department of Environmental Protection and the Florida State Emergency Response Team, published a public survey to help citizens report the location of debris.  Note how they used the Survey Header to include a simple form title, and then leveraged the Survey Description element to place their organization logos as well as a brief note about the purpose of the survey. The Survey Description element also included links referencing the organizations website and other relevant documents.



The Survey Description element is particularly critical for public web surveys where you cannot assume that people know what your survey is all about. A bit of context, is always good!


Right below the Description element is where questions in your form will appear.  I will describe later how you can use Themes to control visual aspects of your questions, but for now, let's jump into the footer.


Survey Footer


The Survey Footer obviously sits at the very bottom of the survey. This is a good place to link back to your organization's website or solicit feedback. Similar to the Header and Description, you can choose to hide or show the footer from the Appearance tab, and you can edit its properties (text and URL link) by simply clicking on the Footer in the preview.  Look carefully at the animation to see how you can bring the window to edit Footer properties.



The URL for your footer does not need to necessarily be a URL to a website. You can also include a mailto link. For example, if your URL is set to , you can help survey takers send you feedback to your email account.


Survey Themes


Survey Themes help you easily define the color scheme of the most relevant visual aspects of your survey. A gallery of basic themes is included with Survey123.  Most themes are based on a primary color applied to the background page of the survey. Different shades of that color are then applied to the header, background of the form and submit button.  The Theme also defines the color assigned to the text in your form, so it contrasts over the background. A second group of default themes uses a background image as the driver for all the visual components in the form.  You can use the themes included as they are. We added a good set of them and you can switch and see how they play out with your own surveys very quickly.



You can also use the included Survey Themes as a starting point to your own design.  That is, you can select a basic theme and then edit it.  The editable properties of a Theme are split as follows:


  • Header: You are already familiar with this element. The theme sets the background color of the header and also the text color. You can easily tweak this as you see fit.
  • Content:The content category refers to the portion of your form containing all the questions. There are a number of important properties: 


Content Background: The content background sits right underneath your survey questions and should not be confused with the page background, which I will describe later. The purpose of the Content Background is to ensure that all questions in your survey are legible. You will want a nice contrast between your questions and the content background: A light background goes with dark question text and inputs, and vice versa. In the vast majority of cases, you will want to use a solid color for your Content Background.


If you want to get creative, you can experiment with images for the Content Background as well, but you need to be careful not to overload it with colors, which would only create distractions. When it comes to images for the Background Content, it is best to use lightly textured images.  Below are a couple of examples using images to create a notebook and wrinkled paper feel.



When using content background images, you will want to play with the different Image Fit strategies available (Repeat, Repeat Vertically, Fit and Center).


For both color and image custom content backgrounds, you can adjust the opacity level, which can give you interesting effects when working in combination with the page background.


Content Text Color: This setting refers to the color used for labels in your questions.  As described above, the color choice for the text depends on the background color.  You will always want to look for good contrast to make your questions more legible.  The content text color is not necessarily applied to hints and notes, as those can override the font colors as specified in the Design view.


Input Background Color: This refers to all the space used to input data. Think of the color of text input boxes for example, but also the background for choices in lists, signature pad, etc.


Input Text Color: This applies to all response text.


  • Web Page: The Web Page element represents all the background behind your actual form content.  This element is visible in desktops and tablets, but it is mostly hidden in smartphone form factors.  You can manipulate the color and image shown in the Web Page background, allowing you to give a strong look to your smart form. The Web Page background is probably the element that can bring the most character to your design. In the following example, I set a colorful image as the background of the page, for my form to stand up strongly, and to highlight the core mission of the form: trees.



As mentioned above, you can use the opacity setting in the Content Background to create interesting visual effects against the Page Background. The next screenshot shows a medium opacity level applied to the Content Background, to create a subtle translucent effect.



The Web Page Background is only shown by the Survey123 Web App. The Survey123 Field App ignores the background because the from content is always expanded to take advantage of all the real estate of your device.

Thank You Screen


The Thank You Screen can be optionally presented in Web Forms right after a survey is submitted.  This is the perfect place for you to thank the survey respondent for taking the time to complete the form, acknowledge the work of your project sponsors or highlight your own organization.



You can include formatted text, links and even custom images within the Thank You Note. I like to give some love to the Thank You Screen in my surveys, particularly when they are public, because they give it a nice touch.


If you look carefully at the bottom of the Thank You Screen dialog, you can optionally enable users to take submit data again with your survey, right after submitting. This option simply adds a link in the Thank You Screen that will quickly take you back to the survey.


Miscellaneous tips and other things to keep in mind


  • Making image assets available to Web Designer:When using Web Designer, all image assets are referenced through a URL. That is, you cannot use Web Designer to upload your image assets directly from your local computer. You must host them somewhere first. Aside from keeping images in your own web server, there are a number of popular options for you to host images, including Box, Google Drive and others. You can also upload your images into your ArcGIS  account, share them and then get their URL as shown in the next animation:



  • Maximum size of images: The maximum size of images you can use in your survey designs is 1Mb. You should always optimize the size of your images to minimize their size without compromising quality. Every image you add will eventually need to be downloaded and that will slow down the initial loading time of the form.
  • Setting custom colors: When setting up the colors for your text and backgrounds, you can use hexadecimal values. Using web browser plugins such as ColorZilla you can easily obtain these hexadecimal values from a website and apply them to your survey visual elements. See the next animation for details.



  • Never underestimate the importance of making your surveys look great.  A good look, can go a long way in terms of helping you get the best data from users.

Starting with version 3.1, you can dynamically change the label of a question, using answers from other questions in the form. Dynamic question labels are particularly handy when working with very long forms, making questions in your survey more meaningful to end-users.


The Water Violation survey sample on the side, for example, shows how you can insert the Type of Violation and Name of Offender in the photo and signature questions that follow.


This is quite a simple example to illustrate the idea. As your survey includes questions across multiple groups, repeats and even pages, dynamic labels become critical to aid with form navigation and to avoid user input errors. 


The dynamic labels technique is often described in survey jargon as question piping, where user responses are inserted or piped into questions further into the survey.


You can add dynamic labels to your forms using Survey123 Connect for ArcGIS. Once published, dynamic labels will work in both the Survey123 web as well as the field apps.



The basics of dynamic labels in XLSForm



In order to insert text dynamically within a question label, you must add XLSForm variables in the label column of your survey. The syntax is quite simple. Insert ${QuestionName} exactly where you want the answer to a particular question in the survey to appear in your label.  This is what the Water Violation example illustrated above looks like in XLSForm.



You can add multiple variables to the same label but it is important to highlight that the use of full XLSForm expressions within the label column is not supported.  Survey123 will only replace XLSForm variables. For example, this is valid:



But this is not valid:



While you cannot use full XLSForm expressions within the label, you can use them in a calculate question, and then reference your calculate question in the label. Calculate questions will not show in your form, but will help you hold the output of full XLSForm expressions, so you can insert those values in a label. For example, lets pretend you want to use a dynamic label in a note to describe the total cost of repairs of a pipe, given its length:



The cost question is a calculate. It will not be shown in the form to the end-user. We use the cost calculate question to run a full expression that evaluates the total cost, and once we have that, we simply use it for our dynamic label.


Working with different data types


As you work with dynamic labels, you will notice that things are straight-forward when you want to insert values from questions of type text, decimal or integer.  All you will need to do is to reference these questions directly exactly as shown above.  When working with other types such as dates or select questions, things are a bit more complicated and you will need to pre-process user values through calculate questions before you insert them into the label.


  • Dates: If you want to insert a date value within a label, you must first use a calculate question and apply the format-date() function. There are some details about formatting dates in Dates and Time in Survey123  After doing this, you can bring the formatted date value string from the calculate question, into your label.


  • Select_one questions: If you want to bring a user selection from a select_one question into a dynamic label, you have to keep in mind that by default, you are going to get the choice name value, not the label of the selected choice.  If you want to display the label of the selected choice, then I suggest you use a calculate using the jr:choice-name() function.



Support for the XLSForm jr:choice-name() function was introduced in Survey123 in version 3.1 in both the field and web Survey123 apps.  This function takes two inputs: a string representing a choice name, and a second string representing the name of the select question. Note that the second parameter requires you to enclose the question with quotes.

The output of this function is the label of the choice name passed-in.  If this function is used in a multi-language survey, the label returned is that of the active language.  


  • Select_multiple questions: Select_multiple questions let you choose one or more values from a predefined list. The output of a select_multiple question is a comma-separated string representing all the values selected by the user. This output, as is, is not the easiest to handle with dynamic labels, but again you can use other calculate questions to properly massage the output before it is added to your question label.  The Understanding Multiple-Choice Questions in Survey123 for ArcGIS  blog post describes in more detail how multiple choice questions behave and how you can work and control its outputs.


Other things to consider


There are some obvious and not so obvious things to consider when working with dynamic labels:


  • If you reference in your label a question for which the user has not provided an answer, then your question is going to have some missing text.  You can choose to be clever with the label. For example, in our Water Violation Example it is not evident when the violation type is missing. You will either read “Photo of the violation” (No violation type chosen) or “Photo of the Broken Pipe violation” (if Broken Pipe has been chosen).  In practice, you will not always get so lucky when the variable is missing.  In the pipe cost repair example above, it is evident that we are missing something in the total cost note when a dollar amount is not present.  You can choose to use a relevant statement to hide questions with dynamic labels until the variable to be replaced (in our example the cost or repair) has a valid value. In these cases, you can use the string-length() function as shown in the following example.



  • Your dynamic labels will certainly look great in the survey, but what about when you bring your survey layers into web maps? Or when you look at your survey data in the Survey123 website? On this one, it is important to understand what really happens when your survey is published, and how the Survey123 website as well as other ArcGIS apps work with your survey layers.


When you publish an XLSForm document with Survey123 Connect, we take the values in the name column of your survey spreadsheet and we use them to create new fields in the survey feature layer.  By default, we use the contents of the label XLSForm column to define the field aliases of your attribute fields.  Typically, ArcGIS apps will use the field alias for display purposes. This is the case in the popup of a web map as well as throughout the Survey123 website.


When you insert a dynamic label, your field aliases will include the variable placeholder and that will not look very nice.  If you are worried about this, make sure you set the alias value for your attribute fields in the esri::bind:esriFieldAlias XLSForm column.  Alternatively, you can also refine the field aliases, after the survey is published, from the Item Details page of the feature layer item.



If used wisely, dynamic labels can help you build better and more user friendly smart forms.  We hope this new feature is useful to you!