Skip To Content

Esri custom columns

The Esri custom columns for XLSForm provide additional functionality for Survey123 users.

Field type and length

The bind::esri:fieldType and bind::esri:fieldLength custom columns should be used when you want to control the type and length of field to be created in ArcGIS for your survey questions.

For many questions, the type and length can be automatically determined by the XLSForm conversion service. Questions that require an integer or decimal value typically do not need to be controlled. However, questions of the select_one type will be converted into a string field in ArcGIS by default. If you require your choice list to store values as integers, you need to explicitly define the field type as an integer.

To control the field type, enter one of the following values in the bind::esri:fieldType column:

  • esriFieldTypeString
  • esriFieldTypeDate
  • esriFieldTypeInteger
  • esriFieldTypeSingle
  • esriFieldTypeDouble
  • esriFieldTypeSmallInteger
  • esriFieldTypePointZ
  • esriFieldTypeGUID

Note that bind::esri:fieldType only controls the field type created in the feature service. To control the field type for a question during a survey, use the bind::type column. For example, entering the value int into the bind::type column for a calculate question will treat the field as an integer, rather than its default field type of string. The values accepted by the bind::type column are as follows:

  • int
  • decimal
  • string
  • date
  • dateTime
  • time

The bind::esri:fieldType column also accepts the null value, which will cause the question to be omitted from the feature service created. While the question will still be present in your survey and behave normally, the answer will not be submitted to the feature service and will not be present when reviewing responses. This is ideal for calculations, constraints, or other questions that need to be present for presentation purposes but are not needed in the results.

The following question types do not support a null field type:

  • select_one or other
  • select_multiple or other
  • image
  • hidden
Note:

Geopoint questions can support a null field type only if there are two or more geopoints in the survey, one of which does not have a null field type, or if the geopoint is in a repeat.

Field aliases

By default, a survey field's alias inherits the same value as the field's label, referred to primarily when the survey is opened in ArcGIS. This can be changed by entering a value in the bind::esri:fieldAlias column, which will then become the field's new alias.

Because hidden and calculate questions do not display on a form, contents of the label field are not preserved. This means that when you view your survey records in the Survey123 website or ArcGIS, you will see the question name displayed in the column header for these types of questions. To force the column header of hidden and calculate questions to show a label, use the bind::esri:fieldAlias column in your spreadsheet to specify a label.

Input mask

Note:

Full support for input masks is still in progress. You may observe issues when using delimiters or after entering a value.

Input masks provide a set format for data entry by using characters and symbols. When you apply an input mask to a question, all responses must follow the specific pattern defined by the input mask.

To apply an input mask to your question, define the mask in the body::esri:inputMask custom column.

The following table lists the characters and symbols that can be used in an input mask:

CharacterMeaning

A

ASCII alphabetic character required. A through Z and a through z.

a

ASCII alphabetic character permitted but not required.

N

ASCII alphanumeric character required. A through Z, a through z, and 0 through 9.

n

ASCII alphanumeric character permitted but not required.

X

Any character required.

x

Any character permitted but not required.

9

ASCII digit required. 0 through 9.

0

ASCII digit permitted but not required.

D

ASCII digit required. 1 through 9.

d

ASCII digit permitted but not required. 1 through 9.

#

ASCII digit or plus/minus sign permitted but not required.

H

Hexadecimal character required. A through F, a through f, and 0 through 9.

h

Hexadecimal character permitted but not required.

B

Binary character required. 0 through 1.

b

Binary character permitted but not required.

>

All following alphabetic characters are uppercase.

<

All following alphabetic characters are lowercase.

!

Switch off case conversion.

\

Escape the special characters listed above to use them as separators.

The mask consists of a string of characters and separators, optionally followed by a semicolon and the character used for blanks. The blank characters are always removed from the text after editing. The following table lists example masks:

Example maskDescription

>A<xxxxxxxxxxxx

Text that starts with a capital letter followed by any lowercase characters.

AAA-AAA-AAA;_

Unique identifier that uses dashes as separators and underscores to represent each character that is to be completed.

B9.99;-

Represents a pH value. The number is constrained to start only with 0 or 1 and can only include two decimal places. A dash is used to represent each character that is to be completed.

999-99-9999

United States Social Security number.

(999) 999-9999

United States phone number.

900 kg

Weight in kilograms between 0 and 999.

99999

United States 5-digit ZIP Code.

AAA

IATA airport code.

Geopoint symbology

A geopoint question can display a custom symbol for the point marker on the map by using the symbol key in the body::esri:style column of your survey. To function, the key needs to provide the file name of the custom symbol, which must be a PNG file in the media subfolder of your survey. The column's contents should look like this:

symbol=imagefile.png

The symbol value can also accept certain optional parameters to configure the display of the symbol on the map. These parameters should be separated from the file name with a question mark, and from each other with an ampersand (&).

  • The x parameter determines the symbol's horizontal anchor point. It accepts a value between 0 (representing the left edge of the image) and 1 (representing the right edge). If not defined, the default value will be 0.5.
  • The y parameter determines the symbol's vertical anchor point. It accepts a value between 0 (representing the top edge of the image) and 1 (representing the bottom edge). If not defined, the default value will be 1.
  • The scale parameter determines what scale the image is displayed at. Values below 1 scale the image down, while values above 1 scale the image up.
Symbol style for geopoint

The value provided can either be a constant or a reference to a question, for example, symbol=${symbol_question}. Inline expressions are not supported.

Group and repeat colors

Groups, pages, and repeats can have colors set independently of the overall survey style in the body::esri:style column.

The backgroundColor and borderColor properties can be used on groups and repeats, and can accept both standard color names (for example, backgroundColor="red") and RGB values (for example, backgroundColor="#fafad2"). These can be provided as a constant or a reference to a question.

Note:

Grid-style groups do not support borderColor. Repeats inside of grid-style groups do not support backgroundColor.