event XML 1.1 (fix recurrances)

Martin Konold martin.konold at erfrakon.de
Wed Jan 17 11:16:50 CET 2007


Am Donnerstag, 11. Januar 2007 13:36 schrieb Martin Konold:

Hi,

here is the new version 1.2 with the enhancments and comments incorporated.

Basically version 1.2 it is the well known old 1.0 format with a single 
additional tag <subevent></subevent>. 

<subevent> is now nested withing <exclusion> in order to express the 
dependencies explicitly.

I added <priority> now also to <events> and <subevents>. Please note that we 
need to fix the priority field anyway. (separate discussion).

To my knowledge this enhanced format is able to describe all known kinds of 
events which are possible in Microsoft Outlook 2k-2k7.


<?xml version="1.0" encoding="UTF-8"?>
  <event version="1.2">
  <!-- Common fields -->
  <uid>(string, no default)</uid>
  <body>(string, default empty)</body>
  <categories>(string, default empty)</categories>
  <creation-date>(datetime, no default)</creation-date>
  <last-modification-date>(datetime, no default)</last-modification-date>
  <sensitivity>(string, default public)</sensitivity>
  {<inline-attachment>(string, no default)</inline-attachment>}
  {<link-attachment>(string, no default)</link-attachment>}
  <product-id>(string, default empty)</product-id>
  <!-- Incidence fields -->
  <summary>(string, default empty)</summary>
  <location>(string, default empty)</location>
  <organizer>
    <display-name>(string, default empty)</display-name>
    <smtp-address>(string, default empty)</smtp-address>
  </organizer>
  <start-date>(date or datetime, default not present)</start-date>
  <end-date>(date or datetime, default not present)</end-date>
  <color-label>(string, default none)</color-label>
  <priority>(number, default not present</priority>
  <show-time-as>(string, default busy)</show-time-as>
  <alarm>(number, no default)</alarm>
  <recurrence cycle="cycletype" [type="extra type"]>
    <interval>(number, default 1)</interval>
    {<day>(string, no default)</day>}
    <daynumber>(number, no default)</daynumber>
    <date>(number, no default)</date>
    <month>(string, no default></month>
    <range type="rangetype">(date or number or nothing, no default)</range>
    {<exclusion>(date, no default)
       <!-- sub events -->
       <!-- one subevent per exclusion is allowed. All subtags of subevent are
            by default "not present" and inherit their values from the primary
            event if they are not explicitly set. Basically this means that
            mainly the difference towards the primary event is stored in
            subevents! 
       -->
      {<subevent>
         <summary>(string, default not present)</summary>
         <location>(string, default not present)</location>
         <start-date>(date or datetime, default not present)</start-date>
         <end-date>(date or datetime, default not present)</end-date>
         <alarm>(number, default not present)</alarm>
         <color-label>(string, default not present)</color-label>
         <priority>(number, default not present</priority>
         <show-time-as>(string, default not present)</show-time-as>
         {<attendee> <!-- attendee is optional but if present the 
                          list of attendees must be complete! -->
         <display-name>(string, default empty)</display-name>
         <smtp-address>(string, default empty)</smtp-address>
         <status>(string, default none)</status>
         <request-response>(bool, default true)</request-response>
         <role>(string, default required)</role>
         </attendee>}
         <inline-attachment>(string, no default)</inline-attachment>
         <link-attachment>(string, no default)</link-attachment>
      </subevent>}   
    </exclusion>}
  </recurrence>
  {<attendee>
    <display-name>(string, default empty)</display-name>
    <smtp-address>(string, default empty)</smtp-address>
    <status>(string, default none)</status>
    <request-response>(bool, default true)</request-response>
    <role>(string, default required)</role>
  </attendee>}  
</event>

(*) A trivial example where the old 1.0 format was not capable enough is:

Imagine a recurring board meeting weekly on wednesday with three attendees P1, 
P2 and P3 in Room R1. Due to some circumstances the room R1 is not available 
on Dec. 13th 2006 and the meeting is therefore moved to room R2. 

This can be easily expressed in the OL GUI but it is impossible in the old 
Kolab XML format 1.0. --> The really bad thing about that is that the 
resulting information loss for the user is initially not visible because the 
OL PST happily stores this information which is later lost...

With the new XML format 1.1 this will be expressed using a subevent:

<?xml version="1.0" encoding="UTF-8"?>
<event version="1.1" >
 <product-id>KOrganizer 3.5.5, Kolab resource</product-id>
 <uid>libkcal-1405437328.834</uid>
 <creation-date>2006-12-03T23:50:00Z</creation-date>
 <last-modification-date>2006-12-06T23:54:41Z</last-modification-date>
 <sensitivity>public</sensitivity>
 <start-date>2006-12-06T09:00:00Z</start-date>
 <summary>Board Meeting</summary>
 <location>Stuttgart</location>
 <organizer>
  <display-name>Martin Konold</display-name>
  <smtp-address>martin.konold at erfrakon.de</smtp-address>
 </organizer>
 <recurrence cycle="weekly" >
  <interval>1</interval>
  <day>wednesday</day>
  <range type="none" ></range>
 <attendee>
  <display-name>P1 Surname</display-name>
  <smtp-address>P1.surname at erfrakon.de</smtp-address>
  <status>none</status>
  <request-response>true</request-response>
  <invitation-sent>false</invitation-sent>
  <role>required</role>
 </attendee>
 <attendee>
  <display-name>P2 Surname</display-name>
  <smtp-address>p2.surname at erfrakon.de</smtp-address>
  <status>none</status>
  <request-response>true</request-response>
  <invitation-sent>false</invitation-sent>
  <role>required</role>
 </attendee>
 <attendee>
  <display-name>P3 Surname</display-name>
  <smtp-address>p3.surname at erfrakon.de</smtp-address>
  <status>none</status>
  <request-response>true</request-response>
  <invitation-sent>false</invitation-sent>
  <role>required</role>
 </attendee>
 <attendee>
  <display-name>Room 1</display-name>
  <smtp-address>room.1 at erfrakon.de</smtp-address>
  <status>accepted</status>
  <request-response>true</request-response>
  <invitation-sent>false</invitation-sent>
  <role>resource</role>
 </attendee>
 <revision>0</revision>
 <show-time-as>busy</show-time-as>
 <end-date>2006-12-06T11:00:00Z</end-date>
  <!-- the modified date dec 13th is excluded 
       from the primary event as it is described 
       in a subevent -->
  <exclusion>2006-12-13
   <subevent>
    <start-date>2006-12-13T09:00:00Z</start-date>
    <end-date>2006-12-13T11:00:00Z</end-date>
    <summary>Board Meeting in Room 2 not Room 1</summary>
    <!-- location did not change and therefore 
         <location> is ommited in the subevent. 
    -->
    <!-- the room changed from room 1 to room 2 
         so we need to restate the new list of attendees
    -->
    <attendee>
      <display-name>P1 Surname</display-name>
      <smtp-address>P1.surname at erfrakon.de</smtp-address>
      <status>none</status>
      <request-response>true</request-response>
      <invitation-sent>false</invitation-sent>
      <role>required</role>
    </attendee>
    <attendee>
      <display-name>P2 Surname</display-name>
      <smtp-address>p2.surname at erfrakon.de</smtp-address>
      <status>none</status>
      <request-response>true</request-response>
      <invitation-sent>false</invitation-sent>
      <role>required</role>
    </attendee>
    <attendee>
      <display-name>P3 Surname</display-name>
      <smtp-address>p3.surname at erfrakon.de</smtp-address>
      <status>none</status>
      <request-response>true</request-response>
      <invitation-sent>false</invitation-sent>
      <role>required</role>
    </attendee>
    <attendee>
      <display-name>Room 2</display-name>
      <smtp-address>room.2 at erfrakon.de</smtp-address>
      <status>accepted</status>
      <request-response>false</request-response>
      <invitation-sent>false</invitation-sent>
      <role>resource</role>
    </attendee>
  </subevent>
 </exclusion>
 </recurrence>
 
</event>

The following is new in Kolab XML Format Version 1.2:

- new tag <subevent></subevent>
This tag may occur multiple times exclusivly as a subtree element of an 
<exclusion> tag. 

- The following explicit list of tags is allowed within a subevent:

{<subevent>
    <summary>(string, default not present)</summary>
    <location>(string, default not present)</location>
    <start-date>(date or datetime)</start-date>
    <end-date>(date or datetime</end-date>
    <alarm>(number, default not present)</alarm>
    <color-label>(string, default not present)</color-label>
    <show-time-as>(string, default not present)</show-time-as>
    <priority>(number, default 5)</priority>
    {<attendee> <!-- default not present - if present the 
                     list of attendees must be complete! -->
          <display-name>(string, default empty)</display-name>
          <smtp-address>(string, default empty)</smtp-address>
          <status>(string, default none)</status>
          <request-response>(bool, default true)</request-response>
          <role>(string, default required)</role>
    </attendee>}
    <inline-attachment>(string, no default)</inline-attachment>
    <link-attachment>(string, no default)</link-attachment>
</subevent>}

- If a tag is not present in a <subevent> the value is inherited from the 
primary <event>.

- If no <attendee> is listed in a <subevent> the list of attendees is 
inherited from the primary <event>. If there is any change to any member of 
the list of attendees then all attendees must be listed in the <subevent> 
entry. All <attendee> entries must be complete and there is no inheritence 
involved with regards to subtree elements of <attendee>. E.g if the <status> 
of an <attendee> is changed for a subevent the complete list of all attendees 
must be included in the subevent and all tags except the <status> tag are 
repeated unchanged in the subevent.

- The concluding list of allowed tags below <subevent> is:

<summary>(string, optional)</summary>
<location>(string, optional)</location>
<start-date>(date or datetime, mandatory)</start-date>
<end-date>(date or datetime, mandatory</end-date>
<alarm>(number, optional)</alarm>
<color-label>(string, optional)</color-label>
<show-time-as>(string, optional)</show-time-as>
<priority>(number, optional)</priority>
{<attendee>} <!-- default not present - if present the 
                  list of attendees must be complete! -->
          <display-name>(string, optional)</display-name>
          <smtp-address>(string, optional)</smtp-address>
          <status>(string, optional)</status>
          <request-response>(bool, default true)</request-response>
          <role>(string, default "required", optional)</role>
</attendee>}
<inline-attachment>(string, optional)</inline-attachment>
<link-attachment>(string, optional)</link-attachment>

- as the above list of fields is concluding tags like <recurrence> or  
<sensivity> are disallowed within a <subevent>!

- one or more <subevent> entries are only allowed if a <recurrence> is present 
in the primary <event>.
 
Yours,
-- martin

-- 
e r f r a k o n
Erlewein, Frank, Konold & Partner - Beratende Ingenieure und Physiker
Sitz: Stuttgart - Partnerschaftsregister Stuttgart PR 126
http://www.erfrakon.com/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: applica