Back to Top

XLSForm parameters

In this topic

  1. General
  2. Audio
  3. Barcode
  4. File
  5. Groups
  6. Images
  7. Map questions
  8. Multiple-choice questions
  9. Range
  10. Repeats
  11. Text
  12. Rangefinder

Some question types in XLSForm have additional parameters that allow you to control the style or behavior of questions in a survey. In some cases, these parameters complement the appearances that a question type supports. The tables below provide an overview of the parameters you can use in XLSForm, and the column on the survey worksheet that accepts each parameter. Not all parameters are supported in both the ArcGIS Survey123 field app and the web app. For more information about field app and web app support, refer to the documentation topic for each parameter.

You can add multiple parameters for a question to the same column by separating the parameters with spaces. For example, a geoshape question can have map, method, lineColor, and fillColor parameters in the body::esri:style column, as follows: 

map="Imagery Hybrid" method=vertex lineColor=#DC143C fillColor=LightYellow

General

The following table contains the XLSForm parameters you can use with various question types. Refer to the description for each parameter for the list of question types that support it. These parameters are only supported in the field app.

XLSForm columnParameterDescription
bind::esri:parameterscalculationMode

Control when the calculation in a question is calculated.

Question types: text | decimal | integer | note | date | time | dateTime | select_one | select_multiple | geopoint | calculate | hidden

Values: auto | manual | always | whenEmpty

Examples:

calculationMode=manual
calculationMode=always
body::esri:styleplaceholderText

Specify the text that appears in the question's input area when the question is empty.

Question types: text | integer | decimal | select_one (with autocomplete appearance) | barcode

Values: @[hint] | @[guidance_hint]

Examples:

placeholderText=@[hint]
placeholderText=@[guidance_hint]

Audio

The following table contains the XLSForm parameters you can use with the audio question type. These parameters are only supported in the field app unless indicated otherwise in the description.

XLSForm columnParameterDescription
bind::esri:parameterscodec

Specify the preferred codec for an audio recording. Multiple codecs can be provided, separated by commas. The first codec compatible with the device will be used.

Value: <codec name>

Example:

codec=amr-nb,aac
fileName

Specify the file name.

Values: <expression>

This parameter is only supported in the web app.

Examples:

fileName=concat("JobID-", ${job_id})
fileName=concat(${asset_id}, "_", 
  format-date(now(), "%Y%m%d%H%M%S"))
max-duration

Specify the maximum duration in seconds for an audio recording. The default duration in the web app is 600 (10 minutes).

Value: <seconds>

Example:

max-duration=45
max-size

Specify the maximum file size in megabytes for an audio recording. The default size in the field app is 10 MB.

Value: <megabytes>

Example:

max-size=5

Barcode

The following table contains the XLSForm parameters you can use with the barcode question type. These parameters are only supported in the field app.

XLSForm columnParameterDescription
body::esri:style

barcodeType

Specify the types of barcodes users can scan. Multiple types can be provided, separated by commas. When the barcodeType parameter is not provided, all supported barcode types can be scanned except aztec, code39, datamatrix, maxicode, and pdf417.

Values: all | 1d | 2d | <barcode types>

  • all—All supported types except code39 and pdf417.
  • 1d—All one-dimensional types except code39.
  • 2d—All two-dimensional types except pdf417.

One-dimensional types: codabar | code128 | code39 | code93 | ean13 | ean8 | itf | upca | upce | upceanextension

Two-dimensional types: aztec | datamatrix | maxicode | pdf417 | qrcode | rss14 | rssexpanded

Examples:

barcodeType=qrcode,aztec,code128
barcodeType=ean8,itf
barcodeType=2d
barcodeType=pdf417

File

The following table contains the XLSForm parameters you can use with the file question type.

XLSForm columnParameterDescription
bind::esri:parametersfileName

Specify the file name.

Values: <expression>

This parameter is only supported in the web app.

Examples:

fileName=concat("JobID-", ${job_id})
fileName=concat(${asset_id}, "_", 
  format-date(now(), "%Y%m%d%H%M%S"))
max-size

Specify the maximum file size in megabytes. The default is 10 MB.

Value: <megabytes>

This parameter is supported in the field app and web app.

Example:

max-size=5

Groups

The following table contains the XLSForm parameters you can use with the begin group question type. These parameters are only supported in the field app.

XLSForm columnParameterDescription
body::esri:style

backgroundColor

borderColor

Set the background and border colors for a group or page. For more information, see Group, page, and repeat colors.

Values: <HTML color name> | <hex color code>

Examples:

backgroundColor=LightBlue
borderColor=#4682B4
backgroundColor=#C7FFC7 borderColor=#3C6D9E

layout

Set the grid layout style for a group.

Values: dynamic-grid | fixed-grid

Example:

layout=fixed-grid

Images

The following table contains the XLSForm parameters you can use with the image question type. These parameters are only supported in the field app unless indicated otherwise in the description.

XLSForm columnParameterDescription
bind::esri:parametersallowAdds

Disable the addition of new images when editing existing records.

Value: false

Example:

allowAdds=false
fileName

Specify the file name.

Values: <expression>

This parameter is also supported in the web app.

Examples:

fileName=concat("JobID-", ${job_id})
fileName=concat(${asset_id}, "_", 
  format-date(now(), "%Y%m%d%H%M%S"))
max-size

Specify the maximum file size in megabytes. The default is 10 MB.

Value: <megabytes>

This parameter is also supported in the web app.

Example:

max-size=5

smartAnnotation

For an image question with annotate appearance, automatically generates annotation graphics of labels and bounding boxes around the detected objects. Append these properties to define the style and formatting of the annotation.

Required property: <model_name>

Optional properties: minScore | cameraPreview | label | class | boundingBoxes | outlineWidth | fontSize | font | bold | italic

Examples:

smartAnnotation=modelname
  &cameraPreview=true&minScore=0.52
smartAnnotation=modelname&
  cameraPreview=true&minScore=0.52
  &class=classname1,classname2
  &label=false&bold=true

smartAttributes

Perform object detection or image classification and use the EXIF results in your survey.

Required property: <model_name>

Optional properties: minScore | cameraPreview | label | class

Examples:

smartAttributes=modelname
  &cameraPreview=true&minScore=0.45
smartAttributes=modelname
  &cameraPreview=true
  &class=classname1,classname2
  &label=false

redaction

Automatically generate or manually add bounding boxes and apply redacting effects on the target region.

Required property: <model_name> | @faces | @manual

Optional properties: minScore | cameraPreview | label | class | effect | symbol | fillColor | scale

Examples:

redaction=modelname
  &cameraPreview=true&effect=blur
redaction=@manual&effect=blockout
redaction=@faces&cameraPreview=true
  &class=classname1,classname2
  &label=false@effect=symbol&symbol=🐻

watermark

topLeftWatermark

topCenterWatermark

topRightWatermark

leftCenterWatermark

centerWatermark

rightCenterWatermark

bottomLeftWatermark

bottomCenterWatermark

bottomRightWatermark

Specify the position of an image watermark. Append properties to define the contents and formatting. For more information, see Watermarks.

Properties: text | color | outlineColor | outlineWidth | haloColor | size | font | bold | italic | margin | image | imageSize

Examples:

watermark="Example Text
  &outlineColor=White"
bottomLeftWatermark="Example Text
  &bold=true"
topRightWatermark="@[latitude longitude]
  &size=20"
body::esri:styleallowRename

Specify whether users can manually edit the file name.

Values: true | false

Example:

allowRename=false
fileNameVisible

Specify whether the file name is visible in the survey.

Values: true | false

Example:

fileNameVisible=true
footerText

For an image question with signature appearance, specify the text to display at the bottom of the signature pop-up. If no value is specified, the question's guidance hint will appear below the signature. This can be changed to the question's hint by using footerText=@[hint].

Values: <none> | @[hint]

Examples:

footerText
footerText=@[hint]
method

Specify the capture method for an image question. The map value is only supported for image questions with annotate appearance.

This parameter is also supported in the web app.

Values: browse | camera | map

Examples:

method=camera
method=map
method=browse,camera,map
palette

For an image question with draw or annotate appearance, specify a custom drawing tools palette.

Value: <palette name>

Example:

palette=SiteLayout
previewHeight

Set the height of the image preview after the image is selected. Use previewHeight=0 if you want your image preview to be of maximum size without unnecessary blank space.

Values: <lines> | <lines>lines | <percentage of screen height>% | <pixels>pixels

Examples:

previewHeight=3lines
previewHeight=120pixels
parametersmax-pixels

For an image question, set the maximum size of the image on the longest edge, preserving the original aspect ratio.

For an image question with signature appearance, set the maximum width for the signature pop-up.

For an image question with draw appearance, set the canvas to a square (1:1) image.

This parameter is also supported in the web app.

Value: <pixels>

Examples:

max-pixels=1500
max-pixels=400

Map questions

The following table contains the XLSForm parameters you can use with the geopoint, geotrace, and geoshape question types. These parameters are only supported in the field app unless indicated otherwise in the description.

XLSForm columnParameterDescription
body::esri:styleheight

Set the height of the map preview.

Values: <lines> | <lines>lines | <percentage of screen height>% | <pixels>pixels

Examples:

previewHeight=6lines
previewHeight=250pixels

lineColor²

fillColor³

Specify the line and fill colors for the line or polygon feature. This applies to the map preview in Survey123 only. For more information, see Style options.

Values: <HTML color name> | <hex color code>

Example:

lineColor=Black 
fillColor=#9EFFF5
lineWidth²

Specify the line width in pixels for the line or polygon feature. This applies to the map preview in Survey123 only.

Value: <pixels>

Examples:

lineWidth=3
map

Set a default basemap.

This parameter is also supported in the web app.

Values: <map name> | <map item ID>

Examples:

map="World Topography"
map=de26a3cf4cc9451298ea173c4b324736

mapTools

Control the map tools that are available for geopoint, geotrace, and geoshape questions.

This parameter is only supported in the field app.

Values: search | mapSwitcher | zoom | home | locate

Examples:

mapTools=zoom
mapTools=search,locate

method²

Specify the capture method. When using the vertex method, additional parameters can be set.

This parameter is also supported in the web app.

Values: sketch | vertex

Additional values for vertex, applicable only in the field app: streaming | beep | haptic | edit

Examples:

method=vertex
method=vertex,streaming
method=vertex,streaming,haptic
minCaptureZoomLevel

Specify the minimum level at which geometry can be captured.

This parameter is only supported in the web app.

Value: <integer>

Example:

minCaptureZoomLevel=17

overlay

Display point locations from the first geopoint question within a repeat on any other geopoint, geoshape, or geotrace question in your survey. Append properties to define the contents and style.

Value: <repeat name>

Properties: view | preview | icon | iconColor | iconOutlineColor | iconSize | label | labelColor | labelOutlineColor | fontSize

Examples:

overlay=campsites&preview=true
overlay=hydrants&label=asset_id&icon=hydrant&iconColor=Red

precision

Specify the number of decimal places that will be both captured in the map question and shown in the individual response panel in the survey. When this parameter is not set, all available decimal places are captured in the map question but only six decimal places will be shown in the individual response panel.

This parameter is only supported in the web app.

Value: <integer>

Example:

precision=4

snapMode

Specify snapping behavior. Points can be snapped to other features, and lines and polygons can be snapped to other features or themselves. Only available when method=vertex.

This parameter is only supported in the web app.

Values: feature | self²

Example:

snapMode=feature
snapMode=self
snapMode=self,feature
symbol¹

Specify a .png file to use as the point marker on the map. Append properties to define the position and scale.

Value: <file name>.png

Properties: x | y | scale

Example:

symbol=meter.png?x=0.6&y=0.1&scale=1.5

¹Supported by the geopoint question type only.

²Supported by the geoshape and geotrace question types only.

³Supported by the geoshape question type only.

Multiple-choice questions

The following table contains the XLSForm parameters you can use with the select_one, select_multiple, and rank question types. This parameter is supported in the field app and web app.

XLSForm columnParameterDescription
parametersrandomize

Randomize the order of choices in a choice list.

Values: true

Example:

randomize=true

Range

The following table contains the XLSForm parameters you can use with the range question type. These parameters are supported in the field app and the web app.

XLSForm columnParameterDescription

body::esri:style

startColor

endColor

color

Specify the color of the slider at the start and end of the range. Use the color parameter to specify the color that is used to fill the space between the start of the slider and the selected value. Parameters must be separated by a space. For more information, see Style options.

Values: <HTML color name> | <hex color code>

Examples:

startColor=Blue endColor=Red
startColor=Orange endColor=White color=#FF6347
endColor=#262626 color=Yellow

parameters

start

end

step

Specify the start, end, and step values of the range slider. Parameters must be separated by a space. For more information, see Range parameters.

Values: <integer> | <decimal>

Examples:

start=0 end=50 step=5
start=10.25 end=1 step=0.25

Repeats

The following table contains the XLSForm parameters you can use with the begin repeat question type. These parameters are only supported in the field app.

XLSForm columnParameterDescription
bind::esri:parametersallowAdds

Allow new repeat records to be added.

Values: true | false

Example:

allowAdds=true
allowUpdates

Allow existing repeat records to be modified.

Values: true | false

Example:

allowUpdates=false
query

Allow existing repeat records to be shown in the form. Specify additional query parameters to filter the available records.

Values: <none> | "SQL statement"

Examples:

query
query="severity='high'"
body::esri:style

backgroundColor

borderColor

Set the background and border colors for a repeat. For more information, see Group, page, and repeat colors.

Values: <HTML color name> | <hex color code>

Examples:

backgroundColor=LightBlue
borderColor=#4682B4
backgroundColor=#C7FFC7 borderColor=#3C6D9E

Text

The following table contains the XLSForm parameters you can use with the text question type. These parameters are only supported in the field app unless indicated otherwise in the description.

XLSForm columnParameterDescription
bind::esri:parametersgeocode

For a text question with geocode appearance, set the locator to return geocoded results from when using geocode appearance.

This parameter is also supported in the web app.

Value: <locator item ID>

Example:

geocode=36ff9e8c13e042a58cfce4ad87f55d19

measurement

For a text question with rangefinder appearance, set which measurements will be stored in the question. Enclose the list of values in quotation marks if values include spaces.

Values: height | azimuth | horizontalDistance | slopeDistance | inclination | multipleHeights

Examples:

measurement=height
measurement=height,azimuth,horizontalDistance
measurement="multipleHeights,Height 1,Height 2"
body::esri:styledefaultHeight

For a text question with multiline appearance, set the initial height of the text box. The height of the text box will increase to accommodate the answer text.

Value: <number of lines>

Example:

defaultHeight=5
indicator

For a text question with geocode appearance, allow geocoded results to show the direction and distance from the current device location.

Values: direction | distance | none

Examples:

indicator=none
indicator=direction
indicator=direction,distance
maxResults

For a text question with geocode appearance, specify the maximum number of results to be returned. The default is 6.

Value: <number of results>

This parameter is also supported in the web app.

Example:

maxResults=10
proximity

For a text question with geocode appearance, specify whether the geocoded results only show results within a certain radius of the device's location.

Values: <distance>m | km | ft | mi | yd

Examples:

proximity=3km
proximity=1000ft
suggestions

For a text question with geocode appearance, change how suggestions are populated. The default is yes.

Values: yes | no

Example:

suggestions=no

Rangefinder

The following table contains the XLSForm parameter you can use with the text, decimal, and integer question types to retrieve values from a rangefinder. These parameters are only supported in the field app unless indicated otherwise in the description.

XLSForm columnParameterDescription
bind::esri:parameters

measurement

For a text question with rangefinder appearance, set which measurements will be stored in the question. Enclose the list of values in quotation marks if values include spaces.

Values: height | azimuth | horizontalDistance | slopeDistance | inclination | multipleHeights

Examples:

measurement=height
measurement=height,azimuth,horizontalDistance
measurement="multipleHeights,Height 1,Height 2"

Feedback on this topic?

In this topic
  1. General
  2. Audio
  3. Barcode
  4. File
  5. Groups
  6. Images
  7. Map questions
  8. Multiple-choice questions
  9. Range
  10. Repeats
  11. Text
  12. Rangefinder