The Esri custom columns for XLSForm provide additional functionality for Survey123 users.
Field type
Use the bind::esri:fieldType custom column to control the type and length of a field to be created in ArcGIS for the survey questions. For more information about the types of field supported, see ArcGIS field data types.
For some questions, you can change the field type that Survey123 assigns by default. The following table lists some examples:
| Question type | Default field type | Comments |
|---|---|---|
select_one | esriFieldTypeString | To ensure the choice is stored as an integer, change to esriFieldTypeInteger. |
date | esriFieldTypeDate | esriFieldTypeDate always includes a time element. To only store a date, change to esriFieldTypeDateOnly. |
dateTime | esriFieldTypeDate | esriFieldTypeDate gives no indication of time zone. To include the time zone in the field, change to esriFieldTypeTimestampOffset. When esriFieldTypeTimestampOffset is set, a time zone picker displays on the form for the dateTime question. The current time zone of the device will be applied by default. |
time | esriFieldTypeString | To store the time as a time value, change to esriFieldTypeTimeOnly. |
To control the field type, provide one of the following values in the bind::esri:fieldType column:
- esriFieldTypeString
- esriFieldTypeDate
- esriFieldTypeDateOnly
- esriFieldTypeTimeOnly
- esriFieldTypeTimestampOffset
- esriFieldTypeInteger
- esriFieldTypeBigInteger
- esriFieldTypeSingle
- esriFieldTypeDouble
- esriFieldTypeSmallInteger
- esriFieldTypePointZ
- esriFieldTypeGUID
Note that bind::esri:fieldType only controls the field type created in the feature layer. To control the field type for a question during a survey, use the bind::type column. For example, providing the value int in the bind::type column for a calculate question treats 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 causes the question to be omitted from the feature layer created. While the question is still present in the survey and behaves normally, the answer is not submitted to the feature layer and is not present when reviewing responses. This is ideal for calculations, constraints, or other questions that must 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
- hidden
Note:
Geopoint, geotrace, and geoshape questions support a null field type only if the survey includes at least one other geopoint, geotrace, or geoshape question that does not have a null field type or if the geopoint, geotrace, or geoshape is in a repeat.
Field length
Use the bind::esri:fieldLength custom column to control the length of string (text) fields to be created in ArcGIS for the survey questions.
Note:
You cannot control integer and decimal questions this way. Databases don't specify a length of a numeric field; the range of valid values is governed by the numeric field type. For example, an integer field stores any integer value between -2,147,483,648 and 2,147,483,647.
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. You can change this by providing a value in the bind::esri:fieldAlias column, which then becomes 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 the survey records in the Survey123 website or ArcGIS, you 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 the spreadsheet to specify a label.
Input mask
Input masks provide a set format for text questions 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. In the Survey123 field app and web app, survey responses cannot be submitted until all input masks are satisfied.
Tip:
Input masks can only be applied to the text question type. For integer or decimal question types, use the constraint column to limit answers. For more information, see Constraints.
To apply an input mask to the question, define the mask in the body::esri:inputMask column. The following table lists the characters and symbols that you can use in an input mask:
| Character | Meaning |
|---|---|
| A | ASCII alphabetic character required. Characters can be A through Z and a through z. |
| a | ASCII alphabetic character permitted but not required. |
| N | ASCII alphanumeric character required. Characters can be A through Z, a through z, and 0 through 9. |
n | ASCII alphanumeric character permitted but not required. |
X | Any nonblank character required. |
x | Any nonblank character permitted but not required. |
| 9 | ASCII digit required. Digits can be 0 through 9. |
0 | ASCII digit permitted but not required. Digits can be 0 through 9. |
| D | ASCII digit required. Digits can be 1 through 9. |
d | ASCII digit permitted but not required. Digits can be 1 through 9. |
# | ASCII digit, or plus or minus signs, permitted but not required. |
| H | Hexadecimal character required. Characters can be A through F, a through f, and 0 through 9. |
h | Hexadecimal character permitted but not required. |
| B | Binary character required. Characters can be 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 to end the input mask and a character to be used for blanks. The blank characters are removed from the text after editing. The following table lists example masks:
| Example mask | Description |
|---|---|
| >A<xxxxxxxxxxxx | Text that starts with a capital letter followed by any lowercase characters. |
| AAA-AAA-AAA;_ | Unique identifier that uses dashes as separators, with a semicolon at the end of the input mask followed by an underscore 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 semicolon ends the input mask, followed by a dash 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. |
Workflow
Use the bind::esri:workflow custom column to indicate that the field can be populated from the Rangefinder tile launched from the gallery. This column is only supported by text questions, and the following values are accepted by the bind::esri:workflow column:
- rangefinderMode=height
- rangefinderMode=offset
- rangefinderMode=height,offset
- rangefinderHeight
Each of the rangefinderMode values enable a similar user experience for the field worker. Once the desired rangefinder workflow is selected, the user is directed to select a survey and take 1 to 3 shots with the instrument, and then the survey is automatically launched for the field worker to complete any other questions.
The rangefinderHeight value is unique, in that it allows the field worker to browse through each survey question that is configured to receive a height value, using forward and back arrows. Once all of the heights are measured, the field worker taps Done and proceeds to the survey to complete any other questions.