Understanding Survey123 Feature Reports

47949
80
07-23-2019 02:10 PM
IsmaelChivite
Esri Notable Contributor
18 80 47.9K

 

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:

 

  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 Syntax Description
${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

 

Tags (2)
80 Comments
AyeletGreenberg
Occasional Contributor

Cool.
I'd like to create a report with photos from a related table, with the basic ${question_name} the photos from the table won't show up in the report. I tried using the form_id/ within the {} but it failed to parse.

Please advise,
Thanks

JamesTedrick
Esri Esteemed Contributor

Hi Ayelet,

You should be able to access an image with ${question_name} when inside a repeat section in the report - can you share your docx file?

AyeletGreenberg
Occasional Contributor

Hi James,
My Survey has no repeat section. 

JamesTedrick
Esri Esteemed Contributor

Hi Ayelet,

In that case, I'm confused - you mentioned accessing a photo from a related record, which is a repeat section in a form.  Is the related table not in the form?

Danielle_Papineau
Occasional Contributor II

Thanks for the post!  Lots of good information here.  Is there a way to format numbers to include thousand separators?  The commas are visible in Data tab on the Survey123 website, but are excluded when pushed out to the report.  I was hoping something like ${question | format: "999,999"} would work, but does not.  Any suggestions?  Thanks!

Environnement_1Lausanne
Occasional Contributor

Hello,

Thanks for the very good article!

I jhave a small question regarding the conditional display of tables in a report. 

I would like to conditionnally display tables depending on the responses I got for a select_multiple field (category field). In the template report, I have a table per category that is being filled up with the results of the specific category. I would like the tables for categories that have not been selected on the field, not to be displayed in the final report (built from the report template).

 

For instance, the user has selected the categories "water" and "air.

 

The template report has the following structure :

Water table results

Waste table results

Air table results

 

The final report built from the template should only display :

Water table results

Air table results

 

What is the nomenclature that should be used for the conditional display of tables in this case ?

 

Thanks for your help !

TimothyKing3
Occasional Contributor

Love the Feature Reports function!  Is there a way to change the style of the checkbox?  I would like to change it to an X without the blue background.

Thanks!

KatieWise
New Contributor II

Is there a way to include information from multiple records based on a unique Id in one report?  So say I have multiple records for one address but want to only have one report for that address with all the information, is there a way?

Thanks.

AyeletGreenberg
Occasional Contributor

The survey is updating a related table with 1:M.  I can see image on the report when there is only a single image attached to a survey. When there are multiple images non of them will show up even when each photo is under a different field name {photo2}, {photo3}, etc.

JamesTedrick
Esri Esteemed Contributor

Hi Ayelet,

The behavior you are describing is unusual.  Could you file an support ticket with Esri to investigate this?

IsmaelChivite
Esri Notable Contributor

Hi Katie. If your survey had a repeat to contain the multiple records for that address, you could easily present a report with information about the address, and then a table with as many rows as related records it has.  If the related records are not part of your survey (as a repeat), then it is not going to be possible. Well, not in a straightforward way. Technically, if you were able to build a 1 to many relationship (using globalid fields) between your address table and your records, then you could build a survey on top of the address layer and get an XLSForm that would create the repeat for you. You would not necessarily use this new survey to capture new data: you would use it just for the reports.

IsmaelChivite
Esri Notable Contributor

Hi. Unfortunately, it is not possible to change the style of the checkbox.

IsmaelChivite
Esri Notable Contributor

Hi Danielle Papineau‌  It is not possible, but I think this is something other people would vote for in https://community.esri.com/community/arcgis-ideas   You may also want to consider submitting an official Enhancement Request via Esri Technical Support.

StevenDel_Castillo
New Contributor III

Where are Integromat generated reports stored? Also, I'm assuming the 2.5 credit report consumption is the same when generating reports via Integromat?

We are currently looking at linking reports to pop-ups so knowing how and where they are stored is key.

Thanks,

Steven

JamesTedrick
Esri Esteemed Contributor

Hi Steven,

There are 2 aspects on this built-in to the feature report system:

- the feature reports once generated are stored for a brief amount of time (24 hours) within the feature report system to facilitate interactive retrieval

- For permanent storage, the feature report is added as an item to the generator's ArcGIS account.  Note that to be usable for pop-ups, this would be one item per feature.

Alternatively, you could, through the Integromat scenario, add the document as an attachment to the feature or move to another CMS for access.

ToryChristensen
New Contributor III

Hello, 

I also require conditional fields for feature reports within my organisation. Depending on the response, i would either want the field to be visible or hidden. Any advice on how to achieve this would be greatly appreciated.

Thanks

StephenBeckman
New Contributor II

The update appears to have changed how case sensitivity works for feature reports. Previously, I had a report using {if select_one == "Yes"} <return> on a bunch of select_one questions (name choices yes/no, labels Yes/No) and working fine. Recently, however, my reports were being generated blank, with none of the conditional statement values being returned, until I modified the templates to respect the name case - now {if select_one == "yes"} will return correctly. However it still returns the value in Title Case ("Yes").

It would be helpful if there was some sort of test/staging environment that could be used when designing feature reports, especially now that testing these things costs credits, too.

TysonHaverkort
New Contributor III

Wow, that's lame!

IsmaelChivite
Esri Notable Contributor

Stephen Beckman‌  Tyson Haverkort

The reason why you need to check against the choice name rather than the label is because the choice name is guaranteed to be unique and also for consistency on how expressions work in XLSForm (in the web and field apps).

We are working towards adding an option to let you create a 'test report' at no cost. We want to make this available as soon as we can (likely in December this year), but we will likely have this functionality available in the Early Adopter Program in early November, may be even earlier.

JamesTedrick
Esri Esteemed Contributor

Hi Troy,

Please refer to the 'Conditional Elements' section of Feature report templates—Survey123 for ArcGIS | Documentation - conditional elements can be specified with ${if <condition} ${/}

yaserkhouja
New Contributor II

Great stuff. Is it possible to create a monthly summary report? 

JamesTedrick
Esri Esteemed Contributor

Hi Yaser,

The feature report functionality is targeted at creating the detailed feature reports, not a summary report.  You can create a summary application via Operations Dashboard; ArcGIS Pro's reporting capabilities can also be used to create summary reports.

erica_poisson
Occasional Contributor III

Hi Ismael Chivite‌,

Is it possible to export attachments other than photos into a report template? I realize that within a webform this is what users see -

- explicit instructions to choose an image file.

However, they are still able to select other types of files as long as they are below 10MB, and some users want to select PDFs. Should users be able to attach files like a PDF? Should I just tell my users to only use image files?

As a related issue, it also seems as if non-image files (a PDF in this case) also cause edit mode of the webform to fail. If the edits were made and the PDF was removed, edit mode works as expected. Is this failure with an attached PDF expected behavior?

Thank you!

Erica

JamesTedrick
Esri Esteemed Contributor

Hi Erica,

It isn't possible to embed other document types inside a Word document using the feature report template.

Could I ask that you file an support ticket on the form edit/file removal process you are describing?

SueJohnston
New Contributor III

Hi Ismael,

How do I get the box to be filled in blue if checked vs if it's not checked?

Thanks!
Sue

TonyViveiros1
Occasional Contributor

Hello James Tedrick‌ and Ismael Chivite,

We've generated a Survey123 feature report and would like to call this from records selected within Operations Dashboard. Is this possible? 

Thanks.

Tony

JamesTedrick
Esri Esteemed Contributor

Hi Tony,

Are you asking to generate feature reports from within Operations Dashboard or access already generated reports?  The first may be possible - the Survey123 Early Adopter Community has details of the REST API calls used to generate the report.  The second can be possible, put requires some setup work for you to attach the document to the feature (or otherwise relate the document to the feature) - this may be possible by using a Webhook (and accompany workflow builder) to build that workflow.

TonyViveiros1
Occasional Contributor

Hi James Tedrick‌,

Generating reports from within Operations Dashboard is what we're interested in doing using an existing feature report template. The dashboard would provide a single interface for staff to access both the information and generate the reports associated with the workflow (timber inspections).  Unfortunately, I was unable to locate the REST API call information you referenced to generate reports within the Early Adopter Community.

Thanks.

Tony

JamesTedrick
Esri Esteemed Contributor

Hi Tony,

This is the direct link to the documentation. This would probably be accomplished via a custom HTML page that is included in the dashboard using the 'Embedded Content' widget.

EnvironmentalIntelligence
New Contributor III

Has ESRI considered adding the ability to have multiple records in one report document? We would like to use survey 123 to export monthly reports of construction photos, but need multiple photos and descriptions to appear on each page. We have about 300 photos per month so simply merging the separate documents is far too long.

IsmaelChivite
Esri Notable Contributor

Hi Environmental Intelligence

Absolutely. In the Survey123 Early Adopter Program you can test a new function that lets you merge multiple feature reports into a single file.  You can select, say 50 records, and then have the Survey123 service merge of these feature reports into a single file.  I suggest you give the Beta version of the Survey123 website a go and let us know thought the Early Adopter Program if this works well for you.  Our intent is to refine this functionality with feedback posted in the Early Adopter Program and make it available in the released software in early 2020.

Additionally, we are working towards expanding the report syntax so you can include statistics (SUM, COUNT, MAX, MIN, etc of values in a field across many records) as well as providing specific syntax to facilitate summary reports. We will disclose shortly some of this new work in the Early Adopter Program as well.

DamienRobinson2
Esri Contributor

Regarding the statement:

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.

What is the URL for the Survey123 ArcGIS Online Feature report service? It isn't listed in the docs or blog. 

Thanks,

Damien

DamienRobinson2
Esri Contributor
CourtneyRoss
New Contributor

My admin and I are having issues with accessing the feature report function.

I understand that only the owner has access to report capabilities for their own survey, but when I go to create one.. the tab simply does not highlight and instead shows the text "you don't have access to this feature. required privileges: generate feature report" 

My admin has looked over my access/privileges and does not see anything about 'generating feature reports'

What are we missing? 

Thanks.

Courtney

JamesTedrick
Esri Esteemed Contributor

Hi Courtney,

It sounds your user role does not have the Feature Report privilege enabled - this would have happened if you were a custom role (when it was introduced in the summer ArcGIS Online release, it was not applied to existing custom roles in organizations).  See User types, roles, and privileges—ArcGIS Online Help | Documentation .  See the last item in the 'Premium Content' section of the role privileges: 

Premium Content Privileges

ToryChristensen
New Contributor III

Hi James, is there a way to avoid having blank rows when a question has not been answered? Thanks

LouisDECOMBE
Occasional Contributor

Hello,

is there a way to lock the possibility to generate a report on all the records and only permit the generation on a single record?

I've some user that made the mistake to choose all the records and that consumed a lot of credits for nothing...

Thank you for your answer

JamesTedrick
Esri Esteemed Contributor

Hi Tory,

What are you meaning by blank rows?  can you provide an example template/layout?

TommyLind
New Contributor II

Is it possible to do feature reports in Microsoft flow (power automate) similar to Integromat?

Marie-LouLabuschagne
New Contributor III

When I use ${multilinetext1 | appearance:"multiline"} in my report to display my multiline comments with carriage returns, I get an error "Failed to parse ${xxxxx | appearance:"multiline"}. Filter appearance: "multiline" is not supported." when I try to upload the report template.

The documentation warns that this expression will cause errors if not placed on a dedicated line, but I don't understand what this means...

The Survey was created with Survey123 Connect 3.7.62, with a theme-grid pages style, so the appearance is w2 multiline, rather than just multiline - don't know if this will cause a problem in the report layout.

GregHacker1
New Contributor II

Hi James Tedrick‌,

I'm hoping you can assist with an issue I have with feature reports.  

I have a report that includes a simple table for repeats.  I have a conditional statement that filters based on a categorical field.  Everything works fine (produces rows based on the number of repeats in the record) except one field in a particular repeat (${Host_Test_Disease} under Agent Tested).  I'm able to pull data from other fields in the same repeat (e.g., Host_Specimen_Type and Host_Test_Type), but for some reason this field is always blank even if there is data in the feature service. Below is the table.  

Sample ID

Field Number

Host Species

Age

Sex

Specimen

Agent Tested

Test Type

Result

${#Host_Data}${#Host_Testing_Table} ${if Host_Testing_Table.Test_Lab==”VRDL”} ${Host_Data.Host_Sample_ID}

${Host_Data.Host_Field_Number}

${Host_Data.Host}

${Host_Data.Age}

${Host_Data.Sex}

${Host_Testing_Table.Host_Specimen_Type}

${Host_Testing_Table.Host_Test_Disease}

${Host_Testing_Table.Host_Test_Type}

${Host_Testing_Table.Host_Test_Result}${/}${/Host_Testing_Table}${/Host_Data}

Any ideas?

Thanks!

Greg

JamesTedrick
Esri Esteemed Contributor

Hi Greg,

It would be helpful to have a sample of your form, template and data to try to replicate this to truly troubleshoot this.  What type of question and value does Host_Test_Disease have?  Does it have a domain?

GregHacker1
New Contributor II

Hi James,

I just sent the files you need to your email.  

Host_Test_Disease is a categorical string that is the result of a calculation based on a select_multiple question.  Basically, for the parent record a user selects one more more disease categories.  Based on this selection, repeat records are created (using the selected-at function) in the child table with the disease categories passed to each repeat.  

Host_Test_Disease does have a domain.  The feature service was created when I first published via Survey123 Connect.  However, I've since changed the domain list to reflect updated categories (i.e., I've changed the names).

Thanks for your help!

Greg

JodyZhengLiu
Esri Contributor

Hi Marie-Lou Labuschagne‌,

You need to put the placeholder of ${multilinetext1 | appearance:"multiline"} in your template docx file in a dedicated line, for example:

Thanks,

Jody Zheng Liu

JamesTedrick
Esri Esteemed Contributor

Following up on this, it appears that the problem was involved with the domain.  using the getValue:"" expression (as if it was a select_one) in the placeholder resolved the issue.

KateBerg2
New Contributor III

Thank you! This is very helpful. I have a client that needs the survey results in a very specific Excel sheet template. What are my options for auto populating an Excel template? It looks like currently you only support .doc? Are you looking to add this functionality in soon? What else can I do if not?

Marie-LouLabuschagne
New Contributor III

Hi

I managed to upload the report, but I'm still getting "Failed to parse ${xxxxx | appearance:"multiline"}. Filter appearance: "multiline" is not supported." when try to Preview the sample report.  Here's what I've done -  maybe this can give you a better idea where I'm going off the tracks...

Appearance Multiline not supported

JodyZhengLiu
Esri Contributor

Hi Marie-Lou Labuschagne‌,

Thanks for providing the example and I can reproduce the issue now. It is because the theme-grid is not currently supported in the Survey123 website so the appearance of "w2 multiline" didn't parse correctly in the report. If you remove the reference for column width and use "multiline" as appearance it will be printed successfully.

While I have logged an internal issue for that, I encourage you to submit this issue as a bug via Esri Support. Our Support team will assign an official bug number for your records. This number can be used to search for and subscribe to the bug on the Esri Support site. If the issue is reported by other customers it will be attached to the same bug report, which helps us assess the impact of the issue and prioritize it accordingly

Thanks a lot,

Jody Zheng Liu

IngridMans
Occasional Contributor II

I didn't realize that the report's inclusion of photos and attachments wasn't available in Enterprise. I'm glad I saw this! We rely on the feature reports for our inspections surveys.

Our organization recently deployed ArcGIS Enterprise Portal 10.8, but our current ArcGIS Online content will still remain intact. I am wondering: is there any major advantage to migrating our surveys to Portal? Keeping in mind that, we need photo attachments to be included in our reports. 

Thanks for the helpful blog!

by Anonymous User
Not applicable

I have created a few reports and really like this feature. I have created a survey using repeats, and now when creating the report i get a generic "An Error occurred while generating report(s)." while trying to generate a preview report. I use the sample template that is generated without any customizing. I do not have any data in the repeats for my testing, just some header data that i am testing with.

do i have to have data in the repeat tables in order to generate a report from that survey?

thank you