Survey123 Tricks of the Trade: Lines and Polygons
Starting with version 3.6, Survey123 supports working with line and polygon GIS features within your smart forms. There are many common scenarios for creating new, or working with existing, line and polygon GIS features in Survey123. For example:
- To support a noxious weed control program, you need a form to report areas where certain chemicals are being applied. You will want your form to include a question for users to delineate the exact area (polygon) where treatment occurred.
- You want to create a digital form following the SCAT methodology for assessing the impact of an oil spill along a shoreline. Your form must be able to let users highlight the segment (line) of the shoreline, or path, that was assessed.
- Let's pretend you want to expedite the completion of ATC building inspection forms against an existing collection of building GIS features. In this case, you will want users to open an inspection form for the selected building (polygon) and let them complete all other details.
This blog describes how you can add support for line and polygon GIS features in your Survey123 smart forms using Survey123 Connect and XLSForm. If you are not familiar with Survey123 Connect and XLSForm, please have a look at our Survey123 video tutorials, our XLSForm essentials—Survey123 for ArcGIS | ArcGIS help topic, or the Survey Customers to Gain Marketing Insight | Learn ArcGIS Learn lesson.
Support for configuring map questions in the Survey123 web designer to capture line and polygons is planned for a future release.
The Basics
The basics: geoshape and geotrace in Survey123 Connect
Hopefully by now you are familiar with the XLSForm geopoint question type. It allows you to bring a map question into your survey, so end users can define a point location of interest as part of your form. The geotrace and geoshape XLSForm question types will also be shown as a map within your form, allowing users to work with line and polygon shapes respectively.
To get started, I suggest you build a new test survey with Survey123 Connect and add the following questions:
| type | name | label |
|---|---|---|
| date | treatment_date | Treatment Date |
| geoshape | treatment_area | Treatment Area |
If the geoshape question does not render correctly when previewing your survey, make sure you download and install the latest version of Survey123 Connect. Geoshape and geotrace questions are only supported with version 3.6 and above.
Next, publish your survey to test your geoshape question within the Survey123 field app or web app. If using the field app, make sure you have version 3.6 or later installed on your device. You should be able to delineate a treatment area and submit. Using the Survey123 website Data tab, you will be able to look at your newly created features.
If you attempt to use geoshape or geotrace questions in forms authored prior to 3.6, keep in mind that the geoshape and geotrace options will not show in type column choice list. If you want to make these new question types appear in your old form, have a look at the https://community.esri.com/groups/survey123/blog/2019/09/15/survey123-tricks-of-the-trade-microsoft-... blog post.
The basics: geoshape and geotrace questions in the Survey123 apps
You can use geoshape and geotrace questions in both the Survey123 field app and web app. The user experience in the native app and web browser are very similar: A map is presented to the end user with tools to sketch or digitize the corresponding shape (line or polygon).
Here is what using a geoshape question looks like from a web browser (Survey123 web app):
And here is the experience for capturing a line in the Survey123 field app using a geotrace question:
You will notice that the map control shows an info bar describing the length and area of the shape digitized. The units in this info bar are set by your device locale. If your locale is set to the United States, imperial units will be used. Otherwise, metric units will be shown.
The basics: Looking at captured data in the Survey123 website
You can view and perform QA/QC operations on all Survey123 captured data using the Survey123 website. Through the Data tab you can visualize data captured through the geotrace and geoshape question types in a map and individual response views.
You can also bring your line and polygon data into your own custom Survey123 feature reports.
Beyond the basics
Adding multiple geo type questions in a survey
Values for geo type questions (geopoint, geoshape, geotrace) are stored in the SHAPE column of your surveys feature layer. The ArcGIS geodatabase model only allows for one single SHAPE (geometry) column per feature layer, so this restricts the number of geo questions you can add to a survey to one: either one geopoint, or one geoshape or one geotrace question. The only exception is when you add repeats to your survey: each of your repeats can also include its own geo question.
For example, with our SCAT survey, lets pretend you want to use a geotrace question to document the segment of shoreline surveyed and then you want to flag locations where severe oil damage has been found. You could create a survey as follows:
| type | name | label |
|---|---|---|
| date | survey_date | Survey Date |
| geotrace | shoreline_surveyed | Shoreline segment surveyed |
| begin repeat | severe_damage | Severe damage observations |
| geopoint | issue_location | Location of damage |
| text | issue_comments | Comments |
| image | issue_photo | Photo |
| end repeat |
Note that the survey includes two geo questions: one in the main body of the survey, and one inside a repeat. This is allowed because questions within the repeat will be stored in a separate (and related) layer.
Input Methods: vertex vs sketch
When using geoshape or geotrace questions, you can optionally define the input method of your map.That is, you can control which style of tools will be presented in the map to help users delineate a shape. You can do this through the body::esri:style column in the survey XLSForm sheet.
The map supports to input methods:
- sketch: Enables drawing tools in the map. This is meant to help users quickly draw, or sketch, a line or polygon in one single take.
- vertex: This input method is more appropriate when you want users to digitize shapes more accurately. The vertex input method provides tools to add vertices one at at time by:
- Tapping on the map.
- Centering the map at a target location.
- Getting the coordinates through the built-in or external GPS.
The vertex method also lets users switch between edit and navigation modes, update and delete existing vertices.
You will want to experience on your own each of these two input methods and decide what is best for your particular workflow. In some cases you want a simple and quick way for people to sketch a geometry. In others you want to give them more control, even if that implies some initial trial and error with the tools until they get familiar with them.
The following example shows how you can set the vertex input method using the body::esri:style column:
| type | name | label | body::esri:style |
|---|---|---|---|
| date | treatment_date | Treatment Date | |
| geoshape | treatment_area | Treatment Area | method=vertex |
XLSForm functions: Calculating perimeter, area and length.
Along with the geotrace and geoshape question types, we have also extended XLSForm support, so you can create expressions to work with these geometries. Two common functions we anticipate you using are area and length. Back to our noxious weed abatement scenario, the area function could be used to automatically compute the area treated.
| type | name | label | calculation | bind::esri:fieldType |
|---|---|---|---|---|
| date | treatment_date | Treatment Date | ||
| geoshape | treatment_area | Treatment Area | ||
| hidden | treatment_sqm | Calculated Area in sqm | area(${treatment_area}) | esriFieldTypeDouble |
Note that in the example above, the calculated area is stored in a hidden field. This is optional, as you could be using a decimal question type instead. You can use a hidden question to keep the output value without presenting it to the end user. Hidden questions are mapped automatically to text questions in the geodatabase but since I want to store the area as a number, I added esriFieldTypeDouble value to the bind:esriFieldType XLSForm column.
The output of the distance and area functions is always in meters (or square meters), but you can easily apply conversions and rounding as needed.
| round(area(${treatment_area}),2) | Extracts the area in square meters of a geoshape and rounds the value to 2 decimals |
| distance(${treatment_area}) | Calculates the perimeter of a geoshape or the length of a geotrace. Output in meters. |
| distance(${shoreline_surveyed}) div 1000 | Gets the distance of a geotrace geomery in meters and divides by 1000 to get the distance in kilometers. |
| distance(${pipe_to_install}) * ${price_per_meter} | Estimates the installation cost of a pipe. |
The distance and area functions can also be used in other contexts. In the example below, we use the function to control if a particular question will be required or not. If the area treated is less than 100 square meters, then a justification text question will be shown, but it will not be compulsory. If the area is larger than 100 square meters, then a justification must be provided.
| type | name | label | required |
|---|---|---|---|
| date | treatment_date | Treatment Date | |
| geoshape | treatment_area | Treatment Area | |
| text | justification | Justification | area(${treatment_area})>100 |
More on XLSForm functions: repeats, sum and count.
With some creative thinking, there are some more advanced XLSForm techniques you could leverage when working with geotrace and geoshape questions. In the next example, a repeat is used to capture the exact location of electric poles. For each pole, type, observations and some GPS metadata for the pole location is collected. Using the sum function, a line feature representing the electric line joining all the poles is automatically generated.
| type | name | label | calculation |
|---|---|---|---|
| date | survey_date | Survey Date | |
| begin repeat | poles | Poles | |
| geopoint | pole_location | Pole Location | |
| hidden | pole_ha | Accuracy (m) | pulldata("@geopoint", ${location},"horizontalAccuracy") |
| select_one types | pole_type | Pole Type | |
| text | pole_obs | Observations | |
| end repeat | |||
| geotrace | pole_line | Electric Line | sum(${pole_location}) |
| hidden | pole_count | # Poles in Line | count(${pole_location}) |
While not included in the example above, it would make sense to set the geotrace question as readonly, to ensure that the electric line is truly following all the pole locations within the repeat. Otherwise the end user could open the map for the pole_line question and manually alter its geometry. Depending on your workflow, the desired behavior is up to you and can be configured either way.
Geotrace and geoshape in the Survey123 field app Inbox
So far, we have explored how to use the geotrace and geoshape questions to enter new line and polygon features. In some scenarios however you may want to simply reference existing line and polygon features and help drive data capture workflows within Survey123.
A classic example is that of building inspections. For example if you need to score a set of buildings to assess fire risk, or to evaluate damage after a hurricane or earthquake. Your intent in this scenario is not to create or update the polygon footprints. Instead, what you want is to update attributes in these existing buildings based on your own on-site assessment.
In this case, you will want to build your survey on top of the existing building (polygon) layer. The geoshape question will help you drive the whole user experience in the Survey123 field app, allowing the selection a building from the Inbox map and opening the assessment form for the selected building right away. When submitting your survey, the polygon shape of the building will remain untouched, but the attributes reflecting the assessment will change.
The next animation shows the whole workflow: 1) Bring features (polygons) into the Inbox, 2) Select a feature from the map to open its corresponding form, and 3) Submit changes to update the feature:
If this pattern interests you, keep in mind that the Survey123 field app Inbox is meant to work with a small number of features. When enabling the Inbox in Connect, I strongly recommend you set a filter to query and filter the features based on attributes (buildings pending inspection, or buildings assigned to the logged-in user, for example). From a practical perspective, with 3.6, you will not want to load more than 200 or 300 surveys in the Inbox. You will see some new performance improvements for the Inbox coming in future releases, but as of version 3.6, you will need to keep the number of records loading in the Inbox as low as possible.
Performance improvements to the Inbox are coming with version 3.7. As of 3.6, keep the number of records in the Inbox under a couple of hundred by applying spatial and attribute queries to the Inbox in Survey123 Connect.
For a more detailed description on the Inbox, check our Prepare for editing existing survey data—Survey123 for ArcGIS | ArcGIS help topic.
Including lines and polygons in your Feature Reports
Using Survey123 Feature Reports you can create high quality printable documents for any of your Survey123 records. Thehttps://community.esri.com/groups/survey123/blog/2019/07/23/understanding-survey123-feature-reports blog post describes in more detail how to use this feature. The Feature Report syntax has been extended to allow you to dynamically include in your report the perimeter and length and area properties of a survey record. For example:
- ${segment_surveyed | getValue:"length":"meters":"geodesic"}
- ${treatment_area} | getValue:"area":"hectares":"geodesic"}
The length property returns the length of a line and the perimeter of a polygon. The area property only applies to polygon features. The length unit options are feet, kilometers, meters, miles, nautical-miles and yards, for length. For area: acres, hectares, square-miles, square-kilometers, square-meters, square-feet and square-yards. The last property defines if you want to get the planar or geodesic measurement. If your data is in WGS 84 Web Mercator Auxiliary Sphere, which is going to be the case with Survey123 unless you set your own custom projection on the data, you should always use geodesic. If your data uses a local projection, typically planar will be the best option.