Add events to a calendar.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
alarmAudio |
ISO 8601 Date Time string |
The time at which to sound an audio alarm. |
N |
N/A |
alarmDescription |
string |
The message sent out with the alarm |
N |
“This is the alarm description” |
alarmEmails |
semicolon-separated list of email addresses |
Recipients of alarm notifications for the event. |
N |
N/A |
alarmFlashing |
ISO 8601 Date Time string |
The time at which to run flashing alarm. |
N |
N/A |
alarmPopup |
ISO 8601 Date Time string, or ISO 8601 Duration string |
The time at which to pop up a dialog alarm. |
N |
N/A |
alarmStart |
ISO 8601 Date Time string, or ISO 8601 Duration string |
The time at which to send the event alarm notification. |
N |
N/A |
appid |
string |
A runtime parameter that is not stored in the database. The parameter specifies which application is making the request. ENS uses this parameter to determine which X-Tokens to return. Does not affect WCAP command output. For more information on the ENS X-Tokens, see the Sun Java System Communications Services 6 2005Q4 Event Notification Service Guide. |
N |
N/A |
attachments |
semicolon-separated list of strings |
This is for iCalendar interoperability only. The strings are URL's. |
N |
N/A |
attendees |
semicolon-separated list of strings |
An event’s iCalendar RFC 2445 attendee properties. For a list of the properties understood by Calendar Server, see Examples of WCAP Attendee Entries. One optional property is specific only to Calendar Server: SENT-STATUS, which can have the value of: NOT-SENT or SENT-SUCCEEDED. The default for this property is NOT-SENT. If this property is set to SENT-SUCCEEDED, the Group Scheduling Engine (GSE) does not process this attendee. |
N |
N/A |
calid |
string |
Calendar identifier, or email address of the calendar, in which to store the event. |
Y |
N/A |
categories |
semicolon-separated list of strings |
The event categories. |
N |
N/A |
charset |
string |
The character set for the calendar. |
N |
N/A |
compressed |
integer (0,1) |
This parameter is deprecated in this release and might be deleted in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, exrules, and exdates. For compressed=1, all recurrence data is returned. |
N |
0 |
contacts |
semicolon-separated list of strings |
Contacts for the event. |
N |
N/A |
desc |
string |
Event purpose description. A string of any length. If not passed, desc is set to the summary value. To include spaces in the string, use the code %20. |
N |
Value of summary parameter. |
dtend |
Date Time string |
Event end time and date. |
N |
N/A |
dtstart |
Date Time string |
Event start time and date. Required to create or modify events. |
Y |
N/A |
duration |
ISO 8601 duration string |
Event duration. If an event has both a duration and a dtend, the duration is ignored. |
N |
N/A |
excludedtstart |
integer (0, 1) |
Whether or not to include the dtstart date in a recurring series if it does not fall within the rrules dates. 0 = include the dtstart date 1 = exclude the dtstart date |
N |
0 |
exdates |
semicolon-separated list of ISO 8601 Date Time Z strings |
Event exclusionary recurrence dates. To successfully create events, the rrules parameter must be used in conjunction with this parameter. |
N |
N/A |
exrules |
semicolon- separated list of ISO 8601 Date Time Z strings |
Event exclusionary recurrence rules. A semicolon-separated list of recurrence-rule strings. Each rule value must be enclosed in quotes. See Recurring Components– Overview |
N |
N/A |
fetch |
integer (0,1) |
A boolean indicating whether or not to fetch and return newly stored todos. 1 = Fetch and return newly stored todos.0 = Do not fetch. |
N |
0 |
fmt-out |
string |
The format for the returned data. The three format types: text/calendartext/xml |
N |
text/calendar |
geo |
two semicolon-separated floats |
Semicolon-separated string of two float numbers representing the event’s geographical location as latitude and longitude. For example, 37.31;-123.2. |
N |
0;0 |
icsClass |
string |
Event class. One of the following values: PUBLICPRIVATECONFIDENTIAL |
N |
PUBLIC |
icsUrl |
string |
Event URL. |
N |
"" |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
isAllDay |
integer (0,1) |
A boolean indicating whether or not the event lasts all day. 1 = Lasts all day. 0 = Does not last all day. |
N |
0 |
language |
string |
Language of a component record. For example, en, fr, de. |
N |
N/A |
location |
string |
Event location. |
N |
"" |
method |
integer (1,2,4,8) |
ITIP methods for group scheduling. The organizer issues the following ITIP methods:
The attendee issues this ITIP method: 4 = REPLY |
Y |
1 (PUBLISH) |
mod |
integer |
Specifies the recurrences to modify. Not required for creating events. Required to modify events. One of the following values: 1 = THISINSTANCE 2 = THISANDFUTURE 3 = THISANDPRIOR 4 = THISANDALL |
N Y |
N/A |
notify |
integer (0,1) |
This has been deprecated. It remains only for backward compatibility. The Group Scheduling Engine (GSE) module now takes care of all email notifications. A boolean indicating whether or not to notify attendees of a change to an event. 1 = Notify attendees. 0 = Do not notify attendees. |
N |
0 |
orgCalid |
string |
Calendar identifier of organizer. One of the following parameters must be specified: orgCalid, orgEmail, or orgUID. |
N |
N/A |
orgCN |
string |
Common name of the organizer. |
N |
N/A |
orgEmail |
email address |
Email address of the event contact, who is usually the organizer. One of the following parameters must be specified: orgCalid, orgEmail, or orgUID. |
N |
N/A |
orgUID |
userid |
The userid of the organizer. One of the following parameters must be specified: orgCalid, orgEmail, or orgUID. |
N |
N/A |
priority |
integer (0-9) |
Event priority. Follows RFC 2445. 0 = undefined 1= highest 9= lowest |
N |
5 |
rchange |
integer (0,1) |
A boolean indicating whether or not to expand a recurring event. 1 = expand 0 = do not expand |
N |
0 |
rdates |
semicolon-separated list of ISO 8601 Date Time Z strings |
Event recurrence dates. To successfully create events, the rrules parameter must also be specified. |
N |
N/A |
relatedTos |
semicolon-separated list of quoted strings |
Other events to which this event is related. |
N |
N/A |
replace |
Integer (0,1) |
A boolean. For parameters with semicolon-separated values: 1 = updateReplace the old values with the new passed-in values. 0 = append Adds the new passed-in values to the old ones. |
N |
0 |
resources |
semicolon-separated list of strings |
The resources associated with the event. |
N |
N/A |
rid |
ISO 8601 Date Time string |
Event recurrence identifier. Not required to create events. If this parameter is not set when trying to modify events, the whole series of events is modified. |
N N |
N/A |
rrules |
semicolon-separated list of strings |
Event recurrence rules. A semicolon-separated list of recurrence-rule strings. Each rule value must be enclosed in quotes. See Recurring Components– Overview |
N |
N/A |
seq |
integer |
(Not implemented) Event sequence number. |
N |
0 |
smtp |
integer (0, 1) |
Send email cancellation to user with no calendar. 0 = No 1 = Yes |
N |
1 |
status |
integer |
The event status code. One of the following values: 0 CONFIRMED 1 CANCELLED 2 TENTATIVE 3 NEEDS_ACTION 4 COMPLETED 5 IN_PROCESS 6 DRAFT 7 FINAL |
N |
N/A |
storetype |
integer |
Designates whether an explicit “create” or “modify” is attempted on an event. An error results if an attempt is made to create an event that already exists, or to modify an event that does not exist. The error returned is STOREEVENTS_FAILED (14) The following values are valid: 0 WCAP_STORE_TYPE_NONE 1 WCAP_STORE_TYPE_CREATE 2 WCAP_STORE_TYPPE_MODIFY If the attribute is not passed or has a value of 0, no error conditions are reported. |
N |
0 |
summary |
string |
Event summary. A string of any length. Required for new events. Not required for modifying events. To include spaces in the string, use the code %20. |
Y/N |
Default summary available for new events |
transparent |
integer (0, 1) |
1= transparent. Exclude this event from free-busy calculations. 0 = opaque. Include it in free-busy calculations. If the isAllDay parameter is set to 1, the default is transparent instead of opaque. |
N |
0 (opaque) 1 (transparent, if isAllDay=1) |
tzid |
time zone ID string |
The time zone used to translate dates to Zulu time for storage. If this parameter is missing, and the time string has no Z after it, the calendar server time zone ID is used. |
N |
Calendar server time zone ID |
tzidout |
time zone ID string |
Time zone returned data should be translated to. |
N |
Returns data in Zulu time |
uid |
string |
Unique identifier of the event to be stored. System generated for new events. Required to modify events. |
N Y |
Default uid available for new events |
X-property name |
string |
One or more X-Token properties, in iCalendar RFC 2445 format. For more information on X-Tokens, see X-Tokens. |
N |
N/A |
Use this command to creates or modify events with the specified attributes and stores them in the specified calendar in the database.
The command creates and stores recurrences as specified by the rrules, exrules, rid, mod, and rchange parameters. See Recurring Components– Overview
Use the language parameter to specify the language of the event. See Changing Language or Character Set
For an explanation of how to use the attendee and method parameters to do group scheduling, see the Common Topics section Group Scheduling.
For an explanation of how to replace, append or delete a parameter, see the explanation in the Common Topics section Updating Parameter Values
The server does not support attachments. The attachments parameter exists to support iCalendar interoperability only, and is not functional.
It is possible to delete an attendee in an existing meeting by assigning the value X-NSCP-WCAP-ATTENDEE-DELETE to the attendee parameter PARTSTAT. For example, to delete attendee jdoe, the attendee parameter would contain the following:
PARTSTAT=X-NSCP-WCAP-ATTENDEE-DELETE^jdoe |
This command creates new events and modifies existing events. You can not add and modify events in the same command. You must do one or the other.
Each case requires a different set of parameters :
To create new events requires only the dtstart parameter.
Every other parameter is optional. The server generates the uid.
To modify existing events requires two parameters:
uid
mod
All other parameters are optional. If a parameter is not specified, the event retains the previous value of the property.
If the ics.conf parameter user.allow.doublebook is set to “yes”, then:
Allowed — Double booking is allowed if the user’s doublebookingcalendar property is set to 1).
Disallowed — Double booking is disallowed if the calendar doublebooking property is set to 0. WCAP returns error 40 STORE_FAILED_DOUBLE_BOOKED.
However, if the user.allow.doublebook parameter is set to “no”, then double booking is disallowed, no matter what the calendar property is set to.
The ending date, dtend, overrides duration. If you specify both duration and dtend, the command ignores duration.
Duration strings can be used in three parameters: duration, alarmPopup and alarmStart.
Specify the duration in iCal format. For example:
P1Y2M3DT1H30M10S represents a duration of 1 year, 2 months, 3 days, 1 hour, 30 minutes, 10 seconds
PT1H30M represents a duration of 1 hour, 30 minutes
P1D represents a duration of 1 day
PT15M represents a duration of 15 minutes
Notice that the T in the string separates the date information from the time information.
The command returns the error value. To have the command return the stored todo data, specify fetch=1. In addition, use the tzidout parameter to specify the time zone the returned data should be translated to. If the tzidout parameter is missing, the data is returned in Zulu time.
This command cannot modify a linked event. If you attempt to issue the command, it fails and returns: FAILED: CANNOT_MODIFY_LINKED_EVENTS (31) in the errno array.
If double booking is disallowed, when you try to store an event in a time slot that is already scheduled, the command fails, and returns: FAILED: STORE_FAILED_DOUBLE_BOOKED(40).
For example, this URL would call storeevents.wcap and would result in storing an event in the calendar john,
http://calendarserver/storeevents.wcap ?id=3423423asdfasf &calid=john &dtstart=20020101T103000 &dtend=20020101T113000&uid=001 &summary=new%20year%20event
The above example results in the following entry in an iCalendar database:
BEGIN:VEVENT DTSTART:20020101T183000Z DTEND:20020101T193000Z UID:001 SUMMARY:new year event END:VEVENT