Date and time

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.

Epoch time and decimal time

There are two ways you can represent time in Survey123: epoch time and decimal time. The Survey123 field app supports both epoch time and decimal time, while the web app only supports decimal time. To ensure that surveys work consistently in both the field app and the web app, you must use decimal time in date and time calculations.

Epoch time and decimal time are different ways of representing time. Epoch time (also known as UNIX time) is defined as the number of seconds that have elapsed since 00:00:00 coordinated universal time (UTC) on January 1, 1970. ArcGIS stores time in milliseconds in UTC, so the Survey123 field app supports epoch time in milliseconds. Decimal time is defined as the number of days that have elapsed since the same point.

Human-readable timeEpoch timeDecimal time

Monday, 31 August 2015 09:00:00

1441011600000

16678.375

This is important because, while the Survey123 field app supports both epoch time and decimal time, the Survey123 web app only supports decimal time. If your survey needs to work on the web (either by itself or along with the field app), you must calculate some dates using decimal time. In particular, this is needed for calculating a duration, for example, calculating an amount of days or seconds, or those that involve the addition or subtraction of date times.

For these types of calculations, perform a calculation on a decimal date format value, perform the calculation, and convert the result to a date value. This sample equation converts a decimal date returned from the now() function, adds 14 days to it, and converts the result back to a date.

date(decimal-date-time(now()) + 14)

You can then use the date returned by this function to update a date in your survey or submit it as part of your survey.

When adding or subtracting from a date value, you must also use decimal days. Use the following table as a reference for how decimal time equates to human-readable time and epoch time.

Human-readable timeEpoch timeDecimal 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

Change epoch time calculations to decimal time calculations

If you have existing surveys that were created using Epoch-based time calculations, you must convert them to decimal time to function correctly in the Survey123 web app. The following are some examples of expressions converted from Epoch to decimal time:

ObjectiveEpoch time calculationDecimal 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 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 in the Survey123 Connect preview 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 the Survey123 field app.