| Oracle Calendar Application Developer's Guide Release 2 (9.0.4) Part Number B10893-01 |
|
|
View PDF |
| Oracle Calendar Application Developer's Guide Release 2 (9.0.4) Part Number B10893-01 |
|
|
View PDF |
This chapter describes how the Oracle Calendar web services toolkit uses Extended Markup Language (XML) and Simple Object Access Protocol (SOAP) to retrieve and store iCalendar objects.
The HTTP header for a proper SOAP v1.1 transaction must contain the following elements:
POST <uri> HTTP/1.1 Content-Type: text/xml; charset="UTF-8" Content-Length: <char length> SOAPAction: <urn> ...soap envelope...
The <uri> is typically the URI for the Oracle Calendar application system (typically, /ocas-bin/ocas.fcgi). This is used mainly by the Web Server (Oracle HTTP Server or Apache) to identify the application system, invoke its internal fcgi protocol module, and pass the request to web services.
Within Oracle Collaboration Suite, to bypass Oracle Single Sign-On mechanism (SSO), a separate URL may be required (typically, /ocws-bin/ocas.fcgi).
The Content-Type charset identifier is optional. If it is not provided, UTF-8 is assumed. However, UTF-8 is the only charset encoding supported. All other charsets will result in an error.
The HTTP response for an error is a 500 status code (for Internal Server Error). This is returned if the actual SOAP envelope is corrupt (in other words, we cannot determine what the data coming in is) or if a SOAP level error occurs. Keep in mind that all application level errors are returned within a SOAP Fault, along with the 500 HTTP status code.
HTTP/1.1 500 Internal Server Error Content-Type: text/xml Content-Length: <char length> ...Optional soap envelope...
If the SOAP envelope can be properly executed, the SOAP information is correct, and the application level function succeeds, the 200 status code (success) will be returned.
HTTP/1.1 200 OK Content-Type: text/xml Content-Length: <char length> ... Soap envelope...
This section describes:
Although data encryption is a very important security element, at the present time there are no plans to encrypt data within SOAP requests.
Within the SOAP domain, there are many efforts underway to define and standardize the authentication, security, and encryption of SOAP messages. Groups such as W3C, IETF, OASIS, and WS-I are all working toward the same end. Unfortunately, at the time of development of Oracle Calendar web services, no definitive specification had been approved. However, some general trends were respected when defining the features that web services supports, including:
|
Note: The proposed specification "WS-Security" outlines some authentication mechanisms, however this is a working draft that does not carry industry approval. |
The adopted practice with all these mechanisms is to include the required information within a series of SOAP headers, with the exception of HTTP level functionality (that is, SSL and certificates).
<SOAP-ENV:Envelope> <SOAP-ENV:Header> ... some encryption, signature, and authentication info goes here ... </SOAP-ENV:Header> <SOAP-ENV:Body> ... a soap method goes here ... </SOAP-ENV:Body> </SOAP-ENV:Envelope >
At the application layer, only plain text authentication is supported. The user's password must be provided in plaintext only (NOT a base-64 encoded string) at the beginning of each transaction.
Security is provided at the transport, protocol and application levels. At the HTTP layer, there are two options: Normal or SSL. This layer is handled completely at the Web server level (that is, Apache and Oracle HTTP Server), providing encrypted data between the HTTP client and HTTP server. The Calendar Application Server has no dependencies on this layer.
The SOAP client must support SSL; not all toolkits do.
The web services Basic Authentication is implemented using the SOAP header.
The initial version requires a BasicAuth element in the header for each request. If the element is not present, a SOAP Fault is generated.
HTTP/1.1 200 OK Content-Type: text/xml:charset="UTF-8" Content-Length: <char length> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Header> <auth:BasicChallenge xmlns:auth= "http://www.soap-authentication.org/2002/01/"> <Realm>Oracle Web Services</Realm> </auth:BasicChallenge> </soap:Header> <soap:Body> <Reply xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> </Reply> </soap:Body> </soap:Envelope>
<Realm> is used to provide a hint to the client. This is a configurable parameter in the ocws.conf file.
[basicauth] Realm=Oracle Web Services # default
A typical SOAP session with Basic Authentication contains the user's credentials within the soap header of the first message.
POST <uri> HTTP/1.1 Content-Type: text/xml; charset="UTF-8" Content-Length: <char length> SOAPAction: <urn> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Header> <auth:BasicAuth xmlns:auth="http://www.soap-authentication.org/2002/01/"> <Name>myname</Name> <Password>mypassword</Password> </auth:BasicAuth> </soap:Header> <soap:Body> ... </soap:Body> </soap:Envelope>
The user name must be the Calendar Server's User ID. X.400 login is not permitted. Also, the User ID and Password must be properly XML encoded.
If the Basic Authentication fails, a SOAP fault is returned, indicating the source of the problem.
HTTP/1.1 500 Internal Server Error Content-Type: text/xml Content-Length: <char length> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Body> <soap:Fault> <faultcode>soap:Server::Data::CalConnection</faultcode> <faultstring>A security error occurred</faultstring> <detail> <cwsl:Error xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <Code>0020-00-00-00000017</Code> ... </cwsl:Error> </detail> </soap:Fault> </soap:Body> </soap:Envelope>
The BasicAuth mechanism is to be used mainly for development and testing purposes. Alone, the mechanism provides little security, due to the use of plain text passwords. If this mechanism is to be used in a production environment, an SLL web configuration is highly recommended.
SOAP queries make use of Universal Identifiers (UIDs) and Global Unique Identifiers (GUIDS). The web services API is based around the ability to uniquely identify a Calendar Store object, retrieve it, and store a reference for last use. In web services, the data-independent property to use is:
x-oracle-data-guid
This Data GUID maps to various data type specific properties stored on the calendar server. For Events, the following properties are available:
uid # a UID settable upon creation x-oracle-event-guid # identifier of the main event x-oracle-eventinstance-guid # identifier of the instance within # the event x-oracle-data-guid # mapped to x-oracle-eventinstance-guid
For tasks, the following properties are available:
uid # a UID settable upon creation x-oracle-data-guid # generated internally by the Application # Server (OCAS) and cannot be used against # any other product. This will be changed # once the Calendar Store supports the # x-oracle-task-guid attribute.
The SOAP Envelope is a predefined XML packet used to identify the SOAP message:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> ...soap header... ...soap body... </soap:Envelope>
Xsi and xsd are options defining a namespace used within the message; these will appear if required (i.e. if there is an element in the soap header or soap body requiring it).
Xsd is used to provide basic predefined type definitions, such as string, integer, etc. Xsi is used to define the "type" attribute for an entry.
<location xsi:type="xsd:string">Soleil</location>
There are 3 main ways of providing type information within SOAP:
xsi:type attribute.Since xCal and CWSL have their own XML Schemas, they do not use explicit type attributes.
There are important issues to be outlined at this point; most current SOAP implementations add an XML document header line before the SOAP envelope. However this is not part of the current SOAP v1.1 specification, but an improvement included in SOAP v1.2.
<?xml version="1.0" encoding="UTF-8" ?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd="http://www.w3.org/1999/XMLSchema"> ...soap header... ...soap body... </soap:Envelope>
In order to maintain consistency between SOAP implementations, the default behavior is to provide the XML document header if the original request has one.
POST <uri> HTTP/1.1 Content-Type: text/xml; charset="UTF-8" Content-Length: <char length> User-Agent: <user agent> SOAPAction: <urn> ...soap envelope...
The SOAP body contains the actual methods used to perform actions on Calendar Server and web services errors.
When any kind of error is returned, a SOAP Fault element appears in the Body of the SOAP response. Within a SOAP fault, there are specific elements to be provided:
ocas.conf, then Line, FileName, Version, LastMod, and Author are returned.
<soap:Body> <soap:Fault> <faultcode>soap:Server</faultcode> <faultstring>Unable to locate the entry in the preferences </faultstring> <detail> <cwsl:Error xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <Class>Error::Data::CalConnection</Class> <Code>000C-01-00-00000029</Code> <Line>1450</Line> <FileName>UniapiConnection.cpp,v</FileName> <Version>1.43</Version> <LastMod>2002/05/23 20:54:48</LastMod> <Author>frederic</Author> <Date>Web May 29 14:05:42 2002</Date> <PID>19458</PID> <TID>5</TID> </cwsl:Error> </detail> </soap:Fault> </soap:Body>
As an example, the preceding Code tag indicates the type of error as follows:
Text description of the illustration errorcod.gif
Generally you need only concern yourself with the first and last segments, which in this case are:
For a list of Module and Error values, see Chapter 11, "Calendar Web Services Status Codes".
A fault can occur at any point in the access of interaction with various components within the application system and the Calendar Server.
CWSL defines the grammar to be used to exchange data between a calendaring SOAP client and calendaring SOAP server. The following methods, taken directly from the CAP draft dated March 2002, provide the main functionality for the Calendaring web service Language. It should be noted that some of the CAP method names are reused here in the CWSL, but the semantics and meaning are changed to reflect a Web-based protocol environment.
The Calendaring language uses "http://www.oracle.com/WebServices/Calendaring/1.0/" as the namespace.
The following Session command is supported:
The following Calendaring commands are supported:
The following Calendaring command is also defined:
It is important to note that some of these methods are greatly restricted in this release.
This command is used to verify the validity of an authentication SOAP header, without executing anything on the server.
POST <uri> HTTP/1.1 Content-Type: text/xml; charset="UTF-8" Content-Length: <char length> SOAPAction: http://www.oracle.com/WebServices/Calendaring/ 1.0/NoOp <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Header> ... </soap:Header> <soap:Body> <cwsl:NoOp xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <CmdId>a command id</CmdId> </cwsl:NoOp> </soap:Body> </soap:Envelope>
The web service response for a success command is:
HTTP/1.1 200 OK Content-Type: text/xml Content-Length: <char length> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> ... <soap:Body> <cwsl:NoOpReply xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <CmdId>a command id</CmdId> </cwsl:NoOpReply> </soap:Body> </soap:Envelope>
The NoOp command can only fail if there is a SOAP header problem.
This section describes how to retrieve data using the Search and vQuery commands.
This command is used to retrieve Events, Tasks, Contacts, and User information from the Calendar Server.
POST <uri> HTTP/1.1 Content-Type: text/xml; charset="UTF-8" Content-Length: <char length> SOAPAction: http://www.oracle.com/WebServices/Calendaring/1.0/Search <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Header> <h:BasicAuth xmlns:h="http://soap-authentication.org/2002/10/"> <Name>myname</Name> <Password>mypassword</Password> </h:BasicAuth> </soap:Header> <soap:Body> <cwsl:Search xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <CmdId>a client id</CmdId> <vQuery> ... </vQuery> </cwsl:Search> </soap:Body> </soap:Envelope>
If there was no prior authentication, the <soap:Header> can include a <BasicAuth> block to ensure all the functionality is performed in one round trip.
<CmdId> is a SOAP client-provided string and appears in the response to identify the originating Search entry.
<vQuery> is the search query criteria and can only appear once. (See the following section, "vQuery".)
The data returned is contained within a <cwsl:Reply>. There is one <cwsl:Reply> element for each <cwsl:Search> element.
HTTP/1.1 200 OK Content-Type: text/xml Content-Length: <char length> SOAPAction: http://www.oracle.com/WebServices/Calendaring/1.0/Search <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Body> <cwsl:Reply xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <CmdId>a client id</CmdId> ... data ... </cwsl:Reply> </soap:Body> </soap:Envelope>
<CmdId> appears in the response, identifying the originating Search command.
If an error occurs during the processing of the request, a SOAP fault is returned. If there are multiple <cwsl:Search> elements, a fault is also returned.
The vQuery forms the basis for requesting data from web service. There are very specific limitations on the vQueries in the initial release.
To limit the potential impact on the Calendar server, the ocws.conf file has a few settings to override any query that is received.
[webservices] maxattendee=200 # limit the total number of attendees that can # be returned per instance. The default is 200. maxresults=200 # limit the total number of meetings or tasks # that can be returned in one query
Events can be queried by a single unique identifier or by a series of identifiers:
<!-- Ability to fetch a single event --> <!-- Remove the Where clause to return all events --> <vQuery> <Select>*</Select> <From>VEVENT</From> <Where>x-oracle-data-guid='event guid'</Where> </vQuery> <!-- Ability to fetch a multiple events --> <vQuery> <Select>*</Select> <From>VEVENT</From> <Where> x-oracle-data-guid ='event id 1' OR x-oracle-data-guid ='event id 2' OR x-oracle-data-guid ='event id 3' </Where> </vQuery>
<Select> may be provided, however it is not supported in the current version of web services. It may not appear if all attributes are required. The value may be "*" to request all event attributes. The property may appear multiple times in order to list the individual attributes required. If only individual attributes are required, they must be explicitly listed.
Events can be queried by date range:
<!-- Ability to fetch events within a time range --> <vQuery> <Select>*</Select> <From>VEVENT</From> <Where>dtend >= 'starttime' AND dtstart <= 'endtime'</Where> </vQuery>
In this example, starttime and endtime provide the time range, in UTC, to be returned. Please note the proper XML encoding of the string within the <Where> clause.
All other event query forms will generate an error.
The event query result set is returned using the xCal draft specification, embedded within the <cwsl:Reply> tag.
<soap:Body> <cwsl:Reply xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <CmdId>a client id</CmdId> <xCal:iCalendar xmlns:xCal= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <vcalendar version="2.0" prodid=...> <vevent> <x-oracle-data-guid>fjldjfdslkjfdksj </x-oracle-data-guid> <dtstamp>19980309T231000Z</dtstamp> <uid>ffdtasfdtasfdta</uid> <summary>My event</summary> <location>Soleil</location> <x-oracle-eventtype>PUBLIC</x-oracle-eventtype> </vevent> </vcalendar> </xCal:iCalendar> </cwsl:Reply> </soap:Body>
There will be no sorting of returned data.
Tasks can be queried by a single unique identifier or by a series of identifiers:
<!-- Ability to fetch a single task --> <!-- Remove the Where clause to return all tasks --> <vQuery> <Select>*</Select> <From>VTODO</From> <Where>x-oracle-data-guid = 'task guid'</Where> </vQuery> <!-- Ability to fetch multiple tasks --> <vQuery> <Select>*</Select> <From>VTODO</From> <Where> x-oracle-data-guid = 'task id 1' OR x-oracle-data-guid = 'task id 2' OR x-oracle-data-guid = 'task id 3' </Where> </vQuery>
The <Where> clause contains the x-oracle-data-guid = string where the right-hand side is an iCal task GUID.
Active Tasks can be queried by date range:
<!-- Ability to fetch active tasks by time range --> <vQuery> <Select>*</Select> <From>VTODO</From> <vCall> <ActiveTasks> <StartTime>20020701T000000Z</StartTime> <EndTime>20020801T000000Z</EndTime> </ActiveTasks> </vCall> </vQuery>
<Select> may be provided, however it is not supported in the current version of web services. It may not appear if all attributes are required. The value may be "*" to request all task attributes. If only individual attributes are required, they must be explicitly listed.
All other task query forms will generate an error.
The <vCall> element indicates the use of an internal procedure (like a database stored procedure). The child element provides the name of the stored procedure to be invoked, as well as the arguments required by the call.
The task query result set is returned using the xCal draft specification, embedded within the <cwsl:Reply> tag.
<soap:Body> <cwsl:Reply xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <CmdId>a client id</CmdId> <xCal:iCalendar xmlns:xCal= "http://www.oracle.com/WebServices/Calendaring/1.0/"> <vcalendar version="2.0" prodid=...> <vtodo> <x-oracle-data-guid>JKLFJLJK</x-oracle-data-guid> <uid>ffdtasfdtasfdta</uid> <dtstamp>19980309T231000Z</dtstamp> <summary>My task</summary> <priority>2</priority> </vevent> </vcalendar> </xCal:iCalendar> </cwsl:Reply> </soap:Body>
The ability to create a meeting on the calendar server is provided through the Create SOAP method. Like other methods, the implementation is limited to creating simple meetings or daily notes. Attributes are limited to class, description, dstart, duration, location, priority, summary, start time, UID and event-type.
<!-- Sent to Web Services --> <Body> <Create> <CmdId>a command id</CmdId> <!-- here is the event select query --> <!-- The original event property/values --> <iCalendar> <vcalendar version="2.0" prodid="any string"> <vevent> <class>PUBLIC|PRIVATE|CONFIDENTIAL</class> <description>a long description</description> <dtstart>mmmm</dtstart> <duration>nnnnM/ duration > <location>my location</location> <priority>0|2|5|7|9</priority> <summary>a title</summary> <uid>a client uid</uid> <x-oracle-eventtype>APPOINTMENT|DAY EVENT| DAILY NOTE|HOLIDAY </x-oracle-eventtype> </vevent> </vcalendar> </iCalendar> </Create> </Body>
The following attributes are to be specified:
<!-- Received from Web Services --> <!-- failure will result in a SOAP fault --> <Body> <CreateReply> <CmdId>a command id</CmdId> <x-oracle-data-guid>cccc</x-oracle-data-guid> </CreateReply> </Body>
The response will be either a SOAP fault or a CreateReply containing the GUID of the event just created.
The following Create issues are to be expected with this release:
The Delete SOAP method provides the ability to delete a meeting, daily note or day event. This includes the ability to delete an instance of a repeating/recurring meeting.
<!-- Sent to Web Services --> <Body> <Delete> <CmdId>a command id</CmdId> <!-- here is the event select query --> <vQuery> <select>*</select> <from>VEVENT</from> <where>x-oracle-data-guid = 'some guid'</where> </vQuery> </Delete> </Body>
The vQuery uniquely identifies a previously returned data GUID. The GUID contains all the information to uniquely identify the instance of a repeating meeting or the recurrence of a recurrence rule.
The vQuery is used to identify the item to be deleted; only one item can be deleted at a time.
<!-Received from Web Services --> <!-- failure will result in a SOAP fault --> <Body> <DeleteReply> <CmdId>a command id</CmdId> <x-oracle-data-guid>cccc</x-oracle-data-guid> </DeleteReply> </Body>
DeleteReply contains the GUID of the deleted item.
The SOAP Modify method permits the modification of xCal properties and attributes. Only a few attributes can be modified. A modify method is made up of 3 sections: the query, the original iCalendar object properties, and the new iCalendar object properties.
<!-- Sent to Web Services --> <Body> <Modify> <CmdId>a command id</CmdId> <!-- here is the event select query --> <vQuery> ... </vQuery> <!-- The original event property/values --> <iCalendar> ... </iCalendar> <!-- The modified event property/values --> <iCalendar> ... </iCalendar> </Modify> </Body>
The vQuery uniquely identifies a previously returned data GUID. The GUID contains all the information to uniquely identify the instance of a repeating meeting or the recurrence of a recurrence rule. The vQuery is used to identify the item to be modified; only one item can be modified at a time, including one simple event (meeting, daily note, or day event) or one instance of a repeating meeting. In a modify operation, properties can be changed, added, or removed (see the following table).
The modify reply returns a GUID of the event. It is very important to note that the GUID can change depending on the type of change applied to the calendar server. Some updates require a delete/recreate type of interaction.
<!-Received from Web Services --> <!-- failure will result in a SOAP fault --> <Body> <ModifyReply> <CmdId>a command id</CmdId> <x-oracle-data-guid>cccc</x-oracle-data-guid> </ModifyReply> </Body>
The first iCalendar object contains the properties to be modified, along with the original values. If there are attributes associated with them, those must be present as well. The second iCalendar object contains the new properties values to be applied.
<!-- The original event property/values --> <iCalendar> <vcalendar> <vevent> <summary>my old title</summary> <location>my old location</location> </vevent> </vcalendar> </iCalendar> <!-- The modified event property/values --> <iCalendar> <vcalendar> <vevent> <summary>my new title</summary> <location>my new location</location> </vevent> </vcalendar> </iCalendar>
The first iCalendar object does not contain any reference to the property to be added. The second iCalendar object contains the new property and value.
<!-- The original event property/values --> <iCalendar> <vcalendar> <vevent> </vevent> </vcalendar> </iCalendar> <!-- The modified event property/values --> <iCalendar> <vcalendar> <vevent> <summary>my new title</summary> </vevent> </vCalendar> </iCalendar>
The first iCalendar object contains the original property and value. The second iCalendar object does not contain the property.
<!-- The original event property/values --> <iCalendar> <vcalendar> <vevent> <summary>my old title</summary> </vevent> </vcalendar> </iCalendar> <!-- The modified event property/values --> <iCalendar> <vcalendar> <vevent> </vevent> </vcalendar> </iCalendar>
If there are other properties within the modify SOAP method, a SOAP fault will be generated (i.e. class, uid, x-oracle-eventtype, Web Conferencing attributes).
This command is used to test to see if the Oracle Calendar web service application server is active. The command has no other effect on web services.
POST <uri> HTTP/1.1 Content-Type: text/xml; charset="UTF-8" Content-Length: <char length> SOAPAction: http://www.oracle.com/WebServices/Calendaring/1.0/Ping <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Body> <cwsl:Ping xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> </cwsl:Ping> </soap:Body> </soap:Envelope>
The web service response for a success command is:
HTTP/1.1 200 OK Content-Type: text/xml Content-Length: <char length> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:PingReply xmlns:cwsl= "http://www.oracle.com/WebServices/Calendaring/1.0/"> </soap: PingReply> </soap:Envelope>
Once the protocol aspects have been taken care of, we are left with the data. For events and tasks, the xCal Draft is used as the official reference for the data format output in the SOAP response.
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. The interpretation of recurrence rules is very complicated and error prone.
In order to understand how web services supports repeating and recurring meetings stored on the calendar server, a few examples are provided.
NOTE: only vEvents and vTodos are supported in the xCal specification; vJournal and vFreebusy are not.
It is important to note that not all xCal elements and properties nor all calendar server attributes are supported in this release.
<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>
If a repeating meeting were pulled directly from the 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.
This is an example of a repeating meeting:
<vcalendar> <vevent> <uid>ORACLE:CALSERV:EVENT:6205/391</uid> <summary>SDK Development Review</summary> <status>CONFIRMED</status> <priority>5</priority> <organizer cn="Ray Bradbury">mailto:</organizer> <location>Salle Saturne (Client/Server)</location> <description> Review of SDK 9.0.4 and Calendar Web Services 9.0.4 Development Plans with PM </description> <dtstart tzid="EST5EDT">20021002T103000</dtstart> <dtend tzid="EST5EDT">20021002T120000</dtend> <class>PUBLIC</class> <rrule>FREQ=DAILY;INTERVAL=1;COUNT=1</rrule> <rdate>20021030T153000Z</rdate> <attendee cn="James Baldwin" partstat="NEEDS-ACTION">mailto:</attendee> <attendee partstat="NEEDS-ACTION"> mailto:Salle Saturne (Client/Server)</attendee> <attendee cn="Albert Camus" partstat="NEEDS-ACTION">mailto:</attendee> <attendee cn="Lewis Carroll" partstat="NEEDS-ACTION">mailto:</attendee> <attendee cn="Frederic Chopin" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Emily Dickinson" partstat="NEEDS-ACTION">mailto:</attendee> <attendee cn="Ray Bradbury" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Alfred Hitchcock" partstat="NEEDS-ACTION">mailto:</attendee> <attendee cn="Yasunari Kawabata" partstat="ACCEPTED">mailto:</attendee> <x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype> <x-oracle-event-guid>fdjskljfdlkj</x-oracle-event-guid> </vevent> <vevent> <uid>ORACLE:CALSERV:EVENT:6205/391</uid> <summary>SDK Development Review</summary> <status>CONFIRMED</status> <recurrance-id>20021030T153000Z</recurrance-id> <priority>5</priority> <organizer cn="Ray Bradbury">mailto:</organizer> <location>Salle Saturne (Client/Server)</location> <description></description> <dtstart>20021030T153000Z</dtstart> <dtend>20021030T170000Z</dtend> <class>PUBLIC</class> <attendee cn="James Baldwin" partstat="ACCEPTED">mailto:</attendee> <attendee partstat="NEEDS-ACTION"> mailto:Salle Saturne (Client/Server)</attendee> <attendee cn="Albert Camus" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Lewis Carroll" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Frederic Chopin" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Emily Dickinson" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Ray Bradbury" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Alfred Hitchcock" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Yasunari Kawabata" partstat="DECLINED">mailto:</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> <timezone> <tzid>EST5EDT</tzid> <daylight> <tzoffsetto>-400</tzoffsetto> <tzoffsetfrom>-500</tzoffsetfrom> <dtstart>19910401T020000</dtstart> <rrule> FREQ=YEARLY;UNTIL=UNTIL=20750407T020000Z;BYMONTH=4;BYDAY=1SU </rrule> <tzname> Eastern Standard Time, Eastern Daylight Time </tzname> </daylight> <standard> <tzoffsetto>-0500</tzoffsetto> <tzoffsettfrom>-0400</tzoffsettfrom> <dtstart>19911025T020000</dtstart> <rrule> FREQ=YEARLY;UNTIL=20751031T020000Z;BYMONTH=10;BYDAY=-1SU </rrule> <tzname> Eastern Standard Time, Eastern Daylight Time </tzname> </standard> </timezone> </vcalendar>
Like a repeating meeting, an event with a recurrence rule requires an interpretation of the data with the vCalendar. Again the recurrence rule provides the information required to interpret or generate all the specific meeting information. This requires complicated processing on the client side.
The Oracle Connector for Outlook can create events with pure recurrence rules.
<vcalendar> <vevent> <uid>ORACLE:CALSERV:EVENT:10750/391</uid> <summary>test recur weekly 3 times</summary> <status>TENTATIVE</status> <priority>5</priority> <organizer cn="Stephen King">mailto:</organizer> <location></location> <description></description> <dtstart tzid="EST5EDT">20021025T123000</dtstart> <dtend tzid="EST5EDT">20021025T133000</dtend> <created>20021101T191154Z</created> <class>PUBLIC</class> <rrule> FREQ=WEEKLY;BYDAY=FR;COUNT=3;INTERVAL=1;WKST=SU </rrule> <rdate>20021101T173000Z</rdate> <attendee cn="Stephen King" partstat="ACCEPTED">mailto:</attendee> <x-oracle-event-guid>fdjskljfdlkj</x-oracle-event-guid> <x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype> </vevent> <vevent> <uid>ORACLE:CALSERV:EVENT:10750/391</uid> <summary>test recur weekly 3 times</summary> <status>CONFIRMED</status> <recurrance-id>20021101T173000Z</recurrance-id> <priority>5</priority> <organizer cn="Stephen King">mailto:</organizer> <location></location> <description></description> <dtstart>20021101T173000Z</dtstart> <dtend>20021101T183000Z</dtend> <created>20021101T191154Z</created> <class>PUBLIC</class> <attendee cn="Stephen King" partstat="ACCEPTED">mailto:</attendee> <x-oracle-event-guid>fdjskljfdlkj</x-oracle-event-guid> <x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype> <x-oracle-eventinstance-guid>fdjskljfdlkj </x-oracle-eventinstance-guid> <x-oracle-data-guid>fdjskljfdlkj</x-oracle-data-guid> </vevent> <vtimezone> <tzid>EST5EDT</tzid> <daylight> <tzoffsetto>-0400</tzoffsetto> <tzoffsettfrom>-0500</tzoffsettfrom> <dtstart>19910401T020000</dtstart> <rrule> FREQ=YEARLY;UNTIL=20750407T020000Z;BYMONTH=4;BYDAY=1SU </rrule> <tzname> Eastern Standard Time, Eastern Daylight Time </tzname> </daylight> <standard> <tzoffsetto>-0500</tzoffsetto> <tzoffsettfrom>-0400</tzoffsettfrom> <dtstart>19911025T020000</dtstart> <rrule> FREQ=YEARLY;UNTIL=20751031T020000Z;BYMONTH=10;BYDAY=-1SU </rrule> <tzname> Eastern Standard Time, Eastern Daylight Time </tzname> </standard> </vtimezone> </vcalendar>
web services will provide repeating and recurrence rules as broken up individual elements ("expanded").
Expanded repeating and recurring meetings will have the following form:
<vcalendar> <vevent> <uid>ORACLE:CALSERV:EVENT:6205/391@20021030T153000Z</uid> <summary>SDK Development Review</summary> <status>CONFIRMED</status> <priority>5</priority> <organizer cn="Ray Bradbury">mailto:</organizer> <location>Salle Saturne (Client/Server)</location> <description></description> <dtstart>20021030T153000Z</dtstart> <dtend>20021030T170000Z</dtend> <class>PUBLIC</class> <attendee cn="James Baldwin" partstat="ACCEPTED">mailto:</attendee> <attendee partstat="NEEDS-ACTION"> mailto:Salle Saturne (Client/Server)</attendee> <attendee cn="Albert Camus" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Lewis Carroll" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Frederic Chopin" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Emily Dickinson" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Ray Bradbury" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Alfred Hitchcock" partstat="ACCEPTED">mailto:</attendee> <attendee cn="Yasunari Kawabata" partstat="DECLINED">mailto:</attendee> <x-oracle-event-guid>fdjkfdsjfljkds</x-oracle-event-guid> <x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype> <x-oracle-eventinstance-guid>fdjskljfdlkj </x-oracle-eventinstance-guid> <x-oracle-data-guid>fdjskljfdlkj</x-oracle-data-guid> </vevent> </vcalendar>
<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>
<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 are represented as:
<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>
<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>
This new property is used to identify the event type stored on the calendar server. This attribute is selectable in the <select> clause and is returned as an element in a vEvent. The possible values are:
In xCal, priorities are mapping to specific Calendar Server levels for maximum compatibility with the suite of calendar clients.
