Sun Java System Calendar Server 6.3 WCAP Developer's Guide

storeevents.wcap

Purpose

Add events to a calendar.

Parameters

Table 3–32 storeevents Parameters

Parameter  

Type  

Purpose  

Required  

Default  

alarmAudio

ISO 8601 Date Time string 

The time at which to sound an audio alarm. 

N/A 

alarmDescription

string 

The message sent out with the alarm 

“This is the alarm description” 

alarmEmails

semicolon-separated list of email addresses 

Recipients of alarm notifications for the event. 

N/A 

alarmFlashing

ISO 8601 Date Time string 

The time at which to run flashing alarm. 

N/A 

alarmPopup

ISO 8601 Date Time string, or ISO 8601 Duration string 

The time at which to pop up a dialog alarm. 

N/A 

alarmStart

ISO 8601 Date Time string, or ISO 8601 Duration string 

The time at which to send the event alarm notification. 

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/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/A 

calid

string 

Calendar identifier, or email address of the calendar, in which to store the event. 

N/A 

categories

semicolon-separated list of strings 

The event categories. 

N/A 

charset

string 

The character set for the calendar. 

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.

0

contacts

semicolon-separated list of strings 

Contacts for the event. 

N/A 

deleteattach

semicolon-separated list of strings 

Attachment IDs of the attachments to be deleted. 

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.

Value of summary parameter.

dtend

Date Time string 

Event end time and date. 

N/A 

dtstart

Date Time string 

Event start time and date. 

Required to create or modify events. 

N/A 

duration

ISO 8601 duration string 

Event duration. If an event has both a duration and a dtend, the duration is ignored.

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

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/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/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

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.

0

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendartext/xml

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.

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).

PUBLIC

icsUrl

string 

Event URL. 

""

id

unique identifier string 

The session identifier. 

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.

0

language

string 

Language of a component record. For example, en, fr, de.

N/A 

location

string 

Event location. 

""

method

integer (1,2,4,8,256)

ITIP methods for group scheduling. 

The organizer issues the following ITIP methods: 

  • 1 = PUBLISH

  • 2 = REQUEST

  • 8 = CANCEL

  • 256 = UPDATE

The attendee issues this ITIP method: 

4 = REPLY

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/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.

0

orgCalid

string 

Calendar identifier of organizer. 

One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.

N/A 

orgCN

string 

Common name of the organizer. 

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/A 

orgUID

userid

The userid of the organizer.

One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.

N/A 

priority

integer (0-9)

Event priority. Follows RFC 2445. 

0 = undefined

1= highest

9= lowest

5

rchange

integer (0,1)

A boolean indicating whether or not to expand a recurring event. 

1 = expand

0 = do not expand

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/A 

relatedTos

semicolon-separated list of quoted strings 

Other events to which this event is related. 

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.

0

resources

semicolon-separated list of strings 

The resources associated with the event. 

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/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/A 

sendattach

integer (0, 1)

0 = Sends information about the attachments in an iTIP message.

1 = Sends the attachment itself.

0

seq

integer 

(Not implemented) 

Event sequence number. 

0

smtp

integer (0, 1)

Send email cancellation to user with no calendar. 

0 = No

1 = Yes

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/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.

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.

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. 

Calendar server time zone ID 

tzidout

time zone ID string 

Time zone returned data should be translated to. 

Returns data in Zulu time 

uid

string 

Unique identifier of the event to be stored. 

System generated for new events. 

Required to modify events. 

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/A 

Description

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

Required Parameters

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 :

Attachments

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:


Note –

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.


Storing Attachments

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

Attachments in the iTIP

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--

Double Booking

If the ics.conf parameter user.allow.doublebook is set to "yes", then:

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.

Duration and dtend

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:

Notice that the T in the string separates the date information from the time information.

Returns

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.

Error Codes

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).

Example

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