Skip navigation
All Places > Survey123 for ArcGIS > Blog > 2017 > October
2017

With the 2.4 release of Survey123 Connect, a null value is now supported in the bind::esri:fieldType column of an XLSFormWhen the field type is null, Survey123 Connect will not create a field when publishing.  I’d like to highlight 3 cases where this can really enhance your forms: 

  1. Intermediate Calculations 
  2. Multiple Geopoints 
  3. More easily match an existing feature services 

 

Intermediate Calculations 

When doing a set of complex calculations, it’s often easier to break out sub calculations into their own question to make them more manageable.  While this was easier for you as a survey author to manage, this meant that you would have these intermediate steps stored in the database.  By assigning these the null field type, we simplify the data being stored to only the final calculations. 

For example, this Excel sheet calculates the linear regression of three observations. This involves a number of intermediate calculations, beginning with calculating the mean value of X & Y and then the distance an observation is from the mean value. 

 

Multiple Geopoints 

Form with 2 points

Another popular request the null value solves is the ability to capture multiple locations in a form; one location can be stored as the geometry of the feature with the other points being stored in x & y fields. Note that as the survey submission needs to have a geometry, you must have 1 geopoint question not set to null.

 

An example where multiple geopoints are useful is when collecting the location of a culvert or other relatively straight linear asset.   

To store the point information, get started by creating 3 (or more) questions for each point after the first: 

  1. The geopoint question to record the value 
  2. Two decimal (or calculate/hidden) questions to store the points x and y values (add additional fields for z and accuracy, if desired) 

Set the field type to null for the geopoint and use the pulldata(‘@geopoint’) function to extract the value after the point is set.  Here's a basic sample with a start and end point. 

 

Matching an existing feature service 

While Survey123 can automatically create a form based on an existing feature service, it may not create the form you quite want.  For example, a field storing how long someone has lived at a place might be better shown on the form by asking when did they move in – the length of time can then be calculated.  By creating a separate question to be asked with the null field type, you can create some flexibility between what is asked and the data that gets stored. 

 

Have another use for the null field type? Share in the comments below! 

 

 

 

On occasion, you may want to limit the extent in which points can be input into a survey. This may be to simply validate the input data on initial entry, or to restrict input for functional requirements. In the attached survey, the extent has been limited to Ireland. In order to do this, there are a few things that have to be done.

 

1. Get Extent Values

 

A good way to do this is to go to your organisations settings. Go to your Organisation - Edit Settings - Map and click Choose Extent as below.

 

 

From there, you can a Draw an extent, and note down the Lat/Long values you will need to use in your survey. The values below correspond to the values used in the attached form, so you can directly replace them as necessary.

 

 

The alternative is to use the super-useful Super-Duper Extent Helper developed by Bradley Snider.

 

Image of Bradley Snider's Super-Duper Extent Helper

 

2. Setup Calculations in Survey123 Connect

 

There are various calculations you have to make in order to limit and input point to a particular extent, as below.

 

  • pulldata("@geopoint",${Location},"x")
    • This pulls the x attribute from the ${Location} geopoint question and stores it as a separate attribute
    • Further information on pulling data from geopoint questions can be found in this blog post
  • pulldata("@geopoint",${Location},"y")
    • This pulls the y attribute from the ${Location} geopoint question and stores it as a separate attribute
  • if((number(${XValue}) > -10.7) and (number(${XValue}) < -5.4), 1, 0)
    • This uses the if function in order to ensure the the x attribute returned from the pulldata function is between -10.7 and -5.4. If this is true, the value of this field is equal to 1, otherwise it is equal to 0
  • if((number(${YValue}) > 51.4) and (number(${YValue}) < 55.4), 1, 0)
    • This uses the if function in order to ensure the the y attribute returned from the pulldata function is between 51.4 and 55.4. If this is true, the value of this field is equal to 1, otherwise it is equal to 0
  • int(${ValidX}) + int(${ValidY})
    • This calculation adds the values of both if calculations together

 

3. Setup Constraint

 

This is ultimately what is used to check whether the point is within the specified extent. A message is returned to the user if it is not within the appropriate extent. In order for this to pass, it's value must equal 2 (i.e. the sum of both if statements). If it is not equal to 2, it means that either the x or y attributes, or both do not lie within the specified extent.

 

4. Hide and Don't Store Validation Calculations

 

In order to hide any validation calculations, we set the field types as hidden. We also use The Power of Nothing to ensure fields are not created to store the calculation results being used as part of the point validation (see bind::esri:fieldType column).

 

5. Add a Note when Outside of Extent

 

This will help notify the user that they are outside of the allowable extent. To do this, you add a note row, along with a label - not including a name here results in a field not being created in the Feature Layer for the note. Then specify a relevant calculation so that the warning message only gets displayed when the user is outside of the allowable extent.

 

See the completed form below (also attached):

 

typenamelabelconstraintconstraint_messagerelevantcalculationbind::esri:fieldType
geopointLocationSpecify Location
hiddenXValueX Co-Ordinatepulldata("@geopoint",${Location},"x")null
hiddenYValueY Co-Ordinatepulldata("@geopoint",${Location},"y")null
hiddenValidXX Within Rangeif((number(${XValue}) > -10.7) and (number(${XValue}) < -5.4), 1, 0)null
hiddenValidYY Within Rangeif((number(${YValue}) > 51.4) and (number(${YValue}) < 55.4), 1, 0)null
hiddenAllowedWithin Specified Extent?.=2Specified Location Outside of Extentint(${ValidX}) + int(${ValidY})null
note<b><center><font color="red">**** Specified Location Outside of Ireland ****</font></center></b>${Allowed} != 2

 

This is not currently supported in Web Forms because the pulldata() function is not supported when used against geopoint question (as documented here)

In this blog post I will describe how you can configure smart sketching in your surveys, step by step.  Smart Sketching was introduced in version 2.4 of Survey123 and allows you to embed questions in your form where users can draw or sketch. Depending on how you configure your survey, you can let users sketch on top of an empty canvas, on top of predefined diagrams, and even on top of photos.

 

There are multiple scenarios where sketching can be handy:

 

  • When performing inspections, a user can take a photo of an asset and sketch on it to highlight issues. Alternatively, the inspector could annotate over a diagram representing the asset. 
  • When submitting a traffic accident report, a police officer can use the sketch capabilities in Survey123 to illustrate the positions of the vehicles involved and skid marks.
  • Free-form sketches in Survey123 allow conservationists to highlight certain features/marks of a whale which can be used later to track the individual specimen across different observation reports.

 

Sketches and annotated images and photos are automatically persisted by Survey123 as a geodatabase attachment, ensuring you can access them from other ArcGIS tools.

 

 

 

 

 

For the instructions below, some familiarity with XLSForms and Survey123 Connect for ArcGIS is assumed. A series of video-tutorials on XLSForms are available in our YouTube Survey123 playlist.

              

 

The Basics: Draw and Annotate appearances

 

In order to add sketching capabilities into your own survey, you need to use the draw or annotate appearances on survey questions of type image.  It is easier than it sounds: In your XLSFile, using Survey123 Connect, simply add a question of type image, and then set the value of its appearance column to either draw or annotate.

 

In Survey123 Connect, create a New Survey using the Advanced template and add a question as follows:

 

typenamelabelappearance
imageaccident_diagramVehicle Collision Diagramdraw

 

Now use the survey preview in Survey123 Connect to exercise the sketching widget.

 

The draw appearance enables a full screen drawing pad where you can use pencils of multiple colors and thickness for your sketches. The draw appearance is ideal when you want end users to draw an idea on top of a white canvas. Note that you can:

 

  • Add an arrow by drawing a straight line.
  • Add text by tapping on the screen.
  • Add shapes of any form through free-drawing. Circles and rectangles will be automatically smoothed for you.

 

The annotate appearance is similar to draw, except that it allows the user to set the background of the canvas with a photo.   Use the annotate appearance when you expect users to first take a photo of something, and then sketch on top of it.  The same sketching tools available in the draw appearance are also available for annotate.

 

Advanced Techniques: Using Defaults and Calculations

 

Rather than starting with an empty canvas, you can configure your survey to present users with a custom background image in the sketching pad.  Before you can reference your image, you must copy it into the media folder of your survey directory.   In Survey123 Connect for ArcGIS, while looking at the preview of your survey, click on the 'Open survey content folder' button.

 

 

Once the survey folder is open, look for the media directory and copy all your images in there.  To play safe, copy images in either .png or .jpg format only.  Be considerate with the size of the images: You want images big enough to look good in phones and tablets, but try to reduce their size as much as possible or otherwise the initial download of your survey into devices will take longer than usual.

 

Most tablets and phones will do pretty well with images smaller than 1920x1080 pixels.

Now that your images are in the media folder. You can reference them in the survey:

 

  • Default: If you always want to display the same background image in the sketching pad, reference your image using the default column. You do not need to enclose the name of your file in quotes, but you will want to make sure you include both the name and file extension. In the next example, the image coyote.png will always be used as background for the draw widget.

 

typenamelabeldefaultappearance
imageanimal_observationsHighlight  where animal was hurtcoyote.pngdraw

 

  • Calculation: If you want to dynamically switch the background image based on previous responses in your survey, use the calculation column.  A typical scenario for this is that where you present users with a choice question and then you switch the background according to user selection.  Say for example, you first let user select the type of tower inspection being inspected. The drawing canvas background will change depending on the type.

 

Lets do this step by step:

 

  1. Ensure you have all your images in the media folder.  For simplicity, make sure the extension for all the images is the same. That is, make sure they are either all .png or .jpg.
  2. Create a list in the choices worksheet where the value of the name column for choices in your list matches the name of filenames in the media folder.
  3. Set the expression in the calculation column of your draw or annotate question as:

 

concat(${ChoiceQuestion},'.png')

 

In the example above, I assume that your choice question is a select_one type of question named ChoiceQuestion. I also assume that your images are in .png format. Remember that all the concat() function does is to concatenate the value of the selected choice in your select_one question, with the .png extension.

 

You could certainly get more fancy with the calculation, but the heart of how this is done is described above.

 

It is always easier to learn with an actual example. The Transmission Tower example is available under the Community category in Survey123 Connect:

  • Log into Survey123 Connect
  • Click on New Survey
  • Select the Community category and then choose the Transmission Tower sample

 

 

A few extra tips and things you should know

 

  • All sketches will be saved as geodatabase attachments once submitted to ArcGIS. This means that you can always easily access sketches associated with a submitted feature.
  • If you use the default or calculation columns to predefine the background of the drawing canvas, keep in mind that iOS (iPhones and iPads). You must reference images making sure that the capitalization in your XLSForm is exactly as in the filenames.
  • Once the user creates the sketch, a preview of the sketch will be made available in the survey. Note that at that point the user can change the name of the image.  Calculating the name of the image filename is not possible at this time.
  • Support for defaults and calculations on draw and annotate images is missing in the WebForm. Only the Survey123 field app will honor your defaults and calculations.
  • [Fixed as of 2.6] As of version 2.4, it  is not possible to let users choose a background for the drawing canvas using an existing image from the photo gallery. This is something that we want to add in the future. As of 2.4, you can only use images from the media folder or let users take a photo on the spot and use it as background.
  • If you are using the Inbox to edit existing features, be aware that as of 2.4 the Inbox does not support images of any type (signatures, photos, drawings or annotated images).
  • If you bring a photo from your gallery or camera into the Draw and Annotate widgets, the EXIF data in your image will be stripped out and lost once submitted  to ArcGIS.

 

As usual, we are eager to hear your feedback. This is a new feature and would love to hear your feedback so we can take next steps with it.

 

Enjoy!