Page Comparison

...

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 is the local time of the serverserver time, with no associated time zone information. The lack of absolute times (with timezone) causes problems when servers are used across timezones, when client & server are in different timezones, when timezone offset for the a 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), 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.

...

The server should send UTC dates formatted as RFC 3339 to the client. Eg. RFC 3339 is ISO 8601 with a Z  offset suffix. Eg. "2021-01-29T13:51:03Z" .

It is the responsibility of the server code to translate any date from the server time zone to a string formatted as RFC 3339. There are definitely multiple ways of doing that, for instance using This can be accomplmished in Joda-Time:

import static org.joda.time.DateTimeZone.UTC;
import org.joda.time.DateTime;
import org.joda.time.format.ISODateTimeFormat;

...

Date date = ..
String rfc3339Date = ISODateTimeFormat.dateTime().print(new DateTime(date.getTime(), UTC));

...

Date date = ..
StringDateFormat rfc3339Daterfc3339Format = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ");
rfc3339Format.setTimeZone(TimeZone.getTimeZone("UTC"));
String rfc3339Date = rfc3339Format.format(date);

...

Client → Server:

...

RFC 3339

The client should send UTC dates formatted as RFC 3339 to the server that are formatted with ISO 8601 such that date, time and time zone information are always available.
Eg. "2021-01-29T16:51:03+03:00".

TODO: Provide an example on how best to do that in JS

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. All APIs must be able to parse RFC 3339 dates.

Client Display: In Local Time Zone

...

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.

This is very straightforward to do in JavaScript as this just works with a RFC 3339 formatted date:If writing client-side code, please familiarize yourself with JavaScript's native support for locale-specific date formatting. Key functions are toLocaleString and its cousins, toLocaleDateString, toLocaleTimeString, and Intl.DateTimeFormat.

varconst localDatedisplayDate = new Date("2021-01-29T13:51:03Z").toLocaleString();