ichivite-esristaff

Understanding Survey123 Feature Reports

Blog Post created by ichivite-esristaff Employee on Jul 23, 2019

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 basic 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.

 

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 from a single 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 use filters or simply manually select multiple records using the shift key.  If you create a single report, you will be able to open the document right away from your browser. If you create reports in bulk (from a selection), then the outputs will be stored in your ArcGIS account.

 

The Survey123 feature report service will always create a single document for every record you select. That is, reports from multiple records will not be merged into a single document.  If you select 200 survey records and you trigger feature reports for them, then Survey123 will create one document for each record: 200 separate documents.

 

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:

 

  1. In the Survey123 website, go to the Data tab of your survey.
  2. Select one record from the table or the map.
  3. Click on Feature Report in the top bar
  4. In the Feature Report panel that just open on the left side, click on the Manage Templates link.
  5. Create a new sample template as shown in the animation below and close the dialog.
  6. 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.

 

Feature Report SyntaxDescription
${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.

${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 our Feature report templates—Survey123 for ArcGIS | ArcGIS help topic.

 

ArcGIS Online support and credit consumption

 

Survey123 feature reports are generated through an ArcGIS Online premium service. At this moment, the use of this service does not consume ArcGIS Online credits, but it will starting with our next update to ArcGIS Online.

The feature report service will consume ArcGIS Online credits at a rate of 2.5 credits per document generated starting with the ArcGIS Online release in October of 2019.

        

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. This is a limitation listed in the backlog of ArcGIS Enterprise.

 

Bearing the limitations above, ArcGIS Enterprise users can leverage the ArcGIS Online Feature Report service at no additional cost. That is, usage of the report service from ArcGIS Enerprise will not incur ArcGIS Online credit costs. Now now, and not passed October 2019.

 

Automation

 

You can automate the generation of Survey123 feature reports through Integromat and the ArcGIS Python API.

 

  • Integromat: You can the Survey123 module in Integromat to automate the generation of feature reports when a new survey is submitted. Even better, with Integromat, you can also take that feature report document and include it as an e-mail attachment, or upload it into cloud storage.  You can learn the basics of automating report generation with Integromat in this brief video-tutorial:

 

 

  • ArcGIS Python API: The ArcGIS Python API is ideal if you want to generate reports in bulk in an automated way. For example, in case that you want to automatically generate reports for all surveys submitted daily or weekly. Refer to our ArcGIS Python API developer documentation for details.

Outcomes