Date, Time and Time Zone Management

This page describes how Verne stores, displays and uses date and time information. This includes the description of the following:

how Verne uses its system clock to apply a date and time stamp to every transaction,
how Verne stores and uses system timestamps and user entered dates,
how Verne runs the business logic where date and time is involved,
how Verne approaches implementations that span multiple time zones,
how Verne handles users accessing the system from various time zones.

The approach described below is based on our experience with the multi-time zone Verne implementations.

Application Time Zone

A single jurisdiction may span multiple time zones. However regardless of the number of the time zones covered by the jurisdiction, Verne implementation by default would select one centralized regulatory (legislative) time zone form the list of standard time zones (refer to tz database). This is configured as an application time zone setting.

Application time zone determines the current application date and time (UTC offset) as well as time zone abbreviation. Both UTC offset and time zone abbreviation will change automatically if the selected time zone supports standard and daylight saving time. For example, New Zealand implementation will set the application time zone to “Pacific/Auckland” with both the UTC offset and a time zone abbreviation changing from NZST (UTC+12) to NZDT (UTC+13) during daylight saving season.

Browser / User Time Zone

A user interacting with Verne outside of its centralized regulatory time zone, will be transacting using the application clock and NOT their local time. In other words, browser time zone settings are not taken into consideration in Verne.

In the following example UTC date-time is 23 September 2020 23:00:00. Verne application time zone is set to Australia/Sydney where current legislative date-time is 24 September 2020 09:00:00 AEDT.

User browser time zone and their local date-time	Example 1: This user submits an application to change company address, it gets auto-approved.	Example 2: While submitting an application to change company address, this user enters the current date as an effective date of address change
User 1: America/Toronto, 23 September 2020 19:00:00 EDT	In Verne the timestamp of this transaction will be set to 24 September 2020 09:00:00 AEDT This date will appear as being in the future for a user from Toronto	Effective date was entered as 23 September 2020 This means that a new address became effective from the legislative point of view in the beginning of 23 September 2020 in Sydney time, not Toronto
User 2: Pacific/Auckland, 24 September 2020 11:00:00 NZST	In Verne the timestamp of this transaction will be set to 24 September 2020 09:00:00 AEDT This date will appear as being in the past for a user from Auckland	Effective date was entered as 24 September 2020 This will be treated as a future dated address in Sydney time. From the legislative point of view this new address is not yet active.

Application Timestamps and Business Dates

Verne supports the following two types of date and time information:

Application timestamp
Business date / date only

Application Timestamp

Mongo data type: date (for example 25 February 2020 12:35:45 NZDT will be stored as 2020-02-24T23:35:45.677+00:00) | Verne data constraint data type: datetime

Application timestamp is the date and time that is either in the past or in the future representing when the data in Verne has been or will be added or amended. For example

Date and time when transaction that changes company address has been created / saved / edited / submitted / activated
Due date of a scheduled future reminder

Note, that the timestamp of when an entity address change was registered in the system can be different from the date when the address has actually changed in "real life" (outside the software). This signifies the key difference between the application timestamps and business dates.

Application timestamps are set by Verne using current application date and time.

Application timestamps are stored as a point in time, that is UTC (Zulu) time following ISO-8601 standard, for example 2020-02-24T23:35:45.677+00:00. When displayed, UTC timestamp is formatted using application time zone setting and default date-time format. For example, for New Zealand implementation UTC timestamp 2020-02-24T23:35:45.677+00:00 will be displayed as 25 February 2020 12:35:45 NZDT.

Note, that the java library that formats the UTC timestamp into a date-time with time zone abbreviation knows exactly what UTC offset was or will be effective on that specific date, so it can pick the right offset and time zone abbreviation (standard or daylight saving). For example:

	Example 1	Example 2
Date and time as stored in DB	2020-02-24T23:35:45.677+00:00	2020-06-24T23:35:45.677+00:00
Application time zone: America/Toronto	2020-02-24 18:35:45 EST	2020-06-24 19:35:45 EDT
Application time zone: Australia/Sydney	2020-02-25 10:35:45 AEDT	2020-06-24 09:35:45 AEST
Application time zone: Pacific/Auckland	2020-02-25 12:35:45 NZDT	2020-06-24 11:35:45 NZST

Business Date / Date Only

Mongo data type: long (for example 25 February 2020 will be stored as 20200225) | Verne data constraint data type: dateonly

Business date is the date representing an event that has happen or will happen in "real life", quite often this is the start or end date of when a real-life object was effective / active. A real-life object could be a person, a legal entity, or any of their attributes. For example:

Company registration or de-registration date
Person’s date of birth or date of death
Date when a company status, address or name became effective or ceased to be effective
Date when a company director became effective or was ceased
Date an individual has taken a new name
Other user entered dates, e.g. date when something was signed, date overseas company was originally formed, date of the associated court order, shares redemption date

In most cases business dates are entered by the user while populating the online form. They can be back-dated or future-dated and therefore very often are different from the application timestamps of the associated filings. Some business dates can be set by Verne and derived form the current application date, this is usually the case when effective time interval of the real life object or its attributes is driven by the object being registered in the online system. For example, company registration date is set to the date when registration filing was approved in the online register.

Business dates are usually stored without the time component as they represent either the whole day, or its beginning or an end. However there are rare exceptions when business dates would need to record the time component, for example in a securities register.

When business date is displayed, value stored in data base is formatted using default date format, time zone is not displayed where time is absent, but it is assumed to be the legislative time zone of this jurisdiction, regardless of the time zone of the user who is viewing the date.

Business Logic and Searches

Verne runs a variety of business rules and searches that require comparing of recorded dates between each other and with the system clock, as well as applying Business Calendar to calculate due dates and late lodgement fees based on working days set for the jurisdiction.

Application timestamps are compared between each other, with user entered dates or with the system clock in UTC time. For example:

A user is searching for all filings approved in New Zealand on 07 October 2020. Verne converts the search criterion date into UTC assuming it was entered in New Zealand time and will be searching for transactions with activation date between 2020-10-06T11:00:00.000+00:00 (inclusive) and 2020-10-07T11:00:00.000+00:00 (exclusive).
A user is searching for all open tasks submitted for review in New Zealand outside of the office hours 9am – 5pm. Verne stores filing submission dates in UTC and will need to find out for each of the submission date whether it falls within or outside of 9am – 5pm time interval in New Zealand time on that particular day. For example, filing was submitted on 07 October 2020 at 7am NZDT (UTC+13) which is stored as 2020-10-06T18:00:00.000+00:00. To determine if this UTC point in time falls outside of 9am – 5pm time interval in New Zealand, Verne will construct the UTC representation of the office hours on 7th of October 2020, which is 2020-10-06T20:00:00.000+00:00 (7th of October 2020 9am – 13 hr offset) and 2020-10-07T04:00:00.000+00:00 (7th of October 2020 5pm – 13 hr offset). For the filing submitted on the day with standard time (NZST), the UTC offset will be 12 hr.

Business dates are compared between each other, with user entered dates or with the system clock in application time. For example:

A company in New Zealand has changed its registered office address twice since registration: Address 1 was effective from 23 February 2020 when company was registered, Address 2 became effective on 06 October 2020 and company is moving to Address 3 on 25 October 2020. Current date and time in New Zealand is 07 October 2020 10am NZDT (which is 06 October 2020 9pm UTC). Verne uses current application date (not UTC) and comperes it with effective dates of all addresses to determine which address is current, which one is pending or former. In this example, Address 1 is former, Address 2 is current and Address 3 is pending.
A user from New Zealand is creating their user profile in Verne implementation over in Canada. Verne application time zone is set to Canada/Toronto and it is 06 October 2020 over there, while in New Zealand it is 07 October 2020. User must enter date of birth and be at least 18 years of age. User just turned 18. So user enters their date of birth as 07 October 2002. Verne compares it with the current date in the application time zone and determines that the person is not yet 18 years of age, validation fails.

Repeater Start and End Dates

Repeater is an array of records representing:

a list of child items of a parent object (e.g. a list of directors of a company, a list of mobile numbers of a person). This is commonly called a child item repeater.
or a history of values of a certain attribute with only one value being effective at any given point in time (e.g. history of changes of entity name, entity status or registered office address). All of those former values are searchable and are presented as a part of the current entity view. This is commonly called a historical repeater.

Start and End Dates of repeater items form a big cluster of Verne business dates. They may have different names in various scenarios of use and be presented under different labels in UI, but it does not change their meaning:

Start Date (a.k.a. Appointment Date, Effective Date) from business perspective represents the beginning of the day when a specific item became effective. This can be either a child record on a parent (e.g. director appointed on a company) or a new value assigned to an attribute (e.g. a company name changed from A to B).
End Date (a.k.a Ceased Date) from business perspective represents the end of the day when a specific item ceased to be effective. This can be either a child record on a parent (e.g. director ceased on a company) or an attribute’s value being cleared (e.g. an optional company address removed). Next and Previous Pointers are captured instead of the End Date for consecutive changes of the values of a historical repeater attribute. Pointers help keep the chronological order of value changes and eliminate the need to store End Date for each value, as it can be fully derived from the Start Date of the next value. If an End Date is explicitly recorded for a repeater item, then it is used to determine the effective time interval of an item, if it is not recorded – then the Next Pointer is used to derive the End Date. If none are populated then an item has not reached the end of its life yet.

Start and End Dates are treated as business dates and are stored as a string without time component (whether set by a user or the system). The reason is that in real life attribute values do not usually change more than once a day, e.g. if an address, status or name has changed, it means it became effective in the beginning of its Start Date and was effective the whole day each day until another value replaced it. If a director was appointed on a certain day, then he/she was liable for that company from the benign of the day they were appointed and till the very end of the day they were ceased.

Start and End Date can be the same date, it means item was active for this whole day. Start Dates of multiple values of a single attribute can be the same, this is not a common business scenario and is rather an exception, but if it does happen it means that there is uncertainty about what value was actually valid on that day. In this case system timestamps displayed in the filings of associated transactions can be investigated and appropriate decisions made.

Historical Repeater for Mandatory Attributes

For mandatory attributes, such as company name or status, the first value will be set at registration and the Start Date assigned based on registration approval date. Then a new record will be created every time a name or a status are changed. Such records will never have an End Date, as name or status can never be cleared.

For example, the name of this entity has been changed three times:

(+) Entity
    (+) Names
        Name 3   Start Date = 30 Jan 2020                         Previous Value = Name 2
        Name 2   Start Date = 15 Jan 2020   Next Value = Name 3   Previous Value = Name 1
        Name 1   Start Date = 01 Jan 2020   Next Value = Name 2

This is usually displayed to the user in the following way:

    Current Name: Name 3   (Start Date of Name 3 = 30 Jan 2020)
    (+) Name History
        Name 2   (Start Date of Name 2 = 15 Jan 2020 - Start Date of Name 3 minus* one day = 29 Jan 2020)
        Name 1   (Start Date Of Name 1 = 01 Jan 2020 - Start Date of Name 2 minus* one day = 14 Jan 2020)

* If effective date of the next value is the same, then one day is not deducted

Historical Repeater for Optional Attributes

This is a very rare case where a historical repeater is used for an optional attribute. However it can happen. For example, a company can optionally record an address where history of its values is important and must be searchable, as well as displayed as a part of the current entity view. In this case, initially it will behave in the same way as a mandatory repeater, however when the address value is cleared (removed) an End Date will be assigned to the record representing the last value. So this last record will have Start Date, Previous Pointer and an End Date. When in the future such attribute is updated again, the last record will be populated with Next Pointer and a new record will be created with Start Date and Previous Pointer. This will form a gap in the history of value changes which is acceptable for optional attributes.

For example, the optional address of this entity has been changed three times:

(+) Entity
    (+) Optional Address
        Address 4   Start Date = 01 Sep 2020                            Previous Value = Address 3
        {time gap}
        Address 3   Start Date = 30 Jan 2020   Next Value = Address 4   Previous Value = Address 2    End Date = 25 Feb 2020
        Address 2   Start Date = 15 Jan 2020   Next Value = Address 3   Previous Value = Address 1
        Address 1   Start Date = 01 Jan 2020   Next Value = Address 2