Date and time fields on the apps and clients

jonnyseymour · ‎03-29-2017

If you thought the GlideDateTime holds the time and the time zone, and you would need to convert from one time zone to another or complex task to use them, think again. GlideDateTime holds the time in Coordinated Universal Time (or UTC). It takes time to get used to this "simple" concept. You would only need to consider the time zone for "displaying" the values.

When you retrieve the data from a GlideRecord, date and time fields are populated with all the relevant information. The values on the date and time fields are in UTC. However, when you are creating a new date and time field from scratch, or trying to get the Display value, you may face the task of validating the Display time. If that is the case, this blog is for you. I will show some examples of the data retrieved from an incident, and another when setting the time from scratch in a script.

Simple enough? The browser will show the GlideDateTime Display value, and calculations are in UTC.

GlideDateTime holds the time in UTC

When reviewing the different ways to overcome multiple time zones, converting the stored data as UTC (Universal Time Coordinated) is really simple and effective.

From a client point of view, they need to worry about time zones when displaying the data. In any other calculations, the times are UTC.

Here is one example of a client time and the user profile time:

In UK, the time shown on the PC was 14:38, while on the app it showed 07:38 because the profile was set to the the America/Los_Angeles time zone.

Both times are at different time zones, but on UTC they are both the same. Closed (closed_at) is "2017-03-19 14:38:01 UTC".

The Display time is calculated based on the time zone

The time zone is calculated based on the user profile, the system time zone, or the client time zone. However, the time zone can later be set manually by scripts.

Then based on the time zone, an offset is set and the "Display" value is calculated.

Here is an example:

--script----

var gr = new GlideRecord('incident');
gr.get("number","INC0020002");
gs.print('\ngr.closed_at: ' + gr.closed_at + " UTC\ngr.closed_at.getDisplayValue(): " + gr.closed_at.getDisplayValue() + " system time");

Results:

*** Script:

gr.closed_at: 2017-03-19 14:38:01 UTC

gr.closed_at.getDisplayValue(): 2017-03-19 07:38:01 system time

Modifying the time zone will NOT modify the stored UTC data; just the Display value.

Modifying the time zone does not modify the stored data. This is an area that may be confusing. GlideDateTime contains a time zone. Changing the time zone, it will only modify the "Display" value. This key on how the data is displayed on the clients.

Here is an example:

--script----

var message = [];
var gr = new GlideRecord('incident');
gr.get("number","INC0020002");
var vclosed_at = new GlideDateTime (gr.closed_at);
message.push('gr.closed_at: ' + vclosed_at);
// Setting to IST timezone
vclosed_at.setTZ(Packages.java.util.TimeZone.getTimeZone("IST"));
message.push('\ngr.closed_at: ' + vclosed_at + " UTC\ngr.closed_at.getDisplayValue(): " + vclosed_at.getDisplayValue() + " IST");
// Setting to US/Pacific timezone
vclosed_at.setTZ(Packages.java.util.TimeZone.getTimeZone("US/Pacific"));
message.push('\ngr.closed_at: ' + vclosed_at + " UTC\ngr.closed_at.getDisplayValue(): " + vclosed_at.getDisplayValue() + " US/Pacific");
gs.print(message.join ('\n'));

Results:

Timezone	Display Time	Database time
IST	2017-03-19 20:08:01	2017-03-19 14:38:01 UTC
US/Pacific	2017-03-19 07:38:01	2017-03-19 14:38:01 UTC

*** Script:

gr.vgdt_ist: 2017-03-19 14:38:01 UTC

vgdt_ist.getDisplayValue(): 2017-03-19 20:08:01 IST

gr.vgdt_pdt: 2017-03-19 14:38:01 UTC

vgdt_pdt.getDisplayValue(): 2017-03-19 07:38:01 US/Pacific

How to initialize a GlideDateTime with Display values

This is probably the most asked question when dealing with dates and times: How do you create a date and time field when we know the display values? The answer is to set the GlideDateTime time zone before setting the display value. This is performing a reverse offset translation from the "Display" value into the database value.

Here is an example:

--script----

var vgdt_ist = setDisplayTime ("2017-03-19 20:08:01", "IST");
var vgdt_pdt = setDisplayTime ("2017-03-19 07:38:01", "US/Pacific");
var message = [];
// Setting to IST
message.push('\ngr.vgdt_ist: ' + vgdt_ist + " UTC\nvgdt_ist.getDisplayValue(): " + vgdt_ist.getDisplayValue() + " IST");
// Setting to US/Pacific
message.push('\ngr.vgdt_pdt: ' + vgdt_pdt + " UTC\nvgdt_pdt.getDisplayValue(): " + vgdt_pdt.getDisplayValue() + " US/Pacific");
gs.print(message.join ('\n'));
// Convert provided date time and timezone into UTC to validate
// Default format is "yyyy-MM-dd HH:mm:ss"
// return: GlideDateTime on vtimezone
function setDisplayTime (originaldt, vtimezone) {
       var a = new GlideDateTime();
       a.setTZ(Packages.java.util.TimeZone.getTimeZone(vtimezone));
       a.setDisplayValue(originaldt, "yyyy-MM-dd HH:mm:ss");             
       return a;
}

Results:

Timezone	Display Time	Database time
IST	2017-03-19 20:08:01	2017-03-19 14:38:01 UTC
US/Pacific	2017-03-19 07:38:01	2017-03-19 14:38:01 UTC

*** Script:

gr.vgdt_ist: 2017-03-19 14:38:01 UTC

vgdt_ist.getDisplayValue(): 2017-03-19 20:08:01 IST

gr.vgdt_pdt: 2017-03-19 14:38:01 UTC

vgdt_pdt.getDisplayValue(): 2017-03-19 07:38:01 US/Pacific

Finally, it is important to simplify date and time fields, considering that they only hold the data in UTC. Everything should be as simple as it can be, but not simpler.

For more information on date and time fields, check out these resources:

Date and time fields on the apps and clients

GlideDateTime holds the time in UTC

The Display time is calculated based on the time zone

How to initialize a GlideDateTime with Display values

Troubleshooting Service Bridge Company Selection Issues: A Deep Dive

Maria DB VS Raptor DB - Record Insertion Performance - Part 1

Application Scoring and Application Assessment in Enterprise Architecture