Working with Time Zones in the Common Data Service

The Common Data Service can manage how time zones are interpreted when displaying records. This is a useful feature but one that can feel complicated because of the multiple attributes present for the user, entity fields, and app forms. This post will shed light on what these attributes do and answer common questions about time zone management.

If you are familiar with the time zone settings, you can jump right to the common problems section.

Where to Configure Time Zones

It is important to know all date/time data is stored in the Common Data Service as a UTC value. The way the data is displayed determines if just the UTC value is used or if the value gets translated to the user’s local time.

There are three distinct locations where time zone attributes are set:

• User settings – Each user account has a time zone value in their personalization settings, this defines what the “local time” is for the user account. This is set in the user’s profile.
• Entity Field settings – There are two types of date/time fields that can be used
  • Date and Time – Makers can select if the values should behave as time zone independent values (a static UTC calculated value that represents the exact GMT date and time) or as user local values (UTC that is translated based on the user’s time zone).
  • Date Only – Makers can choose between three settings: ‘Time Zone Independent’, ‘User Local’, or ‘Date Only’. ‘Date Only’ uses a data type that stores only a date (as the name implies), ‘Time Zone Independent’ and ‘User Local’ date fields include a time with the value of 00:00:00 on the record, allowing for time zone date calculations.
• App forms – Makers can indicate if they want a time/date field to display the data received as UTC or local.

If you create a date/time field as ‘User Local’, you can change it to ‘Time Zone Independent’ at any time. Be aware, this cannot be undone once changed. ‘Date Only’ fields can also switch from ‘User Local’ to ‘Time Zone Independent’ or ‘Date Only’ in the same way. Fields set to ‘Time Zone Independent’ or ‘Date Only’ cannot be changed.

Always be careful changing behaviors as other apps, plugins, or workflows may be relying on the data.

Common Problems When Using Time Zones

There are some time zone scenarios that seem to cause makers trouble more frequently than others:

For my Date/Time field I was expecting (UTC/Local) and I am seeing the opposite value

This is caused by a lack of parity between the entity field setting and the app form setting. When an entity field is configured for ‘Time Zone Independent’ or ‘User Local’, it determines if the time zone offset is honored or not when the data is being retrieved from the store. However, the app form also has a setting of UTC or Local.

This tells the form how to interpret the data it receives from the Common Data Service. If the data retrieved from the store is ‘Time Zone Independent’, but the form is set to local, the UTC data will be displayed as user local time based on the user’s time zone in their profile. The reverse is also true, a user local value from the store will be displayed as UTC if the form is set to UTC. Fortunately, the form’s date time zone values can be modified without disrupting the existing records.

I picked Date Only in my entity field, but my form is showing a time picker along with the date

This happens if you choose a behavior of ‘Time Zone Independent’ or ‘User Local’ for your ‘Date Only’ field. In the Common Data Service it will store a time of 00:00:00 by default, but if you add the field to a form it will assume you need to set the time as well. If you leave the time pickers in the form, users can enter a time and it will be saved as something other than 00:00:00. How can you fix this?

• Edit the form and remove the time picker and associated formulas. This will save the time as 00:00:00 and will still allow for time zone based date calculations.
• If your field is currently set to ‘User Local’, and you don’t need the date to be time zone calculated, you can change it to date only. This is a permanent change and cannot be undone. This change cannot be made to ‘Time Zone Independent’ behavior fields. Always be careful changing behaviors as other apps, plugins, or workflows may be relying on the data.

I have a date only field, but it is showing the wrong date for some users

If this happens, check the behavior that is set up for the ‘Date Only’ field. If the field is set to ‘Time Zone Independent’ or ‘User local’, the included timestamp will cause the date to appear differently for different users. The form display settings of UTC or Local will determine if the date displayed is calculated using the user’s time zone settings or if it displays it as the UTC value. Changing the form values to UTC instead of user local will prevent time zone offset calculations and will display the UTC date for the saved record. Alternately, if you need this to be a static date that does not change and the field is currently user local, you can change the field behavior to Date Only. Be cautious though, this is cannot be undone.

My (script/plug-in) is supposed to intercept the date submitted using the Universal Client before the user local conversion occurs, but instead it is being treated as User Local data

The web client and universal client have slightly different behaviors when it comes to when data is translated between UTC and User Local.

In the web client, dates are entered into the client, passed to the API as provided, and converted later into user local time. This allowed scripts/plug-ins to retrieve the data and take action before data was passed to the platform services and translated into user local time.

In the universal client, the translation of a date into user local values happens before the data is passed to the API, because of this, the data provided will not be a UTC date but rather a user local date based on the user who retrieved or posted it.

To resolve this, a user can either:

• Change the form to ‘Time Zone Independent’ which will retain the UTC value. This only works if the user does not need the form to display in user local time.
• Modify their script to detect the time zone offset used, recalculate back to UTC within the script, then take action.

 

Hopefully this will help when using time zone settings!

Related Links:

Behavior and format of the Date and Time field (makers)

Behavior and format of the Date and Time field (developers)