Oracle® Collaboration Suite Migration and Coexistence Guide 10g Release 1 (10.1.1) Part Number B14486-02 |
|
|
View PDF |
This chapter describes how to migrate calendar data using the iCalendar representation. The chapter contains the following sections:
The iCalendar standard is used to import and export data from any application that can generate iCalendar output. Using standard objects to represent meetings and events, you can use the uniical
utility and Calendar SDK (CSDK) functions to create programs that read or write calendar data and store the information on the Oracle Calendar server. This implies that by using iCalendar objects, you can develop utilities to migrate calendar data. CSDK is a set of C/C++ and Java functions that allows users to create applications for Oracle Calendar.
The following is a sample iCalendar object:
BEGIN:VCALENDAR //must be used for START and END METHOD:PUBLISH VERSION:2.0 PRODID:Oracle/Calendar BEGIN:VEVENT CLASS:PUBLIC PRIORITY:5 STATUS:CONFIRMED DTSTART:20030626T200000Z DTEND:20030626T220000Z SUMMARY: export //Subject(email) or action on object UID:29b#400#177b5abc&0002Yy0yMjA4.. //Unique identifier END:VEVENT END:VCALENDAR
In addition to the CSDK, the uniical
utility can also be used for migrating data to applications that support the iCalendar representation. This utility uses the iCalendar format to represent the import and export of a calendar user's agenda. Using uniical
, you can perform various operations including import, export, and deletion of calendar data. The export
option allows exporting calendar data into an iCalendar format, which can then be imported into a user's agenda in Oracle Calendar. Refer to "Preparing for Migration Using the iCalendar Representation" in Chapter 4, "Calendar Migration Planning" for information on the limitations of uniical
.
When using uniical
for import, each event from the iCalendar file is read and processed, and a status message is displayed on screen. Any error message is written to a log file. Each event can be either created or modified depending on the event UID
. If no UID
is found with the iCalendar event, a new event is created and the calendar server assigns it a UID
. If a UID
is found, you can either create an event with that UID
(if no event exists with that UID
) or modify the existing event with that UID
.When exporting an agenda with uniical
, you can export all the events, the events that are in a certain date range, or the event that matches the specified UID
.
Note:
TheUID
referred here is the event UID
, not a user UID
. The events exported will depend on the access rights you have on the user's agenda.When you export an agenda with uniical
, both the meetings where you are the organizer and the meetings where you are only an attendee are exported. If you import an event with uniical
, then you may or may not be the organizer of the event. The event may also have other attendees besides you.
Oracle Calendar has the concept of an internal attendee and an external attendee. An attendee is internal if he or she has an Oracle Calendar account. An external attendee does not have an Oracle Calendar account.
The uniical
utility uses the meeting organizer field (an e-mail address) to determine whether the current user is the organizer of the event being imported. If the current user is the organizer of the event being imported, then the uniical
utility, by default, uses the attendee's e-mail address to determine whether the attendee is external or internal, by searching the for an Oracle Calendar account matching the e-mail address.
Depending on the command-line options being used, and whether or not the user is the meeting organizer, attendees could be set as external or internal.
You can select from the various options available with uniical
, depending on your requirement. Table 8-1 lists these options:
Table 8-1 uniical Options
Options | Description |
---|---|
|
Displays usage information. |
|
Displays version information. |
|
Deletes the specified events. |
|
Adds or modifies events. |
|
Exports events. |
|
Processes the methods in the iCalendar file. |
|
Specifies the user, resource, or event calendar whose agenda is modified. The user is specified using an X400-like syntax, such as with the |
|
Specifies the host and port on which the user's agenda, which is affected by the operation, resides. |
|
Specifies the node on which the user's agenda that is affected by the operation resides. |
|
Configures |
|
Configures |
|
Restricts |
|
Configures |
|
Specifies the file that holds ( |
|
Specifies the character set in which the iCalendar file is encoded. |
|
Specifies the |
|
Configures the start date from which to export data. |
|
Configures the end date up to which to export data. |
|
Specifies the user who logs in to the Calendar server. This user can be either the same user as the |
|
Specifies a password of the |
To better understand events in iCalendar format, consider the following example:
BEGIN:VCALENDAR BEGIN:VEVENT X-ORACLE-EVENTINSTANCE-GUID:I1+111106+391+1+437960403 X-ORACLE-EVENT-GUID:E1+111106+391+437960403 X-ORACLE-EVENTTYPE:APPOINTMENT UID:20041116T234003Z-1b202-187-503f-Oracle TRANSP:OPAQUE SUMMARY:Stamp pasting STATUS:CONFIRMED SEQUENCE:0 PRIORITY:5 ORGANIZER;X-ORACLE-GUID=88887777666655554444333322221111; CN=GERMAINE LAUZON:mailto:GERMAINE.LAUZON@LES-BELLE-SOEURS.QC.CA LOCATION:My Montreal home DESCRIPTION:Paste one million trading stamps DTSTART:20041120T193000Z DTEND:20041120T200000Z CLASS:PUBLIC ATTENDEE;X-ORACLE-GUID=88887777666655554444333322221111; CUTYPE=INDIVIDUAL;CN=GERMAINE LAUZON; PARTSTAT=ACCEPTED:mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA ATTENDEE;X-ORACLE-GUID=AAAAAAAABBBBBBBBCCCCCCCCDDDDDDDD; CUTYPE=INDIVIDUAL;CN=OLIVINE DUBUC; PARTSTAT=NEEDS-ACTION:mailto:OLIVINE.DUBUC@LES-BELLES-SOEURS.QC.CA ATTENDEE;X-ORACLE-GUID=AAAA1111BBBB2222CCCC3333DDDD4444; CUTYPE=INDIVIDUAL;CN=LISE PAQUETTE; PARTSTAT=NEEDS-ACTION:mailto:LISE.PAQUETTE@LES-BELLES-SOEURS.QC.CA END:VEVENT END:VCALENDAR
In the earlier example:
The organizer is Germaine Lauzon
The three attendees are Germaine Lauzon, Olivine Dubuc, and Lise Paquette
The title of the event is "Stamp pasting", the location is "My Montreal home", and the description is "Paste one million stamps"
The meeting starts at 1930 UTC (coordinated universal time), November 20, 2004, and ends at 2000 UTC of the same day
Note:
In the earlier example, indented lines belong to the preceding line. (The lines that start withORGANIZER
and ATTENDEE
have been broken into several lines because of space restrictions within this document.)If you are using the sample event as the input file for uniical
, importing into Germaine Lauzon's agenda, and ensuring that an event with the UID of this sample event does not exist in the Calendar server, then the uniical
utility will add this event to the Calendar server.
See Also:
For additional information on iCalendar properties:RFC 2445: Internet Calendaring and Scheduling Core Object Specification (iCalendar)
A repeating event is a collection of the event instances that does not follow any rule. The main event has one or multiple RDATE
properties that identify additional instances belonging to the main event. These instances are represented as separate VEVENT
s with the same UID
as the main event, and the RECURRENCE-ID
with a value that matches one RDATE
value in the main event.
The following iCalendar formatted data represents a repeating meeting that occurs three times at 1630 UTC on November 27, 28, and 29, 2004:
BEGIN:VCALENDAR BEGIN:VEVENT X-ORACLE-EVENTINSTANCE-GUID:I1+111110+391+3+437971581 X-ORACLE-EVENT-GUID:E1+111110+391+437971581 X-ORACLE-EVENTTYPE:APPOINTMENT UID:20041117T024620Z-1b206-187-3b4c-Oracle SUMMARY:Repeating Meeting RDATE:20041128T163000Z RDATE:20041129T163000Z ORGANIZER;X-ORACLE-GUID=88887777666655554444333322221111; CN=GERMAINE LAUZON:mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA DTSTART:20041127T163000Z DTSTAMP:20041117T024714Z DTEND:20041127T170000Z CREATED:20041117T024621Z ATTENDEE;X-ORACLE-GUID=88887777666655554444333322221111; CUTYPE=INDIVIDUAL;CN=GERMAINE LAUZON; PARTSTAT=ACCEPTED:mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA END:VEVENT BEGIN:VEVENT X-ORACLE-EVENTINSTANCE-GUID:I1+111110+391+2+437971581 X-ORACLE-EVENT-GUID:E1+111110+391+437971581 X-ORACLE-EVENTTYPE:APPOINTMENT UID:20041117T024620Z-1b206-187-3b4c-Oracle SUMMARY:Repeating Meeting RECURRENCE-ID:20041128T163000Z ORGANIZER;X-ORACLE-GUID=88887777666655554444333322221111; CN=GERMAINE LAUZON:mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA DTSTART:20041128T163000Z DTSTAMP:20041117T024714Z DTEND:20041128T170000Z CREATED:20041117T024621Z ATTENDEE;X-ORACLE-GUID=88887777666655554444333322221111; CUTYPE=INDIVIDUAL;CN=GERMAINE LAUZON; PARTSTAT=ACCEPTED:mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA END:VEVENT BEGIN:VEVENT X-ORACLE-EVENTINSTANCE-GUID:I1+111110+391+1+437971581 X-ORACLE-EVENT-GUID:E1+111110+391+437971581 X-ORACLE-EVENTTYPE:APPOINTMENT UID:20041117T024620Z-1b206-187-3b4c-Oracle SUMMARY:Repeating Meeting RECURRENCE-ID:20041129T163000Z ORGANIZER;X-ORACLE-GUID=88887777666655554444333322221111; CN=GERMAINE LAUZON:mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA DTSTART:20041129T163000Z DTSTAMP:20041117T024714Z DTEND:20041129T170000Z CREATED:20041117T024621Z ATTENDEE;X-ORACLE-GUID=88887777666655554444333322221111; CUTYPE=INDIVIDUAL;CN=GERMAINE LAUZON; PARTSTAT=ACCEPTED:mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA END:VEVENT END:VCALENDAR
In the earlier example, notice that each event has the same UID
. The first event, which occurs on the November 27, has two RDATE
properties, one for each of the other two events. The last two events have a RECURRENCE-ID
property that matches the DTSTART
properties of the respective events.
A recurring event has a recurrence rule RRULE
that specifies when meeting instances occur. Recurring events typically have one VEVENT
for an event with multiple instances.
The following example shows how to create a recurring meeting using the uniical
utility. The meeting occurs daily from 1200 to 1330 EDT/EST.
BEGIN:VCALENDAR VERSION:2.0 PRODID:Oracle/Oracle Calendar Server 10.1.1.0.1 BEGIN:VTIMEZONE TZID:/ORACLE/OCAL/EST5EDT BEGIN:DAYLIGHT RRULE:FREQ=YEARLY;UNTIL=20750407T020000Z;BYMONTH=4;BYDAY=1SU TZNAME:Eastern Standard Time\, Eastern Daylight Time TZOFFSETTO:-0400 TZOFFSETFROM:-0500 DTSTART:19910401T020000 END:DAYLIGHT BEGIN:STANDARD RRULE:FREQ=YEARLY;UNTIL=20751031T020000Z;BYMONTH=10;BYDAY=-1SU TZNAME:Eastern Standard Time\, Eastern Daylight Time TZOFFSETTO:-0500 TZOFFSETFROM:-0400 DTSTART:19911025T020000 END:STANDARD END:VTIMEZONE BEGIN:VEVENT UID:20050427T120000-Recurring SUMMARY:Reccuring RRULE:FREQ=DAILY;COUNT=2;INTERVAL=1;WKST=SU DESCRIPTION:Details 0 DTSTART;TZID=/ORACLE/OCAL/EST5EDT:20050427T120000 DTEND;TZID=/ORACLE/OCAL/EST5EDT:20050427T133000 END:VEVENT END:VCALENDAR
An event must have, at minimum, a DTSTART
property and a DTEND
or DURATION
property, for uniical
to successfully import that event into the calendar server. The following is a sample event in iCalendar format that has the minimum amount of information required for a successful import by uniical
:
BEGIN:VCALENDAR BEGIN:VEVENT SUMMARY:My minimal event DTSTART:20041120T103000Z DTEND:20041120T113000Z END:VEVENT END:VCALENDAR
The Calendar server will automatically assign an organizer (the owner of the agenda in which you are importing the event) and a UID
. In the earlier example, the SUMMARY
property is optional. If you do not specify any summary text, then the default value, which is UNTITLED
, would be used.
The organizer and attendee property has several parameters associated with it including the following:
X-ORACLE-GUID
: Each Calendar user is uniquely identified by this value
CN
: Common Name. Specifies the display name of the Calendar user
PARTSTAT
: Participation status. The possible values of this attribute include the following:
NEEDS-ACTION
: The Calendar user has not specified his or her participation status
ACCEPTED
: The Calendar user has accepted to attend the event
DECLINED
: The Calendar user has declined to attend the event
A list of parameters, separated by semicolons, follow the ORGANIZER
and ATTENDEE
properties. At the end of this list, a mailto URI must appear; it must be separated from the list by a colon. The following is an example of an ATTENDEE
property in iCalendar format:
ATTENDEE;X-ORACLE-GUID=88887777666655554444333322221111; CUTYPE=INDIVIDUAL;CN=GERMAINE LAUZON; PARTSTAT=ACCEPTED:mailto:GERMAINE.LAUZON@LES-BELLES-SOEURS.QC.CA
The organizer may read and modify any property of the event with which it is associated. However, the organizer has some restrictions in regards to an attendee's properties. An organizer may not change the PARTSTAT
property of an attendee. An organizer may add or delete an attendee.
Suppose we want to import Germaine Lauzon's events into an agenda of a new Calendar user. Import only those events for which Germaine Lauzon is the organizer. Do not import any events in Germaine Lauzon's old agenda in which she is not the organizer.
Events are shared entities in Oracle Calendar. For example, if we import the previous sample event ("Stamp pasting"), then the same event will appear in Germaine Lauzon, Olivine Dubuc, and Lise Paquette's agendas. Germaine will be the organizer of the event; she will be the only one able to modify the event. Olivine and Lise will be able to see the event, but cannot modify it.
When you import any event into a particular Calendar user's agenda, the ORGANIZER
property will be set to that user's agenda, regardless of the value of ORGANIZER
. For example, if you import the previous sample event into Olivine Dubuc's agenda, the Calendar server will create a new event with Olivine Dubuc as the organizer.
Therefore, only import those events whose organizer is the same as the agenda owner's.
When you create an event with internal attendees, the PARTSTAT
parameter of the event owner is set to ACCEPTED
, and the PARTSTAT
parameter of the other internal attendees are set to NEEDS-ACTION
. The Oracle Calendar server does not retain the original setting of PARTSTAT
. In addition, the owner of an event cannot change the internal attendee's PARTSTAT
. So, the Oracle Calendar server sets PARTSTAT
to the default value, NEEDS-ACTION
. This happens regardless of whether you authenticate as a user or sysop
.
To set an internal attendee's PARTSTAT
, you need to modify (re-import) the event while authenticating as sysop
. Only event modification with sysop
credentials enables you to modify PARTSTAT
of an internal attendee. Event modification with owner or designate user credentials will ignore PARTSTAT
of an internal attendee. Remember that events are identified by their UIDs
, and to modify an event, you must have a correct event UID
in your iCalendar data.
Another way to set PARTSTAT
outside an Oracle Calendar client is to use the CSDK_SetIdentity
C function or the oracle.calendar.sdk.Session.setIdentity
Java method from the Calendar SDK.
See Also:
Oracle Calendar Application Developer's Guide or the Calendar SDK JavaDoc for more information.