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

ArcGIS Survey123

179 posts

It took longer than we expected, but a new update to Survey123 is now available! This update is part of our 3.10 release cycle, which commenced a few weeks ago with new features introduced in the Survey123 web app, website and report services.  If you haven't already, check ourWhat is new in Survey123 (July 3, 2020) announcement as it covers aspects of this release that are not presented in this blog.

 

We believe you will be excited about the many new things included in this version. Before we start, here is a very quick video with some highlights:

 

 

And now a more detailed discussion:

 

Streamlined Survey123 deployments

 

In this update we have bundled a handful of great new features to help you deploy and manage Survey123 more easily within your organization.

 

Administrator View in the Survey123 website

 

As you login into survey123.arcgis.com as a user with ArcGIS administration privileges, you will notice that a new Organization page will make itself available. As an administrator, you have access to all surveys published in your organization. This new Organization page will help you more easily search and manage surveys created by other users.  You will be able to filter surveys by owner and use the usual search and sorting options.  Once you find the survey you were looking for, you will be able to do all things you, as an admin have been granted privileges to do: change the sharing properties, look at the data, update the survey questions, etc.

 

 

Survey123 organization settings

 

Aside from the gallery of surveys within your organization, you will also find a new Settings tab. You can use these organizations settings to define the default behavior of a handful of important things. For example, you can define the group in your ArcGIS organization that sets the collection of basemaps that should be included in the basemap switcher in the Survey123 app.  Finally, you can also define the basemap within that group that should be applied by default to all new designs in Survey123 designer and Connect.

 

 

Through an organization setting you can also require all users of the Survey123 field app to update surveys in their mobile device when a new update is made available.  Since this is an organization setting, it will override the 'require survey update' policy set by the owner of the survey from within Survey123 Connect (more on this later).

 

Survey123 organization settings are a powerful concept, allowing ArcGIS administrators to define certain behavior for survey users and designers. We envision progressively adding more settings over time.

 

MDM AppConfig support

 

If you choose to deploy the Survey123 field app through a Mobile Device Management solution, you can now define certain behavior of the Survey123 app through the use of AppConfig.  For example, you can use AppConfig to set the URL of the ArcGIS portal that the app will target by default, streamlining the initial setup of the app by end users.  You can also disable certain features in the app, such as the ability to generate diagnostic logs or email data recovery files. Philip Wilson describes all of this nicely in hisConfigure Survey123 Properties in your MDM with AppConfig blog post.

 

Silent installs of Connect and the Field App

 

It is not a secret anymore, we can say this out loud. Both Survey123 Connect as well as the Survey123 field app can now be installed and uninstalled silently (completely silently. No more popups!).  Instructions to create your own installation scripts are included in the Unattended uninstall and install help topic.

 

silent-uninstall-install-ArcGISSurvey123Connect.bat

Survey123ConnectInstallFile.exe

 

Survey123 website installer update

 

For those of you who want to deploy a local copy of the Survey123 website and REST API in your own server, we are preparing a Windows installer. This will allow you to deploy Survey123 entirely in your own infrastructure, side by side with ArcGIS Enterprise, allowing you to work in completely disconnected environments.  Installing the Survey123 website can also be of interest when working in remote areas with weak internet connection, or when you simply want to minimize external dependencies to better comply with security policies within your organization.

 

The first version of the Survey123 website installer will be made available in just a couple of weeks.

 

Better maps for your surveys

 

With this update maps look better and most importantly, you can configure your surveys with your own custom maps too. 

 

Better looking basemaps in the Survey123 field app

 

The Survey123 field app now uses a new ArcGIS Runtime map rendering engine. To start, this means that vector basemaps are now supported. As your ArcGIS organization basemap group is likely using vector basemaps, Survey123 will now be able to render them automatically.  Vector basemaps deliver a much better experience than traditional raster tiled basemaps: they look crisper in your device, are more lightweight and include labels that rotate to remain readable as you change the direction of your map.

 

Survey123 field app showing a custom web map

Defining custom maps for your surveys

 

In the screenshot on the side, you can see how the map included in the survey is using a custom web map: it includes the Esri Topographic basemap and a parcel layer with blue outline and labels on top. 

 

You can now tailor the map shown in your Survey123 smart form so it better fits the workflow at hand. Maps can provide important context to end users while completing the form.  Starting with version 3.10, you can easily configure your surveys to use your own web maps, mobile map packages, vector tile packages, etc.

 

As the author of a survey, you can configure your surveys to use your custom map by default, or simply add it into the basemap switcher.  This is done through Survey123 Connect, using the new Linked Content dialog.

 

Custom maps set on your survey are honored in both the Survey123 web and field* apps.

 

*Note:  Android devices with an armv7 architecture and 32 bit operating system are not capable of efficiently rendering ArcGIS vector tiles and offline maps. In these devices, Survey123 will default to standard Esri raster tiled basemaps and not honor custom maps defined in your survey.

 

Check Survey123 Tricks of the Trade: Configuring survey maps  for more details on this.

 

Better Survey123 folders in the field app

 

The Survey123 field app models the organization of local survey records, similarly to how you organize your email. If you have a survey which you have not completed and you are not ready to send, you keep it in the Drafts folder. If your survey is ready to be sent, but your device is disconnected, then it goes into the Outbox. Once a survey is sent, it goes into the Sent folder.  Finally, just like in your email, there is a folder for anything that needs attention: the Inbox.  The Inbox brings existing records from ArcGIS, so you can open, update and resend them.

 

Survey123 records in these folders can be displayed as a list and as a map. In this release, the list view has improved quite a bit, helping you more easily sort, search and navigate to them. 

 

  • Sorting: Sort alphabetically, by date and by distance to your location.
  • Search and filtering: Enhanced with built-in barcode scanning capabilities.
  • Navigation: Display distance and direction indicators for each record and link to navigation apps in your device.

 

The illustration below shows for example how records in the Inbox can be sorted by distance. If the Inbox is used to list the assets assigned for inspection to the currently logged-in user, this option helps promote to the top the assets that are closer to the inspector.  Note the new location indicators are shown in the middle image.  The arrow indicates the direction in which the asset can be found, as well as the distance. The direction and distance indicators update every few seconds while the end user is on the move.  Finally, a handy shortcut allows users to easily load into third party navigation apps the location of the selected record.  This, naturally, includes ArcGIS Navigator.

 

 

All these enhancements are particularly interesting for routine inspection workflows, where the Inbox is used as a 'to do' list for the day, but the enhancements apply equally to the Drafts, Sent and Outbox as well.  The behavior of the Survey123 folders is defined by the author of the survey according to the needs of the business workflow. See the Survey123 Connect section later in this blog for more details.

 

Better support for attachments: photos (image) and documents (file)

 

Survey123 has supported working with ArcGIS attachments for quite some time. ArcGIS attachments allow you to associate media (photos, images and documents) with existing GIS records.  Survey123, for example, uses ArcGIS attachments to store photos, signatures or drawings sketched from your smart form.  This release introduces quite significant enhancements and new features for working with attachments.

 

One image question, multiple photos

 

Up until this release, image questions in Survey123 allowed end users to take one single question. With this limitation, anyone needing end users to take multiple photos in a survey, either added multiple image questions to the survey or enclosed the image question within a repeat.  While both approaches somewhat worked in some cases, there were drawbacks associated with them.  Starting with this update, you can configure an image question to allow multiple photos.

 

The screenshot below highlights how you can specify, from Survey123 designer, the number of photos that should be submitted with an image question. You can pick a fixed number, or a range.

 

 

The number of photos that can be submitted from an image question can also be controlled through XLSForm syntax in Survey123 Connect. In its simplest form, you can simply apply the multiline appearance to your image question. Additionally, you can also use the count-selected() function against an image question and it will return the number of photos in it. For a more in-depth discussion on this, check the Survey123 Tricks of the Trade: Photos blog post. which explores this and a few more things in more detail.  If you have surveys already with image questions, I bet you may want to make some adjustments in your form after learning about these enhancements.

 

As you work with the Survey123 field app, you will also notice that the experience to capture and manage photos captured from your device has been changed. We made slight modifications to streamline the user experience when navigating through captured photos, for rotating and renaming the photos before submission, etc.

 

Should users take a new photo or will they be allowed to browse for existing ones?

 

So many of your wanted to have a say on that critical question, so we gave you now control so you can decide. As the author of the survey, you can now use the method parameter in the body::esri:style to control if the image question should allow users to browse for existing photos from the gallery or if the camera should be used instead to take a new photo.

You will find more info about the method parameter in body::esri:style in the Survey123 Tricks of the Trade: Photos blog post.

 

File type question

 

The file question allows end users to upload documents as part of a survey submission. PDF files, word documents, compressed files, etc. The complete list of file formats that you can upload through this question type is limited by the file formats supported by ArcGIS attachments. The complete list can be found at the bottom of the Edit tables—ArcGIS Online Help | Documentation topic.

File formats supported by the Survey123 file question: 7Z, AIF, AVI, BMP, CSV, DOC, DOCX, DOT, ECW, EMF, EPS, GIF, GML, GPKG, GTAR, GZ, IMG, J2K, JP2, JPC, JPE, JPEG, JPF, JPG, JSON, M4A, MDB, MID, MOV, MP2, MP3, MP4, MPA, MPE, MPEG, MPG, MPV2, PDF, PNG, PPT, PPTX, PS, PSD, QT, RA, RAM, RAW, RMI, SID, TAR, TGZ, TIF, TIFF, TXT, VRML, WAV, WMA, WMF, WMV, WPS, XLS, XLSX, XLT, XML, and ZIP.

The File question has been supported in Survey123 designer and the web app for quite some time. In this release we enhanced it to support uploading multiple files into a single question (similarly to how the image question behaves). This release also adds support for this question type into the Survey123 field app.  This means that you can use the field app from Windows to upload local documents through a form, but also from iOS and Android!

 

Using XLSForm, you can leverage the mutliline appearance and count-selected() function against file questions.

 

Custom JavaScript functions

 

In every release we expand Survey123's capacity to model more sophisticated logic via XLSForm. This is important, as XLSForm expressions are useful to create your own calculations, constraints and to model the visibility of questions and groups.  With this update, you can invoke your own custom JavaScript logic from the pulldata("@javascript") function.  This is relevant because while XLSForm syntax is very straight-forward, JavaScript allows you to model logic in ways that XLSForms alone cannot handle.  Complementing XLSforms and JavaScript is a winner!

 

Custom JavaScript functions are configured in Survey123 Connect, but once your survey is published, the logic can be used from both the Survey123 field and web apps. Using custom JavaScript functions in your smart forms is definitively an advanced workflow, but it is not rocket science: With a basic understanding of JavaScript, there is quite a bit you can do.  You can read the Extending Survey123 smart forms with custom JS functions blog post and the pulldata("@javascript") help topic to learn more about this feature and common use cases for it.

 

Survey123 Connect

 

Revised XLSForm templates

 

Survey123 Connect includes a couple of XLSForm templates to help you start your survey designs from scratch. These templates include a skeleton of the different worksheets and columns used in XLSForm documents as well as built-in tips, validation rules and a few other useful Microsoft Excel tricks to make your life easier.

 

Consolidating feedback and suggestions made over time, we decided to give these XLSForm templates a revision. They have not changed in a big way, as there was nothing fundamentally wrong with them, but they do incorporate small touches that make them better. To learn about all changes made, check out Jim Moore's blog: Updated XLSForm templates for Survey123 

 

Survey Options

 

The Settings | Options dialog in Survey123 Connect now helps you much better control the behavior of your survey in the field app.  This alone is likely worth an entire blog post on its own. I will highlight here a few of the things you can do:

 

  • Choose, as owner of the survey, if end users are required to update their local copy of the survey if you update it.
  • Hide the Collect button. This is particularly useful if cases where you want users to always update existing records through the Inbox.
  • Show location indicators: Adds a distance and direction of travel indicator to items in the Draft, Inbox (for editing existing records), Sent and Outbox folders. Location indicators are really useful to help field users navigate to existing records.
  • You can also use this dialog to enable the Inbox and Sent folder as well as control the size of images sent from the Survey123 apps.

 

 

Other enhancements and fixes

 

Survey123 Connect and field app

 

  • BUG-000130126 The basemap selected for a geopoint question in Survey123 Connect is not honored when viewing the survey through survey123.arcgis.com.
  • BUG-000102606 Creating a Survey in Survey123 Connect for ArcGIS with a period in the Title results in two broken surveys being created.
  • BUG-000126810 The EXIF Sample Form in the Survey123 field app and the Survey123 Connect does not succeed in pulling the latitude and longitude of photos taken on Arrows F-04K and Arrows F-01K devices.
  • BUG-000103458 Survey123 for ArcGIS custom URL schemes do not include support callback parameters such as http://x-callback-url.com.
  • BUG-000095706 Unable to create a new survey or sign in using the Ubuntu version of Survey123 for ArcGIS app.
  • BUG-000131096 Incorrect spelling for settings in Survey123 in Portuguese OS
  • BUG-000125110 Basemaps do not display as expected for all scales when a survey is re-downloaded to a device after imagery updates.
  • BUG-000129238 Survey123 Connect for ArcGIS does not recognize the decimal numbers if the Windows language settings is in Portuguese (Brazil).
  • BUG-000124917 In Survey123 3.5 app for mobile devices, the geopoint question Default Map View button does not return the map extent to the designated default location and instead shows the null point in the Atlantic Ocean.
  • BUG-000113973 When accessing a publicly available survey published to Portal for ArcGIS using the Survey123 for ArcGIS app, if the portal connection is not configured in the app, the survey is inaccessible with the following error message, "Survey ID is not found."
  • BUG-000105957 Deleting a side loaded basemap (TPK file) using the Map Library within a Survey123 for ArcGIS app does not remove the TPK from an Android device.
    BUG-000128449 Unable to view a web map published from Survey123 Connect for ArcGIS built from an existing feature service.
  • BUG-000132191 Please add directions in the description section of this 'Download Survey123 Data' item.
  • BUG-000132196 The documentation for Survey123, "Prepare for editing existing survey data" still shows information about using Non-Standardize Queries.
  • BUG-000131615 The linked content web maps no longer appear in the basemaps list for geopoint questions when opening in ArcGIS Survey123 field app V3.9.149.
  • BUG-000132302 Unable to add multiple images in ArcGIS Survey123 mobile app (iOS) in a survey that was created with ArcGIS Survey123 Web Designer.
  • ENH-000123885 Improve the process of capturing and sending Diagnostic Log files in the Survey123 for ArcGIS Field App.
  • ENH-000107685 The Survey123 for ArcGIS field app should allow different file formats as attachments while submitting form data
  • ENH-000130703 Allow Survey123 to integrate with other apps using Universal links
  • ENH-000118156 Allow for image attachments to be submitted through a webhook.
  • ENH-000123510 Send related record information to webhook providers
  • ENH-000131457 Ability to view photos taken with Survey123 on iOS and Android devices.
  • ENH-000115447 The Survey123 field app should search all internal storage locations for photos on Android devices
  • ENH-000130402 Provide the ability to submit multiple images from a mobile device in one form when submitting survey
  • ENH-000127042 Add ability to organize or filter downloaded surveys in the field app
  • ENH-000123765 Allow the Collect option to be disabled for users in Survey123 field app
  • ENH-000116753 Allow disable the upload image from device's files in survey 123
  • ENH-000116357 With Survey123 for ArcGIS, allow barcodes to be used to search for existing features in the Inbox
  • ENH-000105321 In Survey123 for ArcGIS application, user would like to request for the copy and edit survey feature to be placed under the 'Inbox' folder/feature instead of 'Sent' folder/feature.
  • ENH-000127282 Enhance the performance with Survey123 barcode scanner to include a greater ability to read codes other than black and white
  • ENH-000129448 Please provide documentation that demonstrates accessibility workflows across the ArcGIS Survey123 platform.
  • ENH-000130111 Provide the ability to run the silent installation completely silent without showing install or uninstall progress pop-up.
  • ENH-000122295 Close/Return to initial Application on submission when survey is launched from Custom URL
  • ENH-000107611 Provide the option for a Survey123 survey called outside of the application with the 'arcgis-survey123://?itemID=' Custom URL Scheme to open the 'Inbox' menu by default instead of the 'Collect' menu
  • ENH-000109445 Implement the ability to utilize a secured service as an online basemap in Survey123
  • ENH-000114786 Add ability to customize the map shown in the Geopoint question form in Survey123 for ArcGIS, either by choosing a custom Web Map or by adding boundary datasets within the default map.
  • ENH-000113866 Survey123 field app: add support for PortalURL property via Mobile Device Management (MDM) configuration to set default portal
  • ENH-000111185 Provide the ability to view feature layers as operational layers in a map in Survey123.
  • ENH-000107257 Display results of a survey submission in the map view of the Survey123 Field app when geopoint locations that were collected are a part of a repeat question.
  • ENH-000126047 The List and Map views are not available on the Sent page of the Survey123 for ArcGIS field app when a survey has a geopoint question within a repeat.
  • BUG-000132618 An error message, "ERR_TUNNEL_CONNECTION_FAILED" is returned when signing in to the ArcGIS Survey123 field app after removing a previous Portal for ArcGIS connection that utilized SAML authentication.

 

Survey123 website, web app and report services

 

 

Next steps

 

We will be watching closely GeoNet and and the Esri Technical Support queue in case that adjustments are needed to this update. We have made quite a bit of changes and have new functionality, so we are not ruling out some focused patches.  While this is ongoing, you will see before the end of August the release of the Survey123 Website installer for Windows. A Beta version of 3.11 should be made available for testing in late August or early September through the Survey123 Early Adopter Community website as well.

Starting with ArcGIS Survey123 version 3.10, you can now configure properties via Managed App Configuration (AppConfig) in your Mobile Device Management (MDM) solution or by configuring application property defaults when creating a custom build of Survey123 using ArcGIS AppStudio. By configuring Survey123 properties you can manage how the Survey123 field app is installed on mobile devices and ensure that the properties are standardized and configured according to your company policies in your enterprise environment.

 

What are EMMs and MDMs?

 

Enterprise Mobility Management (EMM) is a set of people, processes and technology focused on securely and efficiently managing systems and devices (desktop, server, and mobile). This includes setting policies, pre-configuring settings, applying restrictions, deploying apps, and setting profiles and assignment policies to deliver apps to your managed devices. The management of mobile devices is one of the many components available as part of an EMM solution.

 

There are a number of Mobile Device Management (MDM) solutions that can help you implement your EMM solution for managing your enterprise mobile devices, and these MDM solutions include support for what is known as Mobile Application Management (MAM). Here are just a few of the available MDM solutions that many of the Esri mobile apps have already been tested and successfully deployed with: VMware Airwatch, Microsoft Intune, MobileIron Cloud, Samsung Knox, Citrix XenMobile, IBM MaaS360, and Cisco Meraki.

 

What is Managed App Configuration?

 

Managed app configuration allows apps to be remotely configured through an EMM solution. In order to use managed app configuration, the app must be installed on the device and managed via an MDM solution. While managed app configuration is a feature supported by most of the popular MDM providers, it's best to check with your provider if this feature is supported.

 

In general, MDM providers support AppConfig using key-value pairs. In Survey123 we follow the guidelines found within the AppConfig community's XML standard specification for iOS, Windows, MacOS and Linux. On Android, we support Android's Restriction Manager XML spec.

 

Currently, managed app configuration in Survey123 via an MDM is only supported on iOS and Android.

 

Supported AppConfig Properties

 

The following properties can be configured for the Survey123 field app via AppConfig key-value pairs set in your MDM provider. These properties can also be configured as application property defaults in a custom build of Survey123 by modifying the application properties found in the settings menu of your custom application in ArcGIS AppStudio.

 

Key NameTypeDefaultDescription
portalURLstringhttps://www.arcgis.comDefault portal URL.
portalNamestringArcGIS OnlineDefault portal display name. If portalURL is configured then this property should also be configured.
portalAuthenticationstringN/ADefault portal authentication parameters. Comma separated, case insensitive.
  • Blank for default authentication configuration
  • IWA - Integrated Windows Authentication
  • SSO - Enables single sign on for Windows clients when combined with IWA.
portalResourceKeystringSurvey123PropertiesResource name used for organization level properties.
requireSignInbooleanfalseUsers are required to sign in to continue to gallery page.
enablePortalManagementbooleantrueUser can manage ArcGIS Connections (add or remove portal configurations).
enableDiagnosticsbooleantrueEnable diagnostics options in Settings menu.
enableDataRecoverybooleanfalseEnable data recovery to send survey database and attachments.

 

If your portal uses IWA authentication and you are configuring the default portal connection in your MDM or in an AppStudio custom app using the portalURL property, the following three properties must be set:

 

  • portalURL
  • portalName
  • portalAuthentication (set as IWA)


Failure to set the portalAuthentication type on an IWA portal will cause an issue in deploying the AppConfig settings when adding the portal to the list of ArcGIS connections in the Survey123 field app.

 

Adding managed app configuration settings in your MDM provider

 

Below is an example of how to set the key-value pairs when creating an app assignment for your Survey123 application, in this case using the VMware AirWatch MDM console. Note that the UI and available options will differ in each MDM solution so please check with your MDM provider and relevant documentation about how to set AppConfig properties.

 

Setting application property defaults via ArcGIS AppStudio

 

Below is an example of how to set application property defaults via ArcGIS AppStudio for your custom Survey123 application:

 

 

 

For more information on configuring Survey123 properties, please refer to the ArcGIS Survey123 online documentation.

 

If you would like to know more about Esri's approach to Mobile Application Management, please read the ArcGIS Secure Mobile Implementation Patterns document available from the ArcGIS Trust website.

The XLSForm templates for ArcGIS Survey123 have been updated with a fresh new look in version 3.10. The new templates are available in Survey123 Connect in the New Survey dialog under Templates.

 

XLSForm templates in the New Survey dialog in Survey123 ConnectIt's important to note that your existing XLSForms will continue to work as normal! This blog post provides an overview of Survey123's templates and what's new in 3.10, as well as some best practices for working with the templates. But first, a quick XLSForm recap...

 

XLSForm and Survey123

 

Survey123 is based on XLSForm, a standard specification for authoring survey forms. Survey123 Connect takes an XLSForm and converts it into a format that respondents can fill out. Surveys authored in the Survey123 web designer also rely on XLSForm; when you publish a survey in the web designer an XLSForm is created automatically behind the scenes.

 

An XLSForm can be any .xls or .xlsx file that satisfies the minimum XLSForm requirements. For more information on the required sheets and columns, refer to XLSForm essentials—Survey123 for ArcGIS | Documentation. Beyond the required sheets and columns, the Excel file can include any other worksheets you like. You can also change the formatting on any of the sheets (for example, cell shading or font size) and remove any unused columns (with the exception of the required columns) without affecting the function of the XLSForm. So long as the right values are in the right columns on the right sheets, your design should convert to a survey form in Connect without issue. While it's possible to make your own XLSForm from scratch, Survey123's templates provide everything you need to get started with your survey designs.

 

The templates you download in Survey123 Connect are designed to help you conform to the XLSForm specification. The templates contain the required sheets and columns, and include data validation rules and drop-down lists to help you fill out your XLSForm correctly.

 

While we've progressively added new columns, question types and appearances to the template with each release of Survey123, we thought it was time to give the look and feel of the templates a refresh and also introduce a new Standard template.


What's new?

 

Prior to version 3.10 Survey123 had two templates: Advanced and Basic. At 3.10, Advanced has been updated and Basic has been replaced by Standard.

 

Advanced template

 

The updated Advanced template is very similar to the previous one, in that it includes all of the XLSForm question types, appearances, and columns supported in Survey123. Here are the key changes to the new version:

 

  • The types worksheet has been replaced by a set of six supplementary sheets (more details in the worksheets table, below).

 

Excel worksheet tabs in the updated XLSForm templates

 

  • Columns on the survey sheet have been rearranged into a more logical order. The most commonly used columns are closer to the left of the worksheet, where they're easier to access. Because the order of columns has changed, please take extra care when migrating existing surveys to the new template (see more on this, below).
  • Colours, fonts and styles have been refreshed to give the template a more modern look and feel. Arial is so 2004!
  • In the drop-down for the type column on the survey sheet, the square brackets around "list_name" for select_one select_multiple questions have been removed. These brackets should not be included when specifying the list name, and their inclusion in the previous templates was the source of some confusion! As an example, to use a choice list named "fruits" for a select_one question, enter select_one fruits in the type column.

 

Standard template

 

The new Standard template replaces the Basic template, which was deemed to be, well, a bit too basic! The Standard template is essentially a "cut-down" version of the Advanced template that includes only those question types and appearances that are supported in both the Survey123 field app and Survey123 web app. The Standard template is useful for surveys intended to be used in both apps, where you want a comparable experience in the field app and on the web.

 

Some columns have also been omitted to further simplify the Standard template. The language columns have been removed from the choices and settings sheets and a handful of the more specialised columns have been omitted from the survey sheet, as follows: body::esri:inputMask, label::language (xx), hint::language (xx), body::accuracyThreshold, bind::esri:warning, bind::esri:warning_message, and bind::saveIncomplete.

 

Worksheets

 

The following table outlines the contents of each worksheet in both the Advanced and Standard templates. The green shading denotes a required XLSForm sheet and the blue shading denotes a new supplementary sheet:

 

WorksheetDescription
surveyContains all questions, calculations, appearances and other features that make up your survey form design.
choicesChoice lists for multiple choice questions (select_one and select_multiple) are stored here.
settingsGeneral settings for your survey, like form title.
VersionInformation about when the template was last revised. In the Advanced template, the compatibility information on the Question types and Appearances sheets might change with each revision, so it's important to refer to the revision date to determine the currency of this information.
Question typesList of question types you can use in the type column on the survey sheet. In the Advanced template, columns C and D indicate if the question type is supported in the field app and web app, respectively.
AppearancesList of appearances you can use in the appearance column on the survey sheet. In the Advanced template, columns D and E indicate if the appearance is supported in the field app and web app, respectively.
Field typesList of Esri field types and form bind types you can use in the bind::esri:fieldType and bind::type columns on the survey sheet.
ReferenceUseful reference information for functions, operators, HTML formatting, and regular expressions.
ReservedA list of reserved keywords that cannot be used in the name column on the surveys sheet.

 

Best practices

 

Here are some best practices for getting the most out of the Survey123 templates and avoiding common headaches. For a more detailed resource of excellent Excel tips, see Ismael Chivite's blog post Survey123 Tricks of the Trade: Microsoft Excel.

 

  • Do not modify the contents of the supplementary sheets. These sheets contain tables and named ranges that are used in the data validation on the survey and settings sheets, so it's best to leave them alone.
  • When copying and pasting cells or rows, always use the paste values option to preserve data validation:

 

Paste values in an Excel worksheet

 

This is especially important when copying cells or rows from another workbook; unless you paste the values only, you will likely retain a link to the data validation in the other workbook, which can lead to errors:

 

Warning message for links in Excel workbook

 

  • If you're a dab hand with XLSForm you can simply remove the data validation if it's annoying you. Survey123 Connect will validate your form as it's updated, so your syntax will be checked in any case. To remove data validation in Excel:
    • Select a cell, range, row or entire sheet.
    • On the Data ribbon, click Data Validation.
    • Click the Clear All button to remove all data validation rules for the selected cell(s).

 

Clear data validation in Excel

 

Migrate an existing survey to a new template

 

While using the new templates is not essential, you might want to update an existing survey to the new look and feel. Here are some tips for migrating an existing survey to the new template:

 

  • Download a template from one of the following links: Advanced or Standard.
    • Alternatively, create a new survey in Connect to get a copy of the template.
  • In your existing Excel file, column-by-column, copy the contents of the survey, choices and settings sheets and paste into the corresponding column in the new template. As mentioned, the column order has changed so a straight copy-paste of the entire sheet isn't going to work. Remember to use the paste values option!
  • Replace the existing .xlsx file in the survey's folder in your C:\Users\UserName\ArcGIS\My Survey Designs directory with the new version, ensuring the file name is identical to the original.
  • Republish your survey.


For those with a keen eye, here's a list of other changes:

 

  • Added the file question type, which is supported in the field app as of 3.10.
  • Modified the data validation rules in places to make it more user-friendly.
  • Removed the yellow input messages (tool tips) on the survey and choices sheets.
  • Example instance name added to the settings sheet.
  • Dummy form title added to settings sheet.
  • Example select_one question added to survey sheet.
  • All of the samples in Connect have been updated to the new Advanced template.

 

We hope you enjoy the new templates and look forward to your feedback! Please leave a comment below, or drop us a line at survey123@esri.com.

Survey123 includes powerful capabilities to help you specify how photos should be captured from your smart form. With the 3.10 release, even more powerful new features were introduced: multiline appearance and the method setting in the body::esri:style column. This blog highlights these new features and a few other techniques so you can get the best out of photos in your smart forms. Most of what is described in this article involves the use of Survey123 Connect and requires familiarity with XLSForms. Check out the Survey123 XLSForm tutorials in YouTube or our documentation if you need to get started.

 

As with many other Tricks of the Trade articles, we will start easy, and progressively explore more sophisticated techniques one step at a time.

 

The Basics: One question, one photo.

 

If you want your users to submit a photo through your smart form, you will include a question of type image. Here is an XLForm example:

 

typenamelabel
geopointlocationIncident location
imagephotoPhoto of the incident

 

Like any other question type, you can use the required column to define if the end user must submit data for your question or not. In the next XLSForm example, an expression is used in the required column to determine if a photo must be submitted. If the severity of the incident is high, then a photo must be submitted. Otherwise, the photo question will be presented to the user as optional.

 

typenamelabelrequired
geopointlocationIncident location
select_one severityseveritySeverity
imagephotoPhoto of the incidentselected(${severity},"high")

 

Controlling the source of the photo: Camera versus browse

 

By default, the Survey123 web and field apps will let end users either take a new photo using the camera or browse for an existing photo in the device. Sometimes, you want to have control over the source of the photo. If you are designing a survey for inspectors to document code violations, for example, you may want them always to take a new photo with the camera, and not allow browsing of existing photos in the device.

 

The method parameter in the body::esri:style XLSForm column lets you specify if both methods are allowed, or just one. If the method parameter is set to camera, users will need to capture a photo using the camera. If method is set to browse, users will need to browse for an existing photo. If you want to give users a choice, leave the the body::esri:style column empty or set the method parameter to camera,browse

 

Here is a visual representation of what the user experience looks like using the different method parameter options:

And here is what an XLSForm looks like if you want to force users to submit a new photo from the camera:

 

typenamelabelbody::esri:style
geopointlocationLocation
imageimagePhotomethod=camera

 

One question, multiple photos

 

If you want users to submit more than one photo with your survey, you can either add multiple image questions or alternatively use the multiline appearance on an image question. There are good cases for both approaches. For now, lets start with the multiline appearance:

 

typenamelabelappearance
geopointlocationIncident location
imagephotoIncident photosmultiline

 

Support for the multiline appearance for image questions was added in version 3.10. When using the multiline appearance you will initially not see much of a difference in your form. However, after you take the first photo, you will see that new options appear for you to take additional photos and navigate through all the photos you have taken.

 

Counting photos submitted, and limiting how many photos can be submitted

 

The XLSForm count-selected() function can be used to get the number of photos a user has added to an image question. Two common uses for this function are calculations and constraints.

 

The following example shows how you can store as a feature attribute the total number of photos submitted through an image question. Once you have this attribute, you can use it to filter, label or simply set the symbology of features in a web map. For example, you may want to create a filter to hide features with no associated photos.

 

typenamelabelappearancecalculation
geopointlocationIncident location
imagephotoIncident photosmultiline
integerphoto_countPhotos submittedcount-selected(${photo})

 

Using count-selected(), you can also also control how many photos can be submitted with a question. For example, you can setup a constraint to limit photos submitted with your image question to less than 5:

 

typenamelabelappearanceconstraint
geopointlocationIncident location
imagephotoIncident photosmultilinecount-selected(${photo})<5

 

You can use count-selected() against an image question with and without the multiline appearance.

 

Image questions and repeats

 

Support for the multiline appearance in image questions was added with version 3.10. Before that, if you wanted users to upload more than one photo you had to either add multiple image questions to your survey or include the image question within a repeat. Adding multiple image questions in a survey is still a valid pattern, as we will describe later. Creating a repeat block simply to include a single image question is never a good idea, because the repeat will create a new related table and your attachments will link to that table. It will be extremely difficult for you to later explore the attachments in ArcGIS that way. Instead of using a repeat for that, use the multiline appearance as described above.

 

typenamelabelhint
geopointlocationLocation
begin repeatphotosPhotosDo not create a repeat just to add a single image question in it. Use the multiline appearance instead on the image question (as shown above)
imagephotoPhoto
end repeat

 

For clarity, this is not to say that you should not include image questions within a repeat. For example, If you want to have a repeat and then add an image question along with a text question for a description or something else, that is all good. It is adding a repeat containing just an image question that should be avoided.

 

Here is an example where having an image question within a repeat is justified. In this case, the repeat makes sense because we want to associate multiple attributes (Direction, Latitude, Longitude as well as a user entered description) with every photo.

 

typenamelabelcalculationbind::esri:fieldType
geopointlocationLocation
begin repeatphotosPhotos
imagephotoPhoto
textdesDescription
calculatedirDirpulldata("@exif", ${image}, "GpsImageDirection")esriFieldTypeDouble
calculatelatLatpulldata("@exif", ${image}, "GpsLatitude")esriFieldTypeDouble
calculatelonLonpulldata("@exif", ${image}, "GpsLongitude")esriFieldTypeDouble
end repeat

 

Note that photos in the repeat table have attributes to extract their direction, latitude, longitude and even a user-entered description of the photo. Storing all these attributes for every one of the photos would not be possible using the multiline appearance in the image question. This is what justifies the use of the repeat.

 

If you are not familiar with the pulldata("@exif") function check the Working with EXIF image metadata in Survey123 for ArcGIS  blog post.

 

One survey, multiple photos

 

It is possible to include multiple image questions within a single form. Note that adding multiple image questions to a form is very different from enabling multiple photos in a single question.

 

The Virginia Department of Agriculture and Consumer Services (VDACS) was notified in early 2020 that many residents in the State had received unsolicited packages containing seeds from an unknown source. To better understand the extent of the problem, a survey was put together for Virginia residents to submit reports of unsolicited seed packages. In this survey, one question was added to capture a photo of the front of the envelope, and a separate question for the back of the envelope.

 

 

Rather than asking users to take one or more photos of the envelope in a single question with multiline appearance, this survey uses two separate image questions. This gives more explicit direction to the user, which generally is going to yield better data.

 

typenamelabel
imagephotoFrontFront of package
imagephotoBackBack of package

 

An additional advantage of using multiple image questions is that each of the photos will be automatically tagged by Survey123 with the name of the corresponding image question. This later on will be an advantage when you want to put your photos into a Survey123 report. Since the front and back photos are tagged differently, you will be able to specify where exactly each of the photos should go.

 

Using multiple image questions within a form is a good practice when you want to explicitly tell users what each photo should contain. In the Virginia seeds use case above, you are telling users to take a photo of the front of the envelope first, and then a photo of the back. This is a good use case. If you want to simply want to open up the possibility of submitting multiple photos of something, then the multiline appearance is the way to go.  For example, say you want people to submit multiple photos of an issue in an asset. You do not know in advance what exactly the end user will report, but you want that user to be able to submit a few photos; that is a perfect example for multiline.

 

Since the multiline appearance was not available in the past, some of you created surveys with multiple image questions as follows:

 

typenamelabelhint
geopointlocationLocation
imagephoto1Photo
imagephoto2PhotoDon't do this. Use mutliline appearance in photo1 instead
imagephoto3PhotoDon't do this. Use mutliline appearance in photo1 instead

 

Now that the multiline appearance has been added, it is time to adjust the XLSForm design accordingly. Remember you can also use the count-selected() function to limit the number of photos that you want people to submit. Removing the extra image questions in your form will not cause data loss, however, keep in mind that the multiline appearance is only supported in Survey123 3.10 or newer, so you will want end users to be up to date with their app version or otherwise the appearance will be ignored.

 

Controlling the size of photos

 

Using Survey123 Connect, you can control the size of photos to be sent to ArcGIS. There are a number of devices out there and each of them may send photos of different sizes. You can bring consistency by properly configuring your survey from Survey123 Connect.

 

In Survey123 Connect, go to the Options tab of your survey and scroll down until you see the Images section. Use that setting to control how big you want images to be when sent to ArcGIS. The default value is 1280 pixels on the largest edge, which generally works well for most workflows, the quality is good and the size of the photo is manageable.  However, you can reduce images down to 320 pixels or leave them in their original size.

 

 

 

Photos in reports

 

Survey123 includes a powerful report service which you can use to create high quality reports in MS Word and PDF format. Check Understanding Survey123 Feature Reports for an introduction to this service.

 

Survey123 reports require you to create a template specifying the content and look and feel of your report. These templates are authored as Microsoft Word documents where you insert placeholders to fetch data from your survey records. The full syntax for report templates is described at Feature report templates—Survey123 for ArcGIS | Documentation 

 

In regards to photos, you can control the size of the photos in your report and even where to put each of the photos from your survey. This is where using mutliple image questions can really pay off.

 

For example, the following syntax in a report template will insert into your report the photo corresponding to the incident_photo question in your form. The photo will be added to the document with a width of 300 pixels and the height will grow proportionally to preserve the original aspect ratio.

${incident_photo | size:300:0}

If you used the multiline appearance in your survey, you will want to use the following syntax to ensure all photos in your image question are included in your report:

${#$incident_photos}
${$file | size:300:0}
${/}

Using Microsoft Word tables within your template, you can easily use this syntax to perfectly control how photos in your report are placed.

 

Photo Watermarks

 

Photo watermarks is a neat feature in Survey123. Since this article is about photos, I thought I would bring it up, although there is a separate blog covering this topic Survey123 Tricks of the Trade: Photo Watermarks 

Take a look at the two Survey123 projects below, both of them use custom maps. The Hydrant Maintenance form on the left uses a map showing the water network as well as color coded hydrants indicating the status of the last inspection performed in them. The hydrants are also labeled indicating both their Asset ID as well as the date of the last inspection performed. The Violation Report project on the right, combines an Esri Topographic basemap with a couple of feature layers: one representing parcel boundaries in blue, and one highlighting existing violation reports within the last year. Using Survey123 web or field app, it does not matter, you can always decide what map is best for the end users of your smart form.

 

 

Configuring the right map for the workflow at hand is important to provide the best possible experience to end users. The map used in the Hydrant Maintenance form helps users validate if the hydrant they are inspecting is in fact the one that should be inspected. The map provides good geographic context. It also gives a visual indication of when hydrants were inspected for the last time. The Violation Report map helps more clearly identify to which property the violation found belongs and if other violations have been reported in the area in the past.

 

In this blog, I will describe how using Survey123 Connect, you can control what maps should be presented to the users of the surveys you create. It all boils down to a couple of things: defining what is the standard collection of maps for surveys across your organization and what are the specific maps that should be included with each survey. This all comes together in the map gallery that gets presented in the Survey123 web and field apps, when users interact with the map. Lets start first getting clear on what I mean by the app map gallery, and then we will learn how to configure the maps that get shown in them.

 

Understanding the Survey123 app map gallery

 

When a user interacts with a map in any of the Survey123 apps (web or field), a map gallery (aka basemap switcher) is available for users to choose what map should be displayed. The illustration below shows that the map gallery can be accessed from the top-right corner of the map in the Survey123 web app. Once opened, the user selects the map to be shown.

The experience in the Survey123 field app is very similar. Below you can see that the end user has opened the Inbox map to look at all the hydrants that have been assigned for inspection today. The map gallery can be accessed to switch the map at any time.

 

The collection of maps in the gallery, is the combination of two sets: the collection of organization basemaps, and a collection of maps linked to the specific survey. 

 

Organization Basemaps

 

Organization basemaps are, no surprise, defined at the ArcGIS organization level and as such, they apply to all Survey123 projects. These are basemaps that will be made available, always, to all Survey123 users through the map gallery.

 

Traditionally, Survey123 pulled the list of maps from the basemap gallery defined at the ArcGIS (Online or Enterprise) level. However, in practice this may not quite work because often the collection of basemaps that makes sense to users of other ArcGIS apps, is not appropriate for Survey123 users. Starting with version 3.10, we introduced a new Survey123 specific organization setting so you can control the contents of the Survey123 basemap collection in the organization. This setting is honored by the Survey123 field app in 3.10 and will be also honored by the Survey123 web app in 3.11. 

 

Generally speaking, you do not want to include many basemaps at the organization level. One or two at most should do for the vast majority of cases. For context, the standard basemap gallery that comes predefined with ArcGIS Enterprise and ArcGIS Online has more than 20 choices. Definitively way too many for the average Survey123 end user. So many basemaps make sense for someone authoring a web map, but not for someone completing a built-for-purpose form. 

 

To create your own custom Survey123 organization basemap gallery:

 

  • Login into your ArcGIS organization with a user with administrative privileges.
  • Create a new Group in ArcGIS.
  • Share web maps with that group, ensuring that the web maps are also shared with Everyone, or at the very least with all users within your organization.
  • Login into the Survey123 website. You should see an Organization tab (only administrators see this tab).
  • Click on Organization and then activate the organization Settings tab.
  • Choose the group from which the maps should be shown and optionally the default map.

 

It is ultimately your call, but generally speaking, one or at most two maps in this group should probably do. Keep in mind that these maps will be shown in all surveys, so you really want to keep the list to a minimum.

 

Survey Basemaps

 

In addition to the maps set by the ArcGIS administrator in the Survey123 organization basemap gallery setting, survey authors can optionally add maps to their own surveys. This is done through Survey123 Connect.

 

In Survey123 Connect, select a published survey and navigate to your Survey Settings -> Map tab. The map gallery will display choices from your organization Survey123 basemap. While the default map selected is set at the organization, as a survey author you can override it by selecting another one from the list.

 

Most importantly, if you switch to the Linked Content tab you will be able to link your survey with other maps, specific to your project. Linked maps will also show in the survey map gallery. You can also select any of the linked maps as the default map of your survey.

 

Lets do this step by step:

 

  • In Survey123 Connect, select a survey and click on survey Settings
  • Click on Linked Content and link a map
  • Optionally, go to the survey Map tab, open the map gallery and select your linked map as the default map, then publish for the default map change to take effect.

 

 

In many cases, users may not even need to ever switch maps. That is ideally what you want to happen!  If you set the right basemap that will help users do their job, then there will be no need for users switching basemaps.

 

Before we finish, just a few additional notes and considerations:

 

  • Before you can link a map to your survey, you must first publish the survey. It is not possible to link maps to a survey that is not published.
  • Once you link a map using Survey123 Connect, you do not need to republish the survey for end-users to see the new map. However, if you want your linked map to also be the default map of the survey, then you need to re-publish.
  • You can link web maps, and also vector tile packages and mobile map packages. Now, if you link offline maps, then end users will need to manually download those linked maps before they can be used. Linked offline maps do not get automatically downloaded when the survey is downloaded or refreshed in the field app.
  • You are responsible for ensuring that linked maps have been consistently shared with your end users. For example, if you link a map that is not shared with Group A, and you share your survey with Group A, then people in that group will be able to use your survey but not access your linked map. You can, of course, take this to your own advantage . For example, if you work with users in 5 separate regions, it may make sense for you to share a single survey with all of them, link the corresponding 5 regional maps and share your linked apps accordingly so only users will only see maps for their own region.

Starting with ArcGIS Survey123 version 3.10, you can incorporate logic in your forms using custom JavaScript functions. Custom JavaScript functions complement XLSForm expression syntax, giving you flexibility to build better calculations, data validation rules (constraints), etc.

 

This blog provides some guidance to get you started with custom JavaScript functions. For completeness, check the pulldata JavaScript help topic. It assumes familiarity with Survey123 Connect, XLSForm syntax and JavaScript.

 

Getting started

 

Let's start with a simple scenario. In Survey123 Connect, create a new survey and add a couple of questions as shown below. Our goal is to create a custom JavaScript function to calculate the greeting question.

 

typenamelabelcalculation
text

myname

Your Name:

textgreetingGreeting:

 

Using regular XLSForm syntax, we could easily calculate the greeting as follows:

 

concat("Hello ", ${myname})

 

This already teaches us something: custom JavaScript functions are not always the best approach. If you can solve something easily using pure XLSForm functions, do not use a custom JavaScript function. In our case, we will use this example only because it helps us focus on the basics of setting up a custom JavaScript function.

 

To invoke a JavaScript function from XLSForm, we use the puldata() function. For example:

pulldata("@javascript","myFunctions.js","HelloMe",${myname})

 

The parameters for the pulldata() function are as follows. First we pass "@javascript" to indicate that we want to execute a JS function. Then, we pass the name of the JavaScript file that contains our function, which in this example is "myFunctions.js". The next parameter is the name of the function within the file that we want to call: "HelloMe". Lastly, we pass as many parameters as the JS function takes. In our case, we will just pass the name of the survey taker, which is contained in the ${myname} question. If the JS function takes more parameters, we would add them in our pulldata() function call as more parameters separated by commas.

 

typenamelabelcalculation
text

myname

Your Name:

textgreetingGreeting:pulldata("@javascript","myFunctions.js","HelloMe",${myname})

 

For the pulldata() function above to work, we need to create a "myFunctions.js" file with its corresponding "HelloMe" JavaScript function. In fact, as you refresh your survey preview in Connect you will get a File not found: myFunctions.js error. That is totally expected.

 

Custom JavaScript files are stored in the survey directory, within a folder called scripts. In Survey123 Connect, click on Files in the left bar. This will open the survey directory. Create a folder called scripts as shown below.

 

Survey123 Custom JavaScript Functions Connect

 

While custom JavaScript functions are now an official feature of Survey123, some of you have been using them already for the past couple of years. Please note that the folder name for the JavaScript functions is now called scripts. For backwards compatibility the Survey123 field app will continue working with the old folder name, but it is best to use scripts as the name moving forward. Now, keep in mind that Survey123 versions 3.9 and older do not know about the scripts folder!

                            

We will now place our myFunctions.js file in the scripts folder with its corresponding HelloMe function. You can use whatever IDE you want to create the JavaScript file. You can even use Notepad if you like. For this example, we will go with something like this:

 

function HelloMe(whosthere) {

    return "Hello, " + whosthere;
}

Once the file is saved in the scripts folder, use the Update button in Survey123 Connect to reload the survey to test your calculation.

 

Survey123 Custom JavaScript Functions Connect

 

When working with custom JavaScript functions, you will want to frequently make edits in your code and test in Connect. Luckily, Survey123 Connect will automatically reload your JavaScript functions into the preview as soon as you change them from the IDE. In the animation below, note that as soon as the JavaScript file is saved, the form automatically reflects the changes.

 

Survey123 Custom JavaScript Functions Connect

 

Naturally, you will find a few bumps before you get your JavaScript functions working. Here are some of the most common errors that you will encounter:

 

ErrorDescription
File not found: myFunctions.jsYour pulldata() function is trying to load a JavaScript file that cannot be found in the scripts folder
Error in myFunctions.js : 6:16 Expected token `;'Syntax error in line 6 of your function.
@javascript error:TypeError: Property 'HelloMe' of object [object Object] is not a function in myFunctions.js:HelloMeYour pulldata() function is trying to invoke a function that cannot be found in the JS file you specified.

 

When writing your own custom JavaScript functions for execution within your Survey123 form, remember that your code will not run within the context of a web browser; you are limited to JavaScript ES6. You can't use DOM objects, or frameworks like JQuery, Ember, Angular, etc. You can't access local files or make asynchronous calls either. Despite all these limitations, there is quite a bit you can do!

 

Once you have your JavaScript function working, you can publish your survey. Custom JS functions are supported in online surveys as well as in the Survey123 field app. However, keep in mind that JS functions will not execute unless a user is signed in to the Survey123 field app or web app.

 

Custom JavaScript functions are not supported in public surveys. A user must be signed in before the JS function executes.

                            

 

Parsing complex data structures

 

A common use for custom JavaScript functions is to parse complex structures, so you can extract key information from them to calculate questions in your form. From an XLSForm perspective, the syntax in your Survey123 form is really not much different from what you already learned in the Getting started section. The real complexity is handled inside the JavaScript function itself.

 

As an example, let's take the contents of an AAMVA PDF417 barcode. This type of barcode is used in driver licenses and encodes information such as name, birthday and many other things. Since the Survey123 field app has built-in barcode capabilities, you can scan such a barcode. The contents would look something like this:

 

AAMVA

 

This JavaScript function formats the AAMVA string from a driver's license into a JSON object, which can then easily be used within XLSForm to extract the specific information you are looking for:

 

function DL2JSON (data) {
    var m = data.match(/^@\n\u001e\r(A....)(\d{6})(\d{2})(\d{2})(\d{2})/);
    if (!m) {
        return null;
    }

 

    var obj = {
        header: {
            IIN: m[2],
            AAMVAVersion: parseInt(m[3]),
            jurisdictionVersion: parseInt(m[4]),
            numberOfEntries: parseInt(m[5])
        }
    };

 

    for (var i = 0; i < obj.header.numberOfEntries; i++) {
        var offset = 21 + i * 10;
        m = data.substring(offset, offset + 10).match(/(.{2})(\d{4})(\d{4})/);
        var subfileType = m[1];
        var offset = parseInt(m[2]);
        var length = parseInt(m[3]);
        if (i === 0) {
          obj.files = [ subfileType ];
        } else {
          obj.files.push(subfileType);
        }
        obj[subfileType] = data.substring(offset + 2, offset + length - 1).split("\n").reduce(function (p, c) {
            p[c.substring(0,3)] = c.substring(3);
            return p;
        }, { } );
    }

 

    if (obj.DL) {
        ["DBA", "DBB", "DBD", "DDB", "DDC", "DDH", "DDI", "DDJ"].forEach(function (k) {
            if (!obj.DL[k]) return;
            m = obj.DL[k].match(/(\d{2})(\d{2})(\d{4})/);
            if (!m) return;
            obj.DL[k] = (new Date(m[3] + "-" + m[1] + "-" + m[2])).getTime();
        } );
    }

 

    return JSON.stringify(obj);
}

 

This is what the actual XLSForm would look like. Note that the myjson question uses pulldata("@javascript") to first convert the output from the barcode question into a JSON string. Then the pulldata("@json") function is used to extract specific attributes from the string.

 

typenamelabelcalculation
barcodeaamvaDL
calculatemyjsonJSONpulldata("@javascript","aamva.js","DL2JSON",${aamva})
textdnameNamepulldata("@json",${myjson},"DL.DAC")
textdlastLast namepulldata("@json",${myjson},"DL.DCS")
decimaldweightWeightpulldata("@json",${myjson},"DL.DAW")

 

Tip: Set the value of bind::esri:fieldType to null in the myjson question if you do not want to store the aamva raw string in your feature layer, but still be able to process it within your form logic.

              

 

Working with repeats

 

Custom JavaScript functions are ideal for processing data in repeats. As of version 3.10, using repeats with custom JavaScript functions is limited to the Survey123 field app. You can retrieve all values for a question within a repeat, or retrieve all records within a repeat.

As of version 3.10, support for repeats in pulldata("@javascript") is limited to the Survey123 field app.

                    

Passing a question within a repeat to pulldata("@javascript")

 

When you pass a question within a repeat to pulldata("@javascript"), the JavaScript function receives an array of values for the specified question. For example, lets say we want to display a warning message if the user has introduced duplicate values in a question within a repeat. In this case, we want to create a JavaScript function that takes an array and returns true if duplicate values are found. Something like this:

function HasDups (myArray)
{
 return new Set(myArray).size !== myArray.length;
}

 

Now all we need to do is to call the function and pass the question within the repeat to it:

 

typenamelabelconstraintcalculation
begin repeatfruitsFruits
select_onefruitFruit${dups}=false
integerquantityQuantity
end repeat
hiddendupsDupspulldata("@javascript","myFunctions.js","HasDups",${fruit})

 

When passing a question within a repeat to pulldata("@javascript"), it is important to keep the pulldata("@javascript") outside the repeat. In the example above, note that I first keep the result of the duplicates check outside the repeat, and then I use that value in the constraint expression for the fruit question.

 

Passing a repeat to pulldata("@javascript")

 

You can also pass an entire repeat to pulldata("@javascript"). In this case, your JavaScript function will receive all records within the repeat as an array. Each item in the array is in turn another array representing the values for that record.

 

In our fruits example above, let's pretend we want to calculate how many bananas have been entered. If we pass the entire fruits repeat, we can use a JavaScript function to loop through every record. If the fruit in the record is banana, then we get the quantity value and add it to our total.

function totalBananas (fruits)
{
 var totalBananas = 0;
 var i;
 for (i = 0; i < fruits.length; i++) {
  if (fruits[i].fruit=='banana') {
     totalBananas = totalBananas + fruits[i].quantity;
  } }
 return totalBananas;
}

Here is the XLSForm:

 

typenamelabelcalculation
begin repeatfruitsFruits
select_onefruitFruit
integerquantityQuantity
end repeat
integerTotal Bananas

pulldata("@javascript","myFunctions.js","totalBananas",${fruits})

 

Working with web services

 

Using a custom JavaScript function, you can invoke an ArcGIS or third party web service. For example, say you want to query an existing ArcGIS feature layer and retrieve some attributes for the survey location. Or say you want to call a non-ArcGIS web service to retrieve some data. All of that is possible, as long as the user is online, of course.

 

The following JavaScript function takes a geopoint object and returns the first intersecting feature found in a polygon feature layer. The specific layer targeted in the example is a US ZIP code layer, but you can change the URL to use your own. The output of this function is a JSON representation of the feature. We will see shortly how you can use pulldata("@json") to work with such output.

 

function queryPolygon(location,fields,token,debugmode){

 

    if (location===""){
        return (debugmode? "Location Object is empty":"");
    }

 

    var featureLayer = "https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_ZIP_Codes_2016/FeatureServer/0";

 

    var coordsArray = location.split(" ");
    var coords = coordsArray[1] + "," + coordsArray[0]

 

    var xmlhttp = new XMLHttpRequest();
    var url = featureLayer + "/query?geometry=" + coords + "&geometryType=esriGeometryPoint&inSR=4326&spatialRel=esriSpatialRelIntersects&outFields=" + fields + "&returnGeometry=false&returnCount=1&f=json"


    if (token){
        url = url + "&token=" + token;
    }

 

    xmlhttp.open("GET",url,false);
        xmlhttp.send();

 

    if (xmlhttp.status!==200){
        return (debugmode? xmlhttp.status:"");
    } else {
        var responseJSON=JSON.parse(xmlhttp.responseText)
        if (responseJSON.error){
            return (debugmode? JSON.stringify(responseJSON.error):"");
        } else {
            if (responseJSON.features[0]){
                return JSON.stringify(responseJSON.features[0]);
            }
            else{
                return (debugmode? "No Features Found":"");
            }
        }
    }
}

 

The XLSForm looks like this:

 

typenamelabelcalculationbind::esri:fieldLength
geopointlocationLocation
hiddenmyjsonJSONpulldata("@javascript","myJSFunctions.js","queryPolygon",string(${location}),"*","",true)10000
textzipZIPpulldata("@json",${myjson},"attributes.ZIP_CODE")
textplacenamePLACEMANEpulldata("@json",${myjson},"attributes.PLACENAME")

 

Note that a hidden question is first used to get the output from the JavaScript function. In general, it is best practice to keep a call to pulldata() in its own question. It makes your XLSForm easier to read and most importantly ensures that the Survey123 web app will handle it well.

 

The pulldata("@javascript") call includes multiple parameters this time:

 

  • First comes the location, which is enclosed by the string() XLSForm function. This is needed because JavaScript does not know how to handle XLSForm geopoint objects, but we can work easily with their string representations.
  • Then comes "*", to define the fields we want to retrieve from the query to the ArcGIS feature layer. 
  • An empty string for the ArcGIS token is passed, since the feature layer we are targeting is public. Using the pulldata("@property","token") function you could get the token from Survey123 and pass it in if needed.
  • The last parameter is used to show or hide debug messages.

 

The JSON output from a query to an ArcGIS feature layer can get lengthy. To avoid the output being cut off, it is best to use the bind::esri:fieldLength column and set its value to a big number. Say 10000 for example.

 

Finally, note that the pulldata("@json") function is used to extract the ZIP_CODE and PLACENAME attributes from the output of the JavaScript function.

A user has just filled out a form using a survey designed with ArcGIS Survey123. When they click the Submit button, what do they see? Is it a bunch of boring lines of text and a default green check mark? Or is it a custom branded, animated page that looks like you hired a team of developers to create? Let's dive into how you can take that Survey123 submission page to the next level, with this #InAGIF!

 

A check mark with a circle loading around it

 

With the latest version of Survey123, you can upload images to the submission page in the web application by selecting Design > Settings > and clicking the image button. You'll then see the option to upload an image to your survey. And it doesn't take specialized software to create the image above! It was actually created in PowerPoint, as outlined in the video below:

 

 

A video outlining how to create an animated .gif in PowerPoint using animations.

Using just PowerPoint animations and a basic screen capture software, you can create .gifs to add to Survey123

 

In this basic example, a circle and check mark were created in Microsoft PowerPoint. Then, animations were applied. Finally, the animation was played in slideshow mode, while a screen recording software captured the animation. If you have more advanced tools for .gif creation, you could use those, too!

 

This is a basic example. To really make things look great, make sure the animation matches your organization's theme colors and the colors of the survey. Additionally, set the .gif to only loop once, like in the example below (refresh this article--you may have missed it!). This ensures the animation doesn't repeat over-and-over again. 

Not moving? Refresh this article--you may have missed it!

 

You can pair this styling with some added functionality. For example, adding the ?autoRefresh=4 parameter to Survey123 will allow users to fill out the form, submit, see your image for 4 seconds, then the survey will refresh for the next submission.

Esri’s User Conference is the world’s largest GIS event – and this year it’s going virtual! With so many opportunities to connect and learn with industry experts and peers, why not take the time to learn?

 

Registration

 

Check the Registration Details | 2020 Esri User Conference page for more info. Registration is quick and open to everyone. Once registered, you will be given access to the UC Live website. In UC Live, you will be able to watch the plenary, sessions, visit the Expo and connect with peers and Esri staff.  Just like in San Diego, but from your home!

 

 

Here is a brief Survey123 guide to UC Live.

 

Sessions

 

 

Join sessions to learn about Survey123 product features and how to take advantage of them. Sessions are classified into Live Sessions and On Demand Sessions.  Live Sessions are scheduled. You may want to add them to your agenda so you do not miss them. Live Sessions always include a Q&A section with the presenters at the end.  On Demand sessions are made available for you to watch at any time during the conference.  I suggest you add them to your agenda as well, because there are quite a few. If you have questions after watching the recordings, bring them to the team at the Virtual Esri Showcase.

 

Live Sessions (Watch only at scheduled times):

 

 

On Demand Sessions (Watch anytime during the conference):

 

 

 

As you may know, Esri always publishes a selection of sessions for public access after the User Conference. However, do not count on that as not every session will be available beyond the conference.  I suggest you make room in your calendar during the week to make sure you do not miss sessions. Schedule them at the beginning of the week, so you can take your questions to the team at the Esri Showcase.

Tip: Watch on demand sessions early so you can take your questions to the team at the Showcase.

                    

 

 

Networking

 

 

The UC Live wesbite includes a Networking tab. Use it to connect with other attendees and Esri staff. You can connect with the Survey123 team and schedule private chats to resolve your questions. Here is the list of Survey123 team members that will be available during the week. Generally speaking, all of us can take questions on any aspect of Survey123, but the table highlights areas of focus. The table also includes a link to the profile of each member in UC Live so you can find us more easily in UC Live. In case of doubt: simply email survey123@esri.com.

 

Brett StokesSurvey123 Website Installer for ArcGIS EnterpriseEnglish
Calvin JungSurvey123 JS API, WebhooksEnglish, Chinese (Mandarin)
Ismael ChiviteSurvey123 Website, Reports, WebhooksEnglish, Spanish
James TedrickSurvey123 and ArcGIS Enterprise, XLSFormsEnglish
Jim MooreSurvey123 Documentation, Field App, ConnectEnglish
Jody Zheng LiuSurvey123 Reports and Web AppChinese (Mandarin), English
Marika VertzonisSurvey123 Documentation, Learning Paths, GNSSEnglish, Greek
Philip WilsonSurvey123 Field App, Connect, XLSFormsEnglish
Ruth Jiateng XuSurvey123 Web Accessibility, Website and Web AppChinese (Mandarin), English
Shwu-jing JengSurvey123 Internationalization, LocalizationChinese (Mandarin), English
Zhifang WangSurvey123 Website, Web App, ReportsChinese (Mandarin), English

 

The Survey123 Esri Showcase is a great place to network with other attendees and the Survey123 team. During the Esri Showcase hours, a chat room on Survey123 will be live. Join the conversation:

 

Monday, July 13, 2020 | 12:15 pm – 4:00 pm PDT

Tuesday, July 14, 2020 | 7:30 am – 9:40 am & 11:10 am – 3:50 pm PDT

Wednesday, July, 15, 2020 | 7:30 am – 9:40 am & 11:10 am – 3:50 pm PDT

 

Tip: Join the conversation at the Survey123 Esri Showcase and schedule private meetings to ask questions.

                    

 

 

Exhibitor Expo

 

 

Last but not least, you can also virtually visit many of our UC Exhibitors. Visit the Expo to connect with Esri partners with expertise on implementing, customizing, integrating Survey123, plus hardware vendors to run or complement Survey123 capabilities.

 

 

We are looking forward to see you this week!

We are happy to announce a new update to Survey123. This update only touches on the web components of Survey123 (Survey123 website, report services and the web app) and it is available in anticipation to our official 3.10 release, which will be available later in July or early August, including updates to Survey123 Connect, the field app and the documentation.

 

[Added August 6,2020]: Survey123 3.10 for the field app and Connect is available. Check What's new in Survey123 (August 2020) for details.

 

The main driver for this early update is to bring to you a number of important fixes into the Survey123 web app, but since sometimes it is hard to decouple fixes from new features, you will find in this release some extra juice. One important note to make is that new features in this update are not officially documented. The documentation will come in just three weeks in late July, along with updates to other components of Survey123 like Connect and the field app.

 

Enough preamble, here are the highlights:

 

Survey123 Reports (Price reduction and increased capabilities)

 

Survey123 includes out of the box functionality to help you generate high quality documents from records submitted from the Survey123 web or field apps. This is extremely useful when you need to present your Survey123 data following strict formatting guidelines, for example when mimicking legacy paper forms or to comply with legal documents. If you are not familiar with Survey123 reports, check the Understanding Survey123 Feature Reports blog post and our Feature report templates—Survey123 for ArcGIS | Documentation help topic.

 

With this update, the price of this ArcGIS Online premium service drops from 2.5 credits to 0.5 credits per report. We are aware that this was an important aspect for many of you and we want to thank to all of you that took the time to discuss with Esri staff your use cases and reasoning behind your request. We also want to thank all your comments and community discussion at the Reduce Excessive Credit Cost of Survey123 Feature Reports ArcGIS idea thread.

 

Additionally, you can now try new expanded report template syntax, allowing you to include in your reports summary and statistics sections. This is a significant shift for the report capabilities and here is why: So far, the Survey123 report syntax allowed you to create 'feature reports', that is, a report representing a single survey record. Say for example you use Survey123 to perform routine asset inspections. When using feature reports, your reports include information about a single inspection: The date, status, comments, photos, a map of the location of the inspection and potentially data from related records such as all the incidents found. In feature reports, one report represents a single survey record.

 

Using the new summary section syntax in report templates, you can now create reports that include many survey records. For example, you could create a single report that includes all inspections ever performed, or all inspections in the last week. In a summary report, one report can include many survey records. Summary sections are generally shown as tables. In the following animation you can see a typical workflow where a summary section is used in a report to present a collection of survey records. The report is done against all water hydrants inspected in the past 18 days and it breaks down inspections in color coded tables (summary sections), one for each condition assessed.

 

Survey123 Summary Reports

 

Below is a still screenshot of the report. In it you will be able to appreciate that a small section is included at the beginning with some statistics: Number of hydrants inspected and hydrants that need maintenance. That is, of course, a statistics section, which is also part of the new report template syntax that this update includes.

 

Water Hydrant Summary Table

The new statistics and summary sections bring quite a bit of flexibility to your reports. Best of all, you can combine them all in a single report with a feature report section too. 

 

Back to the early discussion about the price, it will be worth clarifying how summary and statistics account for the price of your reports. Essentially, a report in Survey123, regardless of how many summary and statistic sections are included in it, will always cost 0.5 credits. In the event that you include additional feature report sections, the cost will increase at a rate of 0.5 credits per survey record included. For example:

 

Report includingArcGIS Online credits
1 feature report (one survey record)0.5 credits
1 summary section (as many survey records as you want)0.5 credits
4 summary sections (as shown above in the example)0.5 credits
1 feature report + n summary sections + n statistics sections0.5 credits
5 feature reports (5 survey records)0.5 * 5 = 2.5 credits

 

Photos and maps, can only be included within a feature report section.

            

To help you get started with the new report template syntax, we have added the capability to auto-generate sample report templates with summary and statistics sections as shown below. We will also be releasing a dedicated blog with details on this new syntax in the next few days.

 

 

Enhancements to Survey123 designer

 

Survey123 designer lets you visually create your own smart forms. With this update we are introducing the new Ranking question type. The Ranking question allows users to compare items within a list and sort them in order of preference. Based on the order selected, each item gets a numeric score.

 

Ranking Survey123

 

The main use cases for this type of functionality originate in online surveys. For this reason, this question type will not be initially supported in the Survey123 field app.

 

To avoid bias in responses, the ranking question can be configured to arrange the choices in the list randomly. This can easily be done right from within Survey123 designer.

 

Management view for ArcGIS administrators

 

If your account has administrative privileges in your ArcGIS organization, you will find a new 'Organization' tab in the Survey123 website. This new view, will let you easily find and manage any survey published in your organization. You will be able to update the surveys, change their sharing, etc.

 

 

 

Other fixes and enhancements

 

Last but not least comes a list of various fixes and other enhancements included in this update. It is a long list, and it includes work in very critical areas. As I described earlier in this blog, this is really the main driver for this update, to bring to you as quickly as possible the many fixes and enhancements listed here:

 

  • BUG-000120594 - Support for nested repeats in the Survey123 web app
  • Web Accessibility: Support keyboard navigation in the Survey123 web app (except for ranking question type).
  • ENH-000123510 Send related (repeats) record information to webhook providers.
  • BUG-000131124 A user within a Portal for ArcGIS Organization with a username of 20 or more characters long of only numbers for example,12345678901234567890, is prompted with the following error message, "Unable to publish Details: For input string: "12345678901234567890" when publishing a survey in the Survey123 Web Designer".

  • BUG-000126461 Unable to generate a stakeholder view layer when the source of the survey is a hosted feature layer view.

  • BUG-000126792 Attributes in a field created in Survey123 Connect for ArcGIS 3.6.1.137 using the select_one question type that reference a list_name with True and False choices do not populate in Feature Reports exported from Survey123 for ArcGIS.

  • BUG-000127161 The Basemap Gallery does not honor the custom sorting settings configured in the Basemap Gallery settings of the organization when a survey is accessed from the Survey123 for ArcGIS website. ([Design, web app] Refine the map list for geo questions to respect org settings)

  • BUG-000129766 Public-facing survey's service URL exposes the survey's data, even if the survey's sharing settings are set to private. (Restrict permissions on public surveys)

  • BUG-000131590 Pasting an image in the note's description of Survey123 Web Designer fails to publish the survey, returns the error message, "Invalid protocol: data"

  • BUG-000130588 Survey123 for ArcGIS website fails to show the note in preview mode when a note includes '%' and returns the following error message, "Error Initializing Form - URIError URI malformed." (Percentage sign % in group description or note question which is inside group and page cannot be Previewed)

  • ENH-000123861 Create options for summary of data in report for survey123 ([Report] Support summary report or summary section inside a report)

  • BUG-000127719 [Data]Edit in Individual Response with calculation may change original value after loading

  • BUG-000122381 Unable to view the hosted feature layer of a survey in ArcMap, published to ArcGIS Enterprise from Survey123 website.

  • BUG-000130716 The owner is unable to view any data and receives the message, "An error occurred while loading the page. Some features may not work" in the Data tab in the Survey123 for ArcGIS website when choosing 'Only add new records' in the 'What can submitters do' section. ([Data] Error message "An error occurred while loading the page. Some features may not work." raised during loading the page due to lack of Query capability in the survey layer)

  • BUG-000130065 Individual response: map cannot display correctly when the survey has a geopoint question has a default map which the spatial reference is neither geographic (4326) nor web mercator (3857)

  • BUG-000108603 When adding a geopoint question to a survey using the Survey123 for ArcGIS web designer, it is possible to select a non-web mercator basemap for the question, even if the basemap is not compatible with the survey.
  • BUG-000105581 A Survey123 for ArcGIS survey created on survey123.arcgis.com web hub which includes geopoint question with a user defined home location does not zoom to the correct location in the Survey123 field app; instead it zooms to the 0,0 origin point. (On publish, write Survey123 App - compatible survey settings)

  • BUG-000109078 BUG-000110137 Default map of Geo Point question from website will not work on Survey123 app

  • BUG-000130365 Select_One question records the first choice clicked in a repeat, instead of the final choice selected (select_one in a repeat cannot reflect the selected status in UI as expected)

  • BUG-000130473 If a page does not have a label, any Single Choice question in it cannot work

  • BUG-000127417 With Integrated Windows Authentication (IWA) portals, the geopoint question in Survey123 for ArcGIS gets stuck in Loading state on Google Chrome, Mozilla Firefox and Internet Explorer browsers.

  • BUG-000125138 Signature attachments submitted via webform are not visible in AGOL

  • BUG-000131123 A user within a Portal for ArcGIS Organization with a username that is 20 or more characters long of only numbers (ex. 12345678901234567890) is prompted with the error message, "You cannot submit records to the survey since you are not Submitter or the Owner" when accessing a Survey123 form in the web.

  • BUG-000130565 When taking a survey in the web browser created in Survey123 Connect for ArcGIS and a question has the 'minimal' appearance chosen and 'readonly' set to yes, the user is still able to select an answer for the survey (Read only minimal questions can still take value)

  • BUG-000130090 Geopoint question with the 'read-only' parameter enabled does not capture the latitude or longitude when filling the survey through the Survey123 for ArcGIS web app. (Read-only behavior of locate in Geopoint question)

  • BUG-000127924 When a 'View' URL is configured from a Survey123 web form which has pages, it does not show the questions.

  • BUG-000126498 In Operations Dashboard for ArcGIS, an embedded web form fails to reflect edits performed on a geopoint structured using the relevant fields and calculations in an Excel form.

  • BUG-000125101 The error message, "Error Initializing form.... Failed to load data from" is returned when opening a survey in the Survey123 for ArcGIS website that has been configured with a JavaScript extension in Survey123 Connect to pull data from an existing feature service.

  • BUG-000124744 HTML markup codes appear at the start of the published survey in Survey123 for ArcGIS.

  • BUG-000128852 Survey123 feature reports fail to generate when feature layer name contains accented character (example: é)

  • BUG-000125498 The bit.ly link that is generated by Survey123 will generate a 404 error response when navigating through the browser intermittently.

  • BUG-000131376 Adding a new signature to a survey via web using the edit URL does not save the changes if using a mobile device.

  • BUG-000130958 In the Survey123 for ArcGIS web app, the today() function in the calculation column of an XLSX survey file does not return a value if it is a hidden field with an 'esri:field:type' set to DATE.

  • BUG-000131141 The Analyze tab shows incorrect field in the ArcGIS Survey123 website when using a survey published from Survey123 Connect.
  • BUG-000132326 The error "Error occurred when querying data from the feature layer. Pagination is not allowed unless ''supportsPagination'' is true." is returned when running ArcGIS Survey123 feature reports. (Pagination error occurs when generating a report that has attachments for a survey in ArcGIS Enterprise 10.8).
  • BUG-000132135 Some publicly shared ArcGIS Survey123 surveys prompt a sign-in window when opened through the website (Regression 3.10: Public surveys that use one of 6 old basemaps from Survey123 Connect prompt for sign in if there is also no webmap in the org's basemap group with the same name).

 

Next steps

 

Officially, our 3.10 update is scheduled for July 23, 2020. On this date we will update Survey123 Connect, the field app and also include further work in the Survey123 website, web app and report services. We are furiously working towards having everything ready for you on that date. If you want to know what is coming, I encourage you to join our Survey123 Early Adopter Community. You will be able to download the Beta version of the software and provide feedback to the team. Additionally, we will share more information about the 3.10 release at the Esri User Conference.

Muscat Electricity Distribution Co. (MEDC) is implementing the Survey123 for ArcGIS as a transformation from paper-based to digital/smart-based in different activities such as Maintenance inspection for the Distribution Substation (DSS), Patrolling for the OHL, and Operation where the peak load for the DSS to be collected.

 

GIS Department designed the smart forms in housing and published them using ArcGIS Enterprise. After that, multiple users were created and divided into three groups. Each group was assigned Distribution substations of a separate zone. Then we designed web maps for each Zone with its feature class containing the DSS for each inspector and shared them to be used in Explorer for ArcGIS where the inspectors navigates to the substations and start collecting data by clicking on the URL scheme to pre-populate the main information of the assets inside the DSS based on GIS data.

 

 

 

The inspectors asked GIS department to find a way for changing the symbology of the DSS once it is done directly in Explorer for ArcGIS to avoid dual visiting. So, we added the feature layer of the Smart Form to the web maps for each Zone and changed the symbology of the geopoints to company's logo to differentiate between the visited substations and others then we set the layer to be refreshed intervally.

 

Here is the steps that we did:

 

* Xlsform:

1- Add "Geopoint" question type and set it as readonly to avoid any change of survey point.

 

*URL scheme:

1- Set the center of geopoint by pre-populated the coordinate of substation from URL scheme to ensure that the survey point will be not shifted due to accuracy from the substation point.

Understanding Survey123's custom URL Scheme 

&center={latitude},{longitude}

 

*Web Maps:

1- Add the feature layer of the form to a web map where the substations distributed to each inspectors.

2- Change the symbology of the layer to MEDC logo to illustrate the visited substation.

3- Set the Refresh Interval to 0.1 minutes to update the web map in Explorer for ArcGIS with the new records.

 

 

 

 

 

 

 

So, now the inspectors can see the substations that inspected in the Explorer for ArcGIS with the company's logo as you can see in the bellow video:

 

 

 

I hope that you will inspired with this BLOG.

Ismael Chivite James Tedrick

Thanks,

Hussam Al Jabri

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.

 

We have just updated EAC with new Beta versions of Survey123. You can test the Survey123 website, web app, field app and Survey123 Connect across all supported platforms. Below is a list of some of the Beta features available for testing:

 

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.

 

One question, many photos

 

Configure image questions in your Survey123 forms to allow end users to associate multiple photos with it. Below is a screenshot of Survey123 designer, showing the new options we added to give you more control.

 

 

If using Survey123 Connect, you can now apply the multiline appearance to your image questions to support capturing multiple photos. You can also use XLSForm functions such as count-selected() against image questions in your calculations, constraint and relevant columns. This allows you to do things like: store the photo count as a GIS attribute along with the record, force users to take a minimum and a maximum of photos, etc.

 

We want to make this feature available in our July update. Waiting for your last word! More info for Connect users here, and for designer here.

 

Map enhancements in Survey123 Connect

 

Survey123 Connect now lets you easily configure maps in your survey so you can use your own web maps, mobile map packages, offline map areas, etc. You can also use extended XLSForm syntax to control exactly what each of the maps in your survey will show. A new Linked Content section allows you to browser for existing maps in your organization, so end users of your survey can easily access them from the app.

 

 

All of this may already be somewhat familiar to you because the released software has this feature flagged as Beta.

 Your feedback is important now more than ever as this is ready to be shipping in July. Learn about this feature and more mapping enhancements here.

 

Survey123 organizational settings

 

A collection of Survey123 organizational settings can now be controlled by ArcGIS administrators. Use them to help users and Survey123 authors be more effective and bring consistency to your organization. You can access these settings from the Survey123 website when you are logged with a user with administration privileges.  As shown in the screenshot below, there are a number of settings available.

 


Summary reports

 

Do you wish to create a report template including a table for all records, or a selection set in your survey layer? Do you also want to add statistics for these records? Then it will be worth learning about the extended report template syntax.  Find all the details here.

 

Custom JavaScript functions and pulldata()

 

This is for advanced XLSForm ninjas only. Invoke a custom JavaScript function using the pulldata() XLSForm function. This allows you to model complex logic in JavaScript syntax that would be difficult to express in XLSForms (or not even possible). You can check for duplicate values in repeats, lookup values from web services, perform point in polygon queries and much more. 

 

While this capability has been available in the Early Adopter Program for quite some time, we are now aiming to release it in July 2020.  We made quite a few enhancements in Survey123 Connect to help you test your JavaScript functions and also enabled execution of your own code in the Survey123 web app too.  More info here.

 

Survey123 website installer

 

The Windows installer for the Survey123 website is virtually ready to go. This is for those of you who want to install the Survey123 website locally rather than having survey123.arcgis.com configured to work against your ArcGIS Enterprise. You can now test our release candidate before we officially make it available! Info here.

 

And much more...

 

There are many hidden gems available through the Early Adopter Program to test. You can find a more complete list of features for the Survey123 website here, and a list of other features for Connect and the field app here.  You will find that the Beta builds also address many bug fixes and other minor, yet important, enhancements you have requested via Esri Technical Support and GeoNet.

 

I am writing this blog post because I wanted to document a useful workflow that I developed for using Integromat to automate the creation of Feature Reports for Survey123 after editing the survey data.  As someone who had never used Integromat before, I spent a great deal of time researching the different intricacies of the Integromat modules and how to make them work for what I needed, as I couldn't find any examples that were quite the same as mine.  A lot of this workflow was accomplished by trial and error, so I'm posting this here in the event that someone else may find this example useful.  My particular difficulty in this project came when I attempted to process the automation differently when the survey was initially submitted (addData event type) vs. when it was edited (editData event type.)

 

My scenario is this:

 

I work in local government (city level) and we have continually been making services and applications available online as a convenience to our citizens.  As such, one item on our agenda was to make our Application for New Sewer Service available on the internet.  I created a survey in Survey123 for the purpose of allowing citizens to apply to our Sanitary Board for new sewer service (when you move to a new house and need to put the service in your name, or when you build a new house and need brand new service).  I also needed an easy way for our Sanitary Board staff to process these requests.  Creating an automated workflow with Integromat seemed like it would provide the perfect solution for automation, and paired with the power of Dashboards for ArcGIS, I think it did!

 

The Simple Workflow:

 

1) Citizen submits an application for new sewer service.

2) Sanitary Board staff receives the request.

3) Sanitary Board staff processes the request (they need to add some information to the form, such as new account number, deposit cost, date paid, etc.)

4) Microsoft Word application form is filled out with applicant’s information and filed in archive.

 

The Solution:

 

Workflow Item # 1 – Submitting the Application

 

To allow citizens to submit an application, I created a new survey in Survey123 Connect with all pertinent information included and published to our ArcGIS Online Organization.  This was the easy part.

 

Workflow Item # 2 – Receiving the Application

 

In order for the staff to access the information, I was going to train them on how to use the Survey123 online interface.  The problem with doing this is that they also need to have the ability to edit the data, which at the present time is only available to the survey owner or the individual survey submitter.  This was not going to work.  This is where I found out about embedding surveys in a dashboard Survey123 Tricks of the Trade: Embedding a survey in an ArcGIS Dashboard.  Even more importantly, embedding that survey into a dashboard in edit mode using URL parameters Survey123 Tricks of the Trade: Web form URL parameters (both great blog posts by Ismael Chivite).   This gave our staff the ability to go into the survey record and add data to the “office use only” fields (or change any other field that may have been entered incorrectly in the initial survey), including account number, deposit cost, date paid, etc.  Below is a screenshot of the dashboard with the editable survey form included:

 

 

I also wanted the staff to receive an email when a new record was submitted to avoid missing one or prevent a delay in processing, and this is the first use case for Integromat (I could have used Microsoft Power Automate (MS Flow), but I needed to run a feature report later, which at this time was not available in MS Power Automate).  I’ll post a screenshot of the Integromat Scenario a litte farther down.  I will also attach the blueprint exported from Integromat for those who might want to take a look. That takes care of workflow item #2 – the actual receipt of the application.  Moving on to processing.

 

Workflow Item #3 – Processing the Application

 

Using the dashboard with the editable survey form embedded, staff can now select the survey record (newest submissions come in on top of the list), review all the submitted information, add the new account number and other “office use only” information, then re-submit the now-complete survey form.  Now we need to get all this information onto the Microsoft Word Template that is the actual application form.  This is done using the “Create Feature Report” module in Integromat.  There was a little problem with this step, which I’ll explain a little further down when you can see the Integromat Scenario screenshot.

 

Workflow Item # 4 – Getting the Information onto the “paper” application

 

This item is accomplished using the Integromat “Create Feature Report” for Survey123 module https://support.integromat.com/hc/en-us/articles/360020842234-Survey123I then used the "Microsoft Office 365" module to send the Sanitary Board staff an email with the completed Feature Report attached. 

 

Integromat Scenario

 

Here is a screenshot of the Integromat Scenario:

 

 

Here’s an explanation of the scenario, step-by-step:

  1. Watch the survey for a submission using the “Survey 123 – Watch Survey” module
  2. The first router will send the workflow one way when a new record is submitted (using the addData condition) and the other way when a record is updated (using the editData condition). The top branch is the new submission and the bottom branch is the update (when the staff makes their edits).
    1. When a new survey record is submitted (again, top branch), the first module sends a confirmation email to the person who submitted the survey based upon the email they provided in the survey.
    2. Then the next router looks at the survey record and sends the workflow to one of four paths, depending on how many images were attached to the survey. This part was a bit tricky at first.  I initially had the “add photo” option set as a repeat in the survey, but it seems that repeats are difficult to handle in every aspect (and not supported by many ESRI tools and applications at this time, based on my research), so I simply removed the image repeat and modified the survey to only allow up to 3 images (3 separate “image” fields in the survey).  This router looks at the three image fields to determine if an image either exists for each field.  Based on what it finds, it continues along the appropriate path.  In my setup, the very top path is for surveys with no images, the second one down is for those with only 1 image, the third one down is for 2 images, and the fourth one down is for 3 images. 
    3. The images are retrieved using the “HTTP/Get a File” module. In the event that there is more than one file to retrieve, you can string multiple “Get a File” modules in line to accomplish this task, as you can see that I’ve done for those situations where more than 1 file is submitted with the survey.
    4. Last in this branch, I’ve attached the image(s) to an email that is sent to the Sanitary Board staff. This email serves 2 purposes – First, this is the initial notification that a citizen has submitted an application, and second, it provides the staff with the image attachments they will need to process the application.  This completes the initial submission of the application and concludes the automation of the first branch.  Now the staff processes the application.
  3. With all the information provided with the survey submission, the staff process the application (most of which is done is another computer system, which is where the account number is generated). Once they get all the information needed to complete the application, they open the dashboard I discussed previously and add the “office use only” information into the survey form.  When they hit “Submit”, the bottom branch of the scenario is triggered by the first router in the scenario (again, using the “editData” event type, which is accessed by clicking on the connector AFTER the router and applying the filter to look for “editData”.)
    1. (*Edit - read the comments below from Ismael Chivite - there is an easier way to set up for the Feature Report.  This is how I did it, but he describes a better way that I had not discovered at the time of writing this post.)  The first module on the bottom branch is the “HTTP/Make a Request” module. Theoretically, the next step would be the “Create Feature Report” module, but presently you cannot run the “Create Feature Report” module directly from the “editData” condition.  This has not been built into the tools yet, and it will not work.  I encountered most of my problems in this phase. Based on the research I conducted, only the edited attribute information will be included in the payload after the editData condition (not ALL of the attribute information for the feature; i.e. – only the field that was edited is available in the payload). In order to make the feature report work after an edit, you must first use the “HTTP/Make a Request” module to look up the hosted feature layer in AGOL, queried for the globalid of the current survey record (I also grabbed a few other fields that I used later in the process to assign a document name to my feature report).  Here is a screenshot of my HTTP request module:
    2. Then I used the “Parse JSON” tool. This effectively separates the data returned from the HTTP Request module into separate field names.   This tutorial helped me a lot:  https://youtu.be/QEUSzMadHdE
    3. Next is the “Create Feature Report” module (finally!!). This uses the globalId field that was parsed out from the JSON in the previous step. Basically, this provides the module the globalID for the feature it will use to generate the Feature Report. 
    4. Next is the “HTTP/Get a file” module to grab the completed Feature Report URL.
    5. Finally, I sent the email to the Sanitary Board staff email with the finalized Feature Report attached.

 

Now, here is the logical explanation:  When a new survey is submitted, a confirmation email is sent to the submitter, then an email is sent to the office staff to notify them of the new submission, including any image attachments submitted with the survey.  The office staff then processes the application and uses the custom Dashboard to edit the survey record to include additional information.  When they submit their edits, a Feature Report is created from the survey record and it attaches to an email and sends to the office staff.  

 I’m sure there are other ways to go about doing what I have done, but this is the way worked for me.  I could not find a good resource that explained how to run the “Create Feature Report” module after an “editData” condition, so if nothing else, I hope this helps to explain that process. I’m no programming master (by a long shot!).  Shoot, I’m not really even a novice.  But I do have to say that this Integromat integration is pretty easy to use.  Good stuff ESRI!

 

I've exported the blueprint for the scenario from Integromat and attached it to this post for reference.

 

You should also check out Getting Started with Survey123 and Integromat and Survey123 Tricks of the Trade: Integromat.  There is great information in both of these links.  Thanks!

By definition, a public survey is accessible to anyone who wants to submit data to it, but that does not mean that anyone should be able to look at the data itself. If your public Survey123 form contains sensitive information, you should configure your survey to prevent users in the public domain from downloading, querying or changing already submitted data. Unfortunately, it is not uncommon to find public surveys where the security configuration of the survey is not set  appropriately, allowing unauthorized access to the survey’s data. This article describes best practice for securing the data of surveys published in the Survey123 web designer. If you are interested in securing data for a public survey published with Survey123 Connect, refer to Securing data in public surveys (Survey123 Connect) .

 

If you are not familiar with the basics of public surveys, refer to Getting Started with Public Surveys.

                        

 

Sharing your survey publicly while keeping your data private

 

Technically speaking, you can control the sharing of your survey from the Survey123 website as well as from ArcGIS.com. The easiest and safest way to share your surveys is through the Survey123 website. Using the ArcGIS.com website is more error prone and can lead you to inadvertently share, and expose your data.

 

To share your survey publicly:

 

  • Sign in to the Survey123 website at survey123.arcgis.com.
  • From the survey gallery, open the Collaborate tab of your survey

  • The Submitter panel controls who can submit data to your survey. While in the Submitter panel, look for the section named 'Who can submit to this survey?' and check the Everyone (Public) option to share your survey publicly. 

 

If the option to share your survey publicly is missing, contact your ArcGIS administrator.

                        

  • Scroll down the page and look for the 'What can submitters do?' section. Check the 'Only add new records' option.
  • Click on Save at the bottom to persist all changes.

At this moment, your survey is shared publicly, allowing anyone to submit data through both the Survey123 web and field apps. You can get the link to your survey from the top of the Collaborate tab and distribute the link with your users. Since you have restricted access to 'Only add new records' in the Collaborate tab, it will not be possible to query, update, delete or download your survey data through the Survey123 web or field apps. Your survey's feature layer will also be secure, preventing any type of access (other than adding new records), from other Esri, third party apps or programmatic access.

 

Sharing your survey results privately for use within the Survey123 website

 

Your survey data is useful for people to make decisions, so at some point you will need to share that data with people who need it. Through the Collaborate tab, you can privately share this data with members of your ArcGIS organization so they can view, analyze and even download the data from the Survey123 website.

 

  • From the Collaborate tab of your survey, switch to the Viewer panel.
  • Look for the "Who can view results of this survey?" and check the groups within your organization that should have access to your survey's data.
  • Click on Save to persist changes.

Now that you have shared the results of your survey, users with access to the survey results will be able to look at the data from the Survey123 website using the Overview, Data and Analyze tabs of the Survey123 website. You can get the survey results link from the top of the Collaborate tab and distribute it within your organization or alternatively ask users to login into the survey123.arcgis.com website to see the survey results.

 

A deeper view into how all of this works

 

The Collaborate tab in the Survey123 website is meant to make the process for sharing and securing your data easy and error-free. Under the covers, sharing and access control to your survey data is managed through the use of ArcGIS feature layers and hosted feature layer views. These layers are saved in folder created in the ArcGIS account of the survey owner.  Next, we are going to look at these feature layer views in detail.

 

  • Log into the arcgis.com website and click on the My Content tab.
  • Look for your survey's folder in the Content tab. Note that Survey123 folders carry a Survey prefix followed by the name of your survey. It will look something like this:

Here is a brief explanation of the items in your survey directory:

 

  • A Form item: This ArcGIS item contains the definition of your survey with its questions, rules, look and feel and other properties. This item allows end-users to use your form from the Survey123 web or field apps.
  • A Hosted Feature Layer View with a "_fieldworker" suffix in its name. This item is created by the Survey123 web designer when the survey is first published. This item is used by the Survey123 web and field apps to submit data into ArcGIS. Permissions and sharing for this item are controlled via the Submitter panel in the Collaborate tab of the Survey123 website.
  • A Hosted Feature Layer View with a "_stakeholder" suffix in its name. This item is created by the Survey123 website when the survey results are shared through the Collaborate tab. This item is used to control access to the survey results through the Survey123 website.  If the Viewer panel of the Collaborate tab has not been used to share the survey results, this item will be missing.
  • A Hosted Feature Layer. This is where the actual data of your survey is stored. This item is created by the Survey123 web designer when the survey is published. You should never share this item.

 

The Survey123 website, through the Collaborate tab, manages the sharing and permissions set in each of these items. The website guarantees that the sharing across the items is consistent so the Survey123 website and apps work while keeping your data secure. Manually controlling the sharing of these items through the ArcGIS.com website can lead to inconsistencies and inadvertently expose your data.

 

  • The Form item is shared with all groups in the Submitter and Viewer panels of the Collaborate tab. Since the Form item simply describes questions and rules in your survey, it does not provide access to your data. If your survey is shared publicly for submits, this item will be shared publicly. If your survey is shared with specific groups in your organization for viewing results, this item will be shared with these groups as well.
  • The _fieldworker feature layer view is shared with users who need to submit data (submitter panel in the Collaborate tab). If your survey is shared publicly, this item will also be shared publicly. Access privileges in this item control how your data is accessed according to your choices in the Submitter panel of the Collaborate tab.
  • The _stakeholder view is shared with users who need to view survey results. Access privileges are controlled through the Viewer panel of the Collaborate tab.
  • The Hosted Feature Layer is kept private so only the owner of the survey has access to it. As long as there are _fieldworker and _stakeholder views, the Survey123 website and apps do not require direct access to this item. This item should always remain private to the owner of the survey.

 

Never share your survey feature layer. Keep your survey feature layer private and let the views do the sharing.

                        

 

For a more in-depth exploration of the specific security settings present in the _fieldworker and _stakeholder views, you can follow these steps:

 

  • From the ArcGIS.com Content panel, while looking at your survey's folder, click on the _fieldworker feature layer view.
  • Switch to the Settings tab and scroll down to explore all the permissions.

 

The most restrictive permissions in the _fieldworker view that enable submissions from a public survey while preventing access to your data are as follows:

 

SettingComments
EditingEnabled. Editing is required for the Survey123 web and field apps to submit data.
Enable SyncDisabled.
What kind of editing is allowed?Add enabled. Delete and Update disabled.
What features can editors see?Select this option: Editors can't see any features, even those they add
What access do anonymous editors (not signed in) have?Any option is fine since editors cannot see any features.
Export dataDisabled.

 

Sharing your survey results in web applications and dashboards

 

It is very common to build web mapping applications and dashboards on top of survey data. Enabling access to your survey data from these applications must be done with care, carefully controlling what data is shared and with whom.

 

The best way to enable access to your survey data by third party applications is by creating a new feature layer view on top of your survey's feature layer. By creating a new view, you can better control what data from your survey is shared and with whom, tailoring this to the needs of your third party application.

 

Using your survey's feature layer, fieldworker or stakeholder views to support third party applications is not recommended because in the future you may need to make adjustments to the sharing or permissions of these items to satisfy the needs of your third party application, and these changes can affect the normal behavior of your survey and compromising the security of your survey data.

 

Please read the previous paragraph again. Read it carefully so it sticks! 

 

This is how you can create a new view, for example, to support a web mapping application:

 

  • From your survey's folder in My Content, click on your survey's feature layer to open it's item details page.

 

  • Next click on Create View Layer.

Once your new view layer is created, you can control through the Settings dialog the permissions set on that layer. For example, you can disable editing and make it read-only. Through the Visualization tab, you can also use the feature layer view definition to choose which fields in your feature layer you want to expose.  It is also possible to apply filters to your view to hide certain rows, such as non-vetted submitted survey entries, etc. Finally, you can also share this new view layer according to the needs of your web application, which will likely be different from those of your survey.

 

For more information about working with feature layer views:

 

 

Do's and Don'ts

 

For surveys authored from the Survey123 web designer, the easiest and safest way to control the sharing of your survey and access to your survey results is through the Collaborate tab in the Survey123 website. It is recommended that you use the Collaborate tab for this purpose.

 

Altering the sharing and privileges on your survey items directly through the ArcGIS.com website is more error prone and can lead to a broken survey (for example, a survey that cannot access the _fieldworker view to submit data), or to a survey that exposes your data (through a misconfiguration of the sharing for the feature layer or its feature layer views).

 

It is not recommended that you alter the sharing or security properties of the survey form item or its corresponding feature layer and views. Let the Survey123 website do that for you.

 

Note: You should not need to read this last paragraph, because you read it twice already. In the event that you need to enable access to your survey data for third party applications, it is highly recommended that you create a new feature layer view on top of your survey's feature layer. It is not good practice to use the _fieldworker or _stakeholder views to support third party applications, because the sharing and access needed by your survey and the third party apps are likely very different.

By definition, a public survey is accessible to anyone who wants to submit data to it, but that does not mean that anyone should also be able to look at the data itself. If your public Survey123 form contains sensitive information, you should configure your survey to prevent users in the public domain from downloading, querying or changing already submitted data. Unfortunately, it is not uncommon to find public surveys where the security configuration of the survey is not set appropriately, allowing unauthorized access to the survey’s data. 

 

This article describes best practice for securing the data of public surveys published from Survey123 Connect. If you are interested in securing data for a public survey published with the Survey123 web designer, refer to Securing data in public surveys (Survey123 web designer) 

 

If you are not familiar with the basics of public surveys, refer to Getting Started with Public Surveys.

                      

A bit of context before we start

 

To properly secure your survey results it is important to understand first some basic concepts.  When you publish a survey using Survey123 Connect, a new folder is created in your ArcGIS account. This folder includes the name of your survey so you can easily find it.  Inside this folder, you will find a Form item and a Feature layer item:

 

  • Form item: The Form item contains the definition of the questionnaire presented to users: The labels of your questions, the calculations, media files and other resources needed to render your form.
  • Feature layer: The feature layer is the item where responses to your survey are stored.

 

In short, the survey folder contains one item (the form item) for the survey questions and one item (the feature layer) for the survey responses.

 

If you are working with sensitive data, you never want to share your surveys source feature layer. Instead, you will want to keep your survey feature layer private, and build feature layer views on top where you can better control the sharing and privilege properties. At the very least, you will want to create two feature layer views:

 

  • A view for the Survey123 web and field apps to use.  This view will allow the apps to add, and if appropriate to edit records in your feature layer.
  • A view for the Survey123 website to use. This view will control who can access the survey results through the Survey123 website, and with what privileges: just view, or also view and edit.

 

Additionally, you may want to create extra views to support other applications, such as ArcGIS Dashboards, Web AppBuilder apps, etc.

 

This article describes in detail how to build these feature layer views and associate them with your survey. If you are not familiar with the concept of feature layer views, I suggest read the Create hosted feature layer views—ArcGIS Online Help | Documentation help topic.

 

Do not create the views too early.

 

Let me put this upfront: as of version 3.9, Survey123 Connect does not like views: Connect does not create views, and does not handle them well when you delete or modify the survey. This is something that is going to change, rendering this whole article unnecessary, but for now bear with me.

 

As stated above, my recommendation is that you always use feature layer views when your survey is shared with people, but from a practical perspective you do not want to create the views too early. Survey design is an iterative process where you will be adding, changing and removing questions from your survey frequently. Some of these changes necessarily affect the schema of the surveys feature layer. If your survey is configured with views, Connect may not be able to change the schema of the source layer. If the schema of the layer is changed, your views will break.

 

For this reason, keep your survey without views for as long as you are working on it and configure the views when you are ready to put your survey in production, right before you share your survey with users.

 

Create a view for the Survey123 website first

 

I said before you will want to create at least two views: One for users who will look at your survey results through the Survey123 website, and another one for users to submit data through the Survey123 web and/or field apps. It is best to start with the view to control access to the survey results.

 

To build the view:

 

  • Login into the Survey123 website
  • Navigate to the Collaborate tab of your survey
  • Switch to the Viewer panel and hit Save.

 

 

 

If you return now to the Survey123 folder under Content in ArcGIS.com, you will notice that a new view has been created for your survey. This view has a 'stakeholder' suffix.

 

 

This new view will control who can use the Survey123 website to look at your survey results.  You will want to use the Viewer panel in the Survey123 website to control this. For example, say that users in a group called 'City of Cilantro' need to be able to look at the results of your survey, create reports and download data. Then you will go into the Collaborate tab, switch to the Viewer panel and share your survey results with that group. At that point, 'City of Cilantro' users can log into the Survey123 website and use the Overview, Data and Analyze tabs to do what they need. 

 

I would not recommend that you modify the sharing of this view through ArcGIS.com. For the Survey123 website to properly work, the sharing of the Form and stakeholder view items must be in sync.  The Collaborate tab in the Survey123 website takes care of that.

 

Create a view for the Survey123 web and field apps next

 

Configuring the view for the Survey123 web and field apps is a bit more involved. We need to create this view manually, then associate the view with the Survey123 Connect survey.

 

  • Log into the arcgis.com website and click on the My Content tab.
  • Click on the Form item to open its item details page, then click on Create View Layer. You can choose any title for your feature layer view.

To make your survey work against your own  feature layer view, you need to configure the submission_url and form_id XLSForm settings in your survey. This can be an error prone process at first. Once you are familiar with this I am sure you will do this with your eyes closed, but here I am going to follow a long but safe route:

 

  • In Survey123 Connect, from the survey gallery, click on New Survey and then choose the Feature Service option.
  • Look for the feature layer view you just created and give your new survey a throw-away name, such as temp or delete_me.

 

  • Open the XLSForm of your temporary new survey and switch to the settings worksheet. Then copy the values in the form_Id and submission_url cells into a text editor or a safe place, so we can paste them later into the original survey.

The submission_url value defines the feature layer (or feature layer view) that the survey is targeting. If empty, Survey123 Connect will create a new feature layer when you publish the survey. If a value is provided, the survey is published targeting the specified layer by the submission_url . The form_id value defines the sub-layer in your feature layer that drives the questions in your survey.

 

  • Back in Survey123 Connect go back to survey gallery, and open the survey that you want to make public.
  • Open the XLSForm, paste the submission_url and form_id values.
  • Save your XLSForm and publish your survey again.

 

The Publish dialog will indicate that your existing survey will be updated to use a custom feature service as specified by the submission URL, as shown in the next screenshot.

 

Now that your survey has been updated to target your own feature layer view, you can share your survey publicly with confidence. We will do that from the Survey123 website.

 

Sharing your survey publicly

 

  • Log into the Survey123 website at survey123.arcgis.com.
  • From the survey gallery, open the Collaborate tab of your survey

  • The Submitter panel controls who can submit data to your survey. While in the Submitter panel, look for the section named 'Who can submit to this survey?' and check the Everyone (Public) option to share your survey publicly. 

If the option to share your survey publicly is missing, contact your ArcGIS administrator.

                      

  • Scroll down the page and look for the 'What can submitters do?' section. Check if not already the 'Only add new records' option and click on Save at the bottom to persist all changes.

At this moment, your survey is shared publicly, allowing anyone to submit data through both the Survey123 web and field apps. You can get the link to your survey from the top of the Collaborate tab and distribute the link with your users. Since you have restricted access to 'Only add new records' in the Collaborate tab, it will not be possible to query, update, delete or download your survey data through the Survey123 web or field apps. Your survey's feature layer will also be secure, preventing any type of access (other than adding new records) from other Esri apps, third party apps or programmatic access.

 

If you go back to My Content in arcgis.com and check your survey folder, you will find that your feature layer view and the Form item are now shared publicly, while the feature layer remains shared only with you, the owner. This is the way you want it. Do not share the source feature layer if you want to keep your data safe.

 

Sharing your survey results in web applications and dashboards

 

The same technique we used to create a feature layer view for the Survey123 web and field apps can be replicated to support other apps and uses. It is not good practice to reuse the feature layer view we just created or to share the source feature layer. Build new views, restrict access to data as appropriate to the needs of the web app and share accordingly.

 

Here are a few links to learn more about feature layer views:

 

The coronavirus pandemic is front of mind for all of us. This crisis has changed the way we work and many in our community are having to adapt to new challenges and requirements in response to the COVID-19 disease. A key example is the increased demand for the collection and analysis of coronavirus-related data.


With that in mind, we have published a set of COVID-related templates in Survey123 Connect. These templates alone do not pretend to be an end-to-end solution for your COVID-19 needs. Like other community templates, the purpose is to provide practical examples of what you can do with Survey123 and demonstrate best practices for building smart forms with XLSForms.

Esri is offering a host of GIS resources and solutions to help you monitor and respond to the pandemic. This includes maps, applications and data. I encourage you to check out Esri's COVID-19 home page and COVID-19 GIS Hub.

It's also important to note that some of these samples are designed to collect personal information and health-related information. If your survey is to be shared publicly, you will need to secure your data and ensure that your data collection is compliant with the regulations in your region.

 

Let's start by taking a look at the samples. Below you will find a brief description of each template and the specific XLSForm techniques it highlights.

 

Community Support

Preview this sample in the Survey123 web app

 

Community Support survey thumbnailA survey form to help people connect with their community. Respondents can use this form to request support from their neighbours or offer help to others. This survey is designed as a single form that gathers both requests for help and offers of help. If required, you could split it into two separate surveys for requests and offers. The respective rows in the XLSForm have been highlighted in blue and orange. Delete the blue rows for one, and the orange rows for the other. You'll also need to remove the yellow row and the selected() function from the relevant column in each case.

 

This XLSForm sample demonstrates a technique to split out the responses to a select_multiple question into separate fields. A select_multiple question stores its answers as a comma-separated string. Using the selected() function you can record the choices individually in separate hidden fields. For more, see Understanding Multiple-Choice Questions in Survey123 for ArcGIS. This form also uses a regular expression to validate that an email address is formatted correctly. This expression is described in The art of hiding.

 

Testing Request

Preview this sample in the Survey123 web app

 

Testing Request survey thumbnailThis survey is intended to be completed by a health worker requesting a laboratory test for COVID-19. The clinician can collect information about the patient and the specimen type being submitted for analysis.

 

The XLSForm demonstrates how to validate that a date of birth matches an age (in years), and apply this check as a constraint. It also shows how to use the relevant column to control the visibility of questions on the form based on responses to other questions and how to apply the table-list appearance (or Single Choice Grid as it's called in the web app) to present a group of select_one questions in an easy-to-read table layout. For more information, see Survey123 Tricks of the Trade: Groups, Grids and Pages.

 

Inpatient Screening

Preview this sample in the Survey123 web app

 

Inpatient Screening survey thumbnailThis survey is an example of a form that could be completed by a health worker when a patient is admitted to a health facility. Collect personal information about the patient and details about any symptoms the patient is presenting with.

 

The example also uses table-list to display a block of select_one questions that each have the same choices. It also demonstrates how to use the string-length() function in the relevant column to check if an answer has been provided to a question, as well as a signature question to record a digital signature of the referring clinician. See the Signatures! blog for more.

 

Symptoms Check

Preview this sample in the Survey123 web app

 

Symptoms Check survey thumbnailThis survey provides a self-assessment of COVID-19 symptoms and is intended for use by the general public. The form could be useful for counties or cities in their efforts to measure the general impact of coronavirus infection. One of the key features of this survey is that it's in multiple languages! The XLSForm shows how to set out labels, hints and choices in English and Spanish. For more on this see Introducing Multiple Language Surveys. This sample was provided courtesy of Routt County, Colorado, as featured on the County's COVID-19 Information page.

 

If any of these templates is of interest, you can use them as a starting point for your own project. To download the templates, head to the Community samples section in Connect.

 

In Survey123 Connect, select New Survey. Select the Community option (1), enter a search for "COVID-19" or "coronavirus" (2) and then select a sample survey from the list (3).

 

Community samples in Survey123 Connect

 

Feel free to share with our Survey123 community your own COVID-19 XLSForms in a comment, below. I also encourage you to submit your coronavirus-related maps and apps with the greater GIS community here: Submit COVID-19 Maps & Apps | Support Response to Coronavirus Pandemic.

 

Banner image credit: NIAID.

Thumbnail images credit: PHIL and NIAID.

Filter Blog

By date: By tag: