Date and time
Correctly understanding where the date and time are sourced and applied is important for getting the most out of PageSeeder. The orderly processing of edits or comments is critical to efficient collaboration, but it isn’t always straightforward with globally distributed group members.
The purpose of this article is to help developers find more specific information about how PageSeeder processes date and time and provide some direction where the date and time are outside the control of the system.
ISO format
Date and time in the system are represented using ISO 8601 extended format.
More specifically, PageSeeder only uses the following representations:
| Format | Example | Precision | |
|---|---|---|---|
| Date | YYYY-MM-DD | 2016-04-21 | Day |
| Time | hh:mm:ss | 09:21:38 | Second |
| Datetime | YYYY-MM-DDThh:mm:ss | 2016-04-21T09:21:38 | Second |
Precision
Most time and datetime values are returned with second precision.
If they have millisecond precision in the system, as is the case for documents modification times, the value is truncated when returned in the API.
Some time and datetime fields can only be set to the minute through the user interface. PageSeeder doesn’t keep track of the original precision and still includes the seconds component.
Timezone
Dates and times are often followed by a timezone designator in the form ±hh:mm. When the timezone is included, PageSeeder includes both the hour and minute components representing the offset from UTC in the local time of the server.
For example, if the PageSeeder is located in Sydney, the example datetime would be represented as 2016-04-21T09:21:38+10:00.
Exceptions
Possible exceptions are:
- Dates created by external applications such as email clients or third party developers.
- Dates in PageSeeder content or information inherited from the host operating system.
End users
Format
Since ISO 8601 is primarily an interchange format, dates and times aren’t particularly user friendly. Therefore, PageSeeder formats dates and times for end users in a more readable format.
For example:
2016-04-21T09:21:38 is displayed as “21 April 2016 at 9:21:38 AM”.
The accuracy displayed to end users might differ from the accuracy in the system. Generally, the accuracy decreases for events in the distant past or future.
Local time in user interface
To display dates and times which are meaningful to end users, the timezone is adjusted based on the offset from UTC of a user’s local timezone as advertised by the browser.
In other words, a user located in New York sees dates and times in PageSeeder in the Eastern Daylight Time (EDT), so the previous example date (in the +10:00 timezone) would then be 2016-04-20T19:21:38-04:00 or “20 April 2016 at 7:21:38 PM”.
The local offset in minutes is stored in the ps.timezone cookie.
Server time in emails
Since PageSeeder doesn’t keep track of users’ location, dates and times in emails are always displayed in the server time.
Set the server to the timezone of where most end users are located.
Potential issues
When the server date and time are not properly coordinated with external applications, developers might see issues relating to when:
- Comments or tasks are created or updated.
- Document edits have been made or versioned.
- Incidents have been logged.
Because problems like these are a potential source of support issues, it is recommended that some effort be made to create a policy before development starts and have the server time automatically updated correctly.