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 Communications Suite 5 Event Notification Service Guide. |
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 Calendar Server WCAP Attendee Overview. 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 |
deleteattach |
semicolon-separated list of strings |
Attachment IDs of the attachments to be deleted. |
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 in Calendar Server WCAP |
N |
N/A |
fbtype |
integer (0-4) |
A free-busy calculation is performed when the event is created. The value derived is stored in this parameter. The integer values have the following meaning: 0 — None 1 — Free 2 — Busy 3 — Busy-tentative 4 — Busy-unavailable |
N |
0 |
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: PUBLIC— Others can see time and text only PRIVATE — Others can see time and date only CONFIDENTIAL — Others can see nothing. (Set transparent = 1 to make it invisible). |
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,256) |
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 |
A modifier indicating which recurrences to retrieve. One of the following values: 1 = THISINSTANCE 2 = Deprecated, see note. 3 = Deprecated, see note. 4 = THISANDALL Note – Values 2 and 3 were deprecated. Using these values results in undetermined behavior. |
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 in Calendar Server WCAP |
N |
N/A |
sendattach |
integer (0, 1) |
0 = Sends information about the attachments in an iTIP message. 1 = Sends the attachment itself. |
N |
0 |
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 Used by Calendar Server WCAP. |
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 in Calendar Server WCAP
Use the language parameter to specify the language of the event. See Changing Language or Character Set for Calendar Server WCAP
For an explanation of how to use the attendee and method parameters to do group scheduling, see the Common Topics section Calendar Server WCAP Attendee Parameter.
For an explanation of how to replace, append or delete a parameter, see the explanation in the Common Topics section Updating Parameter Values in Calendar Server WCAP
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.
Attachments can be stored as data for an event. Use the sendattach parameter to specify whether an actual attachment is being sent as part of the iTIP invitation data, "0" for none, and "1" for attachment present in data.
Attachments can be stored as part of the event on the Calendar Server through the storeevents.wcap command. This command is enhanced with following new arguments:
deleteattach=attach-id1;attach-id2;attach-id3 : Deletes existing attachments from an event using the parameter without deleting the event itself. The attachid1, attachid2, and so on should be the attachment id values emitted in the X-S1CS-ATTACH-ID x-token as part of the VEVENT returned for a fetch command. You can use the delete_by_* commands to delete the events as well as the associated attachments.
sendattach = 0/1 : Determines whether the actual attachments are sent as part of the iTIP invitation or not.
In earlier versions of Calendar Server, attachments could only be sent as a reference (URL) to a Web location. The attachments parameter was used to hold the URL.
The attachments parameter has been deprecated. It remains functional in this release only for backward compatibility. Change any scripts you have that use the old parameter to the new attachment model.
The currently existing attachments argument in WCAP can be used for specifying URL (web locations of documents) as reference, these attachments will not be stored onto the server, but the reference would be returned to the client.
The actual attachments will follow as multipart mixed data for the POST. Following example shows how attachments can be stored by passing arguments to storeevents in the URI itself and the actual attachments in the data.
<>POST /storeevents.wcap?id=${SESSIONID}&calid=savri &uid=111&dtstart=20050927T150000Z&duration=PT1H=0&sendattach=0 HTTP/1.1 Connection: Keep-Alive Content-type: multipart/mixed; boundary=------------abcdefghij Content-Length: 2381 -----------------------------abcdefghij Content-Type: image/jpeg Content-Transfer-Encoding: base64 Content-Disposition:attachment ; filename=birthday.jpeg MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEMII CajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEB hMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEMIIC ajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBh MCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE -------------------------------abcdefghij content-type: image/GIF content-disposition:attachment ; filename=birthday.GIF Content-Transfer-Encoding: base64 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEMII CajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEB hMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEMIIC ajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBh MCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEFEFF -------------------------------abcdefghij |
When someone outside the Calendar Server is invited to an event as a mailto attendee, an iTIP invitation is usually sent to the attendee using the iMIP protocol. If there are any attachments attached to the event, they will be send depending on the value of sendattach parameter (0 or 1). This provides the organizer, the granularity of deciding whether it is a minor update to the event which does not require sending the attachments, or a major update where new attachments might have been added and requires sending the attachments to the end user.
If sendattach=0, the VEVENT information sent out as an iTIP does not have any information regarding the attachment, or might behave similar to fetchattach=0. If sendattach=1, the URI in the VEVENT structure uses the 'CID' URI scheme to identify the attachments in the multipart mime message that is sent out using iMIP.
The example below shows an iMIP message. Note that the values of the CID URI are the values of content-id mime header field in the attachment.
This is a multi-part message in MIME format. boundary="----_=_NextPart_002_01C5BAFF.DAA83C14" ------_=_NextPart_002_01C5BAFF.DAA83C14 Content-Type: text/calendar; method=REQUEST; name="meeting.ics" Content-Transfer-Encoding: 8bit BEGIN:VCALENDAR BEGIN:VEVENT UID:uid1 RECURRENCE-ID:rid1 DTSTAMP:20050919T165229Z SUMMARY:Calendar Server Engineering meeting DTSTART:20050919T223000Z DTEND:20050919T233000Z CREATED:20050627T184431Z LAST-MODIFIED:20050829T221947Z PRIORITY:5 SEQUENCE:5 CLASS:PUBLIC ORGANIZER;CN="Asavari Ukidve" ;X-NSCP-ORGANIZER-UID=ShortName ;X-S1CS-EMAIL=FirstName.LastName@email.com :savri ATTACH:CID:uid1rid1attachid-1 ATTACH:CID:uid1rid1attachid-2 STATUS:CONFIRMED TRANSP:OPAQUE X-NSCP-ORIGINAL-DTSTART:20050919T223000Z X-NSCP-LANGUAGE:en X-NSCP-DTSTART-TZID:America/Los_Angeles X-NSCP-TOMBSTONE:0 X-NSCP-ONGOING:0 X-NSCP-ORGANIZER-EMAIL:FirstName.LastName@email.com X-NSCP-GSE-COMPONENT-STATE;X-NSCP-GSE-COMMENT="REQUEST-PENDING":131073 END:VEVENT END:VCALENDAR ------_=_NextPart_001_01C5BAFF.DAA83C14 Content-Type: application/octet-stream; name="All day event.ics" Content-Transfer-Encoding: base64 Content-ID: <uid1rid1attachid-1> Content-Description: All day event.ics Content-Disposition: attachment; filename="Alldayevent.ics" QkVHSU46VkNBTEVOREFSDQpQUk9ESUQ6LS8vTWljcm9zb2Z0IENvcnBvcmF0aW9uLy9PdXRsb29r IDkuMCBNSU1FRElSLy9FTg0KVkVSU0lPTjoyLjANCk1FVEhPRDpQVUJMSVNIDQpCRUdJTjpWRVZF TlQNCk9SR0FOSVpFUjpNQUlMVE86c3YxMzQ1MTJAaXBsYW5ldC5jb20NCkRUU1RBUlQ7VkFMVUU9 REFURToyMDAzMDEyOA0KRFRFTkQ7VkFMVUU9REFURToyMDAzMDEyOQ0KVFJBTlNQOlRSQU5TUEFS RU5UDQpTRVFVRU5DRTowDQpVSUQ6MDQwMDAwMDA4MjAwRTAwMDc0QzVCNzEwMUE4MkUwMDgwMDAw MDAwMEEwQTc5MEQ2QzBDNkMyMDEwMDAwMDAwMDAwMDAwMDAwMTAwDQogMDAwMDBBRDNEMEVDQUU2 MTAwNDQ2OEYwQjAyQUEyQTcxNTZCQQ0KRFRTVEFNUDoyMDAzMDEyOFQxOTMxNDVaDQpTVU1NQVJZ OkFsbCBkYXkgZXZlbnQNClBSSU9SSVRZOjUNCkNMQVNTOlBVQkxJQw0KRU5EOlZFVkVOVA0KRU5E OlZDQUxFTkRBUg0K ------_=_NextPart_001_01C5BAFF.DAA83C14 Content-Type: text/html; name="dayviewhtml.htm" Content-Transfer-Encoding: base64 Content-ID: <uid1rid1attachid-2> Content-Description: dayviewhtml.htm Content-Disposition: attachment; filename="dayviewhtml.htm" PEhUTUw+PEhFQUQ+PFNDUklQVD4gdmFyIGptYWluID0gcGFyZW50OyB2YXIgZm9ybV9zdWJtaXR0 ZWQgPSAnMCc7IGZ1bmN0aW9uIGltYWdlc29mZigpIHsgaWYgKGRvY3VtZW50LmltYWdlcykgeyBk b2N1bWVudC5ob21lcGFnZS5zcmMgPSBob21lcGFnZW9mZi5zcmM7IGRvY3VtZW50LmRvY3VtZW50 YXRpb24uc3JjID0gZG9jdW1lbnRhdGlvbm9mZi5zcmM7IGRvY3VtZW50LnVzZXJsb2dvdXQuc3Jj ID0gdXNlcmxvZ291dG9mZi5zcmM7IH0gfSBmdW5jdGlvbiBpbWFnZW9uKGltZ05hbWUpIHsgaWYg KGRvY3VtZW50LmltYWdlcykgeyBkb2N1bWVudFtpbWdOYW1lXS5zcmMgPSBldmFsKGltZ05hbWUg KyAib24uc3JjIik7IH0gfSBmdW5jdGlvbiBvdmVyKGltZ05hbWUpIHsgZG9jdW1lbnRbaW1nTmFt ZV0uc3JjPSBldmFsKGltZ05hbWUgKyAib3Zlci5zcmMiKTsgfSBmdW5jdGlvbiBvdXQoaW1nTmFt ZSkgeyBkb2N1bWVudFtpbWdOYW1lXS5zcmM9IGV2YWwoaW1nTmFtZSArICJvZmYuc3JjIik7IH0g PC9TQ1JJUFQ+PHNjcmlwdD4gdmFyIG9wZW5lciA9IGptYWluLm9wZW5lcjsgdmFyIGFjY2VwdF9m dW5jcyA9IG5ldyBBcnJheSgpOyBmdW5jdGlvbiBnZXRhcnJheSgpIHsgcmV0dXJuIG5ldyBBcnJh eSgpOyB9IGZ1bmN0aW9uIGFjY2VwdChuZXdkYXRhKSB7IHZhciBzdWJtaXRfZm9ybSA9IGZhbHNl OyB2YXIgeDsgZm9yICggeCA9IDA7IHggPCBhY2NlcHRfZnVuY3MubGVuZ3RoOyB4KyspIHsgdmFy IGZ1bmMgPSBhY2NlcHRfZnVuY3NbeF07IGlmIChmdW5jKG5ld2RhdGEpKSBzdWJtaXRfZm9ybSA9 IHRydWU7IH0gaWYgKHN1Ym1pdF9mb3JtKSB7IGptYWluLmZyYW1lc1sxXS5kb2N1bWVudC5mb3Jt LnN1Ym1pdCgpOyB9IH0gZnVuY3Rpb24gY2xvc2VfYWxsKCkgeyBqbWFpbi5jbG9zZV9hbGwoKTsg fSBmdW5jdGlvbiBpY3NOb3JtYWxpemUoYSkgeyB2YXIgYiA9ICcnOyBmb3IgKGkgPSAwOyBpIDwg YS5sZW5ndGg7IGkrKykgeyB2YXIgYyA9IGEuc3Vic3RyaW5nKGksIGkgKyAxKTsgaWYgKGMgPT0g JyAnIHx8IGMgPT0gJ1x0JyB8fCBjID09ICdccicgfHwgYyA9PSAnXG4nKSB7IGIgKz0gJ34nOyB9 IGdmFaXBZT0iMSI+PC9URD48L1RSPjwvVEFCTEU+PC9mb3JtPjwvYm9keT48L0hUTUw+ ------_=_NextPart_001_01C5BAFF.DAA83C14-- |
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