Skip to content

Changes

Page history
Update Event Time Zone Implementation Planning authored by totten's avatar totten
Show whitespace changes
Inline Side-by-side
Event-Time-Zone-Implementation-Planning.md
View page @ 65c94338
## Original changes
[[_TOC_]]
## Glossary
* __Time Zone__: The *time zone* is a social/political/geographical construct; within some geographic zone, there is a shared norm for tracking time.
* (_Ex: "The adjacent states of Iowa, Missouri, and Illinois follow the exact same rules for tracking time. They are in the same `US/Central` timezone."_)
* __Time Offset__: The *time offset* is a numerical value (eg `+0400` or `-0200`). To convert between timezones, you need to identify the relevant offsets.
* (_Ex: "During winter 2020, the `US/Central` timezone uses an offset `-0600`; during summer 2020, it uses `-0500`."_)
* __Time Perspective__: Dates and times are subjective; the same date/time can present with different values depending on one's timezone. While there are many possible perspectives on an `Event`, we define three key perspectives:
* The __nominal__ date/time perspective would appear on a printed pamphlet when advertising an `Event`. This is expressed in the *event-specific timezone*.
* The __canonical__ date/time perspective would drive automated processing (notifications, sorting, etc) on a shared/central server. This is expressed in a *universal timezone* (eg UTC/GMT).
* The __personal__ date/time perspective would appear when you lookup a webinar on the calendar of your personal smartphone. This is expressed based on the attendee's timezone.
## Event-TZ v1: Original changes
The Event time zone change set from included:
......@@ -13,9 +26,12 @@ The Event time zone change set from included:
The TIMESTAMP conversion was done so that the front-end interface would require no changes in order to continue working with unknown systems that were not aware of the timezone change (i.e. the event time would appear in the system timezone, but be stored as UTC). This can not be automatically added to the DAO, so systems bypassing the API and BAO work under the assumption that they're in the CRM timezone or the timezone doesn't matter.
## Proposed solution
## Event-TZ v2: Proposed solution
totten suggests leaving the existing start and end dates ~~as is~~ _in their original form_ (`DATETIME` expressed in _nominal/advertised_ TZ), and adding additional columns with the offset information in a decided timezone. This will work best for the consideration of "systems bypassing the API and BAO work under the assumption that they're in the CRM timezone or the timezone doesn't matter."
The start and end dates have traditionally provided the _nominal perspective_ (*the date/time advertised on a printed pamphlet*). These fields should stay in their original form (`DATETIME`, nominal). Additionally, new columns should (1) store the nominal timezone (`event_tz`) and (2) store the canonical time. This has a few merits:
* It provides backward-compatibility for [relevant screens/tools/APIs](#affected) -- by returning the start and end dates in the same way. (_If you call `Event.get +w id=4 +s start_date` in v5.30 and v5.60, you should get the same value._)
* Screens may be updated incrementally to give richer information (using any of the columns, depending on the downstream goals+preferences).
Changes required to support timezones:
......@@ -37,6 +53,7 @@ Changes required to support timezones:
7. Changes to various system workflow message to display timezone information with event messages †
8. Additional fields to the API to show the event timezone †
† Already implemented in original PR
†† Implementation in original PR exists, but will need adjustment
......@@ -45,25 +62,6 @@ Changes required to support timezones:
TODO: Document the various Test Cases required, including the DST edge cases.
## Potential Impact on Wider CiviCRM Ecosystem.
With the plan to add new columns, the only relevant impact here should be that a timezone field and GMT datetime fields become available to allow timezone considerations.
1. Drupal / Views
1. Drupal / Webforms
1. WordPress / Event Organiser
1. CiviMobile
1. Extended Reports
1. EventBrite Integration / com.joineryhq.eventbrite
1. Event Calendar / com.osseed.eventcalendar
1. QR code check-in / net.ourpowerbase.qrcodecheckin
1. Summary Fields / net.ourpowerbase.sumfields
1. CiviDiscount
1. CiviRules
1. Form Processor & Action Provider
1. Data Processor
1. SearchKit
1. Afform
## Manageability
......@@ -77,3 +75,31 @@ There were some difficulties it would be nice to avoid in future, related to the
3. (Theoretical/Opinion) It is offputting and difficult to do code review for such PRs. Perhaps fewer people than normal looked at the code.
It was mentioned at one point in the review to break it up, but it seemed difficult to do at the time. Perhaps if being refactored it can be planned in a way this can be achieved.
<a name="affected"></a>
## Appendix: Affected components
All of the following components may make use of the dates+times on `civicrm_event` records.
* Core Components / Extensions / Plugins
* CiviEvent: Web UI (*frontend and backend UIs; searches*)
* CiviEvent: Messaging (*message-templates; tokens; scheduled reminders*)
* CiviReport
* Drupal: Views
* Ext: Afform
* Ext: SearchKit
* Contrib Components / Extensions / Plugins
* Action Provider
* CiviDiscount
* CiviMobile
* CiviRules
* Data Processor
* Drupal: Entity (`civicrm_entity`)
* Drupal: Webform (`webform_civicrm`)
* Event Calendar (`com.osseed.eventcalendar`)
* EventBrite Integration (`com.joineryhq.eventbrite`)
* Extended Reports
* Form Processor
* QR code check-in (`net.ourpowerbase.qrcodecheckin`)
* Summary Fields (`net.ourpowerbase.sumfields`)
* WordPress / Event Organiser