Datetime formatting and timezones
Main idea
We all know the world is divided in different timezones. And just like we adjust ourselves to the timezone of the country we go on holiday to, Peripass should also adjust itself depending on the timezone of the location of the yard of our customers.
Therefore Peripass will use the timezone the user is located in. To determine this timezone, Peripass will use the timezone of the browser of the user. By default the timezone used by a browser follows the location of a user.
What does this mean in practice?
All datetimes in the management portal are displayed in the timezone of the user.
Moving to a different timezone, eg on holiday, will change all the timestamps being displayed to that timezone
Peripass adjusts automatic to daylight saving time and back.
The API can handle different timezones as input (POST or PUT) and is consistent in its output
How does it work?
All timestamps in Peripass are stored in UTC in the database.
UTC is the world time standard by which the world regulates clocks and time. See Coordinated Universal Time - Wikipedia for information about UTC.
When Peripass has to output a timestamp (visualization in the management portal, response API, autofill field) the UTC value that is stored in the database is converted to the correct timezone.
Timezones and daylight saving time
A timezone consists out of the following parts:
The county or geographic region for which the timezone is applicable
The offset from UTC
If daylight saving time is applicable
All this information is used by Peripass to determine the correct conversion from UTC to the tenant timezone.
When daylight saving time is applicable the offset depends on when the timestamp takes place. The following examples are for the timezone Europe/Brussels:
6 July 2022 at 13:38 (during daylight saving time): 2022-07-06T13:38:00+02:00
6 December 2022 at 9:30 (not during daylight saving time): 2022-12-06T09:30:00+01:00
Autofill fields and dates / datetimes
When using autofill fields that have a date or datetime as value two parameters can be added to set how these are fields are outputted: the formatting and the timezone.
To avoid unwanted default behavior, it is recommended to always use formatting and choose a timezone when using autofill field.
Formatting dates and datetimes
When using autofill fields for timestamp fields, a format can be added:
%timestamp|format%
The timestamp can also be converted to another timezone:
%timestamp|format|timezone-identifier%Advised:
%PersonStatusTimeStamp.Logged|iso-datetime|UTC%
Examples:
%PersonStatusTimeStamp.Logged|iso-datetime|Europe/London%%PersonStatusTimeStamp.Logged|iso-date|America/Los_Angeles%%PersonStatusTimeStamp.Logged|local-datetime|UTC%
The timezone identifier must be a valid IANA timezone identifier
Peripass standard formats
Peripass includes some standard date and time formats:
Placeholder | Description | Examples |
|---|---|---|
iso-datetime | ISO8601 compliant format for datetime, this always includes the offset. In some older implementations this is used as |o|. Thus |
|
iso-date | ISO8601 compliant format for date. This date uses the timezone of the user by default! To send the UTC date, convert the datetime to UTC: |
|
iso-time | ISO8601 compliant format for time. This date uses the timezone of the user by default! To send the UTC time, convert the datetime to UTC: |
|
local-datetime | A local datetime representation. This uses the language of the visitor to find the culture-specific formatting. |
|
local-date | A local date representation. This uses the language of the visitor to find the culture-specific formatting. |
|
local-time | A local time representation. This uses the language of the visitor to find the culture-specific formatting. |
|
Common use-cases
Use case | Format to use | Examples |
|---|---|---|
Send an ISO timestamp, in UTC. |
|
|
Send an ISO timestamp, including the correct offset. |
or
|
|
Send the local date in ISO format (without the offset from UTC) |
|
|
Send the datetime in a human readable format |
|
|
Send the date in a human readable format |
|
|
Send the time in a human readable format |
|
|
Creating your own format
You can also create your own format such as 16/06/2023 16h (dd'/'MM'/'yyyy HH'h')
In a custom format:
You can use custom patterns
Use text - ALL TEXT SHOULD BE QUOTED BY SINGLE QUOTES!
❌
dd/MM/yyyy→ this is wrong because/is not quoted → ✅dd'/'MM'/'yyyy❌
HH:mm:ss→ this is wrong because:is not quoted → ✅HH':'mm':'ss❌
HHh→ this is wrong becausehis not quoted → ✅HH'h'(16h)
These are the currently supported custom patterns:
Pattern | What? | Example |
|---|---|---|
| Four-digit year | 2023 |
| Two-digit year | 23 |
| Month as a number.
| June: June: |
| Day of month as a number.
| 6th of the month: 6th of the month: |
| The hour of day in the 24-hour clock.
| 7.30am: |
| The hour of day in the 12-hour clock.
| 7.30am: |
| Number of minutes within the hour.
| 5 minutes: |
| The fractional second part of the time (milliseconds, nanoseconds). Up to 9 characters.
| 1 second, 340 milliseconds: 1 second, 340 milliseconds: |
The API and timestamps
The situation below describes the long term documentation and is applicable if the hidden setting is set to true. Older tenants can have the hidden setting set to false. In this situation the offset is not always included in the response or GET.
All responses with datetimes are consistent (tenant time + offset)
All post/put calls support 2 flavours
If an offset is given, the datetime will be transformed to UTC
If no offset is given, the datetime will be assumed in tenant time and transformed to UTC
Timezones and profile validity
Visitor creation
A profile is valid for a specific day or range of days and is not linked to timezones.
Ad hoc visitor creation during registration on the kiosk
If an ad hoc visitor is created during registration at a kiosk, the visitor’s profile will be valid for "today," where "today" is determined by the timezone set on the (browser of the) kiosk.
Manual Creation via Management Portal
When a visitor is manually created in the management portal, and the profile is set to be active "today," the validity is based on the timezone of the browser being used by the user.
API-Based Visitor Creation
If a visitor is created via the API, the profile will be valid for the specified date. This date remains independent of any timezone.
Visitor registration
Registration on physical kiosk
When a visitor registers at the kiosk, we verify if they have an active profile for "today." The definition of "today" is based on the timezone of the kiosk’s browser settings.
This could be improved by validating against a timezone that is set in the site configuration (not implemented at the moment).
Registration on Mobile Driver Portal
When a user registers using the Mobile Driver Portal, the system defaults to the tenant's timezone for profile validation.
The disadvantage of having not time context with profile validities
A notable side effect occurs when a driver has booked a slot for 28/01/2025 at 00:00, and the customer enforces strict profile validity (1 day). In this case, if the driver arrives 30 minutes early, they are unable to register because their profile is not yet valid for the new day.
To address this issue, adopting a rolling 24-hour (time-based) profiles could be an option. However, implementing this change would have a significant impact on the codebase. The logic for determining an "active profile" and its validity is deeply embedded across various parts of the system, not just in the registration process.