Monday, March 21, 2011

Demystifying Time Zones in Apps Script - Part 2

In the last post, we went over the basic concepts of time zones in Apps Script. In this post, we will cover a few facts and best practices regarding time zones.

  • The browser’s time zone is used only once in the entire life of a script, as it is the default value for the script’s initial time zone.

  • Spreadsheets and scripts have their own time zone property. Formulas use the spreadsheet’s time zone while custom functions use the script’s time zone.

  • The time zone of a script can be fetched by executing Session.getTimezone().

  • A JavaScript Date is created using var date = new Date(). The newly created date objects inherits the time zone of the script.

  • Triggers use their script’s time zone by default. However, when a script’s time zone is modified, the associated triggers still maintain their original time zone. The only way to change time zone of a trigger is by recreating the trigger.

  • A Google Calendar has its own time zone. The Calendar service uses JavaScript Date objects for all methods that take a date as a parameter. Javascript Date objects have an associated time zone. This is utilized by the Calendar service to perform time zone conversions.

  • CalendarEvent.getStartDate() will return a Date object that has the script’s time zone (not the calendar’s time zone.)

  • The time zone of a user executing a script has no effect on the time zone of a script’s execution environment.

  • Using Utilities.formatDate() will help you convert Date objects to strings while performing time zone conversions. This method uses the specification used in Java’s Data Format.

  • Standard Time Zones should be used when creating Google Calendars via the Calendar service.


We hope that these tips help you gain better understanding of time zones in Apps Script. For further questions, check out the documentation and the forum.

Posted by Saurabh Gupta, Google Developer Relations

8 comments:

  1. great thanks !

    what about time zone for rss for calenndars ?
    I use the private xml...

    thanks !

    ReplyDelete
  2. Is there any method to convert the Olson ID timezone to the exact offset value (e.g. +8, +9.5, -1...)? If the script could only get an unusable Olson ID of the spreadsheet / calendar timezone, I think it's meaningless...

    ReplyDelete
  3. There have been some bugs in the past, especially with the Utilities.formatDate function. It is not simple to get events from a calendar that cross the DST line and correctly convert them. This link may help: http://code.google.com/p/google-apps-script-issues/issues/detail?id=1035

    ReplyDelete
  4. So we can retrieve the spreadsheet's and the script's time zones, but I have been trying to get the user's time zone and it seems impossible. When I finally thought I had a solution: CalendarApp.getDefaultCalendar().getTimeZone();
    it turned out that you're not allowed to use that in a custom function.

    Ant ideas on how to get the time zone of the current user ?

    ReplyDelete
  5. So we can retrieve the spreadsheet's and the script's time zones, but I have been trying to get the user's time zone and it seems impossible. When I finally thought I had a solution: CalendarApp.getDefaultCalendar().getTimeZone();
    it turned out that you're not allowed to use that in a custom function.

    Ant ideas on how to get the time zone of the current user ?

    ReplyDelete