Better documentation is needed for Report Template Variables

[RobBlash]

I'm glad to see this new functionality, however the documentation poses more questions than answers for me.

1. How do you declare a variable?
2. Are "variables" limited to existing fields in the survey?
3. Can you provide more syntax examples? The provided examples in the help document are not very concise, as a reader I have no understanding of what those variables are or where they come from. Are they existing fields in the survey? Or are they declared elsewhere with an expression?

Report templates—ArcGIS Survey123 | Documentation 

[ClaireProctor]

Hi,

Thanks for this one! We had some consternation when writing that part of the documentation, where we weren't completely sure how much to actually include, and I think in our process of trying to figure out what was and wasn't essential, we missed writing a few things that actually were essential (because, as developers, we already knew them). So to answer your questions directly:

1. A variable is, essentially, already declared as one of the fields in the survey itself. We definitely didn't describe that well enough. You can also set a name for a query that can then be used as a variable in the same way (although I don't think we explained that one all too well, either).
2. Again, variables can be existing fields in the survey, but don't have to be. Most cases you'll be using an internal result from a survey question.
3. As to including more elaborate examples, can I get an example of what you're hoping to be able to do with this? We stuck with relatively simple and digestible examples, but if they aren't sufficient, then we'd love to know what is so that we can include it.

[RobBlash]

Hi Claire,

Thanks for getting back to me. In response to your points:

1. Using an existing field makes sense and is intuitive enough. Setting a name for a query then using that as a variable is still unclear to me after looking at the report query section, so I think improving that and adding a mention in the feature report section would be very helpful! To be honest, I thought about writing a post for clarification on that help topic as well. I tried to check it out one day and was unable to make any progress.
2. This makes sense, thanks.
3. The existing examples have no context which makes them hard to follow.
   1. The help says roadHeading is a variable, but there's nothing to show where/how that variable is set.
   2. Similarly, decimalPlaces has no other context other than saying it's a variable
   3. Maybe a better distinction between variables (and how they are declared, or what their source is) vs question type specific parameters/functions would be helpful. The reader may not know that you're setting map, number formatting, or image parameters using variables at a quick glance.

Hopefully this makes sense? Please let me know if it doesn't!

[Jen_Zumbado-Hannibal]

I agree @RobBlash . The syntax for reports in not very intuitive at all. That's why I submitted this 'Idea Request' for better documentation. Please vote thumbs up to make this a reality. 

https://community.esri.com/t5/arcgis-survey123-ideas/survey123-report-template-syntax-not-enough-doc...

[RobBlash]

Hi @ClaireProctor ,

I'd like to revive this and also point to the idea by @Jen_Zumbado-Hannibal, the documentation can still  be expanded in my opinion. Here's another example where the feature report help could be improved:

https://community.esri.com/t5/arcgis-survey123-questions/feature-report-help-with-conditional-statem...

[DavidRichey]

Hi @ClaireProctor . I have a 5-level relational database, and am wanting to write reports with a summary section and then the details in repeats. I am completely stumped on how to summarize the area for all of one type of child feature, like repeat1_polygon. The errors are "cannot parse field, field not available in this scope", and such. 

I've experimented with the Note on this page "To access questions in a nested repeat,..."which also addresses duplicate layer (or other object, seemingly) names. I've read through the report queries page you reference above, and this blog post by @IsmaelChivite . 

In the summary section, I'd like to sum the area for repeat1_poolygon. An individual record an be retrieved by calling ${ Planting_Unit.Planting_Unit_polygon | getValue:"area":"square-meters":"planar"}. A non-geometric field can be accessed by "sum,pop2000,populationTotal" in the stats statement.

$<$summary>
${Planting_Unit ["Planting_Unti.Planting_Unit_polygon" or variants are declared out of scope] | stats:"sum, [[what goes here??]], PU_SumArea"}
$</>

In the summary section, if getValue syntax is inserted into the "outStatistics" portion of the stats format, it breaks the interpreter because of confusion around opening and closing of brackets, as it does with area(${Planting_Unit_polygon}).

Declaring variables, or other such Arcade syntax seems to be not interpreted. I can do this in a popup, it is frustrating to not be able to execute such a summary in a report...

How can I access the area field to sum the area of (in my example) all planting Units on a Restoration Site?

Here is another unanswered question on gis.stackexchange.com if you're looking for more. Thanks for any and all help!

https://gis.stackexchange.com/questions/383623/how-to-write-syntax-to-sum-values-for-unique-ids-in-s...

Best,

David Richey