Working with utcDateTime Functionality in Dynamics AX 2012

By Bill Thompson | June 2, 2015

Dynamics AX 2012 utilizes the utcDateTime data type to store date time information in the database using the Greenwich Mean Time definition of time. This allows the data to be date stamped in a manner that does not reflect the client or AOS time zone (this date/time stamp is considered to be time zone agnostic).

However, this means that some care may be needed in X++ code to correctly work with these values so the information can be displayed properly in some instances.

The Dynamics AX 2012 kernel has a nice class built in to allow us the ability to easily work with these values. The following job will demonstrate how to use just a few of the built in methods from this class:

static void DateTimeExamples(Args _args)
    // timezone definitions for use in demo code
    Timezone            myTimeZone = Timezone::GMTMINUS0600CENTRALTIME;
    Timezone            NYTimeZone = Timezone::GMTMINUS0500EASTERNTIME;
    Timezone            MSTimeZone = Timezone::GMTMINUS0800PACIFICTIME;
    // DateTime variables for use in demo code
    utcDateTime         myDateTime;
    utcDateTime         GMTDateTime;
    utcDateTime         NYDateTime;
    utcDateTime         MSDateTime;
    // my current system date/time value in UTC
    GMTDateTime = DateTimeUtil::getSystemDateTime();
    info(strFmt("Current system datetime in GMT: %1",datetime2str(GMTDateTime)));
    // apply my timezone offset to see date in my current timezone 
    myDateTime = DateTimeUtil::getSystemDateTime();
    myDateTime = DateTimeUtil::applyTimeZoneOffset(myDateTime,myTimeZone);
    info(strFmt("Current system datetime in my timezone: %1",datetime2str(myDateTime)));
    // apply my timezone offset to see date in my current timezone 
    NYDateTime = DateTimeUtil::getSystemDateTime();
    NYDateTime = DateTimeUtil::applyTimeZoneOffset(NYDateTime,NYTimeZone);
    info(strFmt("Current system datetime in NY timezone: %1",datetime2str(NYDateTime)));
    // bad example of time zone change
    MSDateTime = DateTimeUtil::applyTimeZoneOffset(NYDateTime,MSTimeZone);
    info(strFmt("NY datetime in MS timezone (incorrect): %1",datetime2str(MSDateTime)));
    // proper way to change the timezone information
    MSDateTime = DateTimeUtil::removeTimeZoneOffset(NYDateTime,NYTimeZone);
    MSDateTime = DateTimeUtil::applyTimeZoneOffset(MSDateTime,MSTimeZone);
    info(strFmt("NY datetime in MS timezone: %1",datetime2str(MSDateTime)));    

The job is going to work with the Eastern, Central, and Pacific timezones within the United States.

After the variable declarations, the first method used is the DateTimeUtil::getSystemDateTime() method. This returns the current system dateTime as a type of utcDateTime, and there is NO timezone offset applied to the data.

GMTDateTime = DateTimeUtil::getSystemDateTime();

The next line in the code simply shows the time displayed in an infolog. The use of the datetime2str built in function is shown as well to convert the utcDateTime type into a string for the infolog to use.

info(strFmt("Current system datetime in GMT: %1",datetime2str(GMTDateTime)));

The next set of code is used to retrieve the current system datetime value, and apply the central timezone offset to the retrieved value:

// apply my timezone offset to see date in my current timezone 
myDateTime = DateTimeUtil::getSystemDateTime();
myDateTime = DateTimeUtil::applyTimeZoneOffset(myDateTime,myTimeZone);

This forces the date to be converted into Central Time zone.

NOTE: If it is desired to be converted based on where the user currently resides, the following code could be substituted:

myDateTime = DateTimeUtil::applyTimeZoneOffset(myDateTime,DateTimeUtil::getUserPreferredTimeZone());

The next set of code shows how we apply the timezone offset for the Eastern timezone.

NYDateTime = DateTimeUtil::getSystemDateTime();
NYDateTime = DateTimeUtil::applyTimeZoneOffset(NYDateTime,NYTimeZone);

This is as expected. Here is where it gets interesting however. What if it is desired to convert the above New York time to the Microsoft headquarters timezone in Redmond Washington? One would think that the following code would work:

MSDateTime = DateTimeUtil::applyTimeZoneOffset(NYDateTime,MSTimeZone);

However, this is incorrect. This code will apply the timezone offset as though the NYDateTime value is considered to be in GMT, which is it not. The correct code would be to take the NYDateTime value, strip off the timezone offset, and then apply the new timezone value to the GMT timezone. The code to do that is the following:

// proper way to change the timezone information
SDateTime = DateTimeUtil::removeTimeZoneOffset(NYDateTime,NYTimeZone);
MSDateTime = DateTimeUtil::applyTimeZoneOffset(MSDateTime,MSTimeZone);

At this point, the offset value is applied correctly, and the desired information is retrieved.

Here is the output of the above job being run:

Info        Message (11:05:12 am) Current system datetime in GMT: 10/6/2014 04:05:12 pm

Info        Message (11:05:12 am) Current system datetime in my timezone: 10/6/2014 11:05:12 am

Info        Message (11:05:12 am) Current system datetime in NY timezone: 10/6/2014 12:05:12 pm

Info        Message (11:05:12 am) NY datetime in MS timezone (incorrect): 10/6/2014 05:05:12 am

Info        Message (11:05:12 am) NY datetime in MS timezone: 10/6/2014 09:05:12 am

For more information on the DateTimeUtil class, please see the following:

You can also view my post on working with utcDateTime fields in select statements.


Related Posts

Recommended Reading:

Stoneridge Software Selected for 2022 Microsoft US Partner Award – Dynamics 365 Business Central

Stoneridge Software is honored to be selected as a 2022 Microsoft US (MSUS) Partner Award winner for Dynamics 365 Business […]

Read the Article
6.29.22 Dynamics CRM

Reduce Manual Data & Increase Productivity with Dynamics 365 for Sales

Dynamics 365 for Sales has a ton of great features to help automate processes for you and your team to […]

Read the Article

Dynamics 365 Business Central Boolean Field Bug Temporary Fix

If you are a Dynamics 365 Business Central cloud (SaaS) customer who is using Edge or Chrome to run the […]

Read the Article

Using Non-Sequential Numbering to Prevent Locking In Your Dynamics 365 Business Central System

Running into locks in your system? Enable non-sequential numbering on your number series to prevent number series locking issues! As […]

Read the Article
6.24.22 Dynamics GP

Uncommonly Used Features: Setting Up Account Categories in Dynamics GP

This is the final part of my current series on Uncommonly Used Features in Dynamics GP. In this post, I […]

Read the Article

Increase User Productivity in Dynamics 365 Business Central with These 10 Tips

There are constantly evolving ways for you to increase user productivity in Dynamics 365 Business Central. Here are 10 tips […]

Read the Article

Star Tribune Lists Stoneridge as a Top 200 Workplace for 2022

Stoneridge Software’s emphasis on creating a positive and flexible culture has earned recognition as a top workplace in Minnesota. The […]

Read the Article
6.14.22 Dynamics GP

Uncommonly Used Features – Reconciling Sub-ledger to GL using the Reconcile Routines in Dynamics GP

As we continue the uncommonly used features series, with this post I want to show you how to reconcile your […]

Read the Article

Organize and Prioritize Your Resources with Dynamics 365 Field Service

As a manager, Dynamics 365 Field Service lets you optimize the use of your employees, their skillsets, and other resources […]

Read the Article

Start the Conversation

It’s our mission to help clients win. We’d love to talk to you about the right business solutions to help you achieve your goals.

Subscribe To Our Blog

Sign up to get periodic updates on the latest posts.

Thank you for subscribing!