Report templates

The Survey123 Report tool allows you to design your own personalized templates and produce multiple reports at once.

A report can contain the following:

  • A summary section
  • A single survey record
  • A single survey record and a summary section
  • Multiple survey records
  • Multiple survey records and a summary section

Printing reports is an ArcGIS Online Premium Service and consumes credits. A minimum cost of 0.5 credits is charged. Once multiple survey records are included in a report, the report is charged 0.5 credits per survey record. Any related records of a single survey record can be included in the report at no extra charge. Additionally, the user performing a paid operation must be assigned a user role that includes the Feature report privilege. See Configure roles in ArcGIS Online for more information.

A report template is aMicrosoft Word file (.docx) that provides placeholder text with specific syntax. When printing a report, this placeholder text is 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 create a template, click the Report button on the bar above the map on the Data tab, and click Manage templates. A new window appears, allowing you to download a sample, upload a new template, or edit the name and summary of an existing one. Click New template to upload a new report template, while also providing a name and summary for your template once uploaded. Alternatively, you can use the Download sample template link to download a sample template based on your survey.

Expressions

Expressions are used to define the responses to display in the report and how they are displayed. An expression can be constructed to include just the name of the question, a calculation of questions, or may also include methods and parameters to style or constrain the response. An expression uses the following notation

${questionname | method:parameter }

where | delineates methods, and : delineates parameters.

An expression may include multiple methods and parameters or none at all. Parameters may be either values from other questions, or a fixed value.

The following expression would display the response from a text question called firstname.

${firstname}

The following expression would display the calculation of a number question called floweringtrees divided by a number question called totaltrees.

${floweringtrees / totaltrees}

The following expression would display the x coordinate value from the location question, where getValue is the method and x is the parameter.

${location | getValue:"x"}

Not all question types support expressions and methods. The following table lists which methods and parameters can be used with which question types.

MethodParametersConnect question typeWeb designer question typeDescription

getValue

-

All question types

All question types

Retrieves the raw data value from the feature layer, or raw image from an attachment.

getValue

x, y, z, wkid

geopoint

Map

Retrieve the x, y, z coordinates individually in a specified spatial reference. The wkid parameter is optional, and will be the same as the spatial reference of the feature layer if omitted.

getValue

length, area, unit, measurement type

geotrace, geoshape

Map

Returns the length of a polyline, or the perimeter or area of a polygon, in given units and whether the measurements are planar or geodesic. Default measurement type is geodesic.

getValue

name, size

image, file

Image, Signature, File

Returns the file name or size of an attachment.

getValue

width, height, x, y, date, time, direction

image

Image, Signature

Width and height return the integer value of the image width and height in pixels, and x, y, date, time and direction, return values read from the image EXIF if present.

appearance

multiline

text

Multiline text

Used to retain the line breaks in the string. If no appearance specified, answer returns a single line string.

appearance

bullets

select_multiple

Multiple choice

Returns answer in bullet format.

checked

choice value

select_one, select_multiple

Multiple choice, Single choice, Single choice grid, Dropdown, Likert, Rating

Returns a checked checkbox if the field value equals to choiceValue, otherwise, returns an unchecked checkbox.

selected

choice value

select_one, select_multiple

Multiple choice, Single choice, Single choice grid, Dropdown, Likert, Rating

If coded value domain exists, returns true if the field value equals the choice value, otherwise, returns false.

countselected

-

select_one, select_multiple

Multiple choice, Single choice, Single choice grid, Dropdown, Likert, Rating

Returns the number of selected choices.

selectedAt

index

select_one, select_multiple

Multiple choice, Single choice, Single choice grid, Dropdown, Likert, Rating

Returns the string at index position in the choice list. Index starts at zero.

locale

language code

date, dateTime, start, end, decimal

Date, Date Time, Number

Returns localized date, time and number.

format

format string

date, dateTime, start, end

Date, Date Time

Returns a formatted date string.

utcOffset

offset value

date, dateTime, start, end

Date, Date Time

Returns a UNIX time which is shifted by the UTC offset value.

mapSettings

web map item ID, map scale

geopoint, geotrace, geoshape

Map

Specify basemap and scale when printing the map image.

mapRotation

degree

geopoint, geotrace, geoshape

Map

Specify rotation angle when printing the map image.

src

image URL

image

Image

Specify the source URL of a dynamic image element.

size

width, height, max width, max height

image

Image

Specify the size of the printed image.

round

places

decimal

Number

Rounds a decimal number to specified decimal places.

useGrouping

boolean

decimal

Number

If true returns number with grouping separators determined by the locale, otherwise, if false no separators used.

toFixed

places

decimal

Number

Specify fixed number of digits after the decimal separator. Will pad zero if required to meet fixed number of digits.

On the Manage templates window, select Quick reference to open a page containing example syntax for expressions to modify the response displayed in a report for each question in your survey. To copy this syntax, click the Copy to clipboard button, which you can then paste into a template document. Once a template has been uploaded, use the options in the Report panel to produce your report. For more information, see Print reports.

Report quick reference with syntax examples

The following sections describe common use scenarios of expressions for each question type and gives examples.

Text

Multiline text questions—created either by adding a Multiline Text question in the Survey123 web designer or using the multiline appearance for a text question in Survey123 Connect—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 as follows:

${multilinetext1 | appearance:"multiline"}

Place this expression on a dedicated line; otherwise, errors will occur.

Numbers

Basic mathematical operators can be used with numerical questions, which can be used to add, subtract, multiply, divide, or find the modulus of the responses to these questions. The following are examples:

${number1 - 15}

${number1 * 6}

${number1 / number2}

${number1 % number2}

Tip:

If your expression includes a complex mathematical expression, consider using brackets to ensure that the report generation produces the result you expect.

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

${decimal1 | round:4}

The toFixed expression can be used to set a maximum number of decimal places to which the value is rounded. The following example fixes the number of decimal places in 3.14 to 3.140:

${decimal1 | toFixed:3}

Images and other attachments

For image questions, sizes can be set to ensure that your 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 forces 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 and 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 you are setting an image's size while using any other expression parameter, size must be placed last in the expression.

Dates and times are stored as strings in EXIF data, so these values cannot be formatted in a report using the format expression for date and time questions. If formatting these values is important, consider performing the EXIF extraction as part of your survey using the pulldata() function. For more information, see Images.

The getValue expressions above can also be used to extract data from any valid properties in any type of attachment, including the results of image, audio, and file questions. The properties that can be extracted from all attachments are as follows:

${file1 | getValue:"name"}

${file1 | getValue:"size"}

${file1 | getValue:"globalId"}

${file1 | getValue:"id"}

${file1 | getValue:"contentType"}

${file1 | getValue:"keywords"}

If all attachments to the feature are images, use the following placeholders with each placed on a dedicated line:

${#$attachment}
${$file}
${/}

To return multiple images submitted to the same question in a response, use the image question's name instead of $attachment:

${#image1}
${$file}
${/}

This method is useful for displaying images in ArcGIS Enterprise versions prior to 10.8.1, or for displaying images that were added to a feature outside of Survey123. The following example displays the file names of all attachments attached to a feature:

${#$attachment}
${$file|getValue:"name"}
${/}

To display an image from online, provide its source URL with the src expression when referring to the $image keyword instead of a question name:

${$image | src:"https://upload.wikimedia.org/wikipedia/commons/1/13/Esri_Headquarters%2C_Building_Q.jpg" | size:400:0}

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.

Tip:

You can also display the altitude value through a similar expression but only if the underlying feature layer supports z-values:

${location|getValue:"z"}

By default, these values are output to the same spatial reference used by the survey's feature layer. 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, a map scale of 1:100,000 is used:

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

If you leave the map item ID empty or set the scale to 0, the default basemap or extent of the question is used.

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 while using any other expression parameter, size must be placed last in the expression.

If your survey doesn't contain a map question or you're creating reports for feature layers without an associated survey, the geometry of a question can still be returned using the ${$shape} placeholder.

For all map questions, the mapRotation parameter can be used to define the clockwise rotation of due north in relation to the view. It accepts values from 0 to 360.

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

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 ArcGIS REST API. In your expression, use the numeric code for the constant without quotes as follows:

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

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

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

Geotrace and geoshape questions support setting the web map item ID and map scale as optional parameters when you precede these values with mapSettings:. In the following example, a map scale of 1:100,000 is used:

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

If you leave the web map item ID as an empty string, the default basemap for the question is used. Setting the map scale to 0 causes the map to zoom to the geometry for the question.

Geotrace and geoshape 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:

${polyline1|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:

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

Note:

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

If your survey doesn't contain a map question or you're creating reports for feature layers without an associated survey, the geometry of a question can still be returned using the ${$shape} placeholder.

For all map questions, the mapRotation parameter can be used to define the clockwise rotation of due north in relation to the view. It accepts values from 0 to 360.

${polyline1|mapSettings:"10df2279f9684e4a9f6a7f08febac2a9":100000|mapRotation:90}

Date, time, and date-time

To ensure that your date and date-time questions are presented in a way that's accurate to your region's formatting, an expression can be used to format the question to match a provided locale. The locale parameter should be placed first in an expression, and the locale code must be in lowercase.

${datetime|locale:"pt-br"}

Note:

For information on a specific language's locale code, see Wikipedia's List of ISO 639-1 codes. However, keep in mind that not all of these languages are supported by Survey123.

By default, all date and date-time values stored in a feature layer are displayed in coordinated universal time (UTC). The utcOffset parameter can be used to alter the display of these values in a report to match a specific time zone. The following expression displays the response to a date-time question offset from UTC by one hour:

${datetime|utcOffset:"+01:00"}

The utcOffset parameter supports the formats +01:00, +0100, and +01 and returns the same result. This parameter can also be used to alter the display of the response submission time. Be aware that utcOffset does not work with time questions.

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

You can also 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"}

Note:

The format parameter must be placed at the end of the expression.

Multiple choice

If a select one question is referred to in a placeholder by itself, for example, ${select_one}, it will return the choice label. If a select one question is used in an expression, or if the question uses an external select, a single choice question will return the value of a choice item. The following example uses a choice value, rather than a label, for a conditional statement:

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

To intentionally display the value of a choice rather than the label, use the getValue expression:

${select_one|getValue:""}

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 when the yes option has been selected for a question:

${select_one|checked:"yes"} Yes

Select multiple questions support expressions to output the total amount of choices selected, and to output a specific selected choice:

${select_multiple | countSelected}

${choiceQuestion1 | selectedAt:2}

Note:

The selectedAt expression begins counting selected choices at zero. This means that ${choiceQuestion1 | selectedAt:2} will return the third selected choice.

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

${select_multiple|appearance:"bullets"}

Note:

If the label of your choice item contains double quotation marks, they must be preceded by a backward slash; otherwise, your report will not print. A backward slash is not necessary for single quotation marks. The following is an example:

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

Repeats

To access questions in a repeat, add a repeat section to your template. For a repeat named defects, the ${#defects} placeholder denotes the start of the repeat section, while ${/} denotes the end. Placeholders pointing to questions in the repeat must be between the repeat section's start and end placeholders.

Note:

To print the contents of a repeat in a table, ensure that both the starting tag and the ending tag are 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 in a nested repeat, place its tags between the tags for each repeat layer above the intended repeat section. The following is an example:

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

Report expressions cannot read special characters, such as hyphens, when referencing layer names using the ${layername} syntax. When referencing a layer that contains a special character in its name, use an underscore in place of special characters. Alternatively, you can refer to the layer through the $layers keyword and either the layer name or layer ID, for example, ${$layers["my layer name"]} or ${$layers[0]}. This can be useful with duplicate layer names.

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

To limit the printing of your report to a select number of repeats, rather than every repeat associated with the response, use the resultRecordCount parameter to set a specific number of repeats to print:

${defects | resultRecordCount:20}

The orderByFields parameter can be used to determine the order in which repeats will be printed. Declare a field name, followed by ASC or DESC, and the repeats will be printed according to that field's input in either ascending or descending order, respectively:

${defects | orderByFields:"state_name ASC, pop2000 DESC"}

To display the index of a repeat record, use the getValue expression with the reserved keyword $feature. This example will produce 1 for the first record in a repeat, 2 for the second, and so on:

${#defects}
${$feature | getValue: "position"}
${/}

Report queries

Aggregate functions can be used to produce queries of the values in your printed responses. These queries are best suited to a summary section, which will only appear once in a report, regardless of the amount of responses printed. For more information, see Report queries.

Conditional report elements

Elements of a 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 show or hide parts of a report are the following:

  • ${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.
  • ${if multiple_choice1 | selected:"A"} displays the section only if the multiple choice question has had the choice 'A' selected.
  • ${if (repeat1 | getValue:"count")>=3} displays the section only if repeat1 contains three or more records.

In the following example, the text in the second line will only appear in the report if high is selected for the priority select one question:

${if priority | selected:"high"}
High priority issues must be addressed within seven days.
${/}

To check if a response contains a value for a question, only use an if statement referring to the field name directly with no other operators, for example, ${if photo1}. This format ensures that empty strings, null values, and undefined values are all considered empty values. This format applies to string, number, date, and attachment field types. When this format is used with repeats, the section will appear as long as there is at least one instance in the repeat.

To use conditional statements with date and time questions, perform calculations using Epoch time (milliseconds elapsed since January 1, 1970). For example, ${if (date1|getValue:"") < 1602735375000} displays the section only if the value in the date field is older than October 14, 2020. Be aware that report syntax doesn't have an equivalent to the XLSForm today() or now() functions, so it's impossible to compose a conditional statement for times relative to when the report was printed.

The following logical operators are supported in if statements:

OperatorDescription

||

True if one of two statements returns true

&&

True if both given statements return true

!

True if the statement is not true

==

True if the two given values are equal to each other

!=

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 exist when using report templates:

  • Your map will not appear in your report if the map is using a web map version earlier than 2.0, which was released in July 2014.
  • Your map will not appear in your report if your ArcGIS Enterprise portal doesn't have a valid SSL certificate.
  • Report templates are only supported when using the Survey123 website with ArcGIS Enterprise 10.5 and later.
  • Printing using 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 report templates does not work with ArcGIS Enterprise deployments that use Integrated Windows Authentication (IWA).
  • A maximum of 1,000 reports can be printed in a single report request.