Skip To Content

Feature report templates

If the default format of the printed survey doesn't suit your needs, or you need to print multiple reports at once, the Survey123 website also provides a Report Template feature that provides a personalized template that will be applied to your feature reports.

A feature report represents a single survey record. As of the October 2019 release of ArcGIS Online, printing of feature reports is an ArcGIS Online Premium Service, and as such, consumes credits. Credits are charged at a rate of 2.5 credits per survey record. All related records of a single survey record can be included in the feature report for this single charge amount.

A feature report template is a Microsoft Word file (.docx) that provides placeholder text with specific syntax. When printing a feature report, this placeholder text will be replaced with the contents of the corresponding fields from the survey response. This placeholder text can be used with any formatting, tables, images, or other personalization to create a template specific to your needs.

To apply a new template, click the Feature Report button on the bar above the map on the Data tab, and click Manage Templates. A new window appears, allowing you to either select an existing template or upload a new one. Click Upload New Template to open another new window where you can view the placeholders for your survey's fields (except for fields within repeats) and a name and summary for your template when uploaded.

You can copy and paste the field name codes in the appropriate place in your template document by clicking the Copy button available when hovering your mouse over that field in the Feature Report Template window. Alternatively, you can use the link provided to download a sample template based on your survey. Once a template has been uploaded and chosen, click Generate to create your report. You can also choose to create reports of multiple survey responses at the same time.

Table of question placeholders

Expressions

Expressions can be included for certain types of questions to display the response in a format other than the default. For applicable questions, a Show more options button is available next to their placeholders when hovering your mouse over the field in the Feature Report Template window.

Text

Multiline text questions, either created through adding a Multiline Text question in the Survey123 web designer or using the multiline appearance for a text question in Survey123 Connect, will ignore carriage returns by default, displaying the response in a single block of text. An expression can be used to display the response to the question with carriage returns:

${multilinetext1 | appearance:"multiline"}

This expression will cause errors if not placed on a dedicated line.

Decimals

For decimal questions, the round expression can be used to set a maximum number of decimal places to which to round the value. The following example rounds the question to five decimal places:

${decimal1 | round:5}

Images

For image questions, sizes can be set to ensure your feature reports have images of consistent size. The format for these expressions is as follows:

${image1|size:width:height:max_width:max_height}

The width and height values control the set size of your image, measured in pixels. While these values are required for the expression, providing a value of 0 will place no restriction on that dimension of your image. For example, the following expression would force the width of your image to be 300 pixels, while preserving the aspect ratio of the image:

${image1|size:300:0}

The maximum height and width values limit the maximum size of an image and are optional values. The following example forces the width of the image to be 300 pixels but restricts the image height to no more than 200 pixels:

${image1|size:300:0:0:200}

Image questions can also have image details extracted and displayed in a survey response. This can be used to display the file name and size of the image as follows:

${image1|getValue:"name"}

${image1|getValue:"size"}

${image1|getValue:"width"}

${image1|getValue:"height"}

The same method can be used to display EXIF data from the image, showing details of where and when a photo was taken, as follows:

${image1|getValue:"x"}

${image1|getValue:"y"}

${image1|getValue:"date"}

${image1|getValue:"time"}

${image1|getValue:"direction"}

To display the original image at its full size and quality, use the getValue expression without any value:

${image1|getValue:""}

Note:

If setting an image's size along with using any other expression parameter, size must be placed last in the expression.

Geopoints

For geopoint questions, expressions can be used to display the latitude or longitude values from the question as follows:

${location|getValue:"x"}

${location|getValue:"y"}

It isn't possible to display both values with one expression; if both values are needed, both expressions must be used.

By default, these values are output to the same spatial reference used by the survey's feature service. You can set a different spatial reference as an additional parameter by providing its WKID:

${location|getValue:"x":4326}

Geopoint questions can also support setting the web map item ID and map scale as optional parameters when you precede these values with mapSettings:. In the following example, the map scale of 1:100,000 is used by providing the map scale without the 1: prefix or separating commas:

${location|mapSettings:"10df2279f9684e4a9f6a7f08febac2a9":100000}

If you leave either of these values as an empty string, the default basemap of your ArcGIS organization will be used, allowing you to define a web map or map scale without defining the other.

Geopoint questions also support the size expression available for image questions. This expression can be used to control the resolution of the map displayed in the report, as shown in the following example:

${location|size:400:400}

The mapSettings and size expressions can be used together to provide a web map ID and map scale as well as a map image resolution, as shown in the following example:

${location|mapSettings:"10df2279f9684e4a9f6a7f08febac2a9":100000|size:400:400}

Note:

If you're setting a map's size along with using any other expression parameter, size must be placed last in the expression.

If your survey doesn't contain a geopoint question, or you're creating reports for feature services without an associated survey, the geometry of a question can still be returned using the ${$shape} placeholder. This placeholder can also be used to return the geometry of polyline and polygon features.

Geotrace and geoshape

For geotrace and geoshape questions, the getValue expression can be used to display the length of the line or the perimeter of the polygon, respectively:

${polyline1|getValue:"length":"meters":"planar"}

For geoshape questions, the getValue expression can also be used to display the area of the polygon:

${polygon1|getValue:"area":"hectares":"geodesic"}

The units and calculation method are optional parameters. The following units are accepted for length:

  • feet
  • kilometers
  • meters
  • miles
  • nautical-miles
  • yards

The following units are accepted for area:

  • acres
  • hectares
  • square-miles
  • square-kilometers
  • square-meters
  • square-feet
  • square-yards

Alternatively, you can use any of the esriSRUnitType Constants or esriSRUnit2Type Constants supported by the ArcGIS REST API. In your expression, use the numeric code for the constant without quotes. For example:

${polyline1|getValue:"length":109002:"geodesic"}

If no units are specified, the default will be kilometers for length or square-kilometers for area.

The method can be either geodesic or planar. If no method is specified, geodesic will be used by default.

Date, time, and date-time

For date and date-time questions, an expression can be used to format the date using DD, MM, and YYYY placeholders for day, month, and year, respectively. The following expression displays only the day and month, omitting the year:

${date|format:"DD/MM"}

It's also possible to format the time in date-time questions, using HH, mm, and SS as placeholders for hours, minutes, and seconds, respectively. The following expression displays the day, month, hours, and minutes:

${datetime|format:"DD/MM HH:mm"}

Multiple choice

For both select one and select multiple questions, an expression can be used to place a check box next to a choice item, which is filled depending on the response to the question. The following expression displays whether the yes option has been selected for a question:

${select_one|selected:"yes"} Yes

Select multiple questions also have a supported expression to return all selected choice items as a bulleted list as follows:

${select_multiple|appearance:"bullets"}

If used within an expression, a single choice question will return the value of a choice item. If the question is referred to in a placeholder by itself, for example ${select_one}, it will return the choice label.

${if select_one=="choice1Value"}The user selected the first choice.${/}

Note:

If the label to your choice item contains double quotation marks, any double quotation marks within the label must be preceded by a backward slash. Not doing this will cause your report printing to fail. This is not needed for single quotation marks.

${select_one|selected:"Service provided by \"Greg's Plumbing\""} Service provided by "Greg's Plumbing"

Repeats

The values in a repeat can be accessed if placed between expressions using the repeat's name as a placeholder. The ${#repeatname} placeholder denotes the start of a repeat named repeatname, while ${/repeatname} denotes the end. Placeholders pointing to questions in the repeat perform as expected, but the question placeholders must be in the placeholders of their repeat.

Note:

To print the contents of a repeat within a table, ensure that the starting and ending tags are both placed inside the table, or outside the table. A report can't be generated if one of these tags is inside a table while the other is outside it. In most cases, if a start tag and an end tag are placed inside a table, the start tag should be in the first cell and the end tag should be in the last cell.

To access questions within a nested repeat, place its tags between the tags for every repeat layer above the intended repeat. This may look like the following:

${#repeat1}
${#repeat2}
${#repeat3}
${field1InRepeat3}, ${repeat2.field1}, ${repeat1.field1}, ${mainLayer.field1} 
${/repeat3}
${/repeat2}
${/repeat1}

Feature report expressions are currently unable to read special characters such as hyphens when referencing layer names. When referencing a layer that contains a special character in its name, use an underscore in place of any special characters.

To reference a field in your repeat that has the same name as its parent repeat, use the full path syntax including both field and repeat name. For example, ${sharedName.sharedName}

Conditional elements

Elements of a feature report can be shown or hidden conditionally using if statements. The if statement can be used by typing an expression in the starting ${if expression} placeholder, with ${/} denoting the end of the conditional segment. Some examples of if statements that can be used to hide parts of a report are as follows:

  • ${if photo1} displays the section only if the photo1 question has been answered.
  • ${if integer1>0} displays the section only if the answer to the integer1 question is a positive number.
  • ${if ((geopoint1 | getValue:"y")>0)} displays the section only if the geopoint is in the northern hemisphere.

The following logical operators are supported in if statements:

OperatorDescription

||

Returns true if one of two statements returns true.

&&

Returns true if both given statements return true.

!

Returns true if the statement does not return true.

==

Returns true if the two given values are equal to each other.

!=

Returns true if the two given values are not equal to each other.

>

Evaluates if the first value is greater than the second value.

>=

Evaluates if the first value is greater than or equal to the second value.

<

Evaluates if the first value is less than the second value.

<=

Evaluates if the first value is less than or equal to the second value.

Limitations

The following limitations currently exist when using feature report templates:

  • Your map will not appear in your feature report if the web map is using a version earlier than 2.0, which was released in July 2014.
  • Your map will not appear in your feature report if your ArcGIS Enterprise portal doesn't have a valid SSL certificate.
  • Feature report templates are only supported when using the Survey123 website with ArcGIS Enterprise 10.5 and later.
  • Printing using feature report templates does not work with ArcGIS Enterprise deployments that aren't public facing. Attempting to do so will present a getaddrinfo ENOTFOUND error.
  • Printing using feature report templates does not work with ArcGIS Enterprise deployments that use Integrated Windows Authentication (IWA).
  • Attachments are not supported when using the Survey123 website with ArcGIS Enterprise.