Date and time

An XLSForm can contain date, time, and 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.

Appearance

By setting the appearance column to year, a date question is presented as a year-only button, with arrows to increase or decrease the year value.

By setting appearance to month-year, a date question is presented as a pair of buttons, one for the month and one for the year. Each has arrows to increase or decrease the value.

Note:

The year and month-year appearances appear when the survey loads with values for the current month and year. However, they don't already contain these values and will submit a blank value unless manually edited or a default or calculation has been applied.

By setting appearance to week-number, a date question is still presented with a calendar picker for choosing the date, but once selected, the result is displayed as the equivalent week number of the year, as defined by ISO 8601. For example, if you choose April 27, 2016, Week 17 is displayed as the result.

Note:

The week-number appearance is not supported in the Survey123 web app.

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
ISO 8601 format	String that can include UTC offset. 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. 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. When adding or subtracting from a date value, you must use decimal time.	16678.375

*The Epoch time format is not supported in the Survey123 web app.

Tip:

To ensure that surveys work consistently in all Survey123 submission apps, 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:

1. In Survey123 Studio or 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.
2. Test the updated calculations by previewing them in Survey123 Studio or Survey123 Connect to ensure they work as expected.
3. 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.
4. Have field users update the survey in Survey123 Mobile or the Survey123 field app, or relaunch the survey in the Survey123 web app.