| Oracle® Communications Calendar Server WCAP Developer's Guide Release 7.0 E56603-01 |
|
|
PDF · Mobi · ePub |
| Oracle® Communications Calendar Server WCAP Developer's Guide Release 7.0 E56603-01 |
|
|
PDF · Mobi · ePub |
This chapter contains topics of common interest that span Oracle Communications Calendar Server WCAP commands.
Topics:
See the topic on administering Calendar Server access in Calendar Server System Administrator's Guide.
Attachments can be stored as part of an event by providing it as a MIME part in either the WCAP "storeevents.wcap" or "storetodos.wcap" command over the HTTP POST command. Each user calendar has a special collection called a dropbox. The dropbox stores calendar attachments. Attachments are not stored as part of the event or task itself. In the case of group scheduled events, the attachments are stored in the organizer's dropbox, and attendee's events refer to the organizer's attachment. The location of the attachment is stored in the event or the task's X-S1CS-ATTACH-ID property value.
Attachments can be fetched by using the "fetchattachment.wcap" command.
http://calendarserver:port/wcap/fetchattachment.wcap?
fmt-out=text/xml
&attachid=/home/jdoe/calendar/dropbox/D1E96253-FD32-4E6A-BA92-0637D8F80EF7.dropbox/%2520.jpg
&id=sesionid
Using the "storeevents.wcap" or "storetodos.wcap" command, you can delete the attachments for an event or todo, by sending the attachment URL (X-S1CS-ATTACH-ID value) as value of the deleteattach parameter. The value can be a semicolon separated list of attachment URLs. Attachments are automatically deleted if the events or tasks referring to it are deleted.
Attachments are not sent to external invitees or as part of iCalendar Message-Based Interoperability Protocol (iMIP).
Each attendee entry can contain several sub-parameters, such as invitation participation status, whether attendance is required or not, type of the attendee, and so forth. All such sub-parameters are encapsulated in a syntax very similar to the parameters for the ATTENDEE property defined in the iCalendar Specification (RFC 5545). Read the entire document to have the necessary background information to understand the WCAP attendee syntax. Some differences exist, for example, WCAP uses a different delimiter, ^, to set apart these sub-parameters. (However, WCAP uses the standard iCalendar semicolon delimiter for separating attendees.)
For example, where iCalendar uses the following:
PARSTAT=ACCEPTED;RSVP=TRUE:mailto:abc@xyz.com
WCAP formats it this way:
PARSTAT=ACCEPTED^RSVP=TRUE^mailto:abc@xyz.com
The default setting for the PARTSTAT sub-parameter on creation of an event is NEEDS-ACTION, except for Organizer itself. It is changed to ACCEPTED or DECLINED when the attendee replies to the invitation. The PARTSTAT sub-parameter is reset to NEEDS-ACTION on any significant update from the Organizer. An attendee can be removed from an existing event by the Organizer, by storing the event again with the replace parameter value set to 1, and either not specifying the attendee in the attendee list or changing the attendee PARTSTAT sub-parameter value to X-NSCP-WCAP-ATTENDEE-DELETE.
The method parameter describes the type of store: invitation, response, cancellation. The value is used in the construction of the iCalendar Transport-Independent Interoperability Protocol (iTIP) message only. The actual required action is interpreted by the server from all other provided parameters.
Table 2-1 describes some parameter characters and their encoding.
The %xx string is the hexadecimal value of the character. For example, the & character is 26 in hexadecimal. Double quotes are not allowed as any part of a parameter value per RFC 5455.
Each call to a WCAP command also returns an error number in the property X-NSCP-WCAP-ERRNO. The value is 0 if the command succeeded. In some failure cases more detailed error messages are also included using the properties X-NSCP-WCAP-ERRNO-MESSAGE and X-NSCP-WCAP-ERRNO-DETAILED-MESSAGE.
Table 2-2 describes error codes returned by WCAP commands.
Table 2-2 Error Names, Values, and Meanings
| Error Name | Value | Meaning |
|---|---|---|
|
LOGOUT / UNKNOWN |
-1 |
Successful logout for logout command. Unknown internal server error for other commands. |
|
OK |
0 |
Command successful. |
|
LOGIN_FAILED |
1 |
Login failed, session ID timed out. Invalid session ID |
|
DELETE_EVENTS_BY_ID_FAILED |
6 |
Delete by event id command failed. |
|
SETCALPROPS_FAILED |
8 |
The set_calprops command failed. |
|
FETCH_EVENTS_BY_ID_FAILED |
9 |
Fetch by event id command failed. |
|
CREATECALENDAR_FAILED |
10 |
Create calendar command failed. |
|
DELETECALENDAR_FAILED |
11 |
Delete calendar command failed. |
|
STOREEVENTS_FAILED |
14 |
Store command for an event failed. |
|
STORETODOS_FAILED |
15 |
Store command for a todo failed. |
|
DELETE_TODOS_BY_ID_FAILED |
16 |
Delete by todo id command failed. |
|
FETCH_TODOS_BY_ID_FAILED |
17 |
Fetch by todo id command failed. |
|
SEARCH_CALPROPS_FAILED |
19 |
The search_calprops command failed. |
|
GET_CALPROPS_FAILED |
20 |
The get_calprops command failed. |
|
DELETEEVENTS_BY_RANGE_FAILED |
22 |
Delete events by time range command failed. |
|
DELETETODOS_BY_RANGE_FAILED |
23 |
Delete todos by time range command failed. |
|
CREATECALENDAR_ALREADY_EXISTS_FAILED |
25 |
The command createcalendar.wcap failed because a calendar with that name already exists in the database. |
|
ACCESS_DENIED_TO_CALENDAR |
28 |
The user is denied access to a calendar. |
|
CALENDAR_DOES_NOT_EXIST |
29 |
The requested calendar does not exist in the database. |
|
GET_FREEBUSY_FAILED |
39 |
Get free/busy command failed. |
|
STORE_FAILED_DOUBLE_BOOKED |
40 |
If double booking is not allowed in this calendar, storeevents fails with this error when attempting to store an event in a time slot that was already filled. |
|
WCAP_NO_SUCH_FORMAT |
58 |
Specified output format not recognized. |
|
COMPONENT_NOT_FOUND |
59 |
Returned when a fetch or delete is attempted on a resource that does not exist. |
|
BAD_ARGUMENTS |
60 |
Invalid arguments passed in such as invalid email address, invalid date, and so on. |
|
WCAP_MODIFY_NO_EVENT |
62 |
storeevents.wcap issued with storetype set to 2 (WCAP_STORE_TYPE_MODIFY) and the event does not exist. |
|
WCAP_CREATE_EXISTS |
63 |
storeevents.wcap issued with storetype set to 1 (WCAP_STORE_TYPE_CREATE) and the event already exists. |
|
LIST_SUBSCRIBED_FAILED |
72 |
list_subscribed.wcap failed. |
|
SUBSCRIBE_FAILED |
73 |
subscribe.wcap failed. |
|
UNSUBSCRIBE_FAILED |
74 |
unsubscribe.wcap failed. |
|
ANONYMOUS_NOT_ALLOWED |
75 |
Command cannot be executed without a valid sessionid. |
|
BAD_IMPORT_ARGUMENTS |
77 |
Incorrect parameter received by import.wcap. |
|
IMPORT_FAILURE |
78 |
Some events and todos were not imported successfully. |
|
ATTACHMENT_NOT_FOUND |
87 |
The attachment requested to be fetched from the server was not found. |
|
BAD_SEARCH_STRING_LENGTH |
88 |
Length of search string for search_calprops is less than required minimum. |
|
SET_ACCOUNTPROPS_FAILED |
89 |
set_accountprops command failed. |
|
GET_ACCOUNTPROPS_FAILED |
90 |
get_accountprops command failed. |
|
GET_FREEBUSY_EXTERNAL_FAILED |
91 |
Unable to retrieve the free/busy info from external service. |
|
STOREEVENTS_WITH_ATTACHMENT_FAILED |
92 |
storeevents.wcap with attachment failed. |
|
GET_ACCOUNTPROPS_NOT_FOUND |
93 |
Account not found. |
|
GET_ACCOUNTPROPS_NO_CALENDAR |
94 |
Calendar for account not found. |
|
FETCH_COMPONENTS_BY_LAST_MOD_INVALID_SYNC_TOKEN_FAILED |
99 |
Invalid sync token. |
|
VIRUS_DETECTED |
100 |
Attachment rejected due to virus detected by virus scanning. |
|
VIRUS_DETECTION_SERVICE_FAILURE |
101 |
Attachment rejected due to virus scanning service being unavailable. |
The component-type parameter directs WCAP to return either only events, only todos, or both events and todos. The keyword arguments, respectively, are: event, todo, or all. The parameter is not required. Its default is all, returning both events and todos.
This parameter can be used with the fetchcomponents_by_range and fetchcomponents_by_lastmod commands.
The recurring parameter specifies whether to return recurring events and todos as individual instances or in a master plus exceptions format for any fetch command. The default behavior that is equivalent to setting recurring to 0 is to return in expanded form for fetchcomponents_by_range and store commands. Start and end dates are required for fetching in the expanded form. This is provided by dtstart and dtend in the fetchcomponents_by_range command and expandstart and expandend for a store command that passes in the fetch parameter too. For the fetch_by_id commands expanded form is the default only if a set of rids are provided.
The compressed parameter enables you to retrieve the RRULE and EXRULE properties when in expanded mode. The parameter defaults (compressed=0) to the compressed format, which returns data without the RRULE and EXRULE properties. To receive all the recurrence data back use compressed=1. This parameter is valid only when used with the expanded mode (recurring=0). This parameter is used by the fetchcomponents_by_range command, the fetchevents_by_id and fetchtodos_by_id commands, and the store* commands.
Free/busy information for a user is calculated by taking into account all opaque events in all the user's calendars that are marked for inclusion in the free/busy calculation. A calendar can be included in the calculation list by setting its transparency value using the fbinclude parameter in the set_calprops command. Individual event transparency can be controlled by the transparent parameter in the storeevents command. Default value for the transparent parameter is 0, which indicates an opaque event included in free/busy calculation.
Whether another user can fetch the free/busy information using the get_freebusy command also depends on whether the user has been granted the scheduling free/busy permissions.
The get_freebusy command returns the busy data only. The rest of the time slots are presumed to be free.
A scheduling attempt requested for an account that has the attendance flag set to "decline on conflict" (the attendance flag is set either by a set_accountsprops.wcap command or davadmin account command), triggers Calendar Server to perform a special free/busy check. This check happens as part of the scheduling process for both CalDAV and WCAP clients. Because scheduling is an asynchronous process, the event organizers are made aware of an error only after they have made the booking. However, for clients that use the WCAP protocol, the same check is performed upfront if the scheduled attendee is a resource. This checking enables the organizer to get an immediate error if the event request results in a conflict for the resource.
WCAP commands can request the output format in three content types: text/calendar, text/json, and text/xml.
To change the output format, set fmt-out to the target value. If fmt-out is not specified, the default format of text/calendar is returned.
Topics in this section:
Recurrence handling occurs as follows:
A recurring series of events or todos has a master entry plus entries for exceptions.
Changing the rrules of a single instance returns an error. When rrules are modified for a recurring series, the whole series is deleted and recreated.
Changing dtstart of a recurring series entry causes the whole series to be recreated with the new dtstart thereby losing all exceptions.
Inserting a rid that was not part of the original rule is not supported.
Multiple rrules for any component are not supported.
The following parameters are used with the storeevents and storetodos commands to create and modify recurring components:
rrules: Recurrence-rule string for recurring events.
rid: RFC5545 Date-Time String giving the recurrence ID of an event. If this parameter is not set when trying to modify a component, the whole series is modified.
excludedstart: An integer specifying whether to include the dtstart date in a recurring series if the date does not follow the rrule.
Topics in this section:
The rrules parameter takes a semicolon-separated list of recurrence rule sub-parameter strings. Each string represents a part of the recurrence rule for the event. Many sub-parameters are possible for recurrence rules. (See RFC 5545 for a complete description of the syntax.)
Three example sub-parameters used by Calendar Server for specifying recurrence are FREQ, COUNT and UNTIL:
The FREQ parameter in a rule defines the periodicity of the event. Table 2-3 describes the FREQ parameter possible values.
The COUNT parameter in a rule defines how many times the meeting repeats.
The UNTIL parameter in a rule specifies using an end date as opposed to using the count to limit the number of instances created.
In the event that neither the COUNT nor the UNTIL parameter are specified, the series is considered a never ending series.
The following example shows a rrules parameter that specifies the event is to occur daily for 10 instances (COUNT=10;FREQ=DAILY):
rrules="COUNT%3D10%3BFREQ%3DDAILY"
The following example URL passes the rrules parameter:
http://calendarserver:port/wcap/storeevents.wcap ?id=sessionid &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rrules="COUNT%3D10%3BFREQ%3DDAILY" &dtend=20020301T112233 &summary=uuuu
This parameter specifies a unique recurrence date of an event or todo. Use rid parameter to specify the instance of a recurring event or todo to be modified.
For example:
http://calendarserver:port/wcap/storeevents.wcap ?id=sessionid &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rid=20020331T112233Z &dtend=20020301T112233 &summary=uuuu&mod=1
When creating a recurring series according to the rrule, this integer specifies whether to include the dtstart date if the date does not follow the rrules. For example, if on a Monday, you were creating a recurring series of meetings that were to be held every Wednesday, the dtstart would be Monday, but that does not fit the set of dates (all Wednesdays) generated using the rrules. Therefore the server must decide whether to include the dtstart date or not based on the value of excludedtstart.
A value of 0 indicates the dtstart date is included in the recurring series and a value of 1 indicates the dtstart date is not included in the recurring series. The default is 0.
When you delete a recurring component, specify the recurrence ID and whether to delete the recurrences as well as the original event or todo.
Table 2-4 describes the mod parameters to use for the recurrences to delete:
Table 2-4 mod Parameter Values
| Value | Option |
|---|---|
|
1 |
Delete or modify this instance only. |
|
2 |
Delete specified instance and all future instances. |
|
3 |
Delete specified instance and all prior instances. |
|
4 |
Delete or modify all instances. |
To delete just the single instance of the event, the mod parameter should be set to 1. For example, this URL would delete just the event that occurs on the date March 1, 2002 11:22:33 AM GMT.
http://calendarserver:port/wcap/deleteevents_by_id.wcap ?id=sessionid &calid=jdoe &uid=001 &rid=20020301T112233Z &mod=1
To delete all instances of the event, the mod parameter should be set to 4. For example, this URL would delete ALL instances of the event (uid 001).
http://calendarserver:port/wcap/deleteevents_by_id.wcap ?id=sessionid &calid=jdoe &uid=001 &mod=4
The following parameters are found in the fetchcomponents_by_* commands, and the fetchevents_by_id and fetchtodos_by_id commands:
compressed: A boolean specifying whether to return all of the recurring entry's data, or to exclude the following parameters: rrules, rdates, exrules, exdates.
recurring: A boolean parameter specifying whether to return all components in compressed form (master entry and exceptions).
Calendar Server supports most known time zones. The time zones accepted by the WCAP commands are restricted to those recognized by Convergence. WCAP time zones and its aliases are listed in the file timezoneids.txt in the Calendar Server configuration directory.
Zulu time corresponds to Greenwich Mean Time (GMT) or Coordinated Universal Time (UTC).
WCAP converts the time values to the appropriate time zone settings on input and output depending upon the value of the tzid and tzidout parameters. The default for tzid is Zulu.
The tzid parameter is used for date and time strings passed in with the WCAP command, that is, values of parameters such as dtstart, dtend, and rid, which are not provided in Zulu time. If the tzid parameter is not passed in, the server's default time zone is assumed.
For commands that return events and todos, the data is returned in Zulu time, unless the tzidout parameter is passed in. In this case the Zulu time is translated into the time zone specified in the tzidout parameter. A special value of X-S1CS-TZNATIVE for tzidout outputs date strings in the time zone they were created in.
For example, if the fetch_components_by range command specifies a date range of 20020506T100000 to 20020507T100000, with tzid=America/Los_Angeles, WCAP translates that to Zulu time for database lookup. If the tzidout parameter was also passed in (for our example, tzidout=America/New_York), then the resulting output is translated to that time zone and returned. If the tzidout parameter is missing, the component data is returned in Zulu time.
The tzidout parameter can be used with the storeevents and storetodos command when the fetch parameter is set to 1 (fetch=1).
The following commands use both the tzid and tzidout parameters:
In addition, the following commands use the tzid parameter (but not the tzidout parameter):
The following command uses tzidout only:
Two commands, storeevents and storetodos, enable you to update (replace, append, or delete) parameter values. When updating current values for a component, you can either replace the current values with the new ones being passed in, append the new values to the current values, or pass in empty parameter values to delete the parameter.
The ability to append parameter values applies only to parameters that can accommodate multiple values (that is, parameters that use semicolon-separated values, such as the attendees parameter). The default is to append (replace=0) the new values to the current values. If you want to replace the current values with the new values being passed in, include the replace parameter in the command, with the value set to 1 (replace=1). If you do not include the replace parameter in the command, the system assumes the default setting (replace=0) and appends the new values to the old values. Exceptions are the recurrence and alarm parameters that can only be replaced, not appended though their value is a semicolon separated string. Specifically, the parameters are: rrules and alarms.
Table 2-5 describes the X-tokens used by Calendar Server.
Table 2-5 X-Tokens Returned by WCAP Commands
| Token Name | Type | WCAP Command | Description |
|---|---|---|---|
|
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY |
string |
get_calprops and get_accountprops commands |
Access control string |
|
X-NSCP-CALPROPS-DESCRIPTION |
string |
get_calprops commands |
Calendar description |
|
X-NSCP-CALPROPS-NAME |
string |
get_calprops commands |
Calendar display name |
|
X-NSCP-CALPROPS-PRIMARY-OWNER |
string |
all fetch commands |
Primary owner of the Calendar |
|
X-NSCP-CALPROPS-RELATIVE-CALID |
string |
all fetch/create/delete commands |
Calendar identifier |
|
X-NSCP-CALPROPS-TZID |
string |
all fetch commands |
Time zone identifier |
|
X-NSCP-WCAP-CALENDAR-ID |
string |
login command |
Default calendar ID |
|
X-NSCP-WCAP-ERRNO |
integer |
all |
Error number |
|
X-NSCP-WCAP-ERRNO-MESSAGE |
String |
all |
Error message |
|
X-NSCP-WCAP-ERRNO-DETAILED-MESSAGE |
String |
all |
Detailed error message |
|
X-NSCP-WCAP-SESSION-ID |
string |
login, check_id |
Session ID |
|
X-NSCP-WCAP-USER-ID |
string |
login, list |
Logged in user ID |
|
X-NSCP-WCAPVERSION |
string |
all |
WCAP protocol version. Currently 7.0.0 |
|
X-S1CS-ATTACH-ID |
string |
store command |
Attachment ID |
|
X-S1CS-ATTENDANCE-FLAG |
integer |
get_accountprops |
A flag that controls the behavior of an invitation. |
|
X-S1CS-CALPROPS-ALLOW-DOUBLEBOOKING |
string |
get_calpropsset_calprops |
Doublebooking setting for the calendar |
|
X-S1CS-CALPROPS-COMMON-NAME |
string |
get_calprops |
Name of calendar owner |
|
X-S1CS-CALPROPS-FB-INCLUDE |
integer |
get_calprops |
Free/busy inclusion of calendar |
|
X-S1CS-CALPROPS-OWNED-CALENDAR |
string |
list |
ID of calendars owned by specified user |
|
X-S1CS-CALPROPS-SUBSCRIBED-CALENDAR |
string |
list_subscribed |
ID of calendars specified user is subscribed to |
|
X-S1CS-EMAIL |
string |
all fetch commands |
Email address associated with calendar |
|
X-S1CS-FILENAME |
string |
fetch |
Attachment file name |
|
X-S1CS-NOTIF-EMAIL-ENABLED |
integer |
get_accountprops |
Enable email notification flag. |
|
X-S1CS-NOTIF-EMAIL-RECIPIENTS |
string |
get_accountprops |
Recipients of email notifications. |
|
X-S1CS-RECURRENCE-COUNT |
integer |
all fetch commands |
rrule recurrence count |
|
X-S1CS-RECURRENCE-UNTIL |
string |
all fetch commands |
rrule recurrence until |
|
X-S1CS-RESOURCE-OWNER |
string |
get_accountprops |
Email address of the resource owner |
|
X-S1CS-TZID-ALIAS |
string |
get_all_timezones command |
Time zone alias |
WCAP 7.0 (WCAPbis) enables you to configure multiple alarms by using a single alarms parameter that takes multiple VALARMS information in a semicolon separated string value, that is, alarms=alarm1;alarm2 and so on.
Each alarm value has multiple properties separated by a newline (CRLF). Each value is represented as PROPERTY_NAME:PROPERTY_VALUE%0D%0APROPERTY_NAME:PROPERTY_VALUE and so on. PROPERTY_NAME can contain PARAMETERS, which are separated by the carat character and represented by the following string:
^PARAM_NAME=PARAM_VALUE^PARAM_NAME=PARAM_VALUE
A PROPERTY can be any valid VALARM property as defined in the iCal standard or X-Properties. The ACTION and TRIGGER properties must be present for the alarm to have any effect. An "EMAIL" alarm must include the following properties:
"DESCRIPTION" property: Contains the text to be used as the message body
"SUMMARY" property: Contains the text to be used as the message subject
One or more "ATTENDEE" properties: Contains the address of attendees to receive the message.
The ATTENDEE address value can be an email address represented by mailto:valid_email_address or an SMS address represented by sms:valid_sms_address.
For more details on alarm properties, see the IETF website at:
http://tools.ietf.org/html/rfc5545#section-3.6.6.
Calendar Server supports the Alarm-Agent Property. This property specifies whether a client, server, both client and server, or none, is responsible for processing an alarm when it is triggered. This is in accordance with the Extended VALARM draft.
The following example shows an alarm with multiple VALARMS information in a semicolon separated string value:
alarms=TRIGGER:-PT30M%0D%0AREPEAT:2%0D%0ADURATION:PT15M%0D%0AACTION:DISPLAY %0D%0ADESCRIPTION:Breakfast meeting with executive\nteam at 8:30 AM EST;TRIGGER^VALUE=DATE- TIME:19970317T133000Z%0D%0AREPEAT:4%0D%0ADURATION:PT15M%0D%0AATTACH^FMTTYPE=audio/basic:ftp: //example.com/pub/sounds/bell-01.aud%0D%0AACTION:AUDIO;TRIGGER^RELATED=END:-P2D %0D%0AATTENDEE:mailto:john_doe@example.com%0D%0ASUMMARY:REMINDER: SEND AGENDA FOR WEEKLY STAFF MEETING\; BY MAIL%0D%0ADESCRIPTION:A draft agenda needs to be sent out to the attendees to the weekly managers meeting (MGR-LIST). \nAttached is a pointer to the document template for the agenda file%0D%0AACTION:EMAIL
|
 Copyright © 2015, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|