Time Zones

Introduction

Dates and times in FogBugz can be in three time zones:

• Client (CTZ)
• FogBugz server (STZ)
• Database (UTC)

Best practices suggest that you to store dates and times in Coordinated Universal Time (UTC) in the database.

FogBugz Time Zone Methods

The FogCreek.FogBugz.Plugins.Api.CTimezoneApi provides the following methods related to time zones and time zone conversion. These methods are all accessed via the Plugin base class's instance of the Plugin API, like so: api.TimeZone

Conversions

• CTZFromUTC(DateTime) - Convert a DateTime from a stored UTC value for display to the client (in CTZ)
• STZFromUTC(DateTime) - Convert a DateTime from a stored UTC value to the server's timezone (STZ), e.g. to compare to DateTime.Now
• UTCFromCTZ(DateTime) - Convert a DateTime input by a client's (in CTZ) to universal time (UTC) for storage in the database
• UTCFromSTZ(DateTime) - Convert a DateTime (such as DateTime.Now) from server (STZ) to UTC for storage in the database

Offsets

• CTZOffsetFromUTCSeconds() - Returns the offset between the client's time zone and universal time in seconds
• STZOffsetFromUTCSeconds() - Returns the offset between the server's time zone and universal time in seconds

Strings

• DateDecorator(DateTime) - The date decorator (e.g. 'Today', 'Yesterday', 'Tomorrow') for a date in the client's time zone. Takes an optional argument to decorate dates before one day ago with "Past"
• DateString(DateTime) - Gets the date string (without time) in the client's locale. optional arguments whether to include the date decorator ('Today', 'Yesterday', etc) and whether to decorate dates before one day ago with "Past"
• DateTimeString(DateTime) - Gets the date and time string in the client's locale. optional arguments whether to include the date decorator ('Today', 'Yesterday', etc) and whether to decorate dates before one day ago with "Past"
• TimeString(DateTime) - Gets the time string (without date) in the client's locale
• DateFromString(String) - Convert a string to a date. Does not perform timezone operations
• TimeZoneDisplayName(String) - Gets the display name for the given time zone key (e.g. "Eastern Standard Time"). Returns the display name of the client's time zone if passed no arguments

Example

If your plugin accepts a datetime from the user, you need to convert it to UTC before you store it in the database:

DateTime dtForStorage = api.TimeZone.UTCFromCTZ(dtFromClient);

Note on WikiBlocks

DateTimes in a WikiBlock class will always be treated as server-local FogBugz time. Even if you initialize a DateTime object to a specific UTC date/time, it will be loaded as if it were a date/time in the FogBugz server time zone (STZ).