Tips for handling date values in Outlook add-ins

The Office JavaScript API uses the JavaScript Date object for most of the storage and retrieval of dates and times.

The Date object provides methods such as getUTCDate, getUTCHour, getUTCMinutes, and toUTCString, which return the requested date or time value according to Universal Coordinated Time (UTC) time.

It also provides other methods such as getDate, getHour, getMinutes, and toString, which return the requested date or time according to "local time".

The concept of "local time" is largely determined by the browser and operating system on the client computer. For instance, on most browsers running on a Windows-based client computer, a JavaScript call to getDate, returns a date based on the time zone set in Windows on the client computer.

The following example creates myLocalDate, which is a Date object in local time, and calls toUTCString to convert that date to a date string in UTC.

// Create and get the current date represented 
// in the client computer time zone.
const myLocalDate = new Date (); 

// Convert the Date value in the client computer time zone
// to a date string in UTC, and display the string.
document.write ("The current UTC time is " + 
    myLocalDate.toUTCString());

While you can use the JavaScript Date object to get a date or time value based on UTC or the client computer time zone, the Date object is limited in one respect - it doesn't provide methods to return a date or time value for any other specific time zone. For example, if your client computer is set to be on Eastern Standard Time (EST), there is no Date method that allows you to get the hour value other than in EST or UTC, such as Pacific Standard Time (PST).

Date-related features for Outlook add-ins

The aforementioned JavaScript limitation has an implication for you when you use the Office JavaScript API to handle date or time values in add-ins that run in Outlook on Windows (classic or new (preview)), on Mac, on the web, or on mobile devices.

Time zones for Outlook clients

For clarity, let's define the time zones in question.

Because Outlook on Windows and on Mac uses the client computer time zone, and the user interface of Outlook on the web, new Outlook on Windows (preview), and mobile devices uses the EAC time zone, the local time for the same add-in installed on the same mailbox can be different depending on which platform your Outlook client is running. As an Outlook add-in developer, you should appropriately input and output date values so that those values are always consistent with the time zone that the user expects on the corresponding client.

Date-related API

The following are the properties and methods in the Office JavaScript API that support date-related features.

Helper methods for date-related scenarios

The local time for a user in Outlook on the web, on mobile devices, and in new Outlook on Windows (preview) can be different from that in Outlook on Windows and on Mac, but the JavaScript Date object supports converting to only the client computer time zone or UTC. To overcome this, the Office JavaScript API provides two helper methods: Office.context.mailbox.convertToLocalClientTime and Office.context.mailbox.convertToUtcClientTime.

These helper methods take care of any need to handle date or time differently for the following two date-related scenarios in Outlook on Windows, on Mac, on the web, on mobile devices, and in new Outlook on Windows (preview), thus reinforcing "write-once" for different clients of your add-in.

Scenario A: Displaying item creation or modified time

If you are displaying the item creation time (Item.dateTimeCreated) or modification time (Item.dateTimeModifiedin the user interface, first use convertToLocalClientTime to convert the Date object provided by these properties to obtain a dictionary representation in the appropriate local time. Then display the parts of the dictionary date. The following is an example of this scenario.

// This date is UTC-correct.
const myDate = Office.context.mailbox.item.dateTimeCreated;

// Call helper method to get date in dictionary format, 
// represented in the appropriate local time.
// In Outlook on Windows and on Mac, this dictionary format 
// is in the client computer time zone.
// In Outlook on the web, on mobile devices, or in new Outlook on Windows (preview),
// this dictionary format is in the EAC time zone.
const myLocalDictionaryDate = Office.context.mailbox.convertToLocalClientTime(myDate);

// Display different parts of the dictionary date.
document.write ("The item was created at " + myLocalDictionaryDate["hours"] + 
    ":" + myLocalDictionaryDate["minutes"]);)

Note that convertToLocalClientTime takes care of the difference between Outlook on Windows or on Mac and Outlook on the web, on mobile devices, or new Outlook on Windows (preview).

• If convertToLocalClientTime detects the current application is Outlook on Windows or on Mac, the method converts the Date representation to a dictionary representation in the same client computer time zone, consistent with the rest of the Outlook on Windows or on Mac user interface.

• If convertToLocalClientTime detects the current application is Outlook on the web, on mobile devices, or new Outlook on Windows (preview), the method converts the UTC-correct Date representation to a dictionary format in the EAC time zone, consistent with the rest of the user interfaces of these Outlook clients.

Scenario B: Displaying start and end dates in a new appointment form

If you are obtaining as input different parts of a date-time value represented in the local time, and would like to provide this dictionary input value as a start or end time in an appointment form, first use the convertToUtcClientTime helper method to convert the dictionary value to a UTC-correct Date object.

In the following example, assume myLocalDictionaryStartDate and myLocalDictionaryEndDate are date-time values in dictionary format that you have obtained from the user. These values are based on the local time, dependent on the client platform.

const myUTCCorrectStartDate = Office.context.mailbox.convertToUtcClientTime(myLocalDictionaryStartDate);
const myUTCCorrectEndDate = Office.context.mailbox.convertToUtcClientTime(myLocalDictionaryEndDate);

The resultant values, myUTCCorrectStartDate and myUTCCorrectEndDate, are UTC-correct. Then, pass these Date objects as arguments for the start and end parameters of the Mailbox.displayNewAppointmentForm method to display the new appointment form.

Note that convertToUtcClientTime takes care of the difference between Outlook on Windows or on Mac and Outlook on the web, on mobile devices, or new Outlook on Windows (preview):

• If convertToUtcClientTime detects the current application is Outlook on Windows or on Mac, the method simply converts the dictionary representation to a Date object. This Date object is UTC-correct, as expected by displayNewAppointmentForm.

• If convertToUtcClientTime detects the current application is Outlook on the web, on mobile devices, or new Outlook on Windows (preview), the method converts the dictionary format of the date and time values expressed in the EAC time zone to a Date object. This Date object is UTC-correct, as expected by displayNewAppointmentForm.

See also

• Deploy and install Outlook add-ins for testing