Survey123 Tricks of the Trade: Lines and Polygons

14462
25
09-26-2019 04:12 PM
Esri Frequent Contributor
11 25 14.5K

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:

typenamelabel
datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment 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:

typenamelabel
datesurvey_dateSurvey Date
geotraceshoreline_surveyedShoreline segment surveyed
begin repeatsevere_damageSevere damage observations
geopointissue_locationLocation of damage
textissue_commentsComments
imageissue_photoPhoto
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:

typenamelabelbody::esri:style
datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Areamethod=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.

typenamelabelcalculationbind::esri:fieldType
datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Area
hiddentreatment_sqmCalculated Area in sqmarea(${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 1000Gets 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.

typenamelabelrequired
datetreatment_dateTreatment Date
geoshapetreatment_areaTreatment Area
textjustificationJustificationarea(${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.

typenamelabelcalculation
datesurvey_dateSurvey Date
begin repeatpolesPoles
geopointpole_locationPole Location
hiddenpole_haAccuracy (m)pulldata("@geopoint", ${location},"horizontalAccuracy")
select_one typespole_typePole Type
textpole_obsObservations
end repeat
geotracepole_lineElectric Linesum(${pole_location})
hiddenpole_count# Poles in Linecount(${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.

25 Comments
Occasional Contributor III

I just tried out the "vertex" method, at some point in a future release, will it be possible to "stream" a feature through the "vertex" method? By this I mean in the way you can stream a feature while walking and using Collector.

Overall, this is very exciting, however the current method of adding a vertex at your location as you walk requires presence of mind to pause at corners and press the button. Also, I think that for people working in the woods, the ability to stream might be easier than having to keep the screen turned on so you can press the button to add a new vertex.

New Contributor

This is so exciting. Thanks for all of the hard work Ismael Chivite! I noticed you said it is coming to web soon - and I can't wait for Australian schools to use this awesome feature. Is there an estimated time this feature will be available?

Esri Frequent Contributor

Hi Erica. Adding support for streaming is something we can consider. I encourage you to submit an official Enhancement Request via Esri Technical Support or to post a new ArcGIS Idea.

One question on streaming: for your use case, would it be sufficient to keep streaming active until you either stop streaming in the map toolbar or close the map?  Or do you need to keep streaming while you work in other questions within your form.  In the last case, streaming would only stop if you go back to the map question to stop streaming or if you leave the form to save it as a draft or send it.

Esri Frequent Contributor

Hi Skye Rodgers‌, kudos to the entire Survey123 team and the many Survey123 Early Adopters that have helped us get this out through extensive Beta testing. Ismael just happened to be the messenger here. We really hope you can get good use of this feature.  As soon as we have Lines/Polygons in Survey123 Web Designer available for Beta testing we will make a note in this GeoNet Group. If everything goes according to plan we should have Designer ready in early 2020 but timing can change.  Colleagues in Education from the US have also indicated that they want this feature in Designer. Really looking forward to have you all engaged so we can let the kids show us all what is possible with Survey123!

Occasional Contributor III

Hi Ismael,

It would be more than sufficient, for my use case, to keep streaming active until I stopped streaming in the map toolbar. I'm picturing something similar to the way streaming is used within Collector. I don't foresee, for my particular workflow, the need to stream a feature and then continue answering other questions within my survey.

I will submit an Enhancement Request for this.

Thank you to you and the Survey123 team for all the amazing work on this!

Erica

New Contributor

Yes all of the team are my heroes! Excellent, I would love to test it out. Having the feature available in Designer would make it easily accessible to all of our Survey123 loving students here and I can't wait to see the way it transforms their data collection! Kudos Sir!

New Contributor II

I agree that streaming would be very useful.  I will be sure to vote for it in ArcGIS Ideas.  Thanks for posting this question.

Occasional Contributor III

Hi Reed,

I did not post an Idea, however I did log an official enhancement request through technical support. The enhancement request is - ENH-000125836.

Best,

Erica

New Contributor II

I added an ArcGIS idea here: .

Reed

New Contributor III

Ismael Chivite‌ - Would you mind adding another section to your (awesome) blog post that describes how we can populate a geoshape using URL parameters (such as launching the survey form from a web map with taxlots)?  

I had this working well in 3.5, but it now appears broken.  I'm going to go make a post in the EAC about this as well. 

New Contributor

Hi, When creating the geotrace and geoshape functions does it create a polygon shp file that can be exported? 

Esri Esteemed Contributor

Hi,

Geoshape will create polygon features; Geotrace will create line features.  There is an issue in exporting Survey123 data to shapefiles (BUG-000115279); that will be addressed later this year with the next ArcGIS Online & Survey123 updates.

Regular Contributor

Hey Ismael Chivite‌ et. al.

I am currently in the process of updating an old survey which was created a couple of years ago, to now use geoshape instead of geopoint, and I have hit a hurdle.

With geopoint I used to be able to calculate Lat/Long and also reverse geocode addresses. Can this be done with the newer geoshape or geotrace?

These are the existing fields that no longer work now I have a geoshape field instead of geopoint (and yes I have tried converting @geopoint to be @geoshape, this had no effect). These questions appear blank since updating.

pulldata("@geopoint",${location},"reversegeocode.location.x")
pulldata("@geopoint",${location},"reversegeocode.location.y")
pulldata("@geopoint",${location},"reversegeocode.address.Match_addr")

Any ideas if I can still calculate these coordinates and address using the new question type?

Esri Contributor

Hi Ben,

Reverse geocoding works by comparing a Lat/Long pair to known address locations and returning the best candidates for a match so it requires a point location as the input. This is not going to work with a line or polygon (geotrace or geoshape) input without an intermediate step to extract the Lat/Long of one of the vertices. 

We would need to add the ability to pull the Lat/Long coordinate pairs from the geotrace and geoshape geometry (eg pulldata@geotrace or pulldata@geoshape). This would be a valid enhancement request if you'd like to submit it via support.esri.com?

Depending on the complexity of your lines/polygons, you may be able to capture these using repeated geopoints (see the 'Geotrace and Geoshape' sample available in Survey123 Connect). This way you still have a geopoint to use as the input for a reverse geocoding operation.

Brett

Regular Contributor

Thanks heaps for that info Brett, that workaround may be what I need to keep moving forward. 

I will look into it.

Just to confirm, you think I am best to request that enhancement via support.esri.com and not the ideas page?

Esri Contributor

Hi Ben,

That's right submitting an enhancement request via support.esri.com will give you and official enhancement (ENH) number to track the progress. Cases like this where you're wanting to enhance existing functionality are best submitted to support.esri.com, where as ideas for completely new functionality are best submitted to the ideas page.

Thanks,

Brett

Occasional Contributor III

Hi Ismael Chivite,

Just wondering in your electric poles / transmission lines example, how could junctions be handled, where one pole might act as a point for two transmission line segments?

Regards,

Craig

New Contributor

Good afternoon,

I was curious if it is possible to upgrade a older XLS form to the newer version so that I can add the Geoshape function. Is there a work around so that I can add this function into the form or will I have to rebuild the entire form?

Thanks,

Gregg

New Contributor

I figured out a work around, thank you! Ended up just pasting values and transferring files over to new survey and it worked.

Esri Contributor

Hi Gregg, you can just add the geoshape question to your old XLSForm. It will work if you're running a version of Survey123 / Connect that supports it (v3.6+).

Esri Contributor

Hi Ismael Chivite‌,
Is the sum function for generating lines from points supported in the Web App?

Cheers,

Chris

New Contributor

HiIsmael Chivite

I am working on a building inspection form and I would like the building shape to be populated in the Geoshape based on the building name selected from a drop down.  The form is setup to pull a number of fields from a CSV file and I can pull the vertex values to a text question with no issues. However when I try to pull the data directly to the geoshape question from the CSV or use a calculation to pull the data from the text question, I receive an error in Connect "java.lang.Number.Format.Exception: For input String..." 

I know the vertex information is in the correct format as the building will show up if I paste the coordinates in the default field. 

Am I missing a step that is needed to get the pull data function to work with geoshapes or is this not supported yet?

I know there is the option to launch from Collector but I would rather not require the teams to use another app if they don't need to.  I would consider using the Inbox method you outlined above but the inspectors need to collect photos and I don't see the repeat work around being a viable option for us.

Thanks

Ryan 

Esri Frequent Contributor

Hi Ryan McKenna‌ Can you send your CSV file to me?  ichivite@esri.com

New Contributor III

Hello, where can I find settings to change the units of perimeter and area which are displayed on the survey form while drawing polygon? I see on your pictures that you use kilometers, but I get miles and acres as default and want to change it to kilometers. I have searched different places but I cannot find any option to change it. Survey123 form was created using the Web Designer. 

Esri Contributor

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.

Does this help?