You can use this page to decide whether a MDriven Turnkey date and time should remain the value the user entered or represent an instant that must be shown in different time zones.
Choose the meaning before you model the value
A date and time value can mean two different things. Choose which one it means before relying on browser time-zone conversion.
| Meaning | Use it when | Example | Time-zone owner |
|---|---|---|---|
| Wall-clock date and time | The entered date and time is meaningful as written. | A meeting at an airport is shown as 2015-08-03 12:00 in that airport's local time.
|
A business concept in the model, such as the airport or event location. |
| Instant in time | One occurrence must be presented at the corresponding local time for different viewers. | A webcast starts at 2015-08-03 12:00 in GMT+2 and should be shown as 2015-08-03 19:00 to a viewer in Korea.
|
The event or publishing context must state the intended time zone. |
UTC (Coordinated Universal Time) is a common reference time. A time-zone offset is the difference from UTC, such as GMT+2. The offset can change during the year where daylight-saving time applies.
For most business values, preserve the date and time as the user entered it. Do not let the browser location silently redefine what the value means. If a time zone matters, model or otherwise provide the information that identifies the relevant zone.
Why browser conversion can change a value
JavaScript Date is designed around the time zone of the browser that executes it. A browser in Sweden, for example, can interpret 2015-01-01 as local time at UTC+1. If that value is then converted to UTC for storage, it can become 2014-12-31 23:00.
That conversion is inappropriate when the intended value is the wall-clock value 2015-01-01. The browser's location is not necessarily the location or context that owns the time zone.
Do not calculate offsets from the current date
Do not use a current browser offset, such as the result of d.getTimezoneOffset(), as a general correction for another date. Daylight-saving rules mean that an offset at the time of entry can differ from the offset on the date being entered.
For example, a user entering a summer appointment during winter can be one hour wrong in a zone that changes its daylight-saving offset. The relevant zone and the relevant date determine the offset; the browser's current offset does not.
Model common scenarios
Flights and other location-based schedules
Show a connecting flight in the local time at the connecting airport. The airport's location owns the time-zone meaning, not the location of the browser used to enter or read the schedule.
For example, a user in another country who reads 12:00 for a connection needs to understand that it is 12:00 at the airport. Store or model the information that explains that context alongside the schedule.
Events viewed across locations
A webcast can represent one instant that viewers should see in their own local time. Entering 2015-08-03 12:00 is not enough by itself: the application must also know that the publisher meant GMT+2.
Do not infer that zone from where the publisher's browser happens to be. If the publisher travels to London, entering the same text in a browser there can otherwise represent a different instant from noon in Stockholm.
Current MDriven Turnkey handling
MDriven Turnkey stores times and dates in UTC in the database and streams them in UTC to the Angular application. To preserve the entered wall-clock value, Turnkey handles the incoming UTC value as local for JavaScript display rather than allowing JavaScript to convert it for the browser's time zone.
When JavaScript updates a DateTime, Turnkey treats the value as expressed in UTC rather than as a browser-local value, then sends it back to the server in UTC format.
The practical result is that a date and time can move between the Turnkey user interface, server, and database without shifting merely because the browser is in a +X or -X time zone. This behavior supports values that should remain as entered.
Select the right data type
Use DateTime when the user edits a date. Use TimeSpan when only a time part is needed or when the user edits a time in isolation. See Documentation:Date vs Time for the datatype guidance.
If your user interface receives a time as text, parse and validate it before updating a date-time value. The OCL tryParse operator returns null for invalid date or time text instead of failing. For an example of separating hour and minute text before updating a DateTime value, see Documentation:Split time string to value.
Design checklist
- State whether each attribute represents a wall-clock value or an instant.
- For a wall-clock value, preserve the entered date and time; do not base its meaning on the browser's location.
- For an instant, provide the intended time-zone context. Do not assume the publisher's browser zone is correct.
- Test dates on both sides of a daylight-saving change.
- Test entry and display from browsers in different time zones.
- When exchanging date and time values through a REST endpoint, define the meaning and expected format for the integration. See HowTos:Expose REST Service and Documentation:Rest API.