An XLSForm can contain date, time, or dateTime questions. These questions can be styled to aid data capture using appearances.
You can format dates and times using the format-date function in the calculation column of date, time, or dateTime questions. For more information, see Date formatting.
The ArcGIS field types that date and time questions are assigned by Survey123 by default can be changed to capture date only, time only, or timestamp offset. To learn more, see Esri custom columns.
Caution:
Survey123 Connect 3.19 November Release and earlier cannot assign date only, time only, or timestamp offset field types. Although Survey123 Connect 3.19 February Update can publish these data types to ArcGIS Enterprise 11.2, they are not fully supported and their use in ArcGIS Enterprise 11.2 web layers is considered beta functionality.
Start and end questions capture the start and end date and time of the survey automatically and can be used to calculate the time taken to complete a survey.
Date and time formats
There are three date and time formats that you can use in Survey123: ISO 8601 format, Epoch (Unix) time, and decimal time.
The following table summarizes these formats.
| Name | Description | Examples |
|---|---|---|
String that can include UTC offset. This format is supported by both the Survey123 field app and web app. This format is useful for defaults and constraints because it is human-readable. | 2015-08-31T09:07:01Z 2015-08-31T09:07:01Z-07:00 | |
Epoch (Unix) time | Integer representing the number of milliseconds that have elapsed since 00:00:00 coordinated universal time (UTC) on January 1, 1970. This format is not supported in the Survey123 web app. Although converted to a human-readable date or time when displayed in ArcGIS apps, Epoch time is how data is stored in ArcGIS Online and ArcGIS Enterprise and is what is returned by the feature object. | 1441011600000 |
Decimal time | Decimal number representing the number of days that have elapsed since 00:00:00 coordinated universal time (UTC) on January 1, 1970. This format is supported by both the Survey123 field app and web app. When adding or subtracting from a date value, you must use decimal time. | 16678.375 |
Tip:
To ensure that surveys work consistently in both the field app and the web app, you must use ISO 8601 format or decimal time in date and time calculations.
Epoch time and decimal time calculations
The following table describes how Epoch and decimal time equate to human-readable time.
| Human-readable time | Epoch time | Decimal time |
|---|---|---|
1 second | 1000 | 0.00001157407407 (1 / 24 / 60 / 60) |
1 minute | 60,000 (1000 * 60) | 0.00069444444444 (1 / 24 / 60) |
1 hour | 3600000 (1000 * 60 * 60) | 0.04166666666667 (1 / 24) |
1 day | 86400000 (1000 * 60 * 60 * 24) | 1 |
1 week | 604800000 (1000 * 60 * 60 * 24 * 7) | 7 |
1 month | 2630880000 (1000 * 60 * 60 * 24 * 30.45) | 30.45 |
1 year | 31557600000 (1000 * 60 * 60 * 24 * 365.25) | 365.25 |
If you have existing surveys that were created using Epoch-based time calculations, you must convert them to decimal time to behave correctly in the Survey123 web app. The following are examples of expressions converted from Epoch to decimal time:
| Objective | Epoch time calculation | Decimal time calculation |
|---|---|---|
15 minutes into the future | now() + 15 * 60 * 1000 | date-time(decimal-date-time(now()) + 0.0104166675) |
Two weeks into the future | now() + 14 * 24 * 60 * 60 * 1000 | date(decimal-date-time(now()) + 14) |
Time spent for lunch in minutes | int(${LunchEnd} - ${LunchStart}) div (1000 * 60) | int((decimal-date-time(${lunchends}) - decimal-date-time(${lunchstarts})) * 24 * 60) |
Calculate age from a birthday (in years) | int((today() - ${birth_date}) div (1000 * 24 * 60 * 60 * 365.25)) | int((decimal-date-time(today()) - decimal-date-time(${birth_date})) div 365.25) |
Once you have an understanding of the changes needed for your survey, the update process is as follows:
- In Survey123 Connect, update any Epoch-based time calculations to use decimal date calculations. It's recommended that you save a backup of the XLSForm before proceeding.
- Test the updated calculations in the Survey123 Connect preview to ensure they work as expected.
- Republish the survey. Updates to calculations do not trigger a republishing of the feature layer, so no existing data will be lost by doing this.
- Have field users update the survey in the Survey123 field app.