Understanding Survey123 Feature Reports

24477
73
07-23-2019 02:10 PM
IsmaelChivite
Esri Frequent Contributor
16 73 24.5K

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 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 use filters or 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.

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

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.
Tags (2)
73 Comments
JamesTedrick
Esri Esteemed Contributor

Hi Dan,

No, you would not need data to generate a template.  Could you file a support ticket with Esri so that we can diagnose what is at issue?

DanLindner1
New Contributor II

James,  i found the issue. i am wanting to use the geopoint in a repeat (with the bind::esri:fieldType set to 'null') in trying to get Lat/Lon data for each record in that repeat.

When i remove the geopoint line from the form, it works. is this the only way to record lat/lon's for each record in the repeat?

thanks

-Dan

JamesTedrick
Esri Esteemed Contributor

Hi Dan,

The geopoint has the fieldType set to null?  If that is the case, there is no 'point' data in the repeat to be able to create a map from - null fields are not created (in a repeat, this makes the repeat a table and not a layer in ArcGIS terms).

JodyZhengLiu
Esri Contributor

Hi Marie-Lou Labuschagne‌,

The issue with "w2 multiline" appearance is fixed in the latest release of Survey123 3.9, would you please have a try?

Thanks,

Jody Zheng Liu

JacquieKovarik
New Contributor III

Hello James Tedrick‌,

Is it possible to create feature reports in Survey123 from an Enterprise feature service that's received in my Enterprise site through distributed collaboration? In my current attempts, I get a "Feature service code: 498 "invalid token" error".

Thanks in advance for your help!

Jacquie

OliviaNiziolek
New Contributor

I am not sure if this is what James was referring to however I think I am struggling with a similar questions. 

In this scenario if q1=no  the row (2nd row) shows up as blank, instead I would like the whole row where the if statement is to disappear. I tried putting the if statement at the end of the row above and a few other variations but can't seem to get it to disappear when q1 is no.

JennyHuang3
New Contributor III

Hi all,

I'm hoping to round up the horizontal accuracy number so followed the instruction on this page: Feature report templates—Survey123 for ArcGIS | Documentation but got the below error. I've tried removing spaces, capitalized the "R" in round but got the same error. If anyone has a solution to this that'd be much appreciated. Thank you!!! - Jenny

IsmaelChivite
Esri Frequent Contributor

Jenny Huang

The error message indicates that the round function is not supported against your Hor_Accuracy field.  I think the problem is that in your XLSForm, you have added a question of type 'hidden' called 'Hor_Accuracy'. 

The problem is that hidden questions, by default, are stored using a field of type text. Round cannot be applied to a text field.  You can use the bind::esri:fieldtype column in your XLSForm to set the field type esriFieldType double for your hidden question.  That will make your horizontal_acc field ready for the round function in the template.   Aside from the report templates, you may always want to store the horizontal accuracy as a number anyways, or otherwise it will be hard to query your data.

Please note that if you already have data collected, you will not be able to change the field type without re-creating the feature service. If you do not want to recreate the feature service, you can do the following:

  1. Go into arcgis.com and add a new field of type double. For example hor_acc_temp
  2. Calculate the values of this field by converting the values in your hor_accuracy to numbers
  3. Remove the original hor_accuracy field
  4. Add a new field with the same name as you had before, but with the double type
  5. Calculate the values back
  6. Remove the temporary field
  7. In XLSForm: Change the bind::esrifieldtype value to esriFieldTypeDouble in your hidden question and publish again. Since the field name and type will match, you will not need to recreate the feature service and you will not lose any data.


JennyHuang3
New Contributor III

Thank you so much, Ismael. Yes, you are right, the field is a hidden calculation field of type string. I tried changing the type to double right in connect and also tried, with another feature service, creating a field with the same name but with type double. Both worked. It was interesting though that I was not able to delete the string field right in ArcPro (as it's read-only) so had to switch back and forth between Pro and AGOL. Minor issue really but would like to know if there's a better way to do this. Thanks again! -Jenny

SarahOstertag
New Contributor II

I think I am having similar issues as described by Tory and Olivia. When using conditional statements in my template, blank lines are showing up when the conditions are not met and corresponding to where the conditional statements are written in the word document (even when the conditions are met). I would like there to be no space where conditions are not met so that there are not gaps in text/blank rows in tables in the report.

Example template section in Word (condition is highlighted):

Example where condition is not met (red shows extra lines):

Example where condition is met and there are spaces corresponding to Word template location of conditional statements (see red lines):

Any help with this is greatly appreciated!

JamesTedrick
Esri Esteemed Contributor

Hi Sarah,

This is occurring because you have new lines ('enter/return'): 

  1. Before the beginning of the ${if} statement 
  2. After the beginning of the ${if} statement
  3. After the end of the ${if} (the {/} placeholder).  

That means that a new line will be placed always (1) and then when the if condition is met, a second new line is placed(2).  Finally, an additional new line occurs always.  I would recommend beginning the if() immediately after ppm, which should most directly address this issue.

JamesTedrick
Esri Esteemed Contributor

Hi Olivia,

The row technically begins outside of the if() statement (as it occurs within the row). This may be somewhat difficult to implement; what I would try is beginning the if() immediately after ${q1} in the row above and concluding it at the beginning of the row below.

SarahOstertag
New Contributor II

Thanks James!

Moving the conditional statements to the preceding line and their closing placeholders (${/}) to the end of the condition line (instead of having this on its own line) worked. Repeating this action by placing subsequent conditional statements immediately after the ${/} on the same line was the trick.

Below are some snips so others can see an example of the solution. I failed to mention that my template uses tables to maintain consistent formatting - the solution below is within the same cell of the table.

Template:

Report:

JennyHuang3
New Contributor III

Hello! I'm wondering if it's possible to add a hyperlink of photo attachments to the feature report instead of inserting the photo right in the feature report? Thank you so much!

- Jenny

IsmaelChivite
Esri Frequent Contributor

Jenny Huang‌ Unfortunately, it is not possible to include in your report a hyperlink to an attachment.

JennyHuang3
New Contributor III

thank you

Fco_JavierRomero
New Contributor III

Hi, I am interested in adding a report generated in survey123 as an attachment to the feature service. I suppose I could do it with Python, but is it possible to do it via integromat? Do you have an example of this? I would appreciate any indication. Regards

MattCreaney
Occasional Contributor

Hi Ismael Chivite

I've tried to do as you suggest:

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

My data is currently in the structure Asset > Bay > Survey.  I would like to access data from the Bay layer to include in feature reports in the Survey layer.  I created a survey in Survey123 Connect based on the feature service, then published - I have no data in Survey123 online (my guess is this will only populate via Survey123 field app) so how can I create a feature report on data that isn't there?

IsmaelChivite
Esri Frequent Contributor

Matt Creaney‌  Easiest would be to create some dummy data so you can test your reports. Could not you submit some records using the Survey123 app?

MichaelBruening
New Contributor III

Hello and a quick question - is there a process to change the default marker symbol used within the maps generated and inserted into the custom reports? Currently, the maps are inserted using the "esri-pin-2" marker symbol, but I would like to use something different - more report deliverable to the client symbol.

However, is there a way to use the "default map marker symbol" from within Survey123 connect; that was made available within the BETA program, as the default marker symbol? I feel like I have already asked this question, but I cannot find my related content from my last profile after switching jobs.

I would like to move away from this marker symbol below.

MichaelBruening_0-1605882560511.png

It would be great to use this one that is available either within the ArcGIS Online symbol template or Survey123 Connect.

MichaelBruening_1-1605882655016.png

I have searched around and could not find documentation on how to achieve this if it is possible. Any information would be greatly appreciated.

Thank you,

Mike

DelaereMickael
Occasional Contributor

Hello everybody,

i am trying  to integrate the  DisplayBarcode formula from microsoft windows in my feature template.

but when i download the feature report the qr code return, the name of my field....

any idea?

 

Capture.PNG

My users love cutting trees, that's why they need to print...

 

DerrickWestoby
New Contributor III

Ismael or James, is there a way to limit a (repeat) table in a feature report to a maximum number of records, continuing on with the rest on a new page if needed?  I have a 1-page report that contains a 15-row table in it for the repeat values, as well as other unrelated tables below it.    Instead of leaving a large amount of white space at the bottom of the page (instances where only a few repeat values are included) OR pushing them onto the next page (instances where >15 repeat values are included), I was hoping to format the pages and the report generation in a way that it will accept up to 15 entries for 1 page, and then duplicate the entire 1st page (with it's 15-row table) as page 2 and continue filling in all of the values, repeating as many times as necessary. 

DerrickWestoby_0-1609197177818.png

 

An idea I had for accomplishing this was putting *everything* except my 15-row table into the header or footer and formatting from there as needed, but wasn't sure if that was the easiest approach. 

 

Thank you

SFM_TravisBott
New Contributor III

@JamesTedrick I wanted to follow up on the domain question that seemed half-answered above. 

I want my report to display the domain value for a hidden or display-only (read only text?) field. Is there a way to do this? The survey is being used to field-edit a feature service that is otherwise maintained in Pro/a Web app. The difference is I want the fields in question to remain hidden in the survey itself (or merely display the value) The work around is to make them a read-only select_one field, but that's kind of ugly. 

I tried variations of {MyField | getValue ''''} and {MyField | selected: ''''}. For a read-only text field, but no dice (getValue returns the code still, and selected doesn't pass the syntax test, the error saying 'checked is not supported').