Dates and Time in Survey123

04-17-2016 10:00 AM
Esri Frequent Contributor
20 82 52.2K

[Updated June 16, 2020]

In this blog post I will describe how you can work with dates and time in Survey123 with XLSForm. I will also cover important concepts for you to understand how dates and time are modeled in ArcGIS.

Before we start

To best follow instructions and concepts in this blog, I suggest you open the Dates & Time survey sample in Survey123 Connect. If you have a first look at this sample survey, it will much easier for you to follow content in the blog.

  1. Open Survey123 Connect
  2. Tap on New Survey
  3. Select the Samples category
  4. Scroll until you see the Dates & Time survey sample or use the search function.
  5. Create a new survey from this sample

Create new survey sample in survey123 Connect

Next, spend some time going over the survey. I suggest you explore it first in Connect and you also bring it into your phone or a web browser to see what it feels like. The structure of the blog pretty much follows the sample survey.

Basic Types and AppearancesSurvey123 Date

The Basic Types and Appearances section of the survey sample explores the different ways in which a date or time question can be presented to the end user. Combinations of the question type and its corresponding appearances, will help you control the best user input style that fits the needs of your workflow.

The first question in this survey is of type date and it uses no appearance. A calendar control is shown for users to pick a date.  Note that the question shows the current date by default. This is accomplished by setting the default column in the XLSForm to today().

The following 3 questions illustrate the use of appearances: Year, Month-Year and Week-Number.

  • Week-Number is the most exotic. Week numbers are often used in government and business for fiscal years and timekeeping. With this appearance, the calendar widgets will let the user pick a date and display the week number in the form.  You will also see the week numbers on the side as you select the date. The week numbers are calculated following the ISO-8601 standard.
  • The Year and Year-Month appearances are handy when you simply want to present the user with a choice to pick a year, or a year-month.

As you exercise the calendar control, it may not be obvious, but you can actually tap and hold the arrows to quickly navigate back and forth in time.


  • The DateTime and Time questions are shown at the end of this first section. Note that the questions automatically show the current date and time. This is, again, accomplished by adding he now() function into the default column.

Understanding Dates and Time in ArcGIS

The Date, DateTime and Time types of questions as well as their corresponding XLSForm appearances, help you control the user experience that you want to present to the end-user capturing the data, but it is also important to understand how that date will be stored in ArcGIS.

User input to the Date and DateTime questions will be persisted in ArcGIS in a field of type Date.  Despite the name of this field type, ArcGIS does not store just dates in Date fields: ArcGIS date values always include time as well. Hence, there is a perfect match between DateTime questions in Survey123 and ArcGIS date fields, but when it comes to date questions in Survey123, you need to understand that actually the time will also be stored.   But what time? Well, it depends:

  • The time will be noon (12:00PM) if the user has manually selected a date, or if you set the date using the today() function.
  • The time will vary if you set the date using the now() function. Now captures the current time, even if your date question does not show the time to the user in the form.

It is a bit tricky to get your time to show in ArcGIS, so that deserves an explanation too. The thing is that by default, your web maps in ArcGIS will hide the time... even though it is actually always stored. The screenshot below shows how you can configure your popup to display time. If the show time check box is disabled, do not panic: Change the format to a numeric date format, and it will switch on.


Time values in Date and DateTime questions  are always persisted as Coordinated Universal Time (UTC). This is important when you have people working in different time zones. ArcGIS clients will translate the stored UTC values into your local time zone. The only exception is ArcGIS Pro. ArcGIS Pro will show the time in UTC.

So far, I described how date and datetime questions behave. Lets talk next about Time questions, because they are special. For Time questions, Survey123 does not use the ArcGIS date type (which we know now that actually stores date and time). Survey123 time questions store values as a string. We did it this way, because otherwise you would get dates as well, and this could be confusing: Say you want to capture the time when a store opens.... you would not want the date in there...  Now, because time is stored as a string, there is no information regarding the time zone in it. As such, you need to keep in mind that there will be no time zone coverstion.  Later in the survey, we will explore how to capture times differently.

Date and DateTime questions store values as date objects including time. Time questions store values as text.

Formatting Dates

All graphical controls in the Survey123 apps will honor your locale regional settings. For example, if your browser or smartphone's locale is set to Spanish, then dates will be formatted the Spanish way (which is the correct one, by the way... just kidding).  In the next screenshot I show what the calendar control will look like in a phone set with United States vs Spain regional settings. Note that when using the Spain regional settings, the day goes first, then the month and then the year, versus the US version where the month goes first then the day and then the year.

Survey123 Dates English Spanish

Additionally the format-date and format-date-time function allow you to convert date objects into strings.

In the following example, we  use the wsdatetime question to capture the date and time at which a water sample was taken. The wstime question calculate will be hidden from the end-user and is used to extract the time entered and persist it as a string in military format.  Note that the output of the wsdatetimequestion is stored in ArcGIS as a date object in UTC, versus the wstime which will be stored as a string using local time in your device.

dateTimewsdatetimeSample Date/Time

The qualifiers in the format-date function are as follows:

Header 1Header 2
%Y4 digit year
%y2 digit year
%m0-padded  month
%nnumeric month
%bmonth name abbreviated
%d0-padded day of month
%eday of month
%H0-padded hour (24-hr time)
%hhour (24-hr time)
%M0-padded minute
%S0-padded second
%30-padded millisecond ticks (000-999)
%aThree letter short text day

Date and Date-Time Defaults

Survey123 accepts three possible values in the XLSForm default column:

  • today() This function returns the current date in your device. Typically you apply this function to questions of type date. The time part of this date will always by noon (12:00pm).
  • now()  This function returns the current time in your device. Typically you apply this function to questions of type datetime.
  • Finally, you can also apply a fixed date in ISO 8601 notation. For example: 2020-06-23T00:00:00-07:00.
    • 2020 for the year. Always 4 numbers.
    • 06 for the month. Always 2 numbers
    • 23 for the day. Always 2 numbers
    • T is simply a separator, for time. Always T.
    • 00 for the hour. Always 2 numbers
    • 00 for the minutes. Always 2 numbers
    • 00 for the seconds. Always 2 numbers
    • -07:00 is the UTC offset, which in this case is minus 7 hours.

Technically, you could also apply default value using Unix epoch notation (in milliseconds), but this would only work in the Survey123 field app. For consistency across the field and web apps, it is best to use ISO 8601 notation.

Constraints and CalculationsSurvey123

This section of the sample survey will be useful to understand how you use formulas with dates and date-times, so you can validate user input, as well as pre-compute date values. The questions in the survey are self-explanatory, The best is that you have a look at the XLSFile to better understand how things are done.

  • Constraints: A common constraint you will want to enforce is one that ensures a date is in the past or the future. That is pretty straight-forward: .> now() will ensure the user input is in the future for example. If you want to reference another question in the survey, you can use something like this: ${birthdate}<today(). This will ensure that the birthday question has a value in the past.

In constraints you may be asked to ensure a value is always newer and older than a fixed date. The date function is very useful in these cases. For example, you can set a constraint such as . > date('2006-01-01') or ${manufacture_date} > date('2006-01-01').

If you need to work with time constraints, simply add the time component to the date() function using the ISO 8601 notation.

  • Calculations: Calculations are easy too, as long as you understand that dates in the Survey123 app are encoded as numbers. When users pick a date or a date-time in the survey, all values will be presented in a human friendly way, but internally the application handles them as numbers that represent the total time elapsed since 1970. A positive number represents a date after 1970 and a negative number a date in the past.  As you can imagine those are pretty big numbers, but the math is simple once you understand how time is expressed. There are basically two formats for the elapsed time:


  • Unix epoch is the elapsed time since 1970 expressed in milliseconds.
  • Decimal date or French Revolutionary Time is the elapsed time since  1970 expressed in decimal days. That is, one day is 1.0, an hour is 1/24, a minute is 1/24/60, etc.   To learn more  about Decimal Time have a look at this 'How the French made a 10-hour day' article. You will love it!

UNIX epochDecimal date
2 weeks into the futurenow() + 14*24*60*60*1000date(decimal-date-time(now()) +  14)
Calculate age from birthdayint((today() - ${birth_date}) div (1000*24*60*60* 365.25))

int((decimal-date-time(today()) - decimal-date-time(${birth_date})) div 365.25)

Minutes spent for lunchint(${LunchEnd} - ${LunchStart}) div (1000*60)

int((decimal-date-time(${lunchends}) - decimal-date-time(${lunchstarts})) * 24*60)

15 minutes from nownow() + 15*60*1000

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

0.0104166675 is equal to  (1 (day) / 24 (hours) / 60 (minutes) ) times 15 (minutes).

I recommend you work with decimal date format, because then your XLSForm expressions will work both in the field and web apps. The Survey123 web app ONLY supports decimal time.

If you plan to use date expressions in the web app, use the decimal-date-time function.

If you ever need to populate a Survey123 date or dateTime question using a UNIX epoch number, you can use an expression like this:

textepochEpoch (milliseconds)
dateTimemydateThe Datedate(decimal-date-time(int(${epoch})))

Calculates and Relevants

This section in the sample survey is very similar to the previous one, but shows some other techniques that may be handy. For example, note how a calculate question is used to get the Lunch time computed, and then that value is used in other expressions throughout the survey.   A calculate is a type of question that will let you keep the result of a calculation without having to show it to the user in the survey. 

You will remember that questions of type time are ultimately stored as strings in ArcGIS, however, as far as calculations go, you will treat them as numbers. That is actually pretty handy because otherwise, you would not be able to do much with them!

Other ways to capture Time

The last section in the sample survey shows other techniques to capture time.

  • The 'Time from a list' example should not come as a surprise. A select_one type of question with minimal appearance is a nice way to present a list of hours to choose from.
  • Then there are some other examples illustrating how to use regular expressions in constraints as well as input masks.  I will go into the details here, so nothing is missed.
    • First, an example to capture military type with a period. For example: 11:35.  Note the use of an input mask here. The input mask automatically adds the period (:), so the user does not have to worry about that. The value of the input mask is 99:99 meaning that we expect to digits followed by a period and two more digits. You will see that the constraint column checks to make sure that the hours do not go beyond 23 and the minutes do not go beyond 59.  Note: input masks are NOT supported in the Survey123 web app.
    • In the second example, we want to capture military time, but without the period. For example: 1135. In this case, I want to highlight a couple of things. First, note that I am not using an input mask like before. It is not needed, because we can set the type of question as integer (to ensure that only numbers can be typed) and also set the the maximum length of the field to 4. This is done through the bind::esri:fieldLength column. This will do two things: will ensure that only integers with 4 digits can be entered into the Feature Service, and most importantly, will limit the user input in the Survey, to 4 numbers.  I still added a regular expression in the constraint to ensure that proper values within the 24 hour day are entered.
    • In the third example, I want to capture military time including the time zone. For example 1445Z. Z is the time zone (ZULU, which represents UTC). In 1445G, G is for Golf and represents UTC + 7.  That would be 1445 Golf Time. How awesome is that! More details on this crazy business with Time Zone Abbreviations here. Again in this case I added a mask and complemented it with a regular expression in the Constraint.

If you are not familiar with input masks in Survey123 I recommend you have a look at the Esri custom columns help topic. Regular expressions are tricky to put together, but you can find loads of samples in the web.

Start and End

So far, we have been looking at date and time questions that were visible in the survey. It is for this reason that we cared about the user experience (types of questions, defaults and appearances) as well as the validation of inputs (input masks, constraints).  Now, in Survey123 there are a couple of handy question types that will capture time without the end user knowing. These questions are start and end.  When added to your survey, like in the Sample you are looking at, they will not show in the survey to the end-user, but they will populate data in the Feature Service, that you can see from the survey123 web site or a web map.

Start and end will capture the exact date and time at which the survey was initially opened by the end user, and flagged as done. For you to see how this works, the best is that you load the survey in your phone, complete a couple of surveys and submit the data.

The start and end values are useful if you want to understand how much time people in the field take to complete surveys. To calculate the duration of the survey, you will need to download the data in FileGeodatabase or Shapefile format and calculate a new field with ArcGIS for Desktop. This ArcWatch article describes how you can calculate the duration between two date fields.

On top of start and end, which are optional, you will always get the Creation and Last Edit date and time for every row you add from Survey123 for ArcGIS. It is important to highlight here that the Creation and Last Edit columns are handled through ArcGIS Editor Tracking. The help has a good topic on Editor Tracking in case you are not familiar with it. Do not worry about  enabling Editor Tracking in Survey123, because it is always enabled by default. This feature looks at the time when edits are made in the Feature Service not when the data is necessarily being captured or changed in the field. For example, if someone is working in the field while disconnected from the network, the start and end field will truly reflect the time when the user is working on the survey. The Creation and Edit Times will reflect the time when the data was actually submitted: May be immediately after data capture, or may be a couple days later while back in the office.

This was a long post, but I hope you find it useful.

New Contributor

I was looking for a way to show date and time in my survey in the most compact and clear way -- day, month, military time.

I was able to fix time from AM/PM civilian to 24 hr military by changing my device language settings from English (Canada) to English (UK). But that took a while to figure out!

Now I am trying to find a way to display dates in a more compact way. Right now a date box looks like this: [Tuesday, 12 Novembe...] I would much rather have a simple 11/28/2019 that is not cut off by the box borders.

In the example that Ismael Chivite has provided in The Basic Types and Appearances section, dates are displayed differently in a "Date Question" vs "DateTime Question". When I open this sample survey in my Connect, I see something different -- all dates look the same: day of the week, month, day, year. Seems like date format is not affected by device settings as much.

Anyway, I would appreciate if anyone has any advice on that!

New Contributor III

NewThere is still an an issue occurring when using a calculation to set the dateTime in another questions from an initial question.   The first datetime entered gets recorded as expected,   the second one is changed from pm to am.

  • only happens in web app
  • happens when time set is between 12:00 - 12:59 pm
  • happens when using calculation to set another question

created and tested with S123 Connect v3.7.62. 

test from the web app

the dateTime value changes when set from other question. 

This is having repercussion for some longer complex client forms that rely on information in relates to be set from the top.

Esri Esteemed Contributor

Hi Ryan,

Thanks for pointing this out - the issue above was reported as affecting selecting a time, not based on the calculation.

New Contributor III

Copy thanks.   I am hoping this issue can get a quick fix for a next release, this issue with the webform reading, changing, selecting, calculating the date from 12-1pm has been a continued problem.

It doesn't seem like I can attach the excel file to this post but can send if need be.

Kind regards,


New Contributor III

HI James…

Through some additional testing this issue additionally shows up when using a default set to now() for a dateTime question. If the time is between 12:00 and 12:59PM the default value that is set gets changed to AM.

Looks like there is more to this issue that what was fixed in previous version.



Esri Esteemed Contributor

Hi Ryan,

The default value of now() gets turned into a calculation behind the scenes, so I believe this is the same issue as mentioned above.

New Contributor II


I am trying to get my exported excel sheet to display a field with the UTC time - 8 (my UTC offset it "-8"). I'm wondering what formulas in which fields on my survey connect form I should be entering to get this.

I want this calculation to be hidden to the user, so that they are simply using the automatic time on their mobile screen, and cannot see that I'm calculating the real time, minus the 8 hours on UTC on the form. 

Thank you

Esri Esteemed Contributor

Hi Winley,

As indicated in other posts in this blog, the appropriate calculation is 

now()+pulldata("@property, "utcoffset")*1000*60*60

which can be applied to either a read-only datetime question or to a calculate question that submits to a date field.

New Contributor II

I am trying to auto populate a field based on time, basically if the time is between 8:00AM and 6:00PM return a value of 'A' otherwise give it a value of 'B.'

So if you work between certain times youre in Shift A otherwise youre in shift B.

in my calculation field i have 

if((${time} >= '8:00AM' and ${time}=<'6:00PM') 'A', 'B')

but keep getting an error. I have looked up and down for what I am doing wrong but cant figure it out. Any suggestions on what I am doing wrong?

Occasional Contributor II

You're missing a comma between '6:00PM') and 'A'

if((${time} >= '8:00AM' and ${time}=<'6:00PM'), 'A', 'B')
New Contributor II

Thanks, I am still getting the same error. I went back and deleted all the fields in the bind columns just in case but there is nothing there and get the error in the image below.

dateTimeIncidentDateTimeTime of Incidenthorizontal
dateTimeRecordedDateTimeTime Incident Recordedyeshorizontal
select_one statusstatusIncident StatusSelect Incident Statusyesautocomplete
timetimeTime of Record Input
calculateshiftcalcAutocalculate Shifthorizontal-compactif((${time} >= '8:00AM' and ${time}=<'6:00PM'), 'A', 'B')

Occasional Contributor II

Oh, missed it the first time through. Change =< to <=

if((${time} >= '8:00AM' and ${time}<='6:00PM'), 'A', 'B')‍
New Contributor II

A comma and a bad operator, man, I cant thank you enough. I overlooked that 100 times! 

Occasional Contributor II

Hello thank you for this post,

Does anybody know if there is a way to format a date field with the full/long text day?

thank you

Regular Contributor

I see and accept that the decimal date below works, I am wanting to work out how to calculate this figure (0.0104166675) myself. For example I am now trying to work out what 7.75hr in decimal date equates too.

EPOCH FormatDecimal Date Format
15 minutes from nownow() + 15*60*1000date-time(decimal-date-time(now()) +  0.0104166675)

has anyone got any good links that could help me calculate this?

Esri Esteemed Contributor

Hi Ben,

A decimal date means that 1 day represents 1.0 units.  7.75 hours is 7.75/24 = 0.3229166666...

Occasional Contributor III

How can I get my web form (created in Connect) to show the date entry in English (UK) format? It displays correctly (d/m/y) in Connect and the field app, but as m/d/y in the web form.

Regular Contributor

I asked the same question to ESRI Australia Tech Support, it seems to be a BUG which has been around for some time now, unresolved

Esri Esteemed Contributor

Hi Rob, Ben,

We are planning to work on the display of dates as part of our next release of Survey123 - you should be able to test in the Early Adopter Community when it is ready.

Occasional Contributor III

That's great news

New Contributor III

From skimming the above comments I think I may be having the same or a similar issue as others; I'm hoping someone has a recommendation. I'm having an issue with formatting the dateTime field, as the data seems to vary based on whether the user is using the Survey123 app, or a web browser.

I've attached several images below. Please note, Time of Departure/Return are dateTime fields defaulting to now(). Estimated Time of Return is a time field with no default.

1) Date entry within Survey123.

2) Date entry in web browser (mobile).

3) The data seems to be recorded the same, as seen in the Survey123 website data tab.

However, the formatting is not quite working or matching up depending on when a dateTime value, or time, is submitted via a web browser. This doesn't happen when using the Survey123 app though

4) As a workaround, I've tried formatting the date info within the survey form itself as a hidden text field, and then just passing the string.

In the Survey123 website data tab I seem to get an error though. The top record is data from using the Survey123 app, the bottom record from using a web browser.

Any suggestions how to tackle this? Thanks

New Contributor

I'd like to confirm my understanding of a point in the original post:

Time values in Date and DateTime questions  are always persisted as Coordinated Universal Time (UTC). This is important when you have people working in different time zones. ArcGIS clients will translate the stored UTC values into your local time zone. The only exception is ArcGIS Pro. ArcGIS Pro will show the time in UTC.

If my understanding is correct, dates (dateTime and Date fields) are entered/displayed in local time in Survey123 clients (e.g. field app and web portal). However, the values stored in the feature service table are epoch milliseconds (which have to be UTC time). Is this correct?

For context, we are combining S123 data with other sources of information in an SQL server. Some date/time data is not lining up as expected and we'd like to confirm the how S123 is storing the time to take out one variable.

Many thanks

New Contributor III

Hi James,

I have got this calculation working. Thanks for that. I want to see the correct time both in my table in ArcGIS Online and once I export to Excel. My workflow now is to make a hidden question that applies a correction from UTC and a dateTime question that does not apply a correction. The first field displays the 'incorrect' time when viewed in the table in ArcGIS Online and the 'correct' time once exported to Excel the second field vice versa. Is this the best possible way to achieve having both times? Or am I missing something? Could this e.g. be caught in one field?


New Contributor III


I'm trying to convert a field type "time" from a 24hour format to an AM-PM format. By default, the time field converts the time into a string and It's ok, but I need AM-PM format.

Any Idea?.

Esri Esteemed Contributor

There are 2 components to this

- Getting the hour numerically correct.  This can be done by checking if the hour is between 1 - 12; if so it is correct.  numbers larger than 12 need to have 12 subtracted; 0 needs to be 12.  This can be done with the following if() statements:
if(int(format-date(${q},'%h')) > 12, int(format-date(${q},'%h')) - 12, if(int(format-date(${q},'%h')) > 0, format-date(${q},'%h'), 12))

- Determining AM/PM - this can be done by seeing if the hour is less than 12 or greater than 11:

if(int(format-date(${q},'%h')) > 11, "PM", "AM")

Combined into a H:MM AM/PM string you have:

concat(if(int(format-date(${q},'%h')) > 12, int(format-date(${q},'%h')) - 12, if(int(format-date(${q},'%h')) > 0, format-date(${q},'%h'), 12)), format-date(${q}, ":%M "), if(int(format-date(${q},'%h')) > 11, "PM", "AM") )

New Contributor III

Hello James!

Thanks for your help, It works very good!

New Contributor


I have a report that I generate in a ArcGIS Pro that pulls data that is collected using Survey123 the report pulls the Date and Time, but I just need the date, my team do not want to see the time, is there a way to hide the time stamp in the report or is that something you have done before?

New Contributor

Hi, I have an issue with the time calculation. What's the correct expression to get the time difference in minutes? (landing-takeoff=Lama Terbang)

I tried some expressions and it seemed working perfectly in the form preview in Survey123 Connect. However, after publishing it, "Lama Terbang" question won't calculate it automatically in web. One of expression I used: int((decimal-date-time(${landing_time}) - decimal-date-time(${take_off_time})) * 24*60)

What type of question that can accommodate the time calculation? Is it integers? or decimal?


Another issue is in the form preview Survey123 Connect shows 24H time format, after publishing it it changed to AM-PM format. Actually it's not a big deal, as long as I can still do calculation between 2 different time.


New Contributor II

I'm looking for a way to require 1 and only 1 of 3 or 4 questions to be answered.

I created a survey for intake of a field sample - received from a variety of sources with variable date precision.  Some samples are received with an exact ddmmyy, others will say 1-14 Jun, 2021, others say June-July 2021, etc. 

Is there a way to provide different date format options but STILL make one of them required? (i.e. ensure one of the date questions is completed?)  The date the sample was found is critical, we can use the data as long as there is at least a year, even though a precise date is preferred.

I have come up with 4 date versions/questions with different precisions where user clicks on calendar to select date sample was collected - but how to make only ONE of them required?:

1. Day, month, year.  

2. Month year

3. four digit year

4. Text field for approximate date - to allow for a range such as 1-15Jun?  

Many thanks,


New Contributor III
Hi Peg,

You can enter in if statements in the Required fields so that at least one of them is completed. You can ask questions like 'Do you know the exact date for the field sample?' If they answer yes, you can set up a relevant statement to include the option for the dd/mm/yyyy. If they say no, then you can ask if they know the month and forth. So, you are most likely going to get the exact date if known, and if not at least the month and year, so forth. The options will only appear as they indicate yes or no to what information they do know and then you can make the last option the required field, so that they have to at least enter in the year.
New Contributor III

You could also use the "relevant" setup to only show the exact date for the answer of "Yes" and then have the Year and month be displayed when the answer is "No". The use of an if() statement for "required" or you could use this solution also -


New Contributor II

Thank you for your replies.  I believe the keyword that did not occur to me was "conditional", and I'm new to Connect, so I haven't tackled relevance yet.  The link that @MichaelBruening provided is hopefully what I need.