| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14477-01 |
|
|
View PDF |
| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14477-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 following is the structure of a SOAP request:
HTTP header <?xml version='1.0' encoding='UTF-8'?> <!-- SOAP envelope --> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <SOAP-ENV:Header> <!-- If Basic Authentication is used, it is placed here in the SOAP header --> </SOAP-ENV:Header> <SOAP-ENV:Body> <!-- The SOAP body contains the methods used to perform actions on the Calendar Server --> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
The following is the structure of a SOAP reply:
HTTP header <?xml version="1.0" encoding="utf-8" ?> <!-- SOAP envelope --> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" soap:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"> <soap:Body> <!-- The SOAP body contains the result of the SOAP command or a SOAP fault if the command was not successful --> </soap:Body> </soap:Envelope>
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:
Security and Authentication Design
Basic Authentication
Proxy Authentication
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:
HTTP SSL and Web-based certificates
Simple authentication
An application-specific authentication mechanism (for Oracle Collaboration Suite).
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.
Proxy authentication, or application-to-application authentication, allows any application developed with Calendar Web Services Toolkit to establish a trusted authenticated link to the Calendar Server. This application does not require the authentication of the end-user using it.
The following components are required to enable proxy authentication:
Calendar Web Services Toolkit (Calendarlet.jar)
Calendar Web Services (OCAS)
Calendar Server (Calserv)
Oracle Internet Directory (OID)
You must configure your Collaboration Suite deployment so that the Calendar Server is connected to OID. This should have been done by default. Proxy authentication is designed to use OID security schemes.
You must have access to the following:
OID administrator account
LDAP tools (located in $ORACLE_HOME/ldap/bin)
Oracle Calendar server administrator password
The following steps describe how to configure OID and grant proxy privileges to your application.
Step 1 Create an entry for your application product in OID
Create the following entry in OID, where MyApplicationProduct is the name of your application product:
cn=OracleContext
cn=Products
cn=MyApplicationProduct
To create this entry, create the following LDIF file named MyApplicationProduct.ldif:
dn: cn= MyApplicationProduct, cn=Products, cn=OracleContext objectClass: orclContainer objectClass: top
Enter the following command to add the entry defined in MyApplicationProduct.ldif to OID:
./ldapadd -h HOSTNAME.COM -p OIDPORT -D "cn=orcladmin" -w PASSWROD -f ./MyApplicationProduct.ldif
HOSTNAME.COM is the OID server hostname
PASSWORD is the password for the OID directory
OIDPORT is the OID port
Step 2 Create an application entity for your application in OID
Create the following entry in OID, where MyAppName is the name of your application:
cn=OracleContext
cn=Products
cn=MyApplicationProduct
orclApplicationCommonName=MyAppName
To create this entry, create the following LDIF file named MyAppName.ldif:
dn: orclApplicationCommonName= MyAppName, cn= MyApplicationProduct, cn=Products, cn=OracleContext objectClass: orclApplicationEntity objectClass: top orclApplicationCommonName: MyAppName userpassword: test1
Enter the following command to add the entry defined in MyAppName.ldif to OID:
./ldapadd -h HOSTNAME.COM -p OIDPORT -D "cn=orcladmin" -w PASSWORD -f ./MyAppName.ldif
Step 3 Ensure the application entity entry is properly configured
Perform an LDAP search to search for the entry's distinguished name, which is as follows:
"orclApplicationCommonName= MyAppName, cn= MyApplicationProduct, cn=Products, cn=OracleContext"
To do this enter the following command:
./ldapsearch -h HOSTNAME.COM -p OIDPORT -D "cn=orcladmin" -w PASSWORD -b "cn=MyApplicationProduct,cn=Products,cn=OracleContext" "objectclass=orclApplicationEntity" "c"
Step 4 Grant proxy privileges to the new application entity
Enter the following command from the directory $ORACLE_HOME/ocal/bin. You will need the Oracle Calendar server admin password:
./unioidconf -grantproxyprivilege \ "orclApplicationCommonName= MyAppName, cn=MyApplicationProduct, cn=Products, cn=OracleContext"
This command will create the following entry in OID:
dc=com
dc=oracle
dc=us
cn=OracleContext
cn=Products
cn=Calendar
cn=UserProxyPrivilege
uniquemember: orclApplicationCommonName= MyAppName, cn= MyApplicationProduct, cn=Products, cn=OracleContext
Once you have successfully configured OID and Oracle Calendar server, you enable proxy authentication following these steps in your Java application:
Replace the BasucAuth class with the ProxyAuth class.
Set the end user identity, proxy application name, and proxy application password that you have registered in OID.
Your Java code will look similar to the following:
ProxyAuth auth = new ProxyAuth();
auth.setApplicationName("orclApplicationCommonName=MyAppName, cn=MyApplicationProduct, cn=Products, cn=OracleContext");
auth.setApplicationPassword(Òtest1Ó);
auth.setName(myUserId);
Your application will no longer need to pass the end-user's password to Calendar Web Services. From now on, it is your application's responsibility to authenticate the end-user.
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 Oracle 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:
The data content types are agreed to by both parties ahead of time. This is not useful for general SOAP interaction, only one-to-one site integrations.
Using XML Schemas, where the schema and namespace is used to relate all typing information.
Using XML Schemas and explicit type attributes, where each element in the SOAP XML tree requires an 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:
A faultcode, which can be one of the following values:
VersionMismatch indicating the SOAP namespace is incorrect.
Client indicating a problem originating from the incoming message.
Server indicating a problem occurred during the processing of the request.
A faultstring, which is the textual message of the error that has occurred. This is the application system error string. The default string language is English.
A detail element, used as the container to provide extended information. In our case, the complete application system error log entry is returned to the SOAP client. If server side event logging is set to debug in 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:
Generally you need only concern yourself with the first and last segments, which in this case are:
Module 000C = SYS_MODULE_DATAACCESS
Error 00000029 = e_soapSOAPRequestCode_MissingModifyCmd
For a list of Module and Error values, see Chapter 13, "Oracle 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 calendar SOAP client and calendar SOAP server. The following methods, taken directly from the CAP draft dated March 2002, provide the main functionality for the Calendar 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 Calendar language uses "http://www.oracle.com/WebServices/Calendaring/1.0/" as the namespace.
The following session command is supported:
NoOp performs no operation on the data store, but is used to preauthenticate.
The following calendar commands are supported:
Ping performs a simple check to ensure that Web services is active.
Create performs a create of a new meeting.
Delete performs a delete of an event or instance.
Modify performs an update of an event or instance for specific properties.
Search performs a request to retrieve data through the service.
Summary counts the number of unconfirmed events, open active tasks, and overdue active tasks in a given time range.
It is important to note that some of these methods are greatly restricted in this release.
Verifies the validity of an authentication SOAP header, without executing anything on the server. The NoOp command can only fail if there is a SOAP header problem.
Sample Request
<SOAP-ENV:Body> <cwsl:NoOp xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/"/> </SOAP-ENV:Body>
Sample Successful Reply
<soap:Body> <NoOpReply> </NoOpReply> </soap:Body>
Tests to see if the Oracle Calendar Web service application server is active. The command has no other effect on Web services.
Sample Request
<SOAP-ENV:Body> <cwsl:Ping xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/"/> </SOAP-ENV:Body>
Sample Successful Reply
<soap:Body> <PingReply> </PingReply> </soap:Body>
Creates <vevent> components on the Oracle Calendar server. In this release, the Create method has the following issues and limitations:
The method does not support the creation of <vtodo> components.
There is no current mechanism for creating a recurring meeting.
There is no current mechanism for creating a meeting with additional attendees.
The response will be either a SOAP fault or a CreateReply containing the GUID of the event just created.
Sample Request
Certain properties must be specified in the Create command. Chapter 12, "Oracle Calendar Web Services Supported Data Components and Properties" indicates these properties.
<SOAP-ENV:Body>
<cwsl:Create xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>Testoraptor Command 31</CmdId>
<iCalendar>
<vcalendar prodid="-//Oracle//Calendaring//Calendarlet//EN" version="2.0">
<vevent>
<class>PRIVATE</class>
<description>Sample Event Create</description>
<dtstart value="DATE">20050113</dtstart>
<duration>PT00H00M</duration>
<location>Vision Corporation</location>
<summary>EventCreate Alarm Display Type Day Event Test</summary>
<uid>TESTORAPTOR-UID-2</uid>
<x-oracle-eventtype>DAY EVENT</x-oracle-eventtype>
<x-oracle-isrtcenabled>false</x-oracle-isrtcenabled>
<valarm>
<action>DISPLAY</action>
<trigger>-PT1H05M</trigger>
</valarm>
</vevent>
</vcalendar>
</iCalendar>
</cwsl:Create>
</SOAP-ENV:Body>
Sample Successful Reply
<soap:Body>
<cwsl:CreateReply
xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>Testoraptor Command 31</CmdId>
<x-oracle-data-guid>E1+352322565+14503+442957968</x-oracle-data-guid>
</cwsl:CreateReply>
</soap:Body>
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.
Request Syntax
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.
<SOAP-ENV:Body>
<cwsl:Delete xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>Testoraptor Command 768</CmdId>
<vQuery>
<From>VEVENT</From>
<Where>
x-oracle-data-guid =
'Data GUID of an event or an instance of a repeating event'</Where>
</vQuery>
</cwsl:Delete>
</SOAP-ENV:Body>
The vQuery is used to identify the item to be deleted; only one item can be deleted at a time.
Sample Request
<SOAP-ENV:Body>
<cwsl:Delete xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>Testoraptor Command 768</CmdId>
<vQuery>
<From>VEVENT</From>
<Where>x-oracle-data-guid = 'E1+469763101+14503+442958019'</Where>
</vQuery>
</cwsl:Delete>
</SOAP-ENV:Body>
Sample Successful Reply
DeleteReply will contain the GUID of the deleted item.
<soap:Body>
<DeleteReply>
<CmdId>Testoraptor Command 768</CmdId>
<x-oracle-data-guid>E1+469763101+14503+442958019</x-oracle-data-guid>
</DeleteReply>
</soap:Body>
Modifies, adds, or deletes an event's properties. Only a few properties may be modified, added, or deleted.
Request Syntax
The Modify method is made up of three sections: the query, the iCalendar object properties, and the new iCalendar object properties:
<SOAP-ENV:Body>
<cwsl:Modify xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<vQuery>
<From>
<!-- VEVENT -->
</From>
<Where>
<!-- The event query -->
</Where>
</vQuery>
<iCalendar>
<!-- The event properties (and values) to be changed -->
</iCalendar>
<iCalendar>
<!-- The new event properties and values -->
</iCalendar>
</cwsl:Modify>
</SOAP-ENV:Body>
Only certain properties may be modified with the Modify command. Chapter 12, "Oracle Calendar Web Services Supported Data Components and Properties" indicates these properties.
If there are other properties within the modify SOAP method, a SOAP fault will be generated (for example, class, uid, x-oracle-eventtype, Web Conferencing attributes).
vQuery Section
The vQuery section is used to identify the calendar component to be modified. Only one calendar component can be modified at a time.
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).
Modifying Properties
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>
Adding Properties
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>
Deleting Properties
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>
Reply Syntax
The Modify reply returns the GUID of the modified event. It is very important to note that the GUID can change depending on the type of change applied to the Oracle 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>
Sample Request
<SOAP-ENV:Body>
<cwsl:Modify xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>Testoraptor Command 468</CmdId>
<vQuery>
<From>VEVENT</From>
<Where>x-oracle-data-guid = 'E1+335545478+14503+442957967'</Where>
</vQuery>
<iCalendar>
<vcalendar prodid="-//Oracle//Calendaring//Calendarlet//EN" version="2.0">
<vevent>
<class>PUBLIC</class>
<x-oracle-isrtcenabled>false</x-oracle-isrtcenabled>
</vevent>
</vcalendar>
</iCalendar>
<iCalendar>
<vcalendar prodid="-//Oracle//Calendaring//Calendarlet//EN" version="2.0">
<vevent>
<class>CONFIDENTIAL</class>
<x-oracle-isrtcenabled>false</x-oracle-isrtcenabled>
</vevent>
</vcalendar>
</iCalendar>
</cwsl:Modify>
</SOAP-ENV:Body>
Sample Successful Reply
The Modify method reply returns the GUID of the modified calendar component. It is very important to note that the GUID can change depending on the type of change applied to the Oracle Calendar server. Some updates require a delete/recreate type of interaction.
<soap:Body>
<ModifyReply>
<CmdId>Testoraptor Command 468</CmdId>
<x-oracle-data-guid>E1+335545478+14503+442957967</x-oracle-data-guid>
</ModifyReply>
</soap:Body>
Retrieve Events, Tasks, Contacts, and User information from the Calendar Server.
Request Syntax
<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".)
<soap:Body>
<cwsl:Search xmlns:cwsl=
"http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>
<!-- ID string provided by the client -->
</CmdId>
<vQuery>
<!-- The search query criteria -->
</vQuery>
<x-oracle-limitattendees>
<!-- Integer value -->
</x-oracle-limitattendees>
<x-oracle-overlap
<!-- Either the string "on" or "off" -->
</x-oracle-overlap>
<x-oracle-searchhandle></x-oracle-searchhandle>
<x-oracle-timestamp>
<!-- Timestamp string in UTC format -->
</x-oracle-timestamp>
<x-oracle-basicsearch>
<!-- Search string -->
</x-oracle-basicsearch>
</cwsl:Search>
</soap:Body>
The following properties are optional:
Integer value that limits the number of attendees from the Calendar store. If no attendee information is required, set this value to "0". Retrieving attendee information is typically a very expensive operation on the Calendar store.
If this property is not set, all attendee information will be returned, limited by Web Services configuration and Calendar store settings.
If this property is set to "on", the Search method will retrieve events that overlap the specified date range. For example, if the date range is today, and this property is set to "on", the Search method would retrieve an event that starts yesterday and finishes tomorrow. If this property is set to "off", the Search method would not retrieve this event.
By default, this property is set to "off".
The following properties are required if you want to use the capabilities of Ultra Search:
If this element exists in the SOAP request, the internal Calendar store search API will be used. Set the value of this property to the empty string, "".
An xCal UTC string that represents the timestamp of the SOAP request. Ultra Search uses this timestamp if no dstart information is provided.
The following property is only available if you are using the capabilities of Ultra Search:
The Search method will retrieve events that contain the specified string in any of the <title>, <location>, or <description> properties.
Reply Syntax
The data returned is contained within a <cwsl:Reply>. There is one <cwsl:Reply> element for each <cwsl:Search> element.
<soap:Body>
<cwsl:Reply xmlns:cwsl=
"http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>
<!-- ID string from the originating Search SOAP request -->
</CmdId>
<!-- Data returned from the Search command -->
</cwsl:Reply>
</soap:Body>
vQuery
The vQuery forms the basis for requesting data from the Calendar store.
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>
<From>VEVENT</From>
<Where>x-oracle-data-guid='event guid'</Where>
</vQuery>
<!-- Ability to fetch a multiple events -->
<vQuery>
<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>
Events can be queried by date range:
<!-- Ability to fetch events within a time range -->
<vQuery>
<From>VEVENT</From>
<Where>dtstart >= 'starttime' AND dtend <= 'endtime'</Where>
</vQuery>
In this example, starttime and endtime provide the time range, in UTC, to be returned. Note the proper XML encoding of the string within the <Where> clause.
Note:
All other event query forms will generate an error. In particular, date range queries bust be in the following form:DTEND >= start_date && DTSTART <= end_date
Other date range queries are possible only with the Calendarlet or the public static String getDateRangeQuery(Calendar in_startDate, Calendar in_endDate) method in the CalendarUtils class.
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>
<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. All attributes are returned in the reply.
There is no sort order for the returned data.
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>
</vtodo>
</vcalendar>
</xCal:iCalendar>
</cwsl:Reply>
</soap:Body>
Ultra Search Capabilities
In addition to retrieving events in a given date range, you may use the capabilities of Ultra Search to search for text strings in <summary>, <description>, and <location> properties.
The following example searches for events that take place between February 25, 2005, 5:00am and February 26, 2006, 4:59am and contain the string "Montreal" in the <location> property:
<vQuery>
<From>VEVENT</From>
<Where>DTSTART >= '20050225T050000Z'
AND DTEND <= '20050226T045900Z'
AND LOCATION=Montreal
</Where>
<x-oracle-searchhandle>
</x-oracle-searchhandle>
<x-oracle-timestamp>20050225T050000Z</x-oracle-timestamp>
</vQuery>
You may also use the <x-oracle-basicsearch> property to search for events that contain a specified string in any of the <title>, <location>, or <description> properties.
You may use Ultra Search capabilities only for searching events.
Performance Issues
To limit the potential impact on the Oracle 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
If you use Ultra Search to retrieve events by searching for a string (as opposed to searching by <x-oracle-data-guid>), the attendees of those retrieved events will not be listed, other than the one specified in the property <x-oracle-loginuser>. However, if you search by <x-oracle-data-guid>, the attendees of the retrieved events will be listed.
Attendees are listed only for searches by <x-oracle-data-guid> because retrieving attendee lists may have a negative impact on performance.
Sample Request
<SOAP-ENV:Body>
<cwsl:Search xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>Testoraptor Command 458</CmdId>
<vQuery>
<From>VEVENT</From>
<Where>LOCATION=OracleUltraSearchLocationText
AND DTSTART >=20040913T040000Z AND DTEND <=20050113T050000Z
</Where>
<x-oracle-searchhandle>
</x-oracle-searchhandle>
<x-oracle-timestamp>20050113T050000Z</x-oracle-timestamp>
</vQuery>
</cwsl:Search>
</SOAP-ENV:Body>
Sample Successful Reply
<soap:Body>
<cwsl:Reply xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>Testoraptor Command 458</CmdId>
<x-oracle-searchhandle>
</x-oracle-searchhandle>
<iCalendar
xmlns:xcal="http://www.oracle.com/WebServices/Calendaring/1.0/">
<vcalendar version="2.0" prodid="-//Oracle//Calendaring//OCAS//EN">
<vevent>
<uid>TESTORAPTOR-UID-76</uid>
<transp>OPAQUE</transp>
<summary>OracleUltraSearchText</summary>
<status>CONFIRMED</status>
<priority>5</priority>
<organizer cn="Web Services">
mailto:webserivces@us.oracle.com
</organizer>
<location>OracleUltraSearchLocationText</location>
<description>OracleUltraSearchText</description>
<dtstart>20041129T050000Z</dtstart>
<dtend>20041129T060000Z</dtend>
<class>PRIVATE</class>
<attendee cutype="INDIVIDUAL" cn="Web Services" partstat="ACCEPTED">
mailto:webserivces@us.oracle.com
</attendee>
<x-oracle-areothersinvited>FALSE</x-oracle-areothersinvited>
<x-oracle-data-guid>E1+251659385+14503+442958018</x-oracle-data-guid>
<x-oracle-isextrainstance>FALSE</x-oracle-isextrainstance>
<x-oracle-isexception>FALSE</x-oracle-isexception>
<x-oracle-loginuser cn="Web Services">
mailto:webserivces@us.oracle.com
</x-oracle-loginuser>
<x-oracle-eventinstance-guid>
I1+251659385+14503+1+442958018
</x-oracle-eventinstance-guid>
<x-oracle-event-guid>
E1+251659385+14503+442958018
</x-oracle-event-guid>
<x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype>
<x-oracle-search-relevance>84</x-oracle-search-relevance>
</vevent>
</vcalendar>
<vcalendar version="2.0" prodid="-//Oracle//Calendaring//OCAS//EN">
<vevent>
<uid>TESTORAPTOR-UID-78</uid>
<transp>OPAQUE</transp>
<summary>OracleUltraSearchText</summary>
<status>CONFIRMED</status>
<priority>5</priority>
<organizer cn="Web Services">
mailto:webserivces@us.oracle.com
</organizer>
<location>OracleUltraSearchLocationText</location>
<description>OracleUltraSearchText</description>
<dtstart>20041129T050000Z</dtstart>
<dtend>20050309T050000Z</dtend>
<class>PRIVATE</class>
<attendee cutype="INDIVIDUAL" cn="Web Services" partstat="ACCEPTED">
mailto:webserivces@us.oracle.com
</attendee>
<x-oracle-areothersinvited>FALSE</x-oracle-areothersinvited>
<x-oracle-data-guid>
E1+469763101+14503+442958019
</x-oracle-data-guid>
<x-oracle-isextrainstance>FALSE</x-oracle-isextrainstance>
<x-oracle-isexception>FALSE</x-oracle-isexception>
<x-oracle-loginuser cn="Web Services">
mailto:webserivces@us.oracle.com
</x-oracle-loginuser>
<x-oracle-eventinstance-guid>
I1+469763101+14503+1+442958019
</x-oracle-eventinstance-guid>
<x-oracle-event-guid>
E1+469763101+14503+442958019
</x-oracle-event-guid>
<x-oracle-eventtype>APPOINTMENT</x-oracle-eventtype>
<x-oracle-search-relevance>100</x-oracle-search-relevance>
</vevent>
</vcalendar>
</iCalendar>
</cwsl:Reply>
</soap:Body>
Counts the number of unconfirmed events, open active tasks, and overdue active tasks in a given time range.
Request Syntax
The Summary command consists of one or two <vCall> elements. To count the number of unconfirmed events in a given time range, use the <EventsCount> element in a <vCall> element. To count the number of open or overdue active tasks in a given time range, use the <ActiveTasksCount> element.
Either an <EventCount> or an <ActiveTasksCount> element may appear in a <vCall> element. However, you may count the number of both unconfirmed events and open and overdue tasks. In this case, use two <vCall> elements.
Specify the start and end times of the time ranges in UTC time.
The following is the structure of the SOAP body of the Summary command:
<SOAP-ENV:Body>
<cwsl:Summary xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>
<!-- The command ID. This string is defined by the developer. -->
</CmdId>
<vCall>
<EventsCount>
<StartTime>
<!-- UTC date-time value. The date and time of the start
of the time range. -->
</StartTime>
<EndTime>
<!-- UTC date-time value. The date and time of the end
of the time range. -->
</EndTime>
<Unconfirmed>
<!-- Boolean. If set to TRUE, the SOAP reply will indicate
the number of unconfirmed tasks within the given
time range. -->
</Unconfirmed>
</EventsCount>
</vCall>
<vCall>
<ActiveTasksCount>
<StartTime>
<!-- UTC date-time value. The date and time of the start
of the time range. -->
</StartTime>
<EndTime>
<!-- UTC date-time value. The date and time of the end
of the time range. -->
</EndTime>
<Open>
<!-- Boolean. If set to TRUE, the SOAP reply will indicate
the number of open active tasks within the given
time range. -->
</Open>
<Overdue>
<!-- Boolean. If set to TRUE, the SOAP reply will indicate
the number of overdue active tasks within the given
time range. -->
</Overdue>
</ActiveTasksCount>
</vCall>
</cwsl:Summary>
</SOAP-ENV:Body>
Reply Syntax
Depending on the value of <Unconfirmed>, <Open>, and <Overdue>, a successful Summary command reply will contain <Unconfirmed>, <Open>, and <Overdue> elements that indicate the number of unconfirmed events, open active tasks, and overdue active tasks, respectively.
The following is the structure of the SOAP reply of the Summary command:
<soap:Body>
<cwsl:SummaryReply
xmlns:cwsl="http://www.oracle.com/WebServices/Calendaring/1.0/">
<CmdId>Testoraptor Command 801</CmdId>
<EventsCount>
<Unconfirmed>
<!-- Integer. Number of unconfirmed events. -->
</Unconfirmed>
</EventsCount>
<ActiveTasksCount>
<Open>
<!-- Integer. Number of open active tasks. -->
</Open>
<Overdue>
<!-- Integer. Number of overdue active tasks. -->
</Overdue>
</ActiveTasksCount>
</cwsl:SummaryReply>
</soap:Body>
