...
When it is necessary to compare the business date to an instant in time (now for example), first convert the instant into a LocalDate (thereby extracting just the date part from the timestamp), making a "best guess" about the timezone to use, and then compare. Rough steps for what timezone to use:
...
- For instant dates, the client should send timestamps in UTC timezone.
- For business dates, the client should send dates with no time or timezone information.
When it is necessary to compare the Avoid comparing a business date to an instant in time (now for example), first convert the instant into a JavaScript date, making a "best guess" about the timezone to use, and then compare. Rough steps for what timezone to use:
- If the code is respective to a user, use the timezone in the user's profile.
- If respective to a facility, use the facility's timezone (Note: this would be a new feature, as facility timezone profiles were not in v2).
- If neither, use an implementation default timezone (some configuration setting in the system).
. The reason to avoid this comparison is that the implementation calendar might use a non-gregorian calendar, so processing comparing these values needs domain expertise. If there is a need to compare a business date to a instance date, the implementation default timezone should be used — but we currently don't have or recommend a pattern for how this would be done.
Example 1: Instant Date
The example used here is the submitted date of a requisition.
...
- Persistent Storage - in the processing_periods table, there would be a startdate column of type date.
- Java Backend Code - in the ProcessingPeriod object, there would be a startDate field of class LocalDate. When persisting, startDate would be stored as date. When retrieving, the a LocalDate object would be created based on the date, which is then used for startDate.
- If the startDate needed to be compared to now, to see if the processing period had already started, LocalDate.now(timezone) would be used to get a LocalDate version of now. The timezone specified would be the implementation default configuration setting (or facility timezone setting if there was one). Then the now LocalDate would be compared to startDate to determine if the startDate was before (or at) the now date.
- API Interface
- Serialization: convert the LocalDate into a String of ISO-8601 format, then return in the response.
- Deserialization: convert the String into a LocalDate object. This is what is assigned to startDate.
- Frontend Client
- When displaying to the user, use the date as-is.
- When calling the APIs, make sure the date does not have time or timezone information.
- To compare the start date with now, the frontend client would do something similar as described in the Java Backend Code section, except using JavaScript date objects and methodsDon't compare a business date with an instant date.
Appendix: Survey of Usage
...