Working with Z values in Survey123

Blog Post created by ichivite-esristaff Employee on Nov 28, 2016

In this blog post I will describe how you can handle elevation values (Zs) in Survey123 for ArcGIS.  Typically, geopoint questions in your survey will always work in 2D. That is, only latitude and longitude will be stored.  While not obvious, it is actually fairly easy to configure your surveys to work with 3D geopoints.


Enabling Z-enabled feature services for your survey


Every survey you publish to ArcGIS is made out of two items: a Form and a Feature service item. The Form defines the questions in your survey, as well as the validation logic, look and feel etc. The Feature service is where all the answers to your questions go.  By default, when you publish your survey, a 2D Feature service is created, not allowing the storage of Z values.  To ensure your Feature service is Z-enabled you must explicitly flag your geopoint question as esriFieldTypePointZ in the bind::esri:fieldType column of your XLSForm. This will look something like this:


geopointLocationAsset LocationesriFieldTypePointZ
textAssetIDAsset ID
dateLastInspLast Inspected On


The bind::esri:fieldType column is used when you want to have full control over the Esri field types to be used in the geodatabase. Survey123 will do its best mapping XLSForm question types into Esri field types, but sometimes, like in this case, you may want to tweak things a bit. The Mapping XLSForm questions into ArcGIS Feature Service fields blog post describes in more detail other  reasons why you may want to use the bind::esri:fieldType column.


Once your esri:fieldType is set as above, a 3D Feature service will be created on your behalf. Not totally obvious, but easy once you know the trick. Isn't?


Capturing Z values in the Survey123 app


Capturing Z values in the Survey123 app is also pretty straight-forward but it is important to  understand a couple of things.  First of all, most consumer smartphones and tablets will provide a location including an elevation value, which Survey123 will automatically use. Like with any consumer device with an integrated GNSS receiver, the accuracy of the location coordinates -including the elevation- is not expected to give you a level of accuracy beyond a few meters at best. Properly using an external GNSS receiver along with your device will in most cases improve the location values passed into Survey123 for ArcGIS and provide more consistency to the measurements.  In the event that the device does not provide elevation values, Survey123 will automatically set the Z value to zero (0).


Photo courtesy of Leica Geosistems


Using an external GNSS receiver in combination with Survey123 will greatly improve  the accuracy of elevation values captured. In this photo, Survey123 is being used with a high precision GNSS receiver from Leica Geosystems.


The elevation values, as described above, are  typically provided by your own device. However, if the field user modifies the provided location by tapping on the geopoint map widget and setting a new location manually, the Z values from your device will be cleared allowing the field user to set the elevation value manually.   If no manual Z is set, again Survey123 will reset to the value to zero (0).



Managing Z values


Elevation values are always kept in the Z coordinate of the points you capture. In Esri jargon, you will be working with a 3D point feature, which tools like ArcGIS Pro, ArcGIS Earth and Web AppBuilder understand.  In 3D features, the elevation values are kept in binary format within the geometry field of your feature service. Now, very often you will also want to store the Z value as an attribute of the feature. Having a column in your feature for your elevation values allows you to more easily access Zs in non Esri tools. For example, you can export  your survey data to a CSV table and get the Z values shown in a column. Having elevation values as numeric values in an attribute is also useful within ArcGIS in cases where you want to perform QA/QC workflows or want to query and visualize these values.


To extract the Z value into an attribute of your feature, you will want to create a new question in your survey and populate it with an expression in the calculation column. The next table describes an example of how to do this:


hiddenLatitudeLatitudepulldata("@geopoint", ${location}, "y")esriFieldTypeDouble
hiddenLongitudeLongitudepulldata("@geopoint", ${location}, "x")esriFieldTypeDouble
hiddenElevationElevationpulldata("@geopoint", ${location}, "z")esriFieldTypeDouble


To learn more about the pulldata function, you can read this blog post: Pulling data from geopoint questions  Note that the pulldata function can be used to simply extract the Z value into a specific column that you define, but you can also use it to perform data validation right from the Survey123 app.  You may for example write an expression to warn the field user if a particular crop is reported at an elevation where we know that it does not grow naturally.