Time Zones Conventions

This page details the 3 conventions for handling time zones in OpenMRS on both the client and server sides.

(1) Server → Client: RFC 3339

The server should send UTC dates formatted as RFC 3339 to the client. 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 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));

 Or in old standard Java 7:

Date date = ..
String rfc3339Date = SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSZ").format(date);

The latter is the approach used by the REST Web Services module, see here.

(2) Client → Server: ISO 8601

The client should send dates 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

(3) Client Display: In Local Timezone

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 time zone.

This is very straightforward to do in JavaScript as this just works with a RFC 3339 formatted date:

var localDate = new Date("2021-01-29T13:51:03Z");