10 Managing Oracle Beehive Time Management

This module includes information about various administration tasks relating to Oracle Beehive Time Management services, and contains the following topics:

• Managing Holidays

• Modifying User Time Management Preferences

• Oracle Beehive Time Zone Definitions

Note:

All beectl commands specified in this module are stated as though the shell mode has been invoked. For more information about beectl shell mode, and how to invoke it refer to the "Oracle Beehive Command-Line Utility" module in the Oracle Beehive Administrator's Reference Guide.

Managing Holidays

Use the beectl import_icalendar command-line tool to import holiday events. You can import one or multiple holidays from one iCalendar file. This type of operation is typically performed either by the Oracle Beehive administrator, or by a user who administers holidays for your organization.

Note:

When importing any calendar, you may find it useful to disable notifications. This will avoid sending a large number of notifications to users who are subscribed to be notified whenver their calendar or task list is updated.

To disable notifications, use the beectl import_icalendar command with the --migration option.

This section includes the following topics:

• Creating an iCalendar File

• Sample Holiday Entries

• Importing Holiday iCalendar Files

Creating an iCalendar File

Before importing holidays, you will need to create an iCalendar file with one or more holiday events.

Oracle Beehive will only successfully import iCalendar files that have been formatted according to the Official Internet Protocol Standards for iCalendar.

See Also:

For information about iCalendar standards, including formatting and representing iCalendar objects, refer to the Internet Calendaring and Scheduling Core Object Specification (iCalendar) document on the Official Internet Protocol Standards Web site:

http://www.rfc-editor.org/rfcxx00.html

You can use the following text as a template for creating your iCalendar holiday file:

BEGIN:VCALENDAR
VERSION:2.0
CALSCALE:GREGORIAN
PRODID:-//ORACLE//NONSGML Beehive Time Management - //EN
<holiday1>
<holiday2>
<holidayN>
END:VCALENDAR

Where <holiday1>, <holiday2>, and <holidayN> represent different holidays that you want to import.

Note:

The <holiday1>, <holiday2>, and <holidayN> entries in the template must be replaced by VEVENT-type entries. For samples of VEVENT holidays that can be imported to Oracle Beehive refer to "Sample Holiday Entries".

Sample Holiday Entries

This section includes samples of VEVENT-type entries representing holidays that can be placed into a properly formatted iCalendar file. For information about creating an iCalendar file refer to "Creating an iCalendar File".

Example 10-1 Sample Holiday Event Recurring on a Fixed Date

BEGIN:VEVENT
DTEND;VALUE=DATE:20080702
SUMMARY:Canada Day
DTSTAMP:20080507T132210Z
UID:[e-mail]
DTSTART;VALUE=DATE:20080701
LAST-MODIFIED:20080507T132210Z
RRULE:FREQ=YEARLY
CATEGORIES:HOLIDAY
CREATED:20080507T132205Z
END:VEVENT

In Example 10-1, the VEVENT representing the holiday has an initial occurrence on July 1, 2008. The title of the holiday is "Canada Day", and has a yearly recurrence rule denoted by the RRULE parameter: the holiday occurs every July 1st.

Example 10-2 Sample Holiday Event Recurring on a Variable Date

BEGIN:VEVENT
DTEND;VALUE=DATE:20080527
SUMMARY:Spring Bank Holiday
DTSTAMP:20080507T132214Z
UID:[e-mail]
DTSTART;VALUE=DATE:20080526
LAST-MODIFIED:20080507T132214Z
RRULE:FREQ=YEARLY;BYMONTH=5;BYDAY=4MO
CATEGORIES:HOLIDAY
CREATED:20080507T132210Z
END:VEVENT

In Example 10-2, the VEVENT representing the holiday has an initial occurrence on May 26, 2008. The title of the holiday is "Spring Bank Holiday", and has a yearly recurrence rule denoted by the RRULE parameter: the holiday occurs on the fourth Monday, every month of May.

Importing Holiday iCalendar Files

Once you have created an iCalendar file and populated it with VEVENT-type holiday entries, use the beectl import_icalendar command-line tool to import the holiday events in Oracle Beehive.

For information about creating an iCalendar file, or sample VEVENT-type entries, refer to "Creating an iCalendar File", and "Sample Holiday Entries".

Follow these steps to import holidays from an iCalendar file:

1. Save the iCalendar file with the holiday entries in an accessible location on the computer running Oracle Beehive.

2. Run the following command from the $ORACLE_HOME/beehive/bin directory:

   beectl> import_icalendar --file <icalendar_file> --do_as_authuser <lgoinname> --holiday
   

   Where <icalendar_file> represents the absolute path to the iCalendar file saved in Step 1, and <loginname> represents the login name of the user importing the holiday entries.

Example 10-3 Importing Holiday Events

beectl> import_icalendar --file /tmp/holiday.ics --do_as_authuser jsmith --holiday

Imported invitation series, unique identifier=3449:5915:ocrs:A6E2F29FEB7A49DB9F27C0C3E3226413000000000002, iCalendar UID=[e-mail].
Imported invitation series, unique identifier=3449:5915:ocrs:A6E2F29FEB7A49DB9F27C0C3E3226413000000000006, iCalendar UID=[e-mail].

In Example 10-3, a file named holiday.ics is being imported from the /tmp directory. The events will be imported as user jsmith, and the --holiday option denotes that the events within the file are holiday-type entries. The resulting output on the command-line indicates the two unique invitation series have been imported.

Modifying User Time Management Preferences

This section contains information related to changing specific user preferences related to Oracle Beehive Time Management services, and includes the following topics:

• Changing a User's Time Zone Preference

• Changing a User's Defined Working Hours

Changing a User's Time Zone Preference

When a user temporarily or permanently changes geographic locations, their preferred time zone may change. This section includes information about changing a user's time zone, including determining available time zone identifiers.

Once a user's time zone preference has been changed, events will appear in the user's calendar -- offset by the appropriate number of hours -- relative to their new geographic location.

To change a user's defined time zone preference:

1. Determine the time zone identifier of the time zone that you want to assign to a user. Use the beectl list_timezones command to obtain a full list of available time zones and their associated identifiers.

   Note:

   To list all available time zones on your Oracle Beehive deployment specify the --all option. When the --all option is not specified only common time zones will be returned.

2. Run the following command from the $ORACLE_HOME/beehive/bin directory:

   beectl> modify_user --email <address> --timezone <ID>
   

   Where <address> represents the e-mail address of the user, and <ID> represents the identifier of the time zone.

   Note:

   The --user option can be specified instead of the --email option to identify the user. For more information, refer to modify_user, in the Oracle Beehive Administrator's Reference Guide.

Example 10-4 Changing a User's Time Zone

beectl> modify_user --email [e-mail] --timezone tmzn=Europe/Berlin
 
Successfully modified user: [e-mail]

In Example 10-4, the user with e-mail address [e-mail] had their time zone preference defined as Europe/Berlin. The resulting output on the command-line indicates the modification was successful.

Changing a User's Defined Working Hours

Working hours are set in a user's property preference profile, and can be changed using the beectl add_preference_property command.

The values set for a user's working hours helps other users determine when the person is most likely to be available for meetings. By default, a user's working hours are set to begin at 9:00 AM, an end at 6:00 PM -- in the user's defined time zone.

To change a user's defined working hours:

1. Run this command from the $ORACLE_HOME/beehive/bin directory to list the user's preference properties:

   beectl> list_preference_profiles --consumer <userid>
   

   Where <userid> represents the user identifier of the user.

2. Using the output returned from Step 1, locate the TimeManagement section. Within the section, locate the working_hours preference property, then locate the text below the value field. Copy the string of characters, within and including the <WeekBusinessHours> tags. The string will resemble the following text:

   <WeekBusinessHours xmlns="http://xmlns.oracle.com/2006/Beehive/BOM/business-hours"><<WeekShift StartDay="MONDAY" StartTime="09:00:00" EndDay="MONDAY" EndTime="18:00:00" Type="REGULAR"/><WeekShift StartDay="TUESDAY" StartTime="09:00:00" EndDay="TUESDAY" EndTime="18:00:00" Type="REGULAR"/><WeekShift StartDay="WEDNESDAY" StartTime="09:00:00" EndDay="WEDNESDAY" EndTime="18:00:00" Type="REGULAR"/><WeekShift StartDay="THURSDAY" StartTime="09:00:00" EndDay="THURSDAY" EndTime="18:00:00" Type="REGULAR"/><WeekShift StartDay="FRIDAY" StartTime="09:00:00" EndDay="FRIDAY" EndTime="18:00:00"Type="REGULAR"/></WeekBusinessHours>
   

3. Paste the text copied in Step 2 into a text editor. Modify the StartTime and EndTime values of each work day to reflect the new working hours for the user.

4. Copy the text modified in Step 3.

5. Run the following command from the $ORACLE_HOME/beehive/bin directory to change the working hours for the user:

   beectl> add_preference_property --set prfs=TimeManagement,<userID> --name working_hours --type BUSINESS_HOURS --value <WeekBusinessHours>
   

   Where <userID> represents the user identifier of the user, and <WeekBusinessHours> represents the text copied in Step 4.

Example 10-5 Changing a User's Working Hours

beectl> add_preference_property --set prfs=TimeManagement,loginid=jsmith --name working_hours --type BUSINESS_HOURS --value "<WeekBusinessHours xmlns="http://xmlns.oracle.com/2006/Beehive/BOM/business-hours"><<WeekShift StartDay="MONDAY" StartTime="08:00:00" EndDay="MONDAY" EndTime="18:00:00" Type="REGULAR"/><WeekShift StartDay="TUESDAY" StartTime="08:00:00" EndDay="TUESDAY" EndTime="18:00:00" Type="REGULAR"/><WeekShift StartDay="WEDNESDAY" StartTime="10:00:00" EndDay="WEDNESDAY" EndTime="19:00:00" Type="REGULAR"/><WeekShift StartDay="THURSDAY" StartTime="10:00:00" EndDay="THURSDAY" EndTime="19:00:00" Type="REGULAR"/><WeekShift StartDay="FRIDAY" StartTime="08:00:00" EndDay="FRIDAY" EndTime="14:00:00"Type="REGULAR"/></WeekBusinessHours>"

In Example 10-5, the user with user identifier loginid=jsmith had their working hours modified to 8:00 AM to 6:00 PM on Monday and Tuesday; 10:00 AM to 7:00 PM on Wednesday and Thursday; and 8:00 AM to 2:00 PM on Friday.

Oracle Beehive Time Zone Definitions

This section includes information about time zone definitions, obtaining new time zone packages, and importing new time zone files into Oracle Beehive. This section contains the following topics:

• Overview

• Obtaining a New Oracle Beehive Time Zone Package

• Refreshing the Oracle Beehive Time Zone Package

Overview

Every installation of Oracle Beehive includes a set of time zones with associated rules. As time zones change as a result of political decisions, Oracle Beehive time zones will be updated as part of the regular upgrade process, or by applying a more recent Oracle Beehive Time Zones Package.

The contents of the Oracle Beehive Time Zones Package is based on the time zone definitions provided by the Public-Domain Time Zone Database Web site maintained at the National Institute of Health. For more information, consult the external Web site at the following address:

http://www.twinsun.com/tz/tz-link.htm

Obtaining a New Oracle Beehive Time Zone Package

The most recent Oracle Beehive time zone package is always included with the most recent Oracle Beehive patch.

Consult Oracle Support for information about obtaining time zone packages that are made available between Oracle Beehive releases.

Refreshing the Oracle Beehive Time Zone Package

Once you have obtained the newest time zone package, you will need to import the file using the beectl import_timezones command-line tool.

To import a time zone package:

1. Save the time zone package XML file in an accessible location on the computer running Oracle Beehive.

2. Run the following command from the $ORACLE_HOME/beehive/bin directory:

   beectl> import_timezones --file <timezone_package>
   

   Where <timezone_package> represents the absolute path to the time zone package file saved in Step 1.

Example 10-6 Importing a Time Zone Definition Package

beectl> import_timezones --file /tmp/timezones/tzdata2008a-085.xml
 
Time zones are successfully imported to database.

In Example 10-6, the time zone definition package file named tzdata2008a-085.xml is being imported from the /tmp/timezones directory. A line is returned to the command-line indicating that the time zones were successfully imported.