ODibie-esristaff

Leveraging Custom Form Report Templates in Survey123 for ArcGIS

Blog Post created by ODibie-esristaff Employee on Jul 26, 2017

As stated in the 2.3 release blog post, custom form report templates are now available in Survey123. This feature allows for exporting data submitted from Survey123 into printable documents. The highlight is that the look and feel of the output report can be easily customized to include headers, footers, external images, images from survey, the map from survey etc. Your hard copy survey report documents can be fully customized to meet your business needs.

 

This feature is now in Beta and as such there are some limitations around this functionality, but given how important this is to many of you we wanted to share it with you early.

 

In a nutshell, Custom Form Report Templates are authored in Microsoft Word, your templates will include banners, tables, text etc. but also placeholders with specific syntax that our Survey123 reporting engine understands.  The templates are uploaded and associated to your survey to define what the report(s) should look like.  When you want a report, Survey123 will replace your placeholders with real data and you will get a nice printable document back.  It is a simple approach, yet very powerful!

 

I am going to assume that you already have surveys published, and lots of data in them… so let’s get started!

 

Getting Started

 

In the Survey123 website, open the Data tab for a survey you own. 

 

 

 

Next, select a row from the table, and then select the “Custom Print (Beta)” option by clicking on the pen icon.

 

 

Now , click on the “Upload New Template” button

 

 

This dialog describes in detail what placeholders you need to insert into your Word document.  Note that the placeholders are unique to each survey. To make things easier, you can even click the link in blue titled “Click here to see an example.” to download sample template associated to survey. That is often the best starting point.

 

 

 

Note that you will be able to handle all question types including images and repeats.  Once you are happy with your template, upload it so you can use it later.  You can associate more than one template with every survey.

 

Learning by example and some additional tips

 

I will get into the specifics using the Water Violation Report survey which is available in the community gallery of Survey123 connect.

 

Here is a screenshot of the report template I created and the result I got after using it:

 

 

As shown in the template above, you can use expressions to return survey results. The syntax to access the data related to a question is ${fieldname} or ${%fieldname} when working with images (signatures, photos, maps).  

 

 

 

Tip 1: Check the help!

 

To learn more about the different formats for which a question type may be returned, click on the Show more options button as shown in the screenshot below. This option will only be available for question types with multiple return formats.

 

 

At this point, I will show you how to work with several question types including images, repeats, select_multiple, geopoint etc.

 

Tip 2: Images

 

For all images captured, the expression to return an image is ${%fieldname|size:460:0} – this expression will return an image with a width of 460px while persevering the aspect ratio. There are several other formats for which you can return an image- you can view all possible formats by clicking on the “Show more options” button on an image question. A screenshot showing all possible return formats for an image question is shown below. The image question is from the water violation report survey and the field name is violationphoto.

 

 

 

Tip 3: Maps

 

For all geopoint questions, the standard expression to return the map is ${%fieldname}- this expression will return a map with a standard size. You may return the longitude value, or latitude value using the expression shown in the screenshot below. The geopoint question is from the water violation report survey and the field name is violationlocation.

 

 

 

Tip 4: Formatting dates

 

For a dateTime question, the expression to return date and time is ${field_name|format: ’MM/DD/YYYY HH:MM:SS’}.

 

Tip 5: Working with multiple choice questions

 

For all Select_multiple questions, the expression to return the result is ${field_name}- this will return all selections made. A screenshot showing all possible return formats for a select_multiple question is shown below. The select_multiple question is from the water violation report survey and the field name is violationtype.

 

 

 

 

Tip 6: Working with Repeats

 

For a repeat, the expression ${#repeatname} indicates the beginning of the repeated area while the expression ${/repeatname} indicates the end of the repeated area. Put all the repeated questions & expressions between the two tags. If you want to print repeated records within a table, put the expression ${#repeatname} in the first cell of the repeated section and the expression ${/repeatname} in the last cell of the repeated section. Please note that repeatname is a placeholder for the name of the repeat.

 

Limitations on custom form report templates:

 

  • At this point, it is not possible to define the zoom level of your map through your template. However, as a workaround, you can zoom in the report preview in the Survey123 website and that will set the zoom level when you print. You can specify the web map used and the scale through the mapSettings property: ${location|mapSettings:"<web map ID>":<scale>}
    ${location|mapSettings:"10df2279f9684e4a9f6a7f08febac2a9":264800}
  • Only authors of a form can edit a template. This is more by-design than a limitation, but I thought I should make you aware
  • When the Individual Response tab is accessed by selecting a feature point on the map, a “hanging issue” arises when custom printing. The bug associated with this issue is currently being worked on.
  • Currently, you can only print individual records, but we are working on adding batch printing to the custom form template feature. With version 3.0, batch printing was introduced.
  • The function to create reports is only available from the website, but we plan on making it available through our Survey123 REST API so it can be invoked from the Survey123 apps as well as programmatically.
  • For on-premises support (when working with your ArcGIS Enterprise Portal):
    • The custom form report feature only works in ArcGIS Enterprise Portal (10.5) and above
    • Photos submitted to image questions will not work
    •  The ArcGIS Enterprise must be visible from the Internet
    •  IWA authentication is not supported

 

Summary

 

 

 We're really excited about this new feature because we believe it will meet the needs of our users in the following ways.

  • Creating backups of survey submissions.
  • Creating beautiful forms that give more context to survey data.

 

This feature is still in Beta which means its functionality will only get better. Now go use the Custom Report Template feature and let us know if you have any suggestions on possible improvements.

Outcomes