Skip navigation
All Places > ArcGIS Survey123 > Blog > 2018 > April
For this blog post, and the subsequent blog post on extending Survey123's functionality, I've created a user story for a fictitious municipality called the City of Cilantro that will help guide the customization process. Also, a public repo with the customized app is available at Github: Cilantro Surveys 

I. User Story

The City of Cilantro needs a custom version of Survey123 that will be used by various city departments to conduct public and private surveys. The city currently has three customization needs:

  1. The app needs to be branded to match the organization. [Not extending core functionality]
  2. The city needs the ability to print the time and location onto new photos taken with some surveys. [Extending core functionality]
  3. Some surveys used in the field will include the scanning of barcodes as the only action required of the survey. The application will need to automatically submit the survey after the barcode is successfully scanned and then open a new survey immediately upon successfully submitting the previous survey. [Extending core functionality]
This blog post will address the first customization need. Updating the user interface (UI) to match an organization's branding doesn't affect or amend the application's core functionality and requires no coding experience (there is one caveat to this currently which is noted in section III.4). Let's first look at the asset's needed to create the custom look and feel before downloading the template.

II. Assets & Information Needed

a. App Name

Cilantro Surveys
The app should have a distinct name. It should not be called Survey123. For the City of Cilantro, 'Cilantro Surveys' was chosen as it referenced the city's name and also kept the name simple and succinct.

b. Branding Color

The Survey123 application has one main color used throughout the UI that 'brands' the look and feel. Survey123's branding is built around a hue of green, and can be seen throughout the UI of the application as well as the website and associated marketing materials. When customizing Survey123, it is highly recommended that a different color be used in order to help distinguish the app from Esri's production version of Survey123. The color should ideally match the branding guidelines and needs of the organization that is customizing the app. The City of Cilantro uses a brown hue in their logo, so that same hue of #543e36 will be used in the custom app.

c. App Icon

The app icon is what the user will see in the device's user interface and will be touched or clicked to open the app.
  • 512 × 512 (pixels)
  • .png file

d. Launch Screen Image Overlay

The launch screen overlay is a graphic that will appear above a colored background when the app is launched into the device's memory. 
  • 768 × 768 (pixels)
  • .png file
  • Should include transparency or the background color should match the color set for the background color in the app's settings. In this example the image includes white graphics on a transparent background. The background color is set to #543e36 in app's settings.

e. App Thumbnail [for ArcGIS only]

The app thumbnail is used to help distinguish the app in ArcGIS galleries. It is used throughout the web and AppStudio to visually reference the application item.
  • 200 × 133 (pixels)
  • .jpg or .png file

f. Company / Organization Logo [optional]

The company / organization logo is an optional asset. If included, it will appear on the app's About view. It can additionally be set to open a custom url to an external website.
  • Height should be a maximum of 200px. The width will be automatically adjusted to preserve the image's aspect ratio and fit the logo into horizontal space on the About view.
  • .png or .jpg file

g. Custom Font [optional]

The Survey123 template allows for the use of a TrueType font family in the customized application.
  • .ttf (TrueType) files supported.
  • Ensure that the font is licensed or has a license that allows it to be distributed with the app.
  • For the Cilantro Surveys app, we are using the Raleway font family available from Google Fonts, which has an Open Font License.

III. Steps to UI Customization

Now that I've outlined the assets and information needed to create a custom version of Survey123, the next step is to download the template and get started. I'll go through this step by step and reference the assets and information listed above along the way.

1. Download the template

  1. Open AppStudio for ArcGIS. You don't have to log into your ArcGIS organizational account in order to download the template, but it is a best practice. 
  2. Click "New App"
  3. Click the "Enterprise" tab in the New App dialog
  4. Select Survey123 (Template), enter the title of the app ("Cilantro Surveys" in this example) and click "Create"
  5. The new app template will download and appear in the AppStudio gallery.

2. [Optional] Create the fonts folder and add the font files

This step is only required if you are using a custom font family.

  1. Right-click the gallery card for the app in AppStudio and select Open in folder.
  2. Open the "Controls" folder
  3. If the folder doesn't contain a "fonts" folder, create one. 
  4. Copy all of your .ttf files into that folder. 
    • In this example we'll be copying the Raleway fonts to the folder.

3. Update the app's settings and assets

Now comes the most significant step where the assets and settings for the app are updated.

  1. Make sure the gallery item for the downloaded template is selected and then open Settings for the app. This can be down by right-clicking on the gallery item and clicking Settings from the menu, or using the side menu. 
  2.  Details Tab
    1. First update the app's details under the Details tab.
    2. Click the thumbnail and replace it with the app thumbnail created for the app (See section II.e)
    3. Update the app's summary, description and access use and constraints to reflect the new app. The description will appear in the app's About view.
  3. Survey123 Tab
    • General Tab
      • Text color: The text color used in all non-title text in the app. I'll leave this set to the default value of #4c4c4c.
      • Background color: This will set the background color displayed in the gallery and the survey info views. I'll leave this set to the default of #efeeef.
      • Title bar text color: This sets the foreground (text) and icon colors for the top bar in the gallery and survey info views. I'll leave this set to the default of #ffffff. Because the branding and background color for Cilantro Surveys is dark, the white text will contrast well against it.
      • Title bar background color: The background color used in the app's title bars.
        • For Cilantro Surveys I am using the branding color of #543e36 (see section II.b).
      • Font Family: This is where the name of the custom font is entered. For Cilantro Surveys I am using the Raleway font family.
        • Note: The text entered here would be the same text entered for the css font-family property if the font were being used on the web (e.g. font-family: 'Raleway';)
    • Other Properties
      • backgroundTextureImage: This property is no longer used.
      • companyLogo: The company logo that appears on the app's About page (see section II.f). 
      • companyUrl: URL opened via the company logo on the About page.
      • formBackgroundColor: The default background color used for forms in the app.
      • startBackgroundColor: The background color of the opening splash screen.
        • For Cilantro Surveys I am using the branding color of #543e36 (see section II.b).
      • startForegroundColor: The foreground color of the opening splash screen.
      • startOverlayImage: The image that appears on the opening splash screen.
        • For Cilantro Surveys I'll set this to our company logo as well (see setion II.f).
  4. Resources Tab
    • App Icon
      • I'll set this to the icon created with the assets (see section II.c)
    • Launch Image
      • Overlay image: I'll set this to the launch image created with the assets (see section II.d).
      • Background Image: I won't use this property with the customized app.
      • Background color: I am using the branding color of #543e36 (see section II.b).

4. Fix small bug in code [only for templates based on version 2.7 or less]

Survey123 templates based on version 2.7 of the app or less have a small bug in the code that needs to be fixed in order for the branding color to be reflected on the survey view. To fix the bug do the following:

  1. Open the app codebase in Qt Creator. This can be done by right-clicking on the app card in AppStudio and selecting "Edit in Qt Creator" or by highlighting the app in the AppStudio gallery and clicking the "Edit" button in the side panel.
  2. Open the following file by using the file browser in the left panel of Qt Creator: template > SurveyView.qml
  3. Within the style property of the XForm component in SurveyView (approximately line 501), add the following 2 properties below the line:  fontFamily:app.fontFamily
    titleBackgroundColor: app.titleBarBackgroundColor
    titleTextColor: app.titleBarTextColor
  4. You can view the code in the Cilantro Survey's public repo at CilantroSurveys/SurveyView.qml 
  5. Save the file and close Qt Creator.

5. Upload the app

Upload the app to ArcGIS online. This will allow you to register a client id for the app so that it can use OAuth for login authentication, as well as provide access to CloudMake.

6. Register the client id in order to use OAuth

In order for users to be able to log in to your app with their ArcGIS Online or Portal credentials, a client id must be registered for the app. If the app is located on ArcGIS Online, registering the client id is an easy process*.

  1. Open Settings for the app (see Step 3.1 above). 
  2. Click the Advanced button on the bottom bar next to Apply.
  3. Under ArcGIS Client ID click the "Register" button (You must be logged in to ArcGIS Online). 
  4. Settings will register the app with ArcGIS and return a client id that will appear in the text field.
  5. Once the client id is returned and visible, click "Apply".
  6. That's all

*Note:  If the app needs to authenticate to a Portal for ArcGIS, you will need to follow instructions similar to those outlined in this article (substitute your app's name for Survey123 in the article).

7. Test and Build app

Now the only thing left to do is build the app. Before doing that, most of the changes made in the previous steps can be previewed in AppRun or AppStudio Player.

  • To open the app in AppRun either double-click the app card in the AppStudio gallery or click "Run" in the AppStudio side panel.
  • For more information on AppStudio Player, see: Guided tour—AppStudio for ArcGIS | ArcGIS 


Building the app via CloudMake or Local Make is beyond the scope of this blog post. However, please note that in order to build the app for various platforms appropriate developer certificates and provisioning profiles are required.


That's all there is for white label branding Survey123. However, if you want to finesse the app's look and feel even further, feel free to jump into the code .

On 8 December 2005, the General Assembly declared that 4 April of each year shall be observed as the International Day for Mine Awareness and Assistance in Mine Action.


It called for continued efforts by States, with the assistance of the United Nations and relevant organizations, to foster the establishment and development of national mine-action capacities in countries where mines and explosive remnants of war constitute a serious threat to the safety, health and lives of the civilian population, or an impediment to social and economic development at the national and local levels.


The Geneva International Centre for Humanitarian Demining has leveraged Survey123 for ArcGIS over the last year and a half to capture the location of reported explosive devices, record hazardous areas and interview and support victims and survivors. We devote this update to GICHD and to all organizations committed to make a difference for those who suffer the long lasting consequences of war.


To learn more about GIHCD and their work with Survey123, watch this video:



Next, lets describe the highlights for this update:



Web Designer Enhancements


Starting with this release, you can add signature questions into your surveys, right from Web Designer.


Signature questions are supported in both Web Forms as well as the Survey123 field app and present to the end user a simple black-over-white signature pad.


Signatures are stored as attachments, like other images.



Rules: Rules in Web Designer allow you to define simple conditional statements to control the visibility of questions in your form. Using rules, you can dramatically simplify your forms, ensuring that users are only presented questions relevant to them.  To define a rule, you need to first select a question of type Single Choice, Dropdown, Likert or Rating. At that point, the Set Rule option will be enabled so you can define what questions will be shown when a particular choice or rating is selected. Up until this update, rules were only supported in Web Designer for single choice questions.



Autocomplete: You can now enable autocomplete on questions of type dropdown.  This is particularly useful when working with long choice lists.


Compact choice lists: A new 'horizontal compact' appearance has been added to single and multiple choice questions. Use this appearance if you want the choices to be arranged horizontally, but preserving as much space as possible.



Date questions: Date questions have been enhanced in Web Designer so you can control if the calendar control should let users define a complete date (Year, Month and Day), or simply the year or the year and the month.


Bug fixes and other enhancements:


  • ENH-000111156: Add support for pulldata() in geopoints in the Survey123 Web Form
  • BUG-000111357: Clicking the collaborate option for a survey in the website returns an error, "Survey does not exists or is inaccessible" when labels are kept empty in the corresponding survey form.
  • BUG-000111377: Trying to publish a form using the Survey123 site containing multiple choices, with a choice containing more than 32 characters, fails to publish the survey and results in the error, "Unable to publish the survey. Length >32"
  • BUG-000111206: hide-input appearance does not work when taking the survey in the web app
  • Multiple issues addressed when using Web Forms in IE11 Web Browser.


Survey123 Field App and Connect


Version 2.7 of the Survey123 field app and Connect does not come with major new functionality, but it is loaded with many fixes and enhancements. Lets start with a selection of critical fixes:


  • BUG-000096762: Feature Services published from Survey123 Connect for ArcGIS do not define a "Display Field" in the feature layer rest endpoint. This bug prevented surveys published from Survey123 Connect from working within Collector for ArcGIS Android. It also caused table preview issues in some versions of Portal for ArcGIS.
  • BUG-000108943 Required values for integer, decimal, geopoint, and DateTime questions in a Repeat section can be submitted blank. Also raised by Johan Ekenstedt in GeoNet: Required geopoints in repeats doesn´t work 
  • BUG-000110669: This bug caused the form not to center the screen on empty required questions after validation, making it difficult for end users to identify which required questions had been left empty. Also raised in GeoNet: Survey123 2.0 Change Question 
  • BUG-000109967:  Offline maps not available in the Inbox, Sent and Outbox. Now fixed in this release. Also raised in GeoNet: How to use TPK on Inbox map? 
  • BUG-000108975: When previewing a survey in Survey123 Connect for ArcGIS, validating the input for the first selection in a cascading select will not function as desired. Fixed!
  • BUG-000110311 In iOS operating system, copying sent data to a new survey and deleting an attachment results in the attachment missing from subsequent copy from sent. Addressed.
  • BUG-000106661 Updating a sent survey that is connected to a feature service from the ArcGIS Server that is federated with Portal (not hosted) will result in the following error: Unable to Complete Operation. Error code 400. Fixed.
  • Fix-Heather Follis: This fix accommodates cases where the Sent box could not display submission error messages. More details at: Our completed surveys are not sending. They stay in outbox with red exclamation and no errors. 
  • Fix-John Walls: A fix to address situations where certain surveys would cause Survey123 Connect to crash.More details here: Survey123 Connect Crashing When Opening Survey  Thanks John for reporting.
  • Fix-Chris Shuck: With this fix, a survey can include multiple expressions extracting EXIF metadata from images. More details at Pulldata function on multiple photos freezes the app
  • Fix-Eric Page: With this fix, the Inbox now properly displays and sorts Inbox records based on submission time, when the Inbox makes use of a query. Survey123 Inbox Sorting and Filtering 
  • Fix-David Rebot: Great find by David: Default values were not being applied if the autocomplete appearance was in use. Addressed in this release. ISSUE with Autocomplete interfering with Defaulting Date/Time fields 
  • Fix-Shane Clark: This one was an oldie that we had to accommodate. Input masks now no longer make your questions required. body::esri:inputMask should not require input   Shane: your finding was a good one too...


And here a list of the most relevant enhancements in the Survey123 field app and Connect:


  • Enhancements to annotate appearance: We introduced smart sketching in our 2.4 release and many of you are leveraging it today. In this update we incorporate two popular requests:
    1. Allow end users to sketch on top of existing images from the photo gallery
    2. Allow end users to rotate images before sketching
  • Optionally disable Web Form generation in Connect: A new option has been added in the Publish dialog in Connect so you can disable the Web Form generation. This is handy when you have lists with many thousands of choices in your XLSForm.
  • UTC offset property: ArcGIS Hosted Feature Services store date and time information in UTC. This causes issues in some applications (like ArcMap) that are not UTC-aware, when people work across multiple time-zones. To compensate for this, we have extended the pulldata function so you can store the UTC-Offset of the device from which the data is being submitted as a GIS attribute. The syntax is as follows: pulldata("@property", 'utcoffset').
  • Calculate select_ones: Last but not least, you can now calculate values in select_one questions.  That is, you can trigger a selection on a select_one question from a calculation. There have been multiple threads on this in GeoNet including: Criteria / Calculation Based Select_One Auto-Population , Pre-populate Select One/Select Multiple fields from CSV , Auto-Populate Select One Question Based on a Previous Select One Question  and default depending on previous answer
  • Go to the top of a repeat on new record: Did you ever feel like you were stuck at the bottom of a repeat when adding a new record? Did you ever feel like you wanted to be taken back to the top?  Well... 2.7 does it now for you! Thanks to all of your feedback on this one too:Have a new repeat scroll to top , Adding record in repeat stays at bottom of group. , Have a new repeat scroll to top.


If you are a developer building your own version of Survey123, you can also now download the latest code from AppStudio for ArcGIS.


Beyond 2.7


Looking at next steps beyond 2.7, we have already a handful of projects that have made sufficient progress as to be shared in a near-term road map. Our next major release will be 3.0, which we envision shipping around July 2018.   If needed, we may squeeze 2.8 and 2.9 as maintenance releases with critical fixes, but 3.0 in July will be the update with the most relevant new features, of which I want to highlight:


  • Custom Form Reports: Our The specified item was not found. blog post  anticipated this feature, which is currently available to all of you in Beta.  We are working hard to move this feature into general release and incorporate into it bulk report capabilities.
  • Support for nested repeats: This feature is available for testing already through our Early Adopter Program and allow you to author surveys that have repeats within repeats.
  • Enhanced support for external GNSS receivers: At the moment, you can use external GNSS receivers with Survey123, but only in a limited way. For example, you cannot extract key metadata from the receiver such as  VDOP, HDOP, Number of Satellites or the Fix Type...  With the 3.0 update our intent is to extend the pulldata() function so you can also extract this important metadata and store it along with the features you capture.  We also plan to provide support for RTK corrections. We are working towards having this feature available for testing in our Early Adopter Program around June.
  • Webhook integration: An earlier post Sneak Peek: Survey123 and Webhooks (Integromat) described this work in more detail. Available for testing today through the Early Adopter Program.
  • GeoSearch in the Survey123 field app map widget: Check out this video in our Early Adopter Program for details. Available for testing now.
  • Support for Web Maps, Vector Tiles and Mobile Map Packages: This is  a big deal as it will make maps for geopoint questions much better looking, useful and lightweight.  Looking at having this available for testing around June.
  • Pages: While Pages are not officially supported yet, we continue working on improving this feature.  Starting with 2.7 you will notice that the page navigation has been vastly improved, although there are multiple areas that still need more work before we can call it 'ready'.  If you are into pages, do not hesitate providing your feedback via the Beta forum in our Early Adopter Program.


A lot in the plate as  you can see for 3.0. Our focus however it is not going to deviate from listening carefully to all your feedback through this GeoNet Group, so keep your questions and suggestions coming!


There are many other ideas in our backlog including survey pages, support for polygons and lines, on-premises setup of all components of Survey123 and many other enhancements which remain as high priority in our list, but will see the light after the 3.0 release.