Understanding Survey123 Feature Reports
Survey123 includes out of the box functionality to help you generate high quality documents out of submitted surveys. This is extremely useful when you need to present your survey123 data following strict formatting guidelines, for example when mimicking legacy paper forms or to comply with legal documents.
In this blog post I will describe how you can configure this feature report functionality against your own surveys, defining the content and look & feel of your own feature reports.
A bit of context: Survey123 feature reports vs summary reports
Before we get into the details, I want to provide some context up-front about what exactly I mean by feature reports.
Generally, the word report is associated with summary reports where data is aggregated to help identify trends. Survey123 includes great summary report capabilities, but these are not the focus here. This discussion is about feature reports. A feature report presents data from a single survey record. If you are interested in summary reports, check this blog.
Say for example you use Survey123 to support asset inspections and you want to generate one document, as proof-of-work, for each inspection performed. For that you use feature reports. Say Survey123 is used to document city code violations and you want to generate and mail individual tickets for violations observed... For that you use feature reports too. The purpose of a feature report is not to aggregate data across multiple surveys. The purpose is to represent the data a single submitted survey.
In a way, the Survey123 feature report capability is about bringing your survey data back into a form format, except that in this case, you want the form to present data, as opposed to using the form to collect data.
Creating a feature report from the Survey123 website
The following animation shows how you would generate a report from the Survey123 website. Note that the feature report is triggered from the Data tab in the Survey123 website. The Data tab is designed to help you explore and drill down into individual survey records (features). Using the map or the table views you can select a particular survey record and generate a report for it. That is, of course, assuming that you have previously configured your survey with a template. You will learn shortly about creating your own report templates.
Feature reports can be generated for one or multiple records at once. You can choose if you want your reports in separate files (one PDF document per feature) or merged (may feature reports in a single PDF file).
Creating a Sample Report Template
To get started on your own, you need first a report template to create feature reports. This is how you create one:
- In the Survey123 website, go to the Data tab of your survey.
- Select one record from the table or the map.
- Click on Feature Report in the top bar
- In the Feature Report panel that just open on the left side, click on the Manage Templates link.
- Create a new sample template as shown in the animation below and close the dialog.
- Generate a report.
Now that you have a template, click on the Generate Report button and open the resulting output document. The sample template is generated automatically, and as such, will not create the most beautiful results, but it is a great starting point for you to refine it.
Feature report templates are stored along with your survey in your ArcGIS account. If you navigate to the directory of your survey within your ArcGIS content, you will find your feature report Microsoft Word template in there. You can associate one or more templates with a single survey.
All templates you associate with your survey will be available to any user that has Viewer access to your survey. That is, anyone who has been granted Viewer access to your survey, will also be able to generate reports using the templates you define for that survey.
Getting started with custom feature report templates
Going back to the Manage Templates link you will be able to download the sample template to your computer. Once you download the template, you will realize that it is a simple Microsoft Word document. This is what the sample template for my Water Violation v2 survey looks like:
You can see right away how templates work: A series of placeholders for questions in your form are included in the template. The most basic syntax for the placeholders looks like ${question_name}. All you need to do is to make your Microsoft Word template document look the way you want and insert the Survey123 feature report placeholders accordingly.
Once you are happy with your report template, you can upload it using the Manage Templates link. Until you get familiar with the placeholder syntax, I suggest you start easy: Start by rearranging text within the document and copying and pasting the placeholders from the sample template. Change the color and style of the text, arrange existing placeholders within tables, etc.
Generate a report again with your updated template to see the effect.
Using advanced feature report syntax
Survey123 feature report syntax can get a bit more sophisticated than just a generic ${question_name}. For example, note in the example below how extra parameters are used to format dates, to control the size of a photo or signature and even to define the scale and contents of a map.
This is what the final output of the template above looks like when the report has been generated.
When working on your template, you first need to understand how to uniquely reference questions within your survey. Downloading the sample template is the easiest way to get a complete list of placeholders, but you can also get the complete list from the feature report template dialog as shown below. This dialog also lets you explore some more advanced syntax for your placeholders.
You can insert a | sign after your question name (aka: field code) and include some extra parameters to either format the value written to the report, or extract other information from your survey question.
| ${myquestion} | Inserts in your report the value stored in the specified survey question. |
| ${mydatequestion | format:"DD/MM HH:mm"} | Date questions are tricky, because they will not come pretty unless you format them properly. The format parameter is your friend. For a complete reference look for the Formatting Dates section in our Formulas—Survey123 for ArcGIS | ArcGIS help topic. |
| ${myphoto | size:300:0} | When working with image questions, you can set the exact size in pixels that the image will have in the output report document. The first value defines the width and the second the height. If you set the height to 0, then the width will be applied and the height will be dynamically set so your image aspect ratio is preserved. If you want to display the photo at full resolution use ${myphoto | getValue:””} |
${myphoto | getValue:"name"} ${myphoto | getValue:"date"} ${myphoto | getValue:"time"} | Also for image questions, you can add to your report the photo filename using the getValue:"name" parameter. Similarly, you can also extract the date and time when the photo was taken and have it written in your report. That, of course, assuming that the EXIF of the photo includes that info. |
| ${mylocat | size:400:400} | The size parameter is valid for map questions too. In this case, we will add in the report map with a size of 400x400 pixels. |
${mylocat | mapSettings:"6712da572":5000} ${mylocat | mapSettings:"":5000} | Use the mapSettings parameter to describe the exact webmap you want to draw and the map scale. First you pass the webmap item id and then, separated by a colon, the map scale. If you do not know how to get the webmap item id, have a look at Lisa Berry's Where can I find the item ID for an ArcGIS Online item? blog post. If you pass an empty webmap item id, then the report will use a default webmap. |
${mychoicequestion | selected:"yes"} Yes | When working with choice questions you can use the selected parameter to output a checkbox. The expression on the left will output  Yes if the option selected is yes. This works well with both checklists (select_multiple) and single choice and dropdown questions (select_one). |
Combining your mastery of the syntax above and a bit of good taste applying layouts and formatting in Microsoft Word will go a long way. You can pretty much do anything you want with your Microsoft Word document. For example, you can change the size and orientation of the page, use tables to arrange content, set the alignment and justification of text, its color, size, etc. You can also include Survey123 placeholders in headers, footers or anywhere in the body of your document.
As you get started with the feature report syntax, I suggest that you start slowly, making small incremental changes against the sample template and you let your confidence grow progressively. You will need to upload your template again and again until things look they way you want. Every time you upload the template, the syntax of your report template will be validated. You will get errors when you add an incorrect number of parameters on your placeholders, when you reference field codes that do not exist in your feature service or when you do not open or close the brackets correctly. Also be careful making sure parameters are set with the right casing and honor the necessary spaces.
On top of including photos, signatures and maps in your Survey123 feature report templates, you can also handle related records (repeats) and even define conditional visibility statements. The complete reference for the feature report syntax is included in this help topic.
ArcGIS Online support and credit consumption
Survey123 feature reports are generated through an ArcGIS Online premium service. If your survey is hosted in ArcGIS Online, each survey feature included in your report will cost 0.5 credits.
In the event that a user sees the Feature Report functionality disabled in the Survey123 website, an administrator of the ArcGIS Online organization can enable the Feature report functionality for that user as shown in the animation below.
ArcGIS Enterprise support
The Survey123 feature report service is at this moment hosted in ArcGIS Online and it is designed to work with surveys hosted in ArcGIS Online. However, with some limitations, this service can also be used with surveys hosted in your own ArcGIS Enterprise 10.5 or newer.
- Your ArcGIS Enterprise instance must be accessible to the Survey123 ArcGIS Online Feature report service. That is, you must configure your ArcGIS Enterprise web adaptor to expose access to your Enterprise instance from the internet. Please note that portals with Integrated Windows Authentication will not work with the report service.
- The inclusion of any type of feature service attachments (photo, signature, annotated images...) is not supported when your data is hosted in ArcGIS Enterprise 10.8 or older. As a workaround to include photos in your report now, then you can use this syntax in your report:
${#$attachment}
${$file}
${/}
Make sure you the above as three separate lines in your template. This expression will basically show all attachments found in your feature.
If you are using ArcGIS Enterprise 10.8.1 or newer, as long as you do not use a feature service published from ArcMap, you can use images in your report template normally.
Bearing the limitations above, the use of the ArcGIS Online Feature Report service from your ArcGIS Enterprise instance will not incur into any ArcGIS Online credit costs.
Other resources