This page details the 3 conventions for handling time zones in OpenMRS on both the client and server sides.
| Table of Contents | ||
|---|---|---|
|
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 does not include timezone information in most cases. Also, historically, these times are assumed to be stored in the local time of the server. The lack of absolute times (with timezone) causes problems when servers are used across timezones, when client & server are in different timezones, when timezone for the location changes (e.g., a server in a location that observes daylight savings time), and when transferring data between servers in different timezones.
Over time (pun intended), OpenMRS should evolve toward using absolute times in the database (i.e., using data types that include a timezone rather than leaving it to assumption/convention).
...
- Whenever feasible, any newly created tables should use a datatype that includes timezone (e.g., MySQL's
TIMESTAMP). - 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 latter is the approach used by the REST Web Services module, see here.
...
Client → Server: ISO 8601
| The client should send ISO 8601 formatted dates to the server. |
...
This also means that the server should be ready to parse ISO 8601 formatted dates sent by the client.
See for example how this is done in the REST WS module: https://github.com/openmrs/openmrs-module-webservices.rest/blob/a32a4336c4166153a6769f20c9281645648e70e1/omod-common/src/main/java/org/openmrs/module/webservices/rest/web/ConversionUtil.java#L239-L243
...
Client Display: In Local Time Zone
| The client should display dates in the local time zone of the user. |
...