Date/Time Requirements

• This document details date/time design requirements for Chandler as requested by TedLeung at http://lists.osafoundation.org/pipermail/dev/2004-November/002018.html
• In most design documents, we focus on how user workflows necessitate or drive Chandler features. This page is different from regular design pages because date/time requirements span so many different workflows and mainly in a non-central manner. So, for this document, we focus on Chandler features that utilize date/time functionality.
• This doc is divided into two sections. The first section talks about application functions and areas that require storing of date/time information persistently. Thus, this section is most germane to the Chandler content model. The second section describes application functions in the UI and focuses on date/time requirements that the end-user directly interacts with.

Application functions directly involving date/time content modelling:

• Calendar, Events and Tasks
  • A Calendar is a view into a collection of events that lays out the events along a spatial timeline organized by day, week and possibly month. See ZeroPointFiveCalendarWorkflowsSpec for more details.
  • An event is one of the basic Kinds in Chandler. Regarding date/time attributes, the end-user is most interested in the Event's start time, end time and duration (one of which is a derived attribute).
  • A task is another basic Kind in Chandler. It's germane date/time attributes are "due date" and "do on date"
  • For the above attributes, there are usually (exceptions noted below) a date component and a time component. The date/time of each attribute should be stored in some absolute format that allows for easy comparison and sorting between other date/times. e.g. Universal Time (UTC) or seconds after 1970. Exceptions:
    • Duration is not a date/time. It's just a time interval. Its granularity need not be more specific than seconds.
    • Events can be "All day events" or Multi-day events. In this case, there is no time component to an Event. The event simply represents an entire day or a range of days.
    • Events can also be "Any time" events. These are events that can happen any time within a time period. e.g. "Call Dad 10/4" is an Any Time event reminding me that I should call Dad on 10/4 (but any reasonable time on that day is fine). For Kibble, the time period of an Any Time event is a day. Beyond Kibble, we can imagine Anytime this week or Anytime this month events too.
  • Recurrence
    • An event can recur over a given date range or even indefinitely
    • For Kibble, we must support the simplest recurring patterns i.e. event repeats every day/week/month/year.
    • Depending on the cost, we may want to implement more advanced repeating patterns such as those offered in the custom menu of Apple iCal (e.g. every second Weds of the month)
    • We need to understand the complexities of interoperating with recurrence patterns specific in standards, primarily the iCalendar format. This is discussed further under the interoperability section below.
  • Time zones
    • In order to facilitate collaboration across time zones, time zones are associated to each Chandler date/time attribute and also to the calendar view itself. Furthermore, time zones need to automatically adjust for daylight savings changes.
    • For example, an OSAF staff meeting could be scheduled for 10.45am Pacific Time in San Francisco. If Bear attends this meeting via teleconference in Philadelphia, he would still see the event start time as 10.45am Pacific Time, say in the detail view. But on his calendar, the event would be laid out on the 1.45pm timeline (or tick mark), adjusting for the +3 hours time difference for the East Coast time zone that his calendar is based on. I would think that the appropriate way to do things is for the time for future events to be stored as UTC, but to be displayed based on the user's location (Pacific, Mountain, etc). Thus, Bear wouldn't even see 10.45am PST in the detail view, but 13.45pm EST. -- DuckySherwood ChaoLam: Ducky, I agree that event time should be stored in some absolute format (as I stated above) but I disagree that invitee or sharee of an event need not know the original time zone of the event. I think Apple iCal has the right design: display the event in the calendar summary view in the present user's time zone but in the detail view explicitly display the original time zone and time of the event. It's useful for the invitee to know that times for this event is specified in, say, Pacific time zone even if she is in the Eastern time zone. For example, agenda times in the notes field may also refer to the pacific time zone.
    • Building further on the above example, when a daylight savings switch occurs, the calendars adjust automatically. In this case, the event is brought back or forward by an hour, but Bear's East Coast calendar is also brought back or forward by an hour, so no change occurs on his calendar. However, if Bear were living in, say, Hawaii, which does not observe Daylight Savings, the event start time would still reflect 10.45am Pacific Time but on his Calendar (set to the Hawaiian time zone), it would have moved the meeting start time by an hour. Care should be taken to not move around things that happened on the opposite side of Daylight Savings Time changes. If I have a meeting at 10 AM on October 3, then if on November 3 (after the switch from Daylight Savings Time) I look at my Oct 3 calendar page, it shouldn't say that that meeting was at 11 AM. Similarly, if on October 3, I make an appointment for Nov 3 at 3:15p, when I get to Nov 3, the event should still be at 3:15p. -- DuckySherwood
    • All-day events do not have time zones associated to it e.g. An all-day July 4th event created in Pacific Time calendar, should not be viewed as a start time of 9pm July 3rd when viewed in a Hawaiian Time Zone calendar
    • See Apple iCal for how it deals with time zones as a good model
• Time stamp
  • Time stamps are used in many workflows and tasks within Chandler, primarily to record when a certainly activity has occurred. Such time stamps are later displayed for the user. Time stamps are also used as basis for sorting a list of Items.
  • Following are the main areas in Chandler where time stamps are used:
    • All Content Items have a creation date attribute.
    • Email. The key time stamp attributes in Email are date received and date sent. There are many more attributes to note the routing of an email. These are usually not useful to the end-user.
    • Sharing initiation and updates. Associated with a share is the last modified date and time or created date and time depending on which operation last occurred.
    • Chandler notifications
      • There are a whole class of errors and notifications to the user that need not occur in a real-time manner. e.g. bounced email, sharing invitation failure, WebDAV polling or syncing error etc. We plan to have these notifications arrive in the users in box or "now" section of the dashboard view, just like new incoming email. These notifications need to have time stamp(s) for the event reported.
    • Logs
      • We would like to log and instrument key user actions and Chandler events, for more detailed user explanations, diagnosis and to better design Chandler. Logs of such actions should be accompanied with time stamps.
• Alarms.
  • Users need to be reminded or tickled about certain events e.g. interrupt me 5 mins before OSAF staff meeting. Alarm times can be relative off the actual event date/time itself. This area requires more design.
• Interoperability
  • Chandler date/time formats need to be interoperable with standards (and emerging standards), primarily iCalendar, iMIP and CalDAV. This is necessary in the following areas:
    • importing/export events, tasks and emails (timestamps)
    • Chandler as a CalDAV client
    • iMIP interoperability for event invitation and scheduling
    • ideally, exporting data in iCalendar format on WebDAV servers as part of the developer platform and dog food goals
    • See IETF RFC 2445 and LisaDusseault20041005 for more details on iCalendar and iMIP
  • We also need to look into date/time issues when syncing to other PIMs and PDAs. This requires more investigation. We need to uncover areas where our schema is incompatible with other formats and how so.
  • Parsing of date/time in different formats is an issue here just as it is an issue in date/time entry (below)
• Queries, sorting and rules/filters
  • Content items need be queried by date/time attributes, most of the common ones are described above
  • Collection results also need to be sorted quite commonly by date/time, either chronologically or reverse chronologically.
  • In some views, content items are also grouped together by date/time ranges (primarily in day granularity but possibly week, month or year too).
  • Date/time attributes are also used as terms or parameters in a Rule. e.g. All items in the last 3 weeks. Rules and filters are planned for 0.6^? and will be specified in greater detail. For current thinking (not tied to any release), see RuleBuilder.

Application areas directly affecting Chandler UI

• Date/Time Entry
  • For 0.5, we are proposing a simple numerical field based date/time entry
  • Ideally (beyond 0.5 but possibly beyond Kibble), we would like to support as many different date entry formats as possible. This includes
    • relative date/times (e.g. next Friday, tomorrow, 5pm (implicitly today or tomorrow if already after 5))
    • absolute date/times in multiple formats (formats being defined by the OS where applicable. See i18n issues below) e.g. 11/30/01 & November 30th 2001
• Date/Time Display.
  • Even though dates are probably stored in one fixed absolute encoding, they can be displayed in many different formats. For example, the summary view can have a date column that displays some dates in relative format (e.g. Yesterday, Today) and absolute format.
  • In the latter absolute format, the display of the date can again vary by the amount of space that is provided for that column e.g.
    • 11/5
    • 11/5/04
    • Nov 5 2004
    • Nov 5 2004 3:15pm
    • November 5 2004 3:15pm
    • Beyond Kibble, date/times can be displayed relative off each row in the summary view, in a format we call the fisheye view (See example at DashboardViewSpec)
  • See also I18N issues below
• i18n considerations
  • As much as possible, we should use OS standards and preferences for guidance e.g.
    • Date/Time formatting
      • Month/Date order e.g. April 10 1984 vs. 10 April 1984
      • Spelling of month and days of week.
      • Date/Time abbreviations (e.g. days of week: Su M T W...) and long/short formats (11/30/01 vs November 30th 2001)
      • 12 hr vs. 24 hr clock
      • Separator e.g. /,-,:
      • First day of week (Mon or Sun)
      • This applies to date entry, display, parsing and import/export
  • [OI^?] Are dates/times sorted differently in different locales? I don't believe so, especially if we use one standard encoding method for storing date/times.
  • We need principles to figure how much i18n functionality to bake into Kibble. Examples of more esoteric issues we will probably leave out: Non-Gregorian calendar support (e.g. lunar or Mayan calendar)