Appointment Time Zones
- 5 minutes to read
Time Zone Support
The Scheduler allows you to select the time zone of an appointment and store it in the Appointment.TimeZoneId property. To switch on time zone support, set the SchedulerStorageBase.EnableTimeZones property to true and provide mapping of the Appointment.TimeZoneId property to a data field.
When time zones for appointment are enabled, the default appointment editing form displays the Time Zone button.
You can click the button to display the time zone editor (an instance of the TimeZoneEdit class), which allows you to select a time zone. If the button is not pressed, the time zone of the appointment equals the SchedulerOptionsBehaviorBase.ClientTimeZoneId property value.
An Example of Appointment Data
Consider the following scenario.
The Scheduler Storage is located in Los-Angeles (Pacific Time, UTC-08). By default, the SchedulerStorageBase.TimeZoneId equals the host time zone. So, it has the value “Pacific Standard Time”.
The client application that employs the SchedulerControl runs in New York City (Eastern Time, UTC-04). By default, the SchedulerOptionsBehaviorBase.ClientTimeZoneId equals the time zone in which the application operates. So, it has the value “Eastern Standard Time”.
A recurring appointment is created on March,1 (when no DST shift occurs) at 1AM with one hour duration and a weekly recurrence rule according to which an appointment in a series is repeated each Tuesday and ends after 10 occurrences.
The appointment record has the following fields.
| Field | Value |
|---|---|
| Start | 3/1/2016 1:00:00 |
| End | 3/1/2016 2:00:00 |
| TimeZoneId | Eastern Standard Time |
| RecurrenceInfo | <RecurrenceInfo Start=”03/01/2016 01:00:00” End=”05/03/2016 01:00:00” WeekDays=”4” Id=”0077a5f2-775f-4984-8ecd-6736c46bbb93” Range=”1” Type=”1” FirstDayOfWeek=”0” Version=”1” /> |
DateTime Saving Mode
The datetime value listed in the appointment record is the same as the time of the appointment displayed in the Eastern Standard Time zone. An appointment saved from clients with different time zones will have Start and End times that cannot be compared independently without the time zone information. This is the default behavior that is specified by the SchedulerStorageBase.DateTimeSavingMode set to the DateTimeSavingMode.Appointment value.
However, you can “normalize” the Start and End times to make them comparable for clients in different time zones. This will help you make your data queries more effective. If you set the SchedulerStorageBase.DateTimeSavingMode to the DateTimeSavingMode.Storage value, the dates are converted to the Storage time zone and subsequently written to the data record. Thus, all datetime values will be in the same time zone and can be easily compared. The following table is an appointment data record created after the Storage datetime saving mode is switched on.
| Field | Value |
|---|---|
| Start | 2/29/2016 22:00:00 |
| End | 2/29/2016 23:00:00 |
| TimeZoneId | Eastern Standard Time |
| RecurrenceInfo | <RecurrenceInfo Start=”02/29/2016 22:00:00” End=”05/02/2016 22:00:00” WeekDays=”4” Id=”0077a5f2-775f-4984-8ecd-6736c46bbb93” Range=”1” Type=”1” FirstDayOfWeek=”0” Version=”1” /> |
This data record can be interpreted correctly only if the following conditions are met.,
- The Storage has the SchedulerStorageBase.TimeZoneId property set to the same value as this property had when the appointment was created, i.e. “Pacific Standard Time”
- The SchedulerStorageBase.DateTimeSavingMode is set to the DateTimeSavingMode.Storage value.
Important
A Storage in default (“Appointment“) datetime saving mode assumes that the datetime values are for the time zone specified in the TimeZoneId field of an appointment, i.e., Eastern Standard Time in our example, and will display them converted from Eastern time to the Storage time zone. Therefore, the data will be displayed incorrectly. Thus, you should not switch from one mode to another when working with the same data table.
Time Zones and Recurring Appointments
When you are working with recurring appointments, you have to set the time zone in the recurrence dialog, not on the appointment form.
When you click the Time Zone button, the time zone editor is displayed on the appointment form. However, if you have recurrence selected, the time zone editor is disabled on the appointment form and enabled in the recurrence dialog.
Time Zone support should be enabled when working with recurring appointments. If time zones are disabled, the recurring series is calculated using the Storage time zone. This may result in a behavior that confuses the end-user, as illustrated in the following scenario.
Suppose you have the Storage and SchedulerControl client application with time zones set as mentioned in the beginning of this article. However, TimeZone mapping is null or the SchedulerStorageBase.EnableTimeZones property is set to false, so an appointment does not have a time zone. Invoke a recurrence editing form and create a recurring appointment on March,1 (when no DST shift occurs) at 1AM with a one-hour duration and a weekly recurrence rule. You may notice that when the form is displayed, the Monday check box on the form is checked instead of Tuesday. But the March, 1 is Tuesday, so you check Tuesday instead, close the form and save changes. Now, take a closer look at the created appointment in the Scheduler view.
The recurring appointment is shown every Wednesday, instead of Tuesday. Its recurrence form shows the Tuesday weekly rule. The reason is that in the Pacific Time Zone, the recurrence pattern starts on 2/29/2016 22:00:00, which is Monday. The recurrence engine finds the first Tuesday, which is 3/1/2016 22:00:00, and calculates the client appointment Start time for display by using a conversion from Pacific to Eastern resulting in 3/2/2016 01:00:00 time which is Wednesday.
The appointment data record is shown below.
| Field | Value |
|---|---|
| Start | 2/29/2016 22:00:00 |
| End | 2/29/2016 23:00:00 |
| TimeZoneId | |
| RecurrenceInfo | <RecurrenceInfo Start=”02/29/2016 22:00:00” End=”05/03/2016 22:00:00” WeekDays=”4” Id=”0077a5f2-775f-4984-8ecd-6736c46bbb93” Range=”1” Type=”1” FirstDayOfWeek=”0” Version=”1” /> |