12 Oracle Calendar Web Services Supported Data Components and Properties

The data format of Oracle Calendar events and tasks are based on iCalendar DTD Document (xCal). This document provides an alternative, XML representation for the standard iCalendar syntax defined in RFC 2445 - Internet Calendaring and Scheduling Core Object Specification (iCalendar).

Note that only vEvents and vTodos are supported in the xCal specification; vJournal and vFreebusy are not.

The following tables and sections describe the iCalendar components and properties that Oracle Calendar Web services supports. They also describe which properties may be modified, added, or deleted with the Modify SOAP command or required, optional, or not allowed with the Create SOAP command. Oracle Calendar Web services also supports Oracle-specific components and properties whose names begin with "x-oracle".

The current implementation of Web services does not support the retrieval of repeating and recurring meetings as a whole. When a Search is performed, any meeting with instances or recurrence rules stored on the server is expanded to separate each instance into an individual meeting. This helps processing and UI generation.

It is important to note that not all xCal elements and properties nor all Oracle Calendar server attributes are supported in this release.

For more information regarding data types, syntax, and other characteristics of iCalendar components and properties, refer to the following documents:

RFC 2445 - Internet Calendaring and Scheduling Core Object Specification (iCalendar)
iCalendar DTD Document (xCal)

Components

Calendar Web services supports the <vevent> and <vtodo> iCalendar components.

The following tables describe the component properties of <vevent> and <vtodo>. The following are clarifications of some of these table's headings and abbreviations:

Columns labeled "Min." indicate the minimum number of each component property (or property parameter) that the client must create or generate in order to add the specified component to the Calendar store.
Columns labeled "Max." indicate the maximum number of each component property (or property parameter) the specified component may contain.
Columns labeled "Mod." indicate whether the component property can be modified or deleted (with the Modify SOAP method).
Columns labeled "Add" indicate whether the component property can be added (with the Modify SOAP method).
Columns labeled "Create" indicate whether the component property is required, supported (optional), not supported, or ignored by the Create SOAP method.

vevent

Describes appointments, daily notes, day events, and holidays.

Table 12-1 Component Properties of VEVENT

Component Property	Min	Max.	Mod.	Add	Create	Data Type
attendee	0	n	no	no	not supported	mailto URI of the attendee
class	0	1	yes	no	required	TEXT
description	0	1	yes	yes	supported	TEXT
dtend (must not appear with duration)	1	1	yes	no	not supported	DATE-TIME (default), DATE
dtstart	1	1	yes	no	required	DATE-TIME (default), DATE
duration (must not appear with dtend)	1	1	no	no	required	DURATION
location	0	1	yes	yes	supported	TEXT
organizer	0	1	no	no	not supported	mailto URI of the attendee
priority	0	1	yes	no	supported	INTEGER
summary	0	1	yes	yes	supported	TEXT
uid	0	1	no	no	supported	TEXT
valarm	0	n	yes	yes	supported	valarm
x-oracle-data-guid	0	1	no	no	not supported	TEXT
x-oracle-event-guid	0	1	no	no	ignored	TEXT
x-oracle-eventinstance-guid	0	1	no	no	ignored	TEXT
x-oracle-eventtype	0	1	yes	yes	required	TEXT
x-oracle-isrtcenabled	0	1	yes	yes	supported	BOOLEAN
x-oracle-loginuser	0	1	no	no	supported	mailto URI of the attendee
x-oracle-rtc-attendee-url	0	1	no	no	supported	URI
x-oracle-rtc-dialininfo	0	1	yes	yes	supported	TEXT
x-oracle-rtc-host-url	0	1	no	no	supported	TEXT
x-oracle-rtc-meetingid	0	1	no	no	supported	TEXT
x-oracle-rtc-password	0	1	yes	yes	supported	TEXT
x-oracle-rtc-securitytype	0	1	yes	yes	supported	TEXT
x-oracle-search-relevance	0	1	no	no	not supported	INTEGER

vtodo

Describes tasks stored in the Oracle Calendar server.

Table 12-2 Component Properties of VTODO

Component Property	Min.	Max.	Mod.	Add	Data Type
class	0	1	no	no	TEXT
completed	0	1	no	no	DATE-TYPE
created	0	1	no	no	DATE-TIME
description	0	1	no	no	TEXT
dtstamp	0	1	no	no	DATE-TIME
dtstart	0	1	no	no	DATE-TIME (default), DATE
due (However, must not appear of duration appears)	1	1	no	no	DATE-TIME (default), DATE
last-modified	0	1	no	no	DATE-TIME
percent	0		no	no	INTEGER
priority	0	1	no	no	INTEGER
summary	0	1	no	no	TEXT
uid	0	1	no	no	TEXT
x-oracle-data-guid	0	1	no	no	TEXT
x-oracle-taskid	0	1	no	no	TEXT

valarm

Describes reminders for Calendar entries. Properties of <valarm> include the type of reminder, such as a popup or an email, and the time before which the <valarm> should notify the user of the Calendar event.

Table 12-3 Component Properties of VALARM

Component Property	Min.	Max.	Mod.	Add	Data Type	Description
action	1	1	yes	no	TEXT	Describes the type of action to be performed by the alarm. This can be one of the following: AUDIO DISPLAY (displays a popup) EMAIL (emails a reminder) PROCEDURE X-ORACLE-ALARM-DEFAULT (uses the user's server's default action) X-ORACLE-ALARM-NONE (does not trigger an alarm) X-ORACLE-SMS (triggers an SMS)
trigger	1	1	yes	no	TRIGGER	Time and duration of the alarm

Component Property

Min.

Max.

Mod.

Add

Data Type

Description

action

yes

TEXT

Describes the type of action to be performed by the alarm. This can be one of the following:

AUDIO
DISPLAY (displays a popup)
EMAIL (emails a reminder)
PROCEDURE
X-ORACLE-ALARM-DEFAULT (uses the user's server's default action)
X-ORACLE-ALARM-NONE (does not trigger an alarm)
X-ORACLE-SMS (triggers an SMS)

trigger

yes

TRIGGER

Time and duration of the alarm

vevent and vtodo Component Properties

The following describes the iCalendar and Oracle-specific component properties of the <vevent> and <vtodo> calendar components.

attendee

Defines an attendee within a Calendar component. This component has the same structure as <x-oracle-loginuser> except it may have an additional property parameter named partstat.

The partstat property parameter represents the attendee's participation status. It may have a value of ACCEPTED, DECLINED, or NEEDS-ACTION. Note that DELEGATED and TENTATIVE are not supported.

The following is an example of an <attendee> component property:

<attendee cn="Germaine Lauzon" partstat="ACCEPTED">
  GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA
</attendee>

class

Defines the access classification for a Calendar component. It may have one of the following values:

CONFIDENTIAL
PRIVATE
PUBLIC

completed

Has a value of "true" if the value of percent is "100".

created

Specifies the date and time that the Calendar component was created. The date and time is a UTC value.

description

Provides a more complete description of the Calendar component than that provided by the <summary> property.

dtend

Specifies the date and time that a Calendar component ends.

The data type of this property may be DATE-TIME or DATE. Specify the data type with the value attribute. The following is an example of this property:

<dtend value="DATE">20050119</dtstart>

dtstamp

Indicates the date/time that the instance of the Calendar object was created or last modified. The value must be specified in the UTC time format. This property is different than the <created> and <last-modified> properties. These two properties are used to specify when the particular Calendar data in the Calendar store was created and last modified. This is different than when the Calendar object representation of the Calendar data was created or modified by the client.

dtstart

Specifies when the Calendar component begins. Non-standard, value data type, time zone identifier property parameters can be specified on this property.

If dtend is present, it will be used to calculate the event duration; the actual end time is not stored. As event times are measured in minutes, the start time and duration will have their 'seconds' component set to zero.

The data type of this property may be DATE-TIME or DATE. Specify the data type with the value attribute. The following is an example of this property:

<dtstart value="DATE">20050119</dtstart>

due

Represents the task due date and time. The date and time is a UTC string of type DATE-TIME or DATE.

duration

Specifies a positive duration of time.

For example, a duration of 15 days, 5 hours and 20 seconds would be represented as P15DT5H0M20S. A duration of 7 weeks would be represented as P7W

last-modified

Specifies the date and time that the information associated with the Calendar component was last revised in the Calendar store. This is analogous to the modification date and time for a file in the file system. The property value must be specified in the UTC time format.

location

Defines the intended venue for the activity defined by a Calendar component.

organizer

Defines the organizer for a Calendar component. Uses the same structure as <x-oracle-loginuser>.

percent

An integer between 0 and 100 that represents the percent completed of a task.

priority

Defines the relative priority for a Calendar component.

The following table describes the possible values of this property:

Table 12-4

Possible Value of <priority>	Description
1	Highest
2	High
5	Normal
7	Low
9	Lowest

summary

Defines the title of the event or instance.

uid

Defines the persistent, globally unique identifier for the Calendar component.

If <uid> is not specified when storing data, the Oracle Calendar server will assign a value.

url

Defines a Uniform Resource Locator (URL) associated with the Calendar object.

x-oracle-data-guid

Defines the event's or task's unique identifier so that an entry can be identified when referencing it through OCAS.

x-oracle-event-guid

Uniquely identifies <vevent> components.

x-oracle-eventinstance-guid

Uniquely identifies <vevent> instances.

x-oracle-eventtype

Identifies the type of event that the <vevent> represents. The property can be specified once in the <vevent> component. It can have one of the following values:

APPOINTMENT: Identifies a regular blocking meeting.
DAILY NOTE: Identifies a non-blocking note associated with a calendar day.
DAY EVENT: Identifies a non-blocking all day Calendar event.
HOLIDAY: Identifies a non-blocking holiday specialization of a day event.

x-oracle-isrtcenabled

Indicates that an instance is Web conference-enabled. This property is generated by the Oracle Calendar server and used by Calendar clients. This property can be specified in the vevent Calendar component.

x-oracle-loginuser

Defines the login user.

The value of the <x-oracle-loginuser> the mailto URI of the Calendar user. The property parameters of this property appear as element attributes.

The following is an example of an <x-oracle-loginuser> element:

<x-oracle-loginuser cn="GERMAINE LAUZON">
  mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA
</x-oracle-loginuser>

The cn property parameter is the common or displayable name associated with the login user.

x-oracle-rtc-attendee-url

This property may be specified once in the vevent Calendar component.

x-oracle-rtc-dialininfo

Specifies dial-in information required by attendees to join a teleconference, such as the phone number and conference ID. This property may be specified once in the vevent Calendar component.

x-oracle-rtc-host-url

Specifies the URL of the Web page hosting the Web conference associated with this Calendar component instance. This value is set by Web conference. This property may be specified once in the vevent Calendar component.

x-oracle-rtc-meetingid

Specifies the Web conference ID associated with the vevent Calendar component instance. The value is strictly generated by the Web conference server. This property may be specified once in the vevent Calendar component.

x-oracle-rtc-password

The optional key (the password) of a Web conference. The property can be specified in the vevent Calendar component.

x-oracle-rtc-securitytype

Indicates the security type of a Web conference enabled instance. Possible types are "restricted", "regular", and "public". The property may be specified once in the vevent Calendar component. This property may be specified once in the vevent Calendar component.

x-oracle-search-relevance

Represents the relative weight of this instance in the Ultra Search result set. This property contains a value between 0 and 100. Instances with higher values are considered more likely to be relevant to the end user. This is only to be used for Ultra Search.

x-oracle-taskid

Represents the task ID of a <vtodo> generated by the Oracle Calendar server.

Example XML Calendar Data

The following are examples of <vevent> and <vtodo> iCalendar components.

Simple Events

<vcalendar>
     <vevent>
          <class>CONFIDENTIAL</class>
          <description>a description</desription>
          <dtend>20021101T120000Z</dtend>
          <dtstart>20021101T110000Z</dtstart>
          <location></location>
          <organizer cn="James Baldwin">
               mailto:james.baldwin@oracle.com
          </organizer>
          <priority>1</priority>
          <status>CONFIRMED</status>
          <summary>a meeting</summary>
          <uid>ORACLE:CALSERV:EVENT:48390483290843290</uid>
          <attendee cn="James Baldwin" partstat="ACCEPTED">
               mailto:james.baldwin@oracle.com
          </attendee>
          <x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype>
          <x-oracle-event-guid>fdjskljfdlkj</x-oracle-event-guid>
          <x-oracle-eventinstance-guid>fdjskljfdlkj
          </x-oracle-eventinstance-guid>
          <x-oracle-data-guid>fdjskljfdlkj</x-oracle-data-guid>
     </vevent>
</vcalendar>

Repeating and Recurring Events

If a repeating (or recurring) meeting were pulled directly from the Oracle Calendar server, it would have one vCalendar element with multiple, related vEvents. The main vEvent would contain an rrule element outlining the rule for the meeting followed by instance, exception, and time zone information. All event-guids would be the same through the vCalendar, but the instance-guids would be different.

When a Search is performed, any meeting with instances or recurrence rules stored on the server is expanded to separate each instance into an individual meeting. A meeting and its instances have the same <x-oracle-event-guid>.

The following is an example of a repeating event that repeats daily for two days, from January 21 to January 22:

<vcalendar version="2.0" prodid="-//Oracle//Calendaring//OCAS//EN">
  <vevent>
    <uid>E1+12345678+1+123456789@I1+00000000+1+4+111111111</uid>
    <transp>OPAQUE</transp>
    <summary>Repeating meeting</summary>
    <status>CONFIRMED</status>
    <priority>5</priority>
    <organizer cn="Germaine Lauzon">
      mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA
    </organizer>
    <location>Somewhere</location>
    <description> </description>
    <dtstart>20050122T150000Z</dtstart>
    <dtend>20050122T160000Z</dtend>
    <class>PUBLIC</class>
    <attendee cn="Germaine Lauzon" partstat="ACCEPTED">
      GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA
    </attendee>
    <x-oracle-data-guid>
      E1+12345678+1+123456789@I1+00000000+1+4+111111111
    </x-oracle-data-guid>
    <x-oracle-areothersinvited>FALSE</x-oracle-areothersinvited>
    <x-oracle-isextrainstance>FALSE</x-oracle-isextrainstance>
    <x-oracle-isexception>FALSE</x-oracle-isexception>
    <x-oracle-loginuser cn="Germaine Lauzon">
      mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA
    </x-oracle-loginuser>
    <x-oracle-eventinstance-guid>
      I1+00000000+1+4+111111111
    </x-oracle-eventinstance-guid>
    <x-oracle-event-guid>E1+12345678+1+123456789</x-oracle-event-guid>
    <x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype>
    <valarm>
      <trigger>-P0DT0H10M0S</trigger>
      <action>DISPLAY</action>
      <description></description>
    </valarm>
    <valarm>
      <trigger>-P0DT0H10M0S</trigger>
      <action>AUDIO</action>
    </valarm>
  </vevent>
</vcalendar>
<vcalendar version="2.0" prodid="-//Oracle//Calendaring//OCAS//EN">
  <vevent>
    <uid>E1+12345678+1+123456789@I1+00000000+1+5+000000000</uid>
    <transp>OPAQUE</transp>
    <summary>Repeating meeting</summary>
    <status>CONFIRMED</status>
    <priority>5</priority>
    <organizer cn="Germaine Lauzon">
      GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA</organizer>
    <location>Somewhere</location>
    <description> </description>
    <dtstart>20050121T150000Z</dtstart>
    <dtend>20050121T160000Z</dtend>
    <class>PUBLIC</class>
    <attendee cn="Germaine Lauzon" partstat="ACCEPTED">
      GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA
    </attendee>
    <x-oracle-data-guid>
      E1+12345678+1+123456789@I1+00000000+1+5+000000000
    </x-oracle-data-guid>
    <x-oracle-areothersinvited>FALSE</x-oracle-areothersinvited>
    <x-oracle-isextrainstance>FALSE</x-oracle-isextrainstance>
    <x-oracle-isexception>FALSE</x-oracle-isexception>
    <x-oracle-loginuser cn="Germaine Lauzon">
      GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA
    </x-oracle-loginuser>
    <x-oracle-eventinstance-guid>
      I1+00000000+1+5+000000000
    </x-oracle-eventinstance-guid>
    <x-oracle-event-guid>E1+12345678+1+123456789</x-oracle-event-guid>
    <x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype>
    <valarm>
      <trigger>-P0DT0H10M0S</trigger>
      <action>DISPLAY</action>
      <description></description>
    </valarm>
    <valarm>
      <trigger>-P0DT0H10M0S</trigger>
      <action>AUDIO</action>
    </valarm>
  </vevent>
</vcalendar>

Daily Notes

<vcalendar>
     <vevent>
          <class>CONFIDENTIAL</class>
          <description>a description</description>
          <dtend value="DATE">20021101</dtend>
          <dtstart value="DATE">20021101</dtstart>
          <organizer cn="Par Lagerkvist">
               mailto:par.lagerkvist@oracle.com
          </organizer>
          <priority>3</priority>
          <status>CONFIRMED</status>
          <summary>a daily note</summary>
          <uid>ORACLE:CALSERV:EVENT:49304932-04932-09</uid>
          <attendee cn="Par Lagerkvist" partstat="ACCEPTED">
               mailto:par.lagerkvist@oracle.com
          </attendee>
          <x-oracle-event-guid>fdjskljfdlkj</x-oracle-event-guid>
          <x-oracle-eventtype>DAILY NOTE</x-oracle-eventtype>
          <x-oracle-eventinstance-guid>fdjskljfdlkj
          </x-oracle-eventinstance-guid>
          <x-oracle-data-guid>fdjskljfdlkj</x-oracle-data-guid>
     </vevent>
</vcalendar>

Day Events

<vcalendar>
     <vevent>
          <class>CONFIDENTIAL</class>
          <description>a description</description>
          <dtend value="DATE">20021101</dtend>
          <dtstart value="DATE">20021101</dtstart>
          <organizer cn="Par Lagerkvist">
               mailto:par.lagerkvist@oracle.com
          </organizer>
          <priority>3</priority>
          <status>CONFIRMED</status>
          <summary>a day event</summary>
          <uid>ORACLE:CALSERV:EVENT:49304932-04932-09</uid>
          <attendee cn="Par Lagerkvist" partstat="ACCEPTED">
               mailto:par.lagerkvist@oracle.com
          </attendee>
          <x-oracle-event-guid>fdjskljfdlkj</x-oracle-event-guid>
          <x-oracle-eventtype>DAY EVENT</x-oracle-eventtype>
          <x-oracle-eventinstance-guid>fdjskljfdlkj
          </x-oracle-eventinstance-guid>
          <x-oracle-data-guid>fdjskljfdlkj</x-oracle-data-guid>
     </vevent>
</vcalendar>

Holidays

<vcalendar>
     <vevent>
          <categories>
               <item>Holiday</item>
          </categories>
          <class>PUBLIC</class>
          <description>a description</description>
          <dtend value="DATE">20021031</dtend>
          <dtstart value="DATE">20021031</dtstart>
          <organizer cn="Par Lagerkvist">
               mailto:par.lagerkvist@oracle.com
          </organizer>
          <priority>3</priority>
          <status>CONFIRMED</status>
          <summary>a holiday</summary>
          <uid>ORACLE:CALSERV:EVENT:49304932-04932-09</uid>
          <attendee cn="Par Lagerkvist" partstat="ACCEPTED">
               mailto:par.lagerkvist@oracle.com
          </attendee>
          <x-oracle-event-guid>fdjskljfdlkj</x-oracle-event-guid>
          <x-oracle-eventtype>HOLIDAY</x-oracle-eventtype>
          <x-oracle-eventinstance-guid>fdjskljfdlkj
          </x-oracle-eventinstance-guid>
          <x-oracle-data-guid>fdjskljfdlkj</x-oracle-data-guid>
     </vevent>
</vcalendar>

Tasks

<vcalendar>
     <vtodo>
          <class>PRIVATE</class>
          <completed>20021002T210000Z</completed>
          <created>20021002T210000Z</created>
          <description>the task description</description>
          <percent>0</percent>
          <priority>9</priority>
          <summary>The task title</summary>
          <uid>fdjskljfdlkj</uid>
          <due>20021102T210000Z</due>
          <x-oracle-data-guid>
            ORACLE:CALSERV:TASK:328321890328/489043209
          </x-oracle-data-guid>
     </vtodo>
</vcalendar>