This page details the conventions for handling time zones in OpenMRS on both the client and server sides.
Server: Strive to always specify timezone
For historic reasons, the majority of timestamps within the OpenMRS database use MySQL's
DATETIME instead of
TIMESTAMP , meaning the date & time stored is the local server time, with no associated time zone information. The lack of absolute times causes problems when servers are used across timezones, when client & server are in different timezones, when offset for a location changes (e.g., a server in a location that observes daylight savings time), and when transferring data between servers in different timezones.
OpenMRS should evolve toward using absolute times in the database, whether specified as UTC or with an offset.
- Whenever feasible, any newly created tables should use a datatype that includes timezone (e.g., MySQL's
TIMESTAMP, which stores in UTC).
- When code is being refactored and there's an opportunity to convert from ambiguous times (without timestamp) to absolute times (with timestamp) in the database, we should take them. These changes need to be sensitive not only to how the system behaves going forward, but how the change would affect implementations with existing data.
Ultimately, we'd like to store and use UTC by default within OpenMRS servers/databases; however, we need to work our way there in a way that doesn't put existing implementations (with timezone-less data and assumptions data are not UTC) at risk.
Server → Client: RFC 3339
|The server should send RFC 3339 formatted dates to the client.|
The server should send UTC dates formatted as RFC 3339 to the client. RFC 3339 is ISO 8601 with a
Z offset suffix. Eg.
It is the responsibility of the server code to translate any date from the server time zone to a string formatted as RFC 3339. This can be accomplmished in Joda-Time:
Or in old standard Java 7:
Client → Server: RFC 3339
|The client should send RFC 3339 formatted dates to the server.|
The client should send UTC dates formatted as RFC 3339 to the server. All APIs must be able to parse RFC 3339 dates.
Client Display: In Local Time Zone
|The client should display dates in the local time zone of the user.|
The client should parse RFC 3339 formatted dates to make it readable and useful to the user. In almost all circumstances users should see dates that are local to them, in accordance to their client or local system's time zone.
toLocaleString and its cousins,