One of the features of Survey123 is exporting custom PDF or Word format reports based on survey data. If you are new to Survey123 or haven’t explored Survey123 reports yet, this blog will help you get started with creating reports.
Reports are generated based on a report template associated with the survey. A report template is a Microsoft Word document that provides the report formatting and includes placeholders to indicate where survey data should be inserted when the report is exported. Since the template is a Word document, almost any formatting options that are possible in Word can be included in your template. This could include images or logos, text formatting, tables, headers, and footers. This customizability is useful for designing visually appealing reports, but it is also useful when adhering to a required report format, for example when submitting data to a government agency. See below for examples of report templates and an example of an exported report.
The Survey123 website is the central hub for viewing submitted data and managing various survey settings and features, including reports. The report template is added to the survey by uploading the template file in the Manage templates option on the Reports tab on the survey’s Data tab. Once at least one report template is uploaded, reports for one or multiple records can be exported.
Report types – individual vs. summary
There are two types of reports in Survey123: individual reports and summary reports. It’s also possible to include both in the same report, in which case they would be individual and summary sections.
An individual report displays the data for a single survey record, while a summary report displays data for multiple records in one report. Summary reports often aggregate the data using statistics. For example, if we have a survey that documents a water violation, an individual report will show details for a single specific water violation. A summary report, on the other hand, would display statistics for multiple violations, for example the total count of violations or the total count of each type of violation.
The report template’s syntax determines whether a report will be a summary report or an individual report. A summary report has a designated start tag and end tag, and everything between the two tags will be treated as a summary section.
Report templates
Report templates support a wide array of options for displaying your survey data, but there are a few ideas that are the core components to even the most complex reports:
• Question placeholders – Returns the value for the question name indicated. For example: ${question_name}
• Repeat start/end tags – Accesses questions within a repeat in a survey. Questions from the repeat can be displayed by including question placeholders between the start and end tags.
• Methods and parameters – Methods and parameters are additional syntax appended to start tag or question placeholder that modifies the returned value in some way. For example, the syntax ${geopoint1 | getValue:"x"} will return this geopoint’s x-coordinate because the getValue method is applied to the question placeholder and the parameter is set to x.
• Summary sections – Aggregates the question values for multiple survey records. A summary section is designated with a summary section start tag ($<$summary>) and end tag ($</>).
These are the foundational concepts for creating a report template, but it’s not necessary to create report templates from scratch. There are several resources to help you get started with a report template quickly.
Quick reference
The first resource for getting started with building a template is the quick reference. This option provides examples and descriptions for various methods and parameters that can be used for each question in your survey.
These syntax snippets include the question names from your survey, so they can be copied and pasted directly into your report template. The quick reference section is a good way to discover the different report syntax options that are available.
Sample templates
Another resource for getting started with report templates is the sample template option in the Survey123 website. This option generates a report template that includes the labels and placeholder syntax for all questions and repeats in your survey. You can then modify this template by removing unwanted questions, reordering questions, adding methods, and so on.
Esri templates gallery
If you’d like to see examples of completed report templates, some of the Esri templates available in Survey123 Connect include report templates that can be used with the samples. You can find these by opening Connect, clicking Esri Templates, and searching for “report template”. The survey template description includes a hyperlink to the report template.
Documentation
The final resource for exploring report templates is the Survey123 Report templates documentation. This documentation describes all the supported report functionality, and includes a helpful table of all the methods and parameters that can be used in reports.
What are the requirements for authoring and generating a Survey123 report?
Surveys in ArcGIS Online are generated by an ArcGIS Online premium service. If your survey is hosted in ArcGIS Online, each report will cost 0.5 credits plus 0.5 credits for each additional survey record included in the report (except summary reports).
Survey123 reports can be used with ArcGIS Enterprise with some exceptions. The following list of exceptions was written by Ismael Chivite when the report functionality was originally released in 2019 but is still applicable.
- Your ArcGIS Enterprise instance must be accessible to the Survey123 ArcGIS Online 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.
- If your survey data is stored in ArcGIS Enterprise 10.8 or older, take one of the following steps to include an attachment like a photo or signature in your report:
- Use the Upgrade Attachments tool in ArcGIS Pro.
- Use the following syntax in your report template:
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 in mind the limitations above, the use of the Survey123 report service from your ArcGIS Enterprise instance will not consume ArcGIS Online credit costs.
User types, privileges, and sharing
In order to upload a report template, a user must be either the survey owner or the organization administrator.
In order to export a report, a user must:
- Have the feature report privilege enabled.
- Have at least a ‘User’ level user type.
- Have had the survey results shared with them in the Survey123 website collaborate tab. This shares the survey form item, results feature layer, and report template.
Automation
It’s also possible to automate your report. For example, if you want a report to be exported at the same time every week, this is possible. One of the most common methods of automating reports is with third-party automation software like Microsoft Power Automate or Make, which have drag-and-drop interfaces to set up automations. It’s also possible to automate reports using a code-based approach such as the ArcGIS API for Python or the ArcGIS Rest API.
If you’re interested in learning more about Survey123 reports, also see these webinars on report automation and creating report templates:
Survey123 Tricks of the Trade (Live): Automate Reports
Survey123 Tricks of the Trade (Live): Create Report Templates
Article Discussion: