Time Zones

Base calendars each have a time zone specified. This enables you to use different base calendars in different locations around the world. Overlay calendars do not specify a time zone, so that an overlay can be applied on to any base calendar without any conversion.

Time zones are specified using the time-zone parameter in the saveBaseCalendar function

All date-time entries are stored, whether on a base or an overlay calendar, with a time zone of UTC attached. This does not mean that they are necessarily intended to represent UTC times; in effect times are treated as time zone-neutral. For example, working hours entered as 08:00 to 17:00 on a base calendar with its time zone set to PST (UTC minus 8 hours) are actually stored as 08:00 to 17:00 UTC, not as 16:00 to 01:00 UTC. In most cases this is completely transparent to the user, but you need to be aware of how the system handles time zones and date-time values if you are making calls directly to the API.

Changing a base calendar’s time-zone value does not cause any adjustments to existing or future calendar entries. So if you define the start of the working week as 08:00 on Monday, it is still 08:00 on Monday even if the time zone of the calendar changes.

Although the date-time values are time zone-neutral, it is best practice to specify a time zone of Z (UTC) for values such as the time-slot start and end times that define working hours entries in a base calendar. If no time zone is specified, some functions will automatically convert the value to the time zone used by the server, regardless of the calendar’s time-zone specification. This may not always be the time zone required. For example, if a user in Paris accesses a server in California and enters a calendar time of 11:00, expecting it to be 11:00 CET (10:00 UTC), the time would be interpreted as 11:00 PST and stored as the UTC equivalent of that time, 19:00 UTC. Entering 11:00Z, however, is stored as 11:00 UTC.

Times should be treated in this way whether they are for base or for overlay calendars. This enables the entries to be applied as if they were time zone-neutral, so that any overlay calendar can be applied on top of any base calendar.