To ensure that all surveys you author work consistently in both the field app and the web app, you will need to use decimal time when writing time calculations. There are two ways you can represent time in Survey123: Epoch time and decimal time.
Epoch and decimal time
Epoch and decimal time are different ways of storing time as a value, both defined by the amount of time elapsed since January 1, 1970. Epoch time (also known as Unix time due to being widely used in UNIX and UNIX-like systems) stores time as the amount of milliseconds since this point, while decimal time is stored as the amount of days since the same point.
| Human readable time | Epoch time | Decimal time |
|---|---|---|
January 1, 1980 | 31311360000 | 3652 |
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), some of your date calculations will need to be done 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, you will need to convert a date value (derived from either a question in your survey or a function such as now() or today()) to a decimal date format, perform the calculation, and convert the result back to a date value. This sample equation converts a date returned from the now() function, adds 14 days to it, and converts the result back to a date object.
date(decimal-date-time(now()) + 14)
The date object returned by this function can then be used to update a date control in your survey or submitted as part of your survey.
When adding or subtracting from a date value, you will also need to work with decimal days. Use the following table as reference for how decimal time equates to human-readable time and Epoch 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 |
Migrating surveys
If you have existing surveys that were created using Epoch-based time calculations, they will need to be converted to decimal time. The following are some 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 changes needed for your own survey, the update process is as follows:
- In Survey123 Connect version 2.2 or later, update affected calculations to use decimal date time. It's recommended that you save a backup of the XLSForm before doing this.
- 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 service, so no existing data will be lost by doing this.
- Have field users update their devices with the latest version of the Survey123 field app.
- Have field users download the updated survey.
Note:
Any existing surveys on the device in Drafts or Outbox can be submitted without issue at any point in this process.