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

Survey123 for ArcGIS

82 Posts authored by: ichivite-esristaff Employee

We do not seem to observe the stars as much as we used to, but it is fascinating to look up and think how much our life as a species has depended on a good understanding of the sky. We have dedicated this update to the comet Halley. Tomorrow, over 2,250 years ago, the first documented sighting of comet Halley was made by Chinese astronomers. It was sighted May 24, 240 B.C.  There are potentially earlier accounts from 467 B.C when Chinese and Greek astronomers logged the sighting of a comet, which could also have been comet Halley. We will go with the more certain date of May 24, 240 B.C and celebrate it along with this update of Survey123.

 

The passing of comet Halley has been very well documented since these initial accounts. Initially there was no evidence that all these sightings were of the same comet. The comet's periodicity was first determined in 1705 by English astronomer Edmond Halley, after whom it is now named. It visits us regularly every 75 years. It came last in 1983 and will return in July 2061.

 

This update is focused exclusively on the Survey123 website. Clear your browser cache!

 

Here is what is new:

 

New Survey123 Integromat module

 

Integromat is an amazing online automation platform. With it you can easily automate tasks, visually connecting all sorts of apps together. We strongly believe that facilitating your work with platforms like Integromat can tremendously help you embed Survey123 within larger enterprise workflows, making sure your Survey123 data flows nicely into the way people work within your organization.

 

Many of you have been experimenting with Integromat and Survey123 since we first added support for webhooks in 2018. The uptake of webhooks with Survey123 has been pretty spectacular!  Some of the most common task automations we have seen include:

 

  • Automatically send an email or SMS when an inspection or incident report is submitted from Survey123.
  • Instantly add a new row into an Office 365 Excel spreadhseet when data is submitted from Survey123
  • Create a Workforce for ArcGIS assignment and a Google Calendar event when data is submitted from Survey123
  • Automatically reverse geocode the location a submitted survey and store the address in a GIS attribute of the submitted survey

 

We have worked closely with our friends at Integromat to add a new Survey123 Integromat module. This means that you can now bring your Survey123 data into Integromat much more easily and do much more with it than before. Jim Moore put together this brief but informative video to give you a quick overview of this new Survey123 Integromat module. Here it is:

 

 

If you are just getting started, you can create an Integromat account and give it a go on your own. Start with something simple like automating e-mail notifications or adding a row into an Excel spreadsheet when survey data is submitted.  We added some integration templates to help you get the gist of it. 

 

If you want more formal training, sign up for the Automate E-mail Notifications with Survey123 for ArcGIS Live Training Seminar by Brandon Armstrong and Derek Law, or access a recording of it.

 

Automate E-mail Notifications with Survey123 Live Training Seminar

 

For those of you already familiar with Survey123 and Integromat, you will find that this new module, lets you do some more advanced things you have been asking for.  For example:

 

  • Easily work with photo, signature and markup attachments. Include them as attachments in emails, upload them to Box, Microsoft OneDrive or Google Drive.
  • Automate report generation through the Survey123 Feature Report service. For example, for every survey submitted, automatically trigger a new  report using a custom template and then email or update that final report.
  • Trigger Integromat scenarios when Survey123 is used to update existing records*. Add a router in your Integromat scenario to do certain things if a record is submitted, and other things if the record has been updated.
  • Setup an Integromat scenario on top of ArcGIS Enterprise.

 

* Please note that the field app will not trigger webhooks on edit events until our upcoming update in June.

In the next few days, I will be publishing a blog post describing how you can take advantage of the more advanced techniques described above.

 

Delete and update submitted records (Survey123 website)

 

You can now use the Data tab in the Survey123 website to delete and update submitted records. This comes very handy if you need to do some quick cleanup of test data during your survey design process, or to make adjustments to already submitted data to your survey.

 

This is how it works: First login to the Survey123 web site, select a record in the table shown in the Data tab and then use the Edit button in the panel on the right to enable editing on the individual response form. Make your changes and submit.  The following animation shows the key steps:

 

 

You can use the Edit and Delete options for both surveys created in Survey123 Designer as well as Survey123 Connect. However, if your surveys were created in Survey123 Connect, be aware that the Edit button will be disabled when working against a survey with a repeat.

 

Update submitted records from a Survey123 web form

 

You may be already aware that you can update existing records in your feature layers using the Survey123 field app. Starting with this update you can update existing records with Survey123 from your web browser too! This is possible by opening your web form with URL parameters.  TheSurvey123 Tricks of the Trade: Web form URL parameters blog post introduces the concept of web form URL parameters. Now you can use URL parameters to edit existing records.

 

The syntax is fairly straight-forward:

 

  • Set the mode to edit: mode=edit
  • Pass the objectId of the record you want to update: objectId=13 for example.

 

For example:

https://survey123.arcgis.com/share/815b69a16e2f474e93da7e2eb0255e5d?mode=edit&objectId=13

 

Editing is not supported in web forms published prior to this update. If you want to edit records with surveys you published in the past you have two options:

 

    1) Dynamically upgrade your survey at run-time by adding the version=latest URL parameter

    2) Republish your survey to force a version upgrade at publishing time.

 

The key to all of this is to somehow dynamically construct the URL with the objectId of the record you want to update. In the Survey123 Tricks of the Trade: Editing records in a web form blog post this is all discussed in more detail.

 

Other enhancements and fixes

in the Survey123 website and Survey123 web app

 

 

  • Save Survey As... now works also against surveys that you do not own. 

 

This is very handy if you want to clone survey designs within your ArcGIS organization. Create a survey first using Survey123 Designer, then share the survey with someone else by granting access through the Viewer group sharing settings in the Collaborate page. Next, have that second person login into the Survey123 website and show 'Surveys I can view results for' in the survey gallery. The Save As option will be available on the survey tile menu to clone the survey. 

 

 

The Save As... option in the Survey123 website is only available for surveys authored in Survey123 Designer. If you want to clone a survey authored in Survey123 Connect, use the Save As... option in Survey123 Connect

 

  • You can now quickly switch between ArcGIS accounts in the Survey123 website without having to logout.

 

  • An option to optionally propagate selection filters between the Data and Analyze pages has been added.

 

Filter Options in Data Page

 

  • BUG-000113962 Unable to type certain Japanese character in the hints and explanations of headers in the Survey123 for ArcGIS Web Designer.
  • BUG-000120077 Unable to export data from Survey123 website when logged in as a member having 'User' Role and ‘Creator’ User Type.
  • BUG-000120887 When opening an existing Survey123 for ArcGIS form from ArcGIS Online using the 'Manage in Survey123 Website' option, the error message, "Your account () is not licensed for Survey123. Please ask your organization administrator to assign you a user type that includes Field/Essential Apps..." is returned.
  • BUG-000120055 Reports may fail to generate from a survey response that contains a repeat with many high resolution images.
  • BUG-000120222 Unable to generate a Survey123 for ArcGIS Report if there is an IFstatement containing a choice with an apostrophe.
  • BUG-000120851 Survey123 for ArcGIS web app displays the World Geocoding Service (WGS) on geopoint questions, despite removing WGS from the organization's Utility services.
  • ENH-000115658 Allow for the functionality to configure right to left labels and choices in Survey123 forms.
  • BUG-000113592 Questions label disappear from the survey when default language is changed from English to French or Spanish in a browser.
  • BUG-000112106 Survey123 for ArcGIS web app does not respect the language settings of date type questions in the browser.
  • BUG-000114761 Field Matching and string-length(.) constraints cause a green "It's an invalid answer." subtext to persist in Survey123 for ArcGIS web site under the questions that are constrained that does not disappear after fulfilling the constraints or leaving the fields blank.
  • BUG-000115247 Survey123 for ArcGIS web application does not respect the default language settings in the browser.
  • BUG-000117184 Submitting an Image through the Image Upload Question in Survey123 through the Web Designer in a Desktop Browser fails if the Survey was created with the Web Designer
  • BUG-000116320 The Survey123 for ArcGIS web app displays Image and Geopoint questions in English even if the web browser is set to another language in Internet Explorer.
  • BUG-000120426 Conditional calculations do not populate as expected for select_one questions in the Survey123 for ArcGIS web app.
  • BUG-000118413 Reverse geocoding results are different between Survey123 Connect and Survey123 web application.
  • BUG-000120387 Survey123 web app fails to record time when a time between 12PM and 1PM is selected
  • BUG-000121290 Loading a survey in a web browser with a Toolbar Background Color assigned causes the default color scheme to show momentarily before switching to the chosen color.
  • BUG-000120589 When editing surveys published in Connect the prompt to save changes on exit is not necessary if changes were published, does not work if changes were not published.

 

 

About the next update

 

 

As mentioned above, this update is exclusive to the Survey123 website. As usual we wanted to release both updates for the website and Survey123 field app together, but we decided to pull back on the Survey123 field app at this time. We are doing our best to bring some important fixes you have reported to the Survey123 field app soon. The current schedule is set for an update in 5 weeks (late June 2019). Our Survey123 for ArcGIS Early Adopter Program is making early beta builds of our next update available for testing.  The Survey123 website will also be updated in late June.

Today we will explore how you can edit existing records using the Survey123 web app, also known as a web form. The idea is quite simple, we will populate the contents of a Survey123 web form using an existing record from a feature layer and let users update (edit) that information. When working this way, the submit button in the survey will update an existing record, as opposed to creating a new record for a new survey response.

 

This technique for editing data in a web form be quite handy. You can use it for example to let people review and modify existing submitted data, or to simply let them finish an uncompleted form. You can also incorporate web forms into QA/QC and data validation workflows.

 

Before we start, be aware that the editing of records in web forms is only available in the Survey123 web app after May 23, 2019 (version 3.4 and newer). I will describe later in this blog how you can make your surveys run in this latest version, even if you published it in the past in an earlier version.

 

The Basics

 

Editing of existing data in a web form is possible through the use of web form URL parameters. If you are not familiar with web form URL parameters in general, I strongly suggest you read the Survey123 Tricks of the Trade: Web form URL parameters first.

 

Here is an example:

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?mode=edit&objectId=9

Note the two URL parameters:

 

  • objectId=9, this parameter loads the record in your feature layer with objectId 9 into your form. Of course, you can replace 9 with the specific objectId of the feature you want to load.
  • mode=edit, puts the web form in edit mode. This essentially ensures that when the user hits the submit button, the current record is updated. If the mode is not set to edit, the form will create a new record when submitted, even if the form was initialized with data from a particular record.

 

URL parameters are case sensitive. For example: objectId is not the same as ObjectID or objectID. If you see that your form is not loading the record you want, double check the spelling of the parameter, and also ensure the objectId you are trying to load exists.

 

As described above, the editing mode in web forms was incorporated in version 3.4. If you want to edit records using a survey that was published in the past, you can bring things up to speed in two different ways:

 

  • Upgrade your survey by simply re-publishing it. If you originally published your survey using Survey123 Web Designer, then use Designer to publish it again. You do not need to make any changes other than simply clicking the Publish button. The same goes with Survey123 Connect for ArcGIS: If you originally published your survey with Connect, go back to Connect and hit publish.
  • Upgrade your survey at run-time: You can alternatively add the version=latest URL parameter to force the survey to be loaded using the latest available Survey123 web app. Something like this:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?mode=edit&objectId=9&version=latest

 

My recommendation is that whenever possible you upgrade your surveys by re-publishing them. It will improve the initial loading time of the survey in the web browser, and it will guarantee that the behavior of your web form remains unchanged even if the Survey123 release changes.

 

From a practical perspective, the technique described above is useless unless you somehow present a ready-to-use link (URL) to the end user; A link that already includes the appropriate objectId to edit. Do not expect end users to modify that objectId manually in the web browser URL address!  I will next describe three scenarios to illustrate how you could apply this technique.


Launching an edit web form from a feature popup

 

Our first scenario allows users to navigate a map, and launch an edit web form from the popup of an existing record. The key is to customize the feature layer popup so it dynamically generates the correct URL to launch the survey. Once the popup is configured, you can use the web map within the ArcGIS Map Viewer, custom Web AppBuilder apps, Explorer for ArcGIS and any app that supports web maps.

 

Here is a brief step by step guide to configure your popups:

 

  1. Using the ArcGIS map viewer, add your survey feature layer (or hosted feature layer view) into a web map.
  2. Open the configure popup dialog for your survey feature layer.
  3. In the popup contents section, select a custom attribute display.
  4. Add the URL of your web form into the attribute display. Then add the mode and objectId parameters.
  5. Dynamically populate the objectId parameter using the OBJECTID field from your feature layer.
  6. Use the full web form URL with its parameters to create a link.
  7. Save the popup and test it out.

 

And here are the same steps in a short animation.

 

Editing Web Forms and Popups

 

Embedding an edit web form within Operations Dashboard for ArcGIS

 

The idea with this one is to add an embedded content element within the dashboard, and configure it to display your web form.  The URL of the web form will include the mode parameter set to edit and the objectId will be dynamically populated.  Using a filter action triggered by other element within the dashboard, such as a list, the embedded content element will refresh your web form with the relevant record to be edited.

 

At a high level, the steps are as follows:

 

  1. Set a refresh rate on a web map displaying your survey feature layer.
  2. Add your web map to a new dashboard and configure a list element to display survey records.
  3. Add an embedded content element. In the Data options, set the Type to Features and add the URL of your web form with the mode=edit  and objectId parameters. Make sure the objectId parameter is set to pull a value from the ObjectID column in the fields collection.
  4. Next configure a filter action on the list element and target your embedded content element.
  5. Click on a record in the list, and your web form in the embedded content element will display your record in edit mode.

 

The animation will guide you through the whole process. Click on the animation to make it larger.

 

Editing Web Forms in Dashboard

 

Including an edit web form link in an e-mail.

 

In this scenario, we will use a web hook to automatically send an e-mail to the user submitting the survey. This email will contain a link for the user to complete or make modifications at any time.  To do this you must be familiar with web hooks in general or with either Microsoft Flow or Integromat.   Like in the examples above, the trick is to be able to dynamically populate the objectId of the record you want to edit. Luckily enough, the payload of a Survey123 web hook includes information about the user submitting the data (if logged-in) as well as responses to questions in the survey. So as long as the user is logged-in or a specific question in the survey captures the contact e-mail, you can make this work.

 

Here are the high level steps:

 

  1. Create a new survey. If you plan to share your survey publicly, include an e-mail question and make it required. If  you plan to keep your survey secured, you will be able to get the e-mail from the logged in user's profile.
  2. Use Microsoft Flow or Integromat to automate e-mail notifications when your survey is submitted.  The objectId of the record submitted is included in the payload of the web hook. Simply add the objectId to the URL of your edit web form when you add the link in the body of your e-mail.

 

Here is some visual aid in case you are using Integromat.

 

Integromat

 

If you are using Integromat or Zapier, the pattern is pretty much the same: use the webhook payload to retrieve the objectId of the submitted record and use if for your edit web form url.

In this blog post, I describe some common techniques that will help you better understand and hopefully improve the quality of location data you get from field users.  Location data quality depends on multiple factors, including field conditions, field user skills and the hardware used. Having said this, a good smart form design can do a lot to help get the best possible quality location data.

 

This post focuses particularly on field data collection workflows where you will rely on integrated or external GNSS receivers to capture location data. It assumes familiarity with XLSForms, Survey123 Connect and the Survey123 field app.

 

Persisting Location Accuracy (Part 1)

 

If location quality matters to you, you should consider systematically storing the location accuracy of every record captured.  This is just as true for formal high accuracy field data collection workflows by professionals, as it is for casual field data collection by volunteers.  Horizontal accuracy is about the simplest and most important quality indicator of your location data.  Having field users understand the horizontal accuracy while they collect data is not enough; you need to persist it for every record captured, so you can analyze it later.

 

In XLSForm, you can store the horizontal accuracy as reported by your field device as follows:

 

typenamelabelcalculationbind::esri:fieldType
geopointlocationGPS Location
calculateaccuracyHApulldata("@geopoint",${location},"horizontalAccuracy")esriFieldTypeDouble

 

The key is the calculation in the second question of the survey.  It automatically gets the horizontal accuracy from the geopoint question and stores it in a field named accuracy. Since you do not want end users to overwrite this value, the sample above keeps the output of the calculation in a question of type calculate. Calculate questions are not presented to the end-user in the form, but their values can be be stored in ArcGIS.  In this particular case, since the horizontal accuracy is expressed in meters, the bind::esri:fieldType column has been set to esriFieldTypeDouble.  If the esri:fieldType value is not set explicitly, Survey123 will automatically store the calculated value as text.

Horizontal accuracy values are always expressed in meters.

        

I like to add a calculate like the above to every survey I prepare for field data collection. Looking at a dataset from field users without location accuracy information is not very comforting.  Without location accuracy information in a GIS dataset, what level of confidence can you have on those points in the map?  Capturing the horizontal accuracy like described here adds absolutely no overhead, and it always pays off.

 

In the next screenshot, locations captured along a trail have been buffered to visually represent the reported horizontal accuracy.  This simple visualization can provide you with great information about the quality of locations in your dataset. Before performing GIS analysis, you can set criteria to filter out records that do not meet a location accuracy threshold of your choice.

 

 

You can also use the location accuracy information to better understand in what conditions poor location data is created. You can analyze spatial patterns, identify particular users or devices that do not meet minimum standards.

 

Persisting Location Accuracy (Part 2)

 

The horizontal accuracy that Survey123 returns from a geopoint value is provided by the location sensor you are using.  On top of the actual value (say 6.2 meters for example), it is important to understand the level of confidence level for that value. That is, with what level of confidence will the location be within a radius of the horizontal accuracy reported (say within a radius of 6.2 meters of the point for example)? 

 

The Google Developer documentation, defines horizontal accuracy as the radius of 68% confidence. This is like saying that for Android devices, there is a 68% chance that the true location is within a radius equal to the reported horizontal accuracy. Apple has not documented their definition of horizontal accuracy.

 

When using external high accuracy GNSS receivers with Survey123, the confidence interval can be more accurately be defined if the receiver is able to report what is known as root mean square (RMS) accuracy. For RMS accuracy, the default CL (Confidence Level) is 68%. Some organizations require reporting accuracy with a 95% CL. If this is the case, the United States Federal Geographic Data Committee (FGDC), through its National Standard for Spatial Data Accuracy, establishes that the following factors should be applied:

 

  • 1.7308 for horizontal accuracy.
  • 1.9600 for vertical accuracy.

 

The conversion between RMS 68% CL and 95% CL applying the factors above should only be calculated, again, if the GNSS receiver is reporting horizontal accuracy using RMS.  In the Direct GNSS external receiver support in Survey123 3.3 blog post you can find an example of how you can use RMS horizontal accuracy values into a 95% confidence level.

 

For both built-in and external GNSS receivers, you can complement the reported horizontal accuracy with other commonly available location metadata such as the speed and also the position source type (Integrated GPS, external GPS, user-defined, etc). For a quick reference of other location metadata fields available, have a look at the Pulling data from geopoint questions blog post.

 

If you use external location sensors, such as high accuracy GNSS receivers, then you will be able to get a lot more location metadata with Survey123 such as the fix type (GPS, differential GPS, RTK fixed, RTK float, SBAS...), differential age, number of satellites used, etc. The complete reference guide of all location metadata you can extract is in our Geopoints—Survey123 for ArcGIS | ArcGIS help topic.

 

Persisting the location accuracy as a GIS attribute is generally a good idea, but it does not help field users understand how to to get a better location with Survey123.  Next, I will discuss a handful of techniques that will help end users actively contribute to higher location quality data.

 

 

Location Accuracy Threshold

 

The location accuracy threshold is an XLSLForm value expressed in meters.  When the accuracy threshold is not met, the map panel in the survey will be automatically highlighted in red and the location icon will spin.  This will give the field user a visual clue indicating that (1) a better location is desired and (2) that the Survey123 app is actively trying to get new locations to meet the threshold. 

 

Setting the location accuracy threshold in your smart form is a very simple way to visually alert end users when the location is not considered accurate enough.  A red map panel is an indication to end users that it is best to stay put and wait until the device is able to get a better location.  If for whatever reason the device cannot get the desired accuracy, the end user can manually tap on the spinning location icon to fix the geopoint.

 

The accuracy threshold is set, in meters, in the body::accuracyThreshold XLSForm column as shown below.  This column accepts integers and decimals, but not XLSForm expressions. That is, the accuracy threshold is a fixed value.

 

typenamelabelbody::accuracyThreshold
geopointlocationGPS Location5

 

It is important to train end users so they understand exactly what is happening when the map panel is red and the location icon spins.  While the location icon is spinning, Survey123 is actively retrieving new locations from the device. If the end user moves, the location will change!  This is very different to the typical behavior of the Survey123 field app, which by default will immediately fix the location after the form is open.

 

A conservative value on your accuracy threshold, can help reduce situations where field users report location data that is clearly below the capabilities of their device.  For example, when a device has been off for a while, the GPS may need some extra time to warm up before getting the best results.  If you know that in normal conditions, you can get your devices to report horizontal accuracy in a range between 5 and 10 meters, then you can conservatively set the accuracy threshold to 20 meters. This will cause the map panel to turn red only in exceptional cases, letting the user know that it is best to stay put and wait a bit in order to let the device get a better fix.  In normal conditions, the accuracy threshold will be met after a few seconds, the map panel will turn green and the location will be fixed. Figuring out such conservative value for the accuracy threshold requires some trial and error. It will vary depending on the range of devices used and average field conditions. 

 

You can also go with a more aggressive approach where the accuracy threshold is set closer to the limits of what field conditions and your hardware can typically provide. In this case, you will be using the accuracy threshold to constantly remind end users of the importance of getting the best location possible. With an aggressive accuracy threshold value, some users may not be able to get a horizontal accuracy value below the threshold.

 

Always be aware that the location accuracy threshold value by itself will not prevent users from submitting data below the threshold. If you do not want data to be submitted unless a specific accuracy threshold is met, then you will need to use constraints. We will describe this later in this blog.

 

Location Quality Expressions

 

Using XLSForm syntax you can build sophisticated validation rules for location data.  These XLSForm expressions can take into account the horizontal accuracy, and many other properties of your location data. You can also use other form data in your expressions. Here are some examples of location quality expressions you can build:

 

XLSForm expressionDescription
${speed}<0.2Speed is less than 0.2 meters per second.
${positionSourceType}=3Location has been captured with an external location sensor
${fixType}=4 and ${positionAccuracy}<1Location is RTK fixed and mean radial spherical error is less than 1 meter.
${differentialAge}<3Location's differential age is less than 2 seconds

 

You can use XLSForm expressions like the above in different contexts. For example, you can use them to show visual warnings to the field user using notes. See the Understanding Notes in Survey123 for details on using notes for this purpose.

 

You can also use apply these expressions to the constraint and bind::esri:warning columns of a geopoint question. If you apply them to the constraint column, the end user will not be able to submit the survey unless the expression evaluates to true and the map panel will be highlighted in red.   This is what is known as a hard constraint.  If you apply them to the bind::esri:warning column, the map panel will be highlighted in yellow when the expression is not met.  This will simply give end users a visual clue indicating that something is wrong with the location data.  That is a soft constraint.

 

 

The contraint_message and bind::esri:warning_message columns are used to provide users with a specific error or warning message. Here is a complete example illustrating how to use the bind::esri:warning column to display a warning if the location has been captured while moving at a speed larger than 0.2 meters per second.

 

typenamelabelcalculationbind::esri:warningbind::esri:warning_message
geopointlocationLocation${speed}<0.2Please do not move while fixing the location
calculatespeedSpeedpulldata("@geopoint",${location},"speed")

 

Typically, a location quality expression is going to validate some properties of your location data. For example, its speed, accuracy, etc. These properties are obtained through the pulldata() function. It is not good practice to combine the pulldata() function with any other XLSForm operator or function.  In the example above, I created a calculate question to get the user speed from the geopoint object first, and then I referenced that value in the bind::esri:warning column. In this way, the pulldata() function is left alone in its own question avoiding any potential issues.

 

Expressions in bind::esri:warning define soft constraints. Even if the condition is not met, users will be allowed to submit the survey.

 

In the next example, I use the constraint column to apply a hard constraint. The user will not be able to submit the survey unless the accuracy is less than 1 meter and the fix type is RTK.

 

typenamelabelcalculationconstraintconstraint_message
geopointlocationLocation${fixtype}=4 and ${pa}<1RTK fix and sub-meter accuracy are required.
calculatefixtypeFixpulldata("@geopoint",${location},"fixType")
calculatepaPApulldata("@geopoint",${location},"positionAccuracy")

 

In this example, I use a constraint to force users to use a GPS to set the location of the geopoint. If the user manually changes the location in the map, Survey123 will not let the submission go through.

 

typenamelabelcalculationconstraintconstraint_message
geopointlocationLocation${source}!=1
You can't manually set the location. Use the GPS.
calculatesourceSourcepulldata("@geopoint",${location},"positionSourceType")

 

Expressions in the constraint and warning columns are evaluated every time the value of the question changes. If you add expressions to these columns in a geopoint question, they will get evaluated as soon as the location is updated. 

 

Summary

 

A good smart form design can help field users capture better location data. Using XLSForm expressions we can actively check the quality of location data in the survey and provide users with clues to help correct issues.  XLSForm expressions can also be used to prevent users from submitting location data that does not comply with our own business rules.  Finally, XLSForm expressions allow us to store many location quality indicators as GIS attributes.  This information is very valuable to support QA/QC workflows and before analysis and visualizations of the data are performed.

New Britain is the largest island in the Bismark archipelago of Papua New Guinea. William Dampier, takes credit for being the first British man to land on this island. This happened on February 27, 1700. Since then we call this island New Britain (Nova Britannia at the time). Both Wiliam Dampier and New Britain are fascinating. This island, of volcanic origin, was populated by two main indigenous groups: the Papuans who arrived tens of thousands of years ago, and the Austronesians, who joined the party around 2000 years ago. The island hosts remarkable traditional cultures. Still today, over 10 different Papuan languages  are spoken in the island and as for the Austronesians languages, we count more than 40! William Dampier is known for being the first man to circumnavigate the world three times. He grew as a pirate attacking Spanish ships in America and then became a successful navigator and explorer. Dampier documented winds, tides and currents that were critical for future explorations by James Cook and Horation Nelson. His natural history observations were also highly influential on works of Alexander Von Humboldt and Charles Darwin.

 

With our 3.3 update, we celebrate the adventures of William Dampier and his landing over 300 years ago to the island today known as New Britain.

 

 

Enhanced support for GNSS receivers in the Survey123 field app

 

Starting with version 3.3, you can establish a direct connection between the Survey123 field app and your GNSS receiver. This is useful for several reasons:

 

  • More accurate location data:  By leveraging dedicated high accuracy GNSS hardware, you can substantially improve the quality of the location data you capture with your smart forms.  There is a wide range of GNSS receivers, some of them able to produce, if used properly, sub-meter and sub-centimeter accuracy. 
  • Better understanding of the quality of the data: Having more accurate location data is not enough. It is also important to understand how accurate that data is.  Most GNSS receivers are able to provide important information that describe how the locations you are getting were produced. This includes things like the type of fix (RTK Fixed, RTK Float, GPS, Differential GPS, SBAS...), the differential age, reference station ID and many others.  With version 3.3 of Survey123 and above, you can select which of these properties are important to you and store them as GIS attributes in the feature layer columns of your choice. For a complete list of all the location metadata you can extract from your location data with Survey123 refer to the extract geopoint values help topic.
  • Custom validation rules: You can use all the GNSS metadata described above to create custom data validation rules that get triggered while the data collection is happening. This is critical, as it can save many trips back to the field! It is important to note that you can use all the power of XLSForms to build sophisticated expressions that take advantage of this metadata.

 

In this initial release, we have thoroughly tested GNSS receivers built by a number of vendors including Leica, Eos Positioning Systems, Bad Elf, SXblue, and Trimble, although it technically can work with other receivers as long as they output NMEA sentences. Our choose a receiver help topic includes more information regarding currently supported hardware.

 

To support direct connections to external GNSS receivers, you will notice we have introduced several changes in the Survey123 field app. The Settings dialog in the app now includes options to connect to external location sensors via Bluetooth and network ports. For each connection you can also set user preferences such as a custom name for your device, the height of the antenna and handy visual and audio alerts to warn users in case the connection between the GNSS receiver and your device is interrupted.

 

Our XLSForm support has also been expanded so you can include in your form expressions to help work with the GNSS metadata in real time.  This really opens a wealth of possibilities for you to use this information to design soft and hard data validation constraints in your forms.  The geopoint help topic in our doc describes in more detail how to take advantage of this.

 

Point to Point Measurements with Spike® and the Survey123 field app

 

We introduced support for the Spike laser range-finder in March 2018.  Spike is an excellent complement to Survey123, allowing you to quickly bring laser-accurate measurements into your forms. Jim Moore and Brett Stokes, who recently joined the Survey123 team, put together this video to demonstrate the basics of bringing measurements from Spike into Survey123.

 

 

In this release, we are bringing support for the Point to Point (P2P) measurement mode which was missing in our initial implementation. P2P is a very handy way to calculate distances between two objects because it does not require you to identify a 2D plane on which to measure. In P2P mode you can simply aim Spike at the first object, such as the side of a house, and take a photo. Then, aim at the second object, such as a tree or fence, and take a second photo. Spike will calculate the distance between those two objects and bring that value into your Survey123 form. You can also use Point to Point to measure the height of an object such as a tree, streetlight or building.

 

If  you are already using Spike with Survey123 and wish to try Point to  Point measurements, make sure you upgrade your Spike app from the store  with the latest version.

 

For more details on how Spike and Survey123 work together, check out theUsing Spike® with Survey123 for ArcGIS blog post.

 

Date/Time question type in web designer

 

A new Date/Time question type has been added in web designer.  This will help you capture both a date and a time in one single row, saving vertical space in your forms. Within web designer you can set a default value for this question, either selecting a static value, or the exact time when the form is open.  You can also set validation rules to constrain inputs to a time window.

 

Date-Time Question type in Survey123 web designer

 

Better field and choice naming in web designer

 

If you never liked auto-generated field names such as field_0, field_1... in your Survey123 feature layers, you will want to pay attention to this one. Let me start with a bit of context first:  When you publish a survey in web designer, we create on your behalf a feature layer field for every question in your form.  These fields are used later to store responses to your survey. Up until this release, the name of these fields followed a simple field_0, field_1 pattern. This was typically never an issue when using the Survey123 web site to inspect your data, but it was not ideal when exporting results into Excel, CSV, or when configuring web hooks.

 

Starting with this update, a more friendly name will be given to these fields based on the label of your questions. The following animation compares what an auto-generated feature layer schema looked like before, compared to what you will get now.

 

 

Field and choice names are now derived from your question and choice labels. Given that there are some constraints that apply to the names that can be given to fields in a feature layer, you will notice that your labels will not be used literally. For example, spaces will be replaced with underscores (_), very long labels will be shortened and special characters will be eliminated.

 

Using the Modify Schema dialog you can optionally fine tune the names of fields and choices to your liking, although remember that you will not be able to make adjustments in the schema once the fields have been added to the feature layer.

 

The option to Modify Schema in the Publish Survey Dialog has also been made more visible as a reminder of this important step before you publish your survey.

 

 

Delete and edit existing records for survey owners

 

As a survey owner, I am sure you always submit a couple of records to test out your survey designs, immediately checking values in the Data tab. You can now easily delete, and even edit values right from the Survey123 web site. You no longer need to use a separate tool to do that. All you need to do is to select the records in the table view, and then choose the Delete or Edit options in the right panel to make the changes you want.

 

Edit and delete records, right from within the Survey123 web site

 

At  this moment in time, the option to edit records will not be available  for surveys published from Survey123 Connect, but we are looking to  relaxing this limitation in the future.

 

 

 

Other fixes and enhancements

 

Survey123 web site:

 

  • ENH-000107831 Provide the ability to edit the survey submission "Thank you" screen seen in the browser when the survey is published from Survey123 Connect
  • Import custom themes from other surveys.
  • For text questions, in the Analyze tab, you can now choose to display a list of word counts or complete responses.
  • Much improved user experience for configuring custom report templates.
  • BUG-000119133 Field aliases in a survey in the Survey123 for ArcGIS application are not respected in single choice and drop-down lists.
  • BUG-000098360 When downloading data from a Survery123 survey that was made using Survey123 web designer, the field names are converted to {field_1}, {field_2}, ... instead of honoring the name in the data table.
  • BUG-000103150 Surveys created in Survey123 web designer using drop-down choices display 'choice1, choice2, ...' when exported to a CSV file or a shapefile.
  • BUG-000105778 Survey question choices from single choice questions do not correctly translate when exported to CSV or shapefile from surveys that were created via Survey123 web designer.
  • BUG-000114116 When using a custom template that writes out results from related and non-related attributes from a survey, the non-related records do not populate the template table.
  • BUG-000113548 When an audio attachment is included in the survey, the Survey123 for ArcGIS website fails to generate a report.

 

Survey123 field app and Connect

 

  • Allow users to zoom beyond level 18 if the tile package includes more detailed levels.
  • BUG-000119481 When creating a Survey123 for ArcGIS survey with an existing feature service, the float or single field types do not auto populate in the XLSForm created
  • BUG-000110786 When signing in to the Survey123 for ArcGIS (iOS) app configured with an IWA portal, the app uses the username and password entered at the beginning of the app session for all subsequent sign-in attempts.
  • BUG-000119847 Date questions in certain languages are not displaying the calendar correctly
  • BUG-000119899 Integer type questions with the "spinner" appearance type do not work
  • ENH-000105170 In Survey123, allow users to change the Location Provider, from the internal receiver to an external receiver.
  • ENH-000109937 Provide an indicator within the Survey123 interface to display which GPS unit the app is using.

In this blog post I will describe how you can integrate Survey123 with Spike. Spike is a laser-based measurement solution by Esri partner ikeGPS.   What makes Spike unique is that it allows you to easily measure the dimensions of remote objects, such as areas and lengths, all from a photo.

 

Say, for example, while doing a property inspection you need to calculate the height of a balcony, or the size of a garage door.  Rather than using a ladder and measuring tape, you can simply take a photo of the building, and then calculate dimensions by drawing on top of the photo.  You can similarly use Spike to calculate the size of road signs, billboards, poles, etc.   

 

You can embed Spike questions within Survey123 and automatically bring all measurements from Spike into your form: Tap on a Spike question, snap a photo, measure on it… and your measurements will get persisted in ArcGIS along with the rest of the survey data.

 

The integration of Survey123 with Spike is exciting news, because it has the potential to boost the productivity of certain data capture workflows tremendously.  This short video tutorial describes the basics of how Survey123 and Spike work together:

 

 

Lets next get into the details...

 

 

About Spike®

 

The Spike laser: The most visible aspect of Spike is the laser instrument. It is an eye safe Class-1 laser, designed to measure distances in a range between 2 and 200 meters with an accuracy of 5 centimeters. The laser is designed to be attached to your smartphone or tablet and paired using a Bluetooth connection.

 

Spike units have a retail price of $499 and are sold online and through a network of resellers.

 

The Spike app: Once the laser is paired, the Spike app uses the camera on your smartphone or tablet so you can take a photo of your object of interest. Using the distance to the photographed object captured by the laser, the Spike app can accurately calculate lengths and areas as you draw lines and polygons over the photo.

 

The Spike app is available for iOS and Android operating systems and is certified for use against a wide collection of smartphones and tablets

 

Getting familiar with Spike: Spike is straight-forward to use, but knowing a handful of tips and good practice in the field is key to get the best out of it.  The best reference to take your first steps is the Spike User Manual

 

Spike can be operated through two main modes:

 

  • Photo Measurement: When working in New Photo Measurement mode, you take a single photo, and then derive all measurements from it.  You can for example simply get the distance from your location to the object, or extract lengths and areas by drawing on your photo.
  • Point-to-Point Measurement: In this mode you can calculate the distance (horizontally and vertically) difference between two objects by taking a separate photo of each object.

       

Photo Measurement mode:In its simplest form, the Photo Measurement mode will allow you to simply snap a photo of an object, and get back the exact distance to that object form your current location.  This alone can be useful in multitude of use cases.  Say for example you need to document the width of a road: stand on one side of the road and take a photo targeting at the other end across. After taking the photo, Spike will give  you the exact distance. Not only you can get an accurate measurement, but you can do it without risking your life; safely from one side of the road. 

 

With Photo Measurement mode you can also measure distances (and areas) on objects by simply drawing on top of the photo you just took. For example, say you want to know what is the height of a building. Well, you take a photo of it, and then you extract the height by drawing on that photo.  If you want to derive measurements from a photo in this way, certain conditions need to be met.  When used correctly and in ideal conditions, you can expect a measurement with an accuracy of 1%.  For example, if you measure the height of an object to be 10 meters, you can expect the accuracy to be around 10 centimeters.

 

Let’s describe next what used correctly and ideal conditions means:

 

  • Measurements against a flat surface: You should only perform measurements on flat surfaces, such as a wall or a sign. The specific shape you want to measure should be on a rectangular plane. This is because you will need to define the plane in the photo before you can measure anything. 
  • Face your target front-on: For the most accurate measurements, you should take your photo while facing your target perpendicularly. That is, you need to be right in front of the plane on which you will do your measurements. If you need to take your photo at an angle, the expected accuracy of the measurements will be reduced progressively as you get further from being perpendicular.

 

 

  • Ideal target range: The ideal working range of the laser is between 6 and 100 meters, although technically you can push the limits and measure objects between 2 and 200 meters away.
  • Center your target: You also want to make sure that the object you want to measure is right in the center of the camera bulls eye, because the laser always calculates distances through the bulls eye.
  • Draw accurately: Once you have taken the photo, you will want to make sure you accurately draw your lines and areas for measurement. The Spike app has a handy magnifying window that will help you with that task.   If your photo is taken following all the tips above, but you do not take pride in carefully drawing the exact shapes you want to measure… the measurement will not be as accurate as it could be.

 

So far all of this may sound a little bit intimidating, but once you have the Spike device in your hand things are much simpler. Not just simpler, but also fun. Next you can see Brandon having a good time while ‘spiking’ outside Esri.

 

 

From our own experience, the Photo Measurement mode works best with man-made structures: walls, signs, billboards, doors, straight poles, streetlights etc.  Measuring the height of trees, rocks etc is much more challenging because you often do not have a good plane to reference your measurements.  If you do not have a good 2D plane to make your measurements on, then you should consider using the Point to Point measurement mode.

 

Point to Point Measurement mode: Point to Point or P2P is very useful when all you need is to measure the distance between two objects in front of you and you either cannot fit the two objects within a single photo, or when you do not have a good 2D plane on which to base your measurements. With P2P, you simply need to center your camera on your first target, say for example a tree and take a photo. Then you turn from that same location to take a photo of your second target, say for example a wall. Spike will compute the horizontal and vertical distances between the two photographed objects.

 

Like with any tool out there, it takes a bit of practice to fully understand what is the best measurement mode for the job.  Spike can greatly boost the productivity of field workers saving valuable time. It also can provide a much safer way to make measurements. For hard to reach objects, Spike can make it possible to perform measurements that could not be done otherwise.

 

Now that I have described the basics of Spike, it is time to go into the details of how Survey123 and Spike work together.

 

Integrating Survey123 with Spike (Photo Measurements)

 

Starting with Survey123 version 2.6, you can incorporate Spike functionality into your form. This allows you to streamline the use of Spike within your data collection workflows. For example,

if you have a survey to help map the presence of graffiti in the city, you will want to capture many things including the location, typology (Tag, Throw-up, Blockbuster…), surface, photo and size.  Spike can help you capture the size accurately, so you can estimate the cost of removal.

 

Adding Spike questions into a survey: You can add Spike questions to a survey using Survey123 Connect for ArcGIS. In your XLSForm, add a question of type image, and then set the appearance to either spike-full-measure, spike or spike-point-to-point:

 

  • spike: With this appearance, Survey123 will launch the Spike app so you can simply aim at your object of interest and snap a photo of it.  The spike appearance is useful when you simply want to get the distance to the photographed object and its estimated location.
  • spike-full-measure: This appearance sets the Spike app in New Photo Measurement mode as described in the previous section. When using this appearance, you will be able to get the measured lengths and areas, into your form.
  • spike-point-to-point: Launches Spike in Point to Point mode so you can calculate the horizontal and vertical distances between two photographed objects.

 

When using the spike-full-measure, spike-point-to-point and spike appearances, Survey123 will let users easily launch the Spike app from within the form.  Once the photo has been taken and measurements added, Spike will return back to Survey123, so all measurements of interest can be extracted and stored in the survey.  The measure object with Spike help topic describes step by step how Survey123 and Spike work together.

 

Spike photos will be stored as an attachment automatically.  This is a great feature because photos will become a verifiable record persisted with your data. Photos will show how accurately the measurement was made in the field, and if needed, the photo itself could be used in the back-office to make additional measurements.

The use of Spike within Survey123 is only available to logged-in users. Spike questions can be used while online or offline, but you must be logged-in.

                            

 

Extracting Spike measurements with pulldata(): Spike uses EXIF photo headers to store information such as the location from which the photo was taken, the direction, distance and measurements made in the Spike app.  In a previous blog post we explored how to extract EXIF metadata from an image in Survey123 using the pulldata() function. This same technique can be used to extract Spike metadata.

 

The Spike metadata in the EXIF of the image is split between standard EXIF tags and custom information stored in the ImageDescription tag. The following table describes standard tags populated by Spike:

 

 

EXIF tagDescription
gpsdestlongitude

The estimated X coordinate of the photographed object

gpsdestlatitude

The estimated Y coordinate of the photographed object

gpsdestcoordinate

The XY coordinate pair of the photographed object

gpstimestamp

The time when the photo was taken

gpsdatestamp

The date when the photo was taken

gpsdestdistance

The distance between the photographed object and your device

imageDescription

A JSON string including measurements captured by the Spike app

 

This expression will extract the distance in meters between the photographed object and the device:

 

pulldata("@exif", ${spike}, "gpsdestdistance")

 

In order to extract photo-measurements from Spike, your pulldata() function will need to first get the ImageDescription EXIF tag, and then parse the returning JSON string to extract the specific dimensions you are looking for.

 

For example, the following expression assumes the first measurement made in Spike was of type length, and gets its value in meters:

 

pulldata("@json",  pulldata("@exif", ${spike }, "ImageDescription"), "Spike.objects[1].dimensions")

 

The next expression assumes the first measurement made was of type area and extracts its value in square meters:

pulldata("@json",  pulldata("@exif", ${spike_full}, "ImageDescription"), "Spike.objects[1].area")

 

This expression gets the horizontal distance between two objects as measured through the Point  to Point measurement mode:

 

pulldata("@json",  pulldata("@exif", ${spike }, "ImageDescription"), "P2P.horizontal_distance")

 

 

Spike returns many other properties through the ImageDescription EXIF tag including: the pitch, roll and direction of your device when the photo was taken, the unique identifier of the specific Spike laser unit that captured the distance measurement etc. The Spike section of the Media help topic describes in detail the contents of the JSON object stored in the ImageDescription.

 

Another way to explore the contents of the ImageDescription tag is to simply add a text question to your form and have it populated with the contents of the ImageDescription tag through a calculation.  When you do this, it is important that you set the esriFieldLength column of your text question to 1000 characters. The ImageDescription JSON string can be quite big.

 

A great starting point to experiment with all the things you can do with XLSForms and Spike is our Spike sample. I strongly recommend that you have a look at it:

 

1.    Open Survey123 Connect for ArcGIS
2.    Click on Create New Survey
3.    Search for the Spike survey in the Samples category
4.    Publish it and test from your smartphone
5.    Look into the XLS file to learn all the techniques used in the sample.

 

Integrating Survey123 with Spike (Estimate Locations)

 

While the heart of what Spike excels at is helping you measuring dimensions over photos, you can also use Survey123 to roughly estimate the location of remote objects.  For example, you can map the location of a building without stepping out of your car, or the location of a streetlight across the street.

 

Before we go into the details of estimating the location of remote objects, I want to emphasize that Spike is not a high accuracy surveying device.  It can measure accurately distances to objects, but when estimating the location of remote objects there are several sources of error that will come into play outside of what Spike is designed to do.

 

To define the location of a remote object, Spike relies on the following:

 

  • The location of your own phone or tablet: This is the first source of error. A typical smartphone is not going to give you a highly accurate location for your phone. Your location accuracy may vary depending on many factors and if your location is off, the estimated location of the remote object will be off too.  To correct this problem, you can connect an external GNSS receiver to your own phone or tablet via Bluetooth. If used correctly, external GNSS receivers will improve the source location used by Spike in its calculations. In the side photo, for example, Survey123 is combined with Spike and Juniper Systems Geode Sub-meter GNSS antenna.
  • The distance to the remote object: This is going to be very accurate as long as you keep yourself within the working range of Spike (2 to 200 meters) and you aim at the remote object using the bull’s eye in the Spike app. Measuring distances to objects is what Spike is designed to do, and does it very well.
  • The azimuth to the remote object as measured from your own device location: The azimuth is another important source of error. The azimuth is obtained from the compass in your own smartphone or tablet. The compass in your smartphone must be calibrated before use by Spike. It is critical that you follow steps in this compass calibration video-tutorial before you estimate remote locations. Even with your compass calibrated, it is normal to get deviations of a few degrees, which will increase the error as the distance to the remote object increases.

 

The gpsdestlongitude and gpsdestlatitude properties will be populated with both the spike and spike-full-measure appearances.If you do not plan to capture any length or area measurements and all you want is the location of the photographed object, then the best is to use the spike appearance.

 

To extract the estimated latitude and longitude of the photographed object, you will use the pulldata() function within a calculation. For example, the following expression will extract the latitude:

 

pulldata("@exif", ${spike}, "gpsdestlatitude")

 

You can store the latitude and longitude as attributes in your survey, and then create an XY Event Layer with them in ArcGIS Pro or other tools.  

While it should be possible for you to calculate a geopoint question with the latitude and longitude values extracted from the Spike photo, there is currently a known limitation in Survey123 preventing the successful calculation when applied. This is in our backlog and we will work towards resolving the problem as soon as possible.

          

As stated before, it is best that you exercise Spike in the field in all its capabilities. To fully understand its potential and limitations you must experience it in the field in real working conditions.

 

If you need some ideas, here is an informative video by IkeGPS further describing some common use cases for Survey123 and Spike.

 

Our Developer Summit conference is approaching fast.  We at Esri always put a lot of energy into this event. It is an opportunity to meet face to face with many of you, share our work, discuss new features and road map plans. 

 

2019 will be very special for us as we will make 4 years since we announced the graduation of Survey123 from an Esri Labs proof of concept into a full fleshed ArcGIS Product. This year we will announce details on ambitious plans for the new releases to come: direct connections to external GNSS receivers in the field app, added support for polygon and line features, a release date for our Survey123 report services, enhanced integration with Spike laser measurement tools, a new extensibility framework and many more great news. Members of the Survey123 team from our offices in Beijing, Australia and Redlands will come to Palm Springs. We are really excited for the opportunity to meet you again.

 

Today we want to share with you some tips and a guide for anything Survey123 at these events.

 

The Events App

 

I highly recommend that you download the Esri Events app, so you can always be on top of last minute changes and manage your schedule.  As of the time when I write this post the detailed schedule is not yet up in the app, but it will be available shortly.  This app will be a good companion throughout the entire conference.

 

Pre-Summit Hands-On Training

 

Our Esri Pre-Summit Hands-On training sessions take place on Sunday 3 and Monday 4. These are full day sessions with a mix of lessons and practical challenges. You bring your own laptop, so you can take all homework home. Massive learning guaranteed!   Our sessions start at 8:30 sharp. You can register starting at 7:30 at the Hotel Riviera.

 

  • Mastering Smart Form Design with Survey123 and XLSForm.
    • Sunday, March 3 from 8:30am to 5:00pm
    • Royal II at Hotel Riviera Palm Springs.
  • Extending Survey123 for ArcGIS.
    • Monday, March 4 at Royal II from 8:30am to 5:00pm
    • Royal II at Hotel Riviera Palm Springs

 

Esri Showcase and GIS Solutions Expo

 

The GIS Solutions Expo area opens Monday from 2:00pm to 7:00pm at the Primrose Ballroom. This is a great place to meet many partners who work closely with Survey123.  Here are a few:

 

  • Microsoft. Diamond sponsor this year. Showcasing the Survey123 Microsoft Flow connector.
  • Bad Elf, EOS Positioning Systems, Trimble, GENEC:  Providing GNSS receivers for which Survey123 3.3 will provide direct connectivity capabilities.
  • Zebra Technologies: Manufacturing rugged devices compatible with Survey123.
  • Geo Jobe: Custom software development services.

 

During this time, you can also swing by the Esri Showcase area to visit the Survey123 team in the Apps area.

 

On Tuesday from noon to 8:30pm, Wednesday from 1:00pm to 6:30pm and Thursday from 9:00am to 4:00pm the Esri Showcase will continue open in Oasis 1 and 2. Come to the Showcase and look for the Survey123 booth. This is your chance to meet people from the Survey123 team, have a relaxed conversation, ask questions and network with other Survey123 users.

 

Meet the Teams

 

The Meet the Teams event will take place from 6:00pm to 8:30pm in Oasis 1 and 2 on Tuesday. In other words, at the Esri Showcase area. Drinks, food and GIS to spare.

 

Esri Dev Summit Technical Workshops

 

These are 60 minute sessions. All take place in the Palm Springs Convention Center. A good place to learn from the best, ask questions and meet other Survey123 users.

 

Other related Technical Workshops

 

If you plan to extend or customize Survey123, the AppStudio sessions are a must.

 

 

Survey123 Demo Theaters

 

Short and to the point sessions focusing on very specific topics. Live demos and time for questions are guaranteed. All Demo Theaters take place at the showcase area.

 

 

Survey123 Special Interest  Group (SIG)

 

This session is a great place to mingle with other Survey123  Ninjas and members of the Survey123 team. Keep your own lunch box because this SIG takes place at noon. We will break the ice with help from a special guest who will share his own work deploying Survey123. Then we will open an interactive Q&A session.

 

  • Survey123 SIG
    • Thursday, March 7 from noon to 1:00pm
    • Primrose A at the Palm Springs Convention Center

Many web applications support the notion of URL parameters; Survey123 web forms are no exception. URL parameters allow you to dynamically pass data into your survey. This data can be used to prepopulate questions, hide questions, change the language of a form and many other things with your survey form. In this blog post, I will explore the options available in detail.

 

Before I start, I want to clarify that in the past we already covered how to use the Custom URL Scheme in the Survey123 field app. The concept of a Custom URL Scheme is similar to URL parameters, but they are two different things: the Custom URL Scheme applies to the Survey123 field app and the URL parameters discussed in this post only apply to web forms. That is, to forms loaded within a web browser, as opposed to loaded into the Survey123 field app in your device.

 

With that, lets get started:

 

The Basics

 

Lets first get familiar with how surveys get loaded into the Survey123 web app. Take the following URL:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765

 

The first part of the URL refers to the Survey123 web app: https://survey123.arcgis.com/share/ We host the Survey123 web app in our ArcGIS Online servers, and it is used to render your surveys as web forms.  The second part of the URL is the unique identifier of your survey. In this particular case, it is: 1cb28b212b5542acbbdbaa35feba0765. The complete URL will open the Survey123 web app in your web browser and immediately present the survey 1cb28b212b5542acbbdbaa35feba0765, in this case it is an Oak Tree Health survey.

 

So far, no URL parameters have been used, but now we are going to add one parameter to automatically populate one of the questions. Try the following:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?field:submittedBy=Fernando Paredes

 

You will notice that now the Submitted By question is automatically adding the name Fernando Paredes in the survey.  Well, that was a URL parameter!  Note that immediately after the basic URL of the web form, I added a question mark (?). The question mark indicates that what follows are URL parameters. Next, I added the name of the parameter, which in this case is field:submittedBy and a value for that parameter: Fernando Paredes.

 

You can add multiple parameters by simply separating them with an ampersand (&). For example:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?field:submittedBy=Fernando Paredes&field:commonName=Oak

 

Next, lets learn about the different URL parameters you can pass to Survey123 web forms.

 

Some of the URL parameters described here are supported in surveys published with 3.2 or newer versions. If your URL parameters do not seem to take effect, re-publish your survey so it gets upgraded to the latest version, and then try again.

 

Setting values on questions (field:fieldname)

 

In the previous section you saw how a URL parameter can set a value to a question in your form, but lets take a closer look at how it works. The syntax is simple:

 

field:commonName=Oak

 

The name of the parameter is made  out of two distinct parts. First, you have the field: suffix and then you have the name of the question where you want to put a value.  Figuring out the name of a question can be tricky. The question name should not be confused with the label of the question. The label is what users see in the form. The question name represents the column in your feature layer  where the response will be stored. 

 

If you author surveys in Survey123 Connect, I am sure you already know what  I am talking about: The question name is represented by the name column in the survey worksheet of your XLSForm.  If you design your forms in Survey123 web designer, then finding out the exact name of your questions deserves a more detailed explanation.

 

After adding a question into your survey in web designer, you need to set its label and other properties, but not the name. The name of your question is automatically assigned by Survey123 web designer.  Assigning a valid question name needs to follow very strict rules (the name cannot start with a number, cannot have special characters, or  spaces and must be unique within your entire form) and that is why we put that out of your way in designer. This simplifies  authoring for beginners, although in cases like this it obscures what is really going on.   In any event, you can look at the question names by using the 'Modify Schema' link during the publishing process. 

 

Modify Schema in Survey123 web designer

 

The Modify Schema dialog will let you define the exact names of your questions only when you add your questions to the form for the first time. Once you publish your survey, questions that already exist in your survey will appear as read-only in the Modify Schema dialog.   In my case, I really did not want to change anything, I simply wanted to get the names so I could use them with my URL parameters.

 

Question names are case sensitive. You must pass the exact name. For example, in the oak survey, field:commonName=Oak will work, but field:CommonName=Oak will not work.

            

 

Centering geopoint questions (center)

 

The center parameter lets you set the default location of the geopoint question in your survey.  It looks like this:

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?center=34.1,-117

 

This parameter accepts a latitude/longitude coordinate pair where the values are separated by a comma.  Now. there are a couple of important things to remember when using this parameter:

 

  1. This URL parameter only takes effect if the geopoint question is flagged as required, AND
  2. If authoring from web designer, the option to 'Ask user's location when opening this question' must be disabled'.

 

If the geopoint question is not required or the user location is used, the values from this URL parameter will be overridden at runtime when the end-user opens the question.

 

Hiding questions and survey elements (hide)

 

The hide parameter is handy when you want to control visual aspects of your survey. You can load a survey and hide questions, the navigation bar and more.  This parameter takes as an input more or more values, separated by a comma.

 

Parameter ValueDescription
navbarHides the navigation bar. That is, the bar at the top of the survey that includes options to login/logout and to change the language. This is particularly useful when you embed your survey within a website. Example.
headerHides the survey header. The header typically includes the title of the survey or alternatively a banner image. This is particularly useful when you embed your survey within a website. Example.
descriptionThe description element is optionally included if you author your survey in web designer.
footerHides the footer element, which includes the Powered by Survey123 link, or an alternative link if you modified it. Also useful when embedding your survey within a website. Example.
themeUse the theme value to disable any custom theme applied to your survey.  Example.
field:fieldNameThis value is used to hide specific questions within your survey. If you want to hide multiple questions, simply add their names separated by a comma. Example hiding the Submitted by and Survey Date questions.

 

The hide parameter is very flexible, allowing you to hide multiple elements at once. That is, you can hide the navigation bar, the footer, description and as many questions in the survey as you like.   To hide multiple elements, you simply need to keep adding comma separated values to hide the different components. For example:

 

...?hide=field:submittedBy,field:surveyDate,theme,footer

 

Another interesting thing you can do is hide a question and at the same time set its default value through a URL parameter. For example, you can hide the Submitted by question in the Oak survey and also set a value for it through your URL parameter.

 

Redirect the Survey123 web app to your own ArcGIS Enterprise (portal)

 

While the Survey123 web app is hosted in ArcGIS Online, there is no reason why you can't load surveys from your own ArcGIS Enteprise instance.  You do this through the portal URL parameter, which takes as a value the URL of your own ArcGIS Enterprise  Web Adaptor. For example:

 

https://survey123.arcgis.com/share/acb28b212b5542acbbdbaa35feba0765?portalUrl=https://acme.com/gis

 

The above URL will load into your web browser the survey with identifier acb28b212b5542acbbdbaa35feba0765 as found in the https://acme.com/gis ArcGIS Enterprise instance.

 

Set the app that will open your survey (open)

 

You can use the open URL parameter to determine the app to use with survey. Valid values for this parameter include: web, native and menu.

 

https://survey123.arcgis.com/share/1cb28b212b5542acbbdbaa35feba0765?open=menu

 

Parameter Value Description
webOpens your survey in the Survey123 web app, as a web form. This is the default. Example.
nativeWill open your survey in the Survey123 field app. This option will only work if the Survey123 field app is already installed in the device. Example.
menuWill open web page to let the end user decide if the survey should be open in the Survey123 field app or within a web browser. Example.

 

Set the language of your survey (lang)

 

The lang parameter switches the language of your survey dynamically. This parameter only will work if you have included language translations for your survey.  For more details on mutiple-language surveys refer to Introducing Multiple Language Surveys 

 

The lang parameter accepts ISO language codes. For example: lang=zh-cn  and lang=en.

National Weatherperson's Day, also known as National Weatherman's Day, is observed on February 5 primarily in the United States. It recognizes individuals in the fields of meteorology, weather forecasting and broadcast meteorology, as well as volunteer storm spotters and observers. It is observed on the birthday of John Jeffries, one of the United States' first weather observers who took daily measurements starting in 1774. Jeffries also made the first balloon flight over London in 1784 with the purpose of gathering data for a scientific study of the air at high altitudes.

 

Our forecast for the 3.2 release is as follows: Bright like the sun, new features and enhancements in the morning, particularly in the Survey123 website and web designer. A joyful rain of fixes for the Survey123 field app at night, including massive improvements to repeats and nested repeats. 

 

Pages for your web forms

 

In this update you can organize questions in your surveys across multiple pages. Pages are particularly useful when working on very large forms, helping you logically organize your questions and giving end users a sense of progress across the entire survey.

 

 

In the example above, I added a welcome image and text on the first page to create a cover for  my survey. Note that the first page does not expect any input from the survey. It is just a welcoming page, or cover.  Next, I organized the actual questions within my form into pages, giving each page a descriptive title at the top.  As users move from page to page, a progress bar at the bottom shows how close they are to the end of the survey.

 

You can combine groups and pages to further help organize questions within your survey!

 

If you use web designer to create your surveys, you will find that we have added a Page option in the main panel. Just like you do with other question types, simply click on Page, and it will be added to your form. You will be able to drag and drop questions into your new page, move questions from one page to another and even merge and duplicate pages!

 

 

If you want to work with pages in Survey123 Connect, you need to do two things:

 

  • First, in the settings worksheet of your XLSForm, you will set the value of the style column to pages.
  • Then, in the survey worksheet, you will use the field-list appearance for any XLSForm begin_group question type that you want to turn into a page. 

 

Also note that when using the pages style, pages will be automatically created for any question outside field-list groups.

 

Whilst the implementation for pages is complete in our web form, currently in the field app constraint and required checks will not be performed when you leave a page.  These checks will only be done when you attempt to submit the survey. In some scenarios this can make it difficult for end users to identify the exact question in the form where the validation rules were broken. Make sure you define good error messages for your required and constraint rules. Other than that, pages work pretty well in the field app!

 

Embedded public web forms

 

You can now embed public web forms in your own web site. As shown below, the Collaborate tab of your survey will now include an Embed option from which you can copy the HTML code needed to embed your survey within a web site.

 

 

A handful of embed options let you quickly configure your embed HTML code to hide elements of your survey that you may want to hide, such as the header, sign-in, multiple language options, footer, etc.  You can even disable the theme colors to provide a more neutral presence of your embedded survey within the web site.

 

Below is an example showing a Survey123 form embedded within a web page.  Note that the header, footer and themes have been disabled to make the survey fit better within the web site.

 

 

Better word clouds

 

The Survey123 website includes a number of reporting capabilities to help you understand data captured through your surveys. The Analyze page, for example, aggregates responses for categorical, date and number questions and creates charts and maps to more quickly identify trends on your data. 

 

Questions with free text are always trickier to aggregate, but that is where word clouds come to help. A word cloud takes the most common words found in your data and sizes them according to popularity. The bigger the word, the more repetitions. It is a simple concept but it often gives great insight.  Unfortunately, the most common words in our language are far from interesting in this context. Think about it: this, that, of, a...  all pretty useless stuff in a word cloud, don't you think?  These words are known as stop-words, and now you can set a filter to ignore them. In English at least.

 

Here you can see how word cloud filters made a difference for our friends at City of Lakeland, in Florida:

 

In this particular scenario, the survey asked people in the city 'What are your thoughts on how can we better educate drivers to pay attention?'. The most popular words among the responses are 'the', 'and', 'to' and 'of', but if we  apply the stop word filter, much more relevant words will come out:  speed, signs and people.  With stop word filters you can more easily understand certain relevant trends in your data.

 

More on custom themes

 

We introduced Custom Themes not long ago. Definitely a good addition to give your surveys a nice final touch! If you haven't already, I highly recommend you watch this video-tutorial or read the Introducing Custom Themes blog post.

 

 

In this update 6 new theme templates have been added. 5 of them will help you quickly switch through different color combinations. You can also make tweaks in them, of course, but they provide a nice start.  The sixth template is more interesting, in that it will mirror the Shared Theme of your ArcGIS organization.  If you are not familiar with this concept of Shared Theme, have a look at Ian's blog post Introducing Shared Theme: a new app styling capability in ArcGIS Online.  The Shared Theme is set by the administrator of an ArcGIS Organization defining the basics for styling configurable apps in it: text and background color, etc.  Now, you can easily match that style!

 

Web designer: Option to automatically center map at the device's location in web forms

 

A new option has been added in web designer to automatically center the map at the user's location when a geopoint question is open within a web form.

 

 

Lets describe in more detail what is going on here, because this option only makes sense once differences between the behavior of geopoint questions across web forms and the Survey123 field app are understood. 

 

Geopoint questions in the Survey123 field app are by default centered at the user's location. In a Web Form, the behavior is very different.  When your geopoint questions are shown within a web browser, the location of the map remains as set by the author of the survey. The Survey123 web app by default will not attempt to gather the user's location. Otherwise, as soon as the survey is loaded, the web browser will automatically present a dialog to the end user asking for permission to gather the device's location.  Without proper context on why that  message is appearing, this would cause distrust in many users.

 

The user can change the location of the map by either manually panning the map or centering it at a particular address or at the user's location. By enabling this new option, the map, once in edit mode, will automatically center to the user's location.  This will trigger the web browser to require confirmation before handing over the location to the Survey123 web app, but this will happen in context.  Users will understand at that point why the survey is attempting to gather their location.

 

For the reasons described above, this new setting has no effect when the survey is loaded in the Survey123 field app.

 

Other enhancements and fixes

 

Survey123 Website

 

  • BUG-000112899 Publishing a survey on survey123.arcgis.com connected to a Portal for ArcGIS using Integrated Windows Authentication (IWA) returns the error message, "Unable to publish the survey. Unexpected token < in JSON at position 0".
  • BUG-000116898 Renaming the survey under 'Edit Survey Info' in survey123.arcgis.com will cause the feature service to change the name from _fieldworker to _stakeholder.
  • BUG-000117623 When survey123.arcgis.com is accessed via Portal and only one record is present in the service, the default extent and zoom level configured on the survey are not honored when viewing from the Data tab.
  • BUG-000116269 When printing a web map in a custom report from the Survey123 for ArcGIS website, at least one element of the web map must be public, otherwise the error message, "An error occurred while generating report(s)" is returned.
  • BUG-000117239 Survey123 does not honor survey’s viewer collaboration with a group in ArcGIS Online if the survey has been authored through Survey123 Connect using an ArcGIS Server secured feature service added to ArcGIS Online as item with Credentials stored.
  • BUG-000116800 Reports generated from the Survey123 for ArcGIS website show the Object ID as a date.
  • BUG-000116268 When printing custom reports from survey123.arcgis.com, the web map in the report fails to display all layers in the map.
  • BUG-000118284 In Survey123 for ArcGIS, the map scale setting is not honored when including a map in a report.
  • BUG-000118703 Surveys with calculate type questions that use pulldata() on a geopoint question within an if statement display the error "Error: Initialing Form... FormLogicError: pulldata with incorrect number of parameters found: pulldata('@geopoint', // , '')" and load without form logic when opened in the Survey123 Web App.
  • Custom Reports can now access all fields within the underlying feature service.
  • Custom Report syntax in Microsoft Word documents is now checked immediately after uploading the template.
  • Added support for the XLSForm function @property in Web Forms.

 

Survey123 Connect

 

  • Survey123 Connect will no longer overwrite survey settings (such as web hook configurations) updated through the Survey123 website.
  • BUG-000111392 Survey123 Connect installed on a Windows 2012 R2 machine crashes when publishing a survey to Portal for ArcGIS 10.5.1 configured with enterprise logins.
  • BUG-000119026 Delete refresh token stored in SecureStorage if auto login fails with invalid refreshtoken error.
  • BUG-000097165 - Copy images used for form background into the media folder.

 

Survey123 Field App

 

  • Various fixes affecting repeats and nested repeats (BUG-000117852, BUG-000117987, BUG-000118094, BUG-000118449 and many others).
    • BUG-000117852 : Surveys for geopoint, picture and select one questions are not displayed for the second and subsequent repeat questions/related tables in sent folder if those questions are relevant questions.
    • BUG-000117987 : Calculation fields fails to retain submitted values in Inbox if the field are part of "Repeats".
    • BUG-000118094 Relevancy questions within repeats do not save the information when the survey is saved as a draft.
    • BUG-000118449 : When including a signature field in a relevancy controlled group within a repeat in Survey123 Connect, the first signature entered is not displayed in the outbox (drafts).
  • BUG-000117493 "SSL Handshake failed (6)" error is generated in Survey123 app when using Android 7.0 or higher and using non-CA certificates for Portal.
  • BUG-000110786 - Survey123 cannot change from an Windows Authentication (IWA) portal to another.
  • BUG-000113293, BUG-000113294 - User signed out when losing network connection.
  • BUG-000098854: Survey123 App Portal cannot be added after tapping "Add Portal" in Windows Mobile.
  • BUG-000118375 Mathematical calculations from Inbox do not trigger when NaN or null values are used.
  • BUG-000106578, BUG-000112873 - When choice_filter used, the name text is saved as the data value, instead of the label text.

 

Did you know that using XLSForm you can choose to save the label of the selected item in a list instead of the name? For more details see: Survey123 Tricks of the Trade: XLSForm functions for lists 

 

  • ENH-000109073 - Include a comma (thousands separator) in decimal questions.
  • Various bug fixes for localization issues.

 

For more details on the 3.2 release, check out our What's New Help Topic, which also includes an archive of all new features added in previous releases.

[Last updated January 23, 2019]

 

In this blog post I will describe how you can configure your Survey123 smart forms to support multiple languages.  With multiple language support, end-users can pick the language for the questions presented in the form and you can get all their responses into a single feature layer. Multiple language surveys are authored in Survey123 Connect, but once published, they are supported in both the Survey123 Web and Field apps.

 

Multiple language surveys are created in XLSForms with Survey123 Connect

 

In order to add multi language support into a survey, you will use Survey123 Connect for ArcGIS. Survey123 Connect is a desktop tool that you can download into your Mac and Windows machine. Survey123 Connect works in combination with Microsoft Excel and lets you author smart forms following the XLSForm specification. Multiple language support is one of the many features of the XLSForm standard, and Survey123 works with it. If you are not familiar with XLSForm yet, I would strongly recommend you start with our XLSForm essentials, XLSForm video tutorials or this beginner exercise.

 

You can use Survey123 Connect to start a new survey from scratch, or to modify a survey you may have authored on the Survey123 web site.

 

How-to: A first look

 

The easiest way to understand how multiple language surveys are built is to look at an example.

 

  1. Open Survey123 Connect for ArcGIS
  2. Click on New Survey and select the Samples category
  3. Choose the Multiple Languages sample and open it

 

Note that in the Connect preview you will already see the language switcher in the top-right corner of the preview.  You can use the language switcher  to flip through the different languages.  If you publish the survey, the language switcher will also be present in the Survey123 Field app as well as in Web Forms.

 

Next, open the XLSForm spreadsheet by clicking on the top icon of the left toolbar. This will open your XLSForm in your spreadsheet editor.

 

Multiple columns have been added into the XLSForm to translate the labels of questions. Each language is notated using a descriptive string for the language followed by its corresponding ISO 639-1 code enclosed in parenthesis. For example, the XLSForm column with the question label in Spanish will be label::Español (es), and the label in English will be label::English (en).

 

You can add translations to labels, but also to hints (hint::Español (es), hint::English (en)...), constraint messages and even images! For example, if you want to include an image with a diagram along with your question, you can use the image::Español (es) column to reference a diagram that has text in Spanish and the image:: English (en) column to include that same diagram with text in English.

 

typenamelabel::English (en)label::Greek (el)hint::English (en)
textnameWhat is your name?Ποιο ειναι το ονομα σου?Type your name
select_one ananimalWhat is your favorite animal?Ποιο είναι το αγαπημένο σας ζώο;Choose one animal

 

Note: If you start adding language columns for your labels, make sure you add a language qualifier to all of them.

      

 

Similarly to how questions are translated in the survey XLSForm worksheet, choices in lists can also be translated. If you turn into the choices worksheet you will note that the same technique is used to translate the choice labels. Similarly to questions, if  you are using the image column with your choices, you can translate it too.

 

list_namenamelabel::English (en)label::Chinese (zh)label::Greek (el)label::Español (es)
andogdogσκύλοςperro
ancatcatγάταgato
anbirdbirdπουλίpájaro
anfishfishψάριpez

 

By default, Survey123 will get the language code of your device’s locale settings and try to find the right column in your spreadsheet that matches that locale. In this way, the survey will by default open in the language that matches the device’s locale. You can overwrite this behavior by defining the default language in the settings worksheet of your XLSForm.  The language switcher in the Survey123 app will let users switch to any of the available languages defined in your form.

 

form_titleform_idinstance_namedefault_language
Multiple LanguagesEnglish (en)

 

All the above is also nicely described in this new video tutorial created by James Moore.

 

 

Other important things to know:

 

  • Not everything in a survey can be translated to multiple languages. The title of the survey, for example, only supports one language.

 

  • If you use select_one_or_other type of questions in your XLSForm, your translations will not apply to the ‘other’ choice. If you plan to use your survey in a language other than English, you should not use select_one_or_other and instead build that functionality manually by adding an 'other' choice into your list and then using a relevant statement to make visible the free text question for 'other' when that option is chosen.

 

  • The language of your form defines the format of Dates in the calendar control.

 

Learn more:

 

 

[Update November 20,2017] A new learn.arcgis.com lesson on Multiple Language surveys has been published.

[Update July 20, 2018] Included list of 2-character language codes. As of version 3.0 (update July 2018) you can no longer specify languages outside the official ISO 639-1 list of 2-character codes. For any previously published forms, language codes outside the list will continue to work.

[Update December 19, 2018] Minor adjustments  made  here and there to more consistently use ISO 639-1 codes throughout the text.

In this blog post I will introduce a handful XLSForm functions that will help you work with user selections on lists.  If you are not familiar with the basics of publishing smart forms in Survey123 using XLSForms, or with selection questions, then I suggest you take a tour of the basic Video Tutorials in our Survey123 YouTube Playlist.  Below you will find a introductory video tutorial on selection questions and lists.

 

 

Using XLSForm expressions you can process user selections on lists and implement data validation rules, conditional statements to show and hide portions of your forms, and more. Here are some of the most common XLSForm functions you will be able to use:

 

selected(question, value)

 

The selected() function is used to check if a particular choice has been selected from a list. Here is an example:

 

typenamelabelrelevant
select_one yes_norepair_neededAre repairs needed?
textrepairs_commentRepairs needed:selected(${repair_needed},'yes')

 

The selected() function returns a boolean value. In the example above, I am using the function within the relevant column, to define if the repairs_comment question will be shown to the end user, or kept hidden.

 

The first  parameter passed to this function is the question on which the user made the selection.  You can only pass questions of type select_one or select_multiple.

 

The second parameter represents your test choice value. It is important to remember that the test choice value represents the name of your choice, not its label.  This makes sense because otherwise, it would be tricky to write expressions in multi-language surveys.

 

Do not pass the label of a choice to the selected() function. The selected() function expects the name value of your choice.  Also keep in mind that this function is case sensitive. 'Yes' is not the same as 'yes'.

  

 

The selected() function is particularly useful when working with multiple-choice questions (select_multiple). In the example below, I use the function to populate hidden questions with a value of 1, if a particular choice has been selected, or 0 if not selected. 

 

The violations question is a select_multiple. In it, the end-user can select one or more choices from the violations list. The output of select_multiple questions is a comma separated string representing all the choices selected. That is not very useful if I want to query the data later...   For each type of violation presented in the select_multiple question, I have created a corresponding hidden question. Using a calculation, hidden questions get populated with 1s and 0s based on the user selections.

 

typenamelabelcalculationbind:esri:fieldType
select_multiple violationsviolationsViolations observednull
hiddenoverwateringOverwateringif(selected(${violations},'10'),1,0)esriFieldTypeInteger
hiddenbrokenpipeBroken Pipeif(selected(${violations},'20'),1,0)esriFieldTypeInteger
hiddenwrongtimeTimeif(selected(${violations},'30'),1,0)esriFieldTypeInteger
hiddenwrongdayDayif(selected(${violations},'40'),1,0)esriFieldTypeInteger
hiddenwaterfeatureWater Featureif(selected(${violations},'50'),1,0)esriFieldTypeInteger

 

As I indicated before, the output of the selected() function is a boolean. That is, either true or false. In my example, I wanted to store numbers (0 and 1) so I can more easily count values later or use the data in Operations Dashboard. That is achieved by complementing the selected() function with an if() statement. When selected() returns true, signifying that the choice was selected, I store a value of 1 and otherwise a 0.

 

The column bind:esri:fieldType plays an important role here too. For my select_multiple question I chose null. This indicates that the output of the question (the comma separated list of selected values) will not have a corresponding field in the target ArcGIS feature layer.  In other words, a null esri:fieldType says that we are not interested in persisting the output of that question. After all, the values in the hidden questions are really what we want to persist.

 

For the hidden questions, I explicitly set the esri:fieldType to esriFieldTypeInteger, because hidden questions by default are mapped to text fields. Since I know that my calculation is either going to output a 1 or a 0, and I want the output values as numbers, I set the esri:fieldType correspondingly.

 

To learn more about how XLSForm questions get mapped to Esri fields, check the Mapping XLSForm questions into ArcGIS Feature Service fields blog post.

  

 

There are some other tempting options for figuring out what choices have been selected in a list. I strongly recommend that you do not get tempted by them:

 

One bad habit is using a straight value comparison on select_one questions:

 

typenamelabelrelevant
select_one yes_norepair_neededAre repairs needed?
textrepairs_commentRepairs needed:${repair_needed}='yes'

 

Technically, it is going to work, but if you get used to that you may be led into this...

 

typenamelabelcalculationbind:esri:fieldType
select_multiple violationsviolationsViolations observednull
hiddenoverwateringOverwateringif(${violations}='10',1,0)esriFieldTypeInteger
hiddenbrokenpipeBroken Pipeif(${violations}='20',1,0)esriFieldTypeInteger
hiddenwrongtimeTimeif(${violations}='30',1,0)esriFieldTypeInteger

 

And that is definitively not going to work!  As you may remember, the output of a select_multiple is a comma separated list of values, so if someone selects more than one option in the violations question, your calculations will not work correctly. 

 

Another temptation, for select_multiple questions, is the use of contains(). For example:

 

typenamelabelcalculationbind:esri:fieldType
select_multiple violationsviolationsViolations observednull
hiddenoverwateringOverwateringif(contains(${violations},'10'),1,0)esriFieldTypeInteger
hiddenbrokenpipeBroken Pipeif(contains(${violations},'20'),1,0)esriFieldTypeInteger
hiddenwrongtimeTimeif(contains(${violations},'30'),1,0)esriFieldTypeInteger

 

The use of contains() could actually work in some cases, but it is not worth the risk.

 

The function selected() works beautifully for both select_multiple and select_one. Use it consistently if you want to check what options were selected in them.

 

 

count-selected(question)

 

The count-selected() function returns the number of selected choices in a select_multiple question.

 

typenamelabelconstraintconstraint_message
select_multiple toppingstoppingsSelect up to 2 toppingscount-selected(${toppings})<3Pick no more than 2!

 

In this example I built a constraint to prevent people from getting too greedy with pizza toppings. If the number of toppings selected is not below 3, a warning message will appear and the user will not be able to submit data.

 

You can also use count-selected() in a relevant statement, for example to present a comments field if any issues have been found during an inspection.

 

typenamelabelrelevant
select_multiple compsissuesCheck manhole components with issues
textcommentsEnter comments relevant for repair effortcount-selected(${components})>0

 

Pretty handy!

 

jr:choice-name(choice, 'question')

 

jr:choice-name() is useful when you need to retrieve the label of a list choice. The syntax goes as follows:

jr:choice-name(${activity},'${activity}')

In the example above, I am passing with the first parameter the user selection in the 'activity' question.  The second parameter is the question in the form using the list where the choice has been made.  Very often, the first and second parameters will reference the same XLSForm question, but note that the second parameter is enclosed with quotes, because it does not refer to the value (response) of the question, but to the actual question itself.

 

This is a very useful function in several scenarios:

  • When you want to include the label of a selected item in the payload of a webhook.
  • When you want to store the label of a selected item in your target feature layer.
  • When you want to display the selected item's label in a note, or use it within a label (dynamic label).

 

Take this example:

 

typenamelabelcalculation
select_one prioritypriorityPriority of the incident
hiddenpriority_labelRepairs needed:jr:choice-name(${priority},'${priority}')

 

The hidden question, obviously, will not be shown in the form to the user, but will keep the label of the selected choice in the priority question.  This value will be stored in the target feature layer of the survey, and will also be part of the payload sent in any webhooks you configure.

 

If working with multi-language surveys, the jr:choice-name() function will return the label in the language active when the user submits the data.

    

 

A common use case for jr:choice-name() is dynamic labels. Dynamic labels are discussed in more detail in the Understanding Dynamic Labels in Survey123 for ArcGIS blog post. In short, dynamic labels allow you to embed user responses and the result of calculations within labels in your survey. This is a pretty useful technique to help end users navigate along very large surveys for example, because you can bring more context to your questions, using prior responses.

 

typenamelabelcalculation
select_one prioritypriorityPriority of the incident
calculatepriori_labelPriority Labeljr:choice-name(${priority},'${priority}')
textcommentsDescribe why the priority is ${priori_label)

 

When using dynamic labels, you cannot include expressions within the label. You can only perform simple variable replacements. This is why in the example below I first add a calculate question to get the label, and then I embed the variable within the label of the comments question.  Just for clarity, the following will not work:

 

typenamelabel
select_one prioritypriorityPriority of the incident
textcommentsDescribe why the priority is jr:choice-name(${priority},'${priority}')

 

I always wonder why the jr:choice-name has the jr: prefix in front of it. I am sure there is an obscure explanation somewhere for that. I also wonder why if the function was named jr:choice-name instead of choice-label, since the output is the label, and not the name. Oh well... the function works nicely, so I would not dig to much into this mystery of the XLSForm specification.

 

selected-at(question, number)

 

The selected-at() function is unique to select_multiple questions. It is kind of an exotic function but I am including it for completeness. It returns the choice name selected at a specific index within the selection. This is best explained with pizza:

 

typenamelabelcalculation
select_multiple toppingstoppingsSelect your top 3 favorite toppings
hiddenmost_favoriteselected-at(${toppings},0)

 

Above, the selected-at() function is first passed the output of our toppings question. That is, a comma separated list with 3 pizza toppings selected by the user.  The second parameter indicates the zero-based index in that list for which we want to know the value.  Since we are passing 0, the output will be the pizza topping that the user selected in the first place. If we pass an index 2, it will give us the last topping that the user selected, assuming that we have limited the number of favorite toppings to 3.

 

This function is particularly useful when you want to know the exact order in which the user selected choices within a select_multiple question.  If the index you pass in the second parameter is not within the range of the user selection, the function returns an empty string. For example,  selected-at(${toppings},4) will return an empty string if the user only selected 3 items.

 

All XLSForm functions described in this document are compatible with both the Survey123 field app as well as with web forms.

  

[Last updated March 4, 2019]

 

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

 

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

 

An Overview of ArcGIS User Types

 

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

 

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

 

 

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

 

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

ArcGIS User Types from a Survey123 perspective.

 

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

 

Creator (formerly known as Level 2)

 

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


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

 

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

 

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

 

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

              

Field Worker

 

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

 

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

 

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

      

Editor

 

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

 

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

 

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

      

Viewer (formerly known as Level 1)

 

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

 

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

 

GIS Professional

 

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

 

Using Survey123 without an ArcGIS Account

 

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

 

Other important facts

 

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

 

Creator

Field

Worker

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

 

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

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

 

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

 

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

 

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

 

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

 

Summary

 

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

 

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

 

Overall, the new User Types include capabilities progressively:

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

 

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

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

 

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

 

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

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

 

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

 

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

 

 

Custom Themes in Web Designer

 

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

 

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

 

 

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

 

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

 

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

 

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

 

 

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

 

 

Character counter in text questions (Web and Field app)

 

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

 

 

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

 

 

Dynamic Question Labels

 

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

 

 

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

 

 

 

 

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

 

 

 

 

 

 

 

 

 

 

 

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

 

Main Fixes and Enhancements to Survey123 Website and Web App

 

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

 

Main Fixes and Enhancements to Survey123 Field App and Connect

 

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

 

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

 

 

What is coming next

 

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

 

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

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

 

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

 

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

 

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

 

 

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

 

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

 

 

Basic Layout Elements: Header, Description and Footer

 

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

 

 

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

 

Survey Header

 

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

 

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

 

 

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

    Always try to optimize the size of your images.

 

Survey Description

 

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

 

 

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

 

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

 

 

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

 

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

 

Survey Footer

 

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

 

 

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

 

Survey Themes

 

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

 

 

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

 

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

 

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

 

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

 

 

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

 

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

 

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

 

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

 

Input Text Color: This applies to all response text.

 

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

 

 

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

 

 

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

Thank You Screen

 

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

 

 

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

 

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

 

Miscellaneous tips and other things to keep in mind

 

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

 

 

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

 

 

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

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

 

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

 

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

 

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

 

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

 

 

The basics of dynamic labels in XLSForm

 

 

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

 

 

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

 

 

But this is not valid:

 

 

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

 

 

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

 

Working with different data types

 

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

 

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

 

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

 

 

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


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

 

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

 

Other things to consider

 

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

 

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

 

 

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

 

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

 

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

 

 

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