Scheduler

Scheduler

The scheduler is one of the most advanced applications available in the OpenGroupware suite, and the available functionality is growing all the time.

Customization

The OpenGroupware scheduler can be customized via the Defaults mechanism to match your organizations structure and psychology. It is important to consider these options before deploying the scheduler, particularly the web interface, to your users as the configuration can significantly impact this applications behavior.

Limiting Available Teams

The default behavior of the scheduler is to present all the teams to users when setting appointment permissions or selecting participants. For some rigidly divided organizations you may only want to permit people to select teams of which they are a member1. You can enable this behavior by setting the “scheduler_memberteams_only” default to a value of “YES”.

Hiding Non-Visible Appointments

Appointments which a user has no permission to read appear on the calendar as a key icon if a participant is selected in the current view. The participants, start time, and end time is visible to all users regardless of permissions. This facilitates scheduling between users while still providing privacy; location, description, comment, and notes are not available to users without read permissions. If, however, you desire that users be completely unaware of each others private appointments you can set the “scheduler_hide_listonly_appointments” default in the "ogo-webui" domain to a value of “YES”.

Participant Roles

Enabling this feature allows roles to be assigned to participants of an appointment, matching the functionality provided by the iCal format. Roles are: Chairperson, required participant, optional participant, and non-participant. If roles are assigned a user can subsequently accept, tentatively accept, or decline their participation; this allows a meeting organizer to actively track who has responded to the appointment and who has not. For more specific information on the meaning of the specific roles, see the section “Roles”.

In order to enable this functionality set the “apteditor_useattendeeselector” and “scheduler_participantRolesEnabled” defaults in the “ogo-webui-{version}” domain. If participant role support is enabled one should consider also enable automatic team flattening. Otherwise a role can be assigned to a team, but the logic concerning accepting and declining becomes non-intuitive as one member of the team may desire to accept while another prefers to decline. If only “scheduler_participantRolesEnabled” is enabled and not “apteditor_useattendeeselector” then roles will appear in the web interface of the schedular but you will be unable to assign roles to participants via the web interface, but they may still be set or altered via other interfaces such as the commercial ZideLook connector.

Flattening Teams

With team flattening enabled, by setting the “scheduler_editor_canResolveTeams” default in the “ogo-webui” domain to “YES”, when a team is selected as the participant in an appointment it is automatically converting to an enumeration of its members when the appointment is saved. This means that all meeting participants will be individual contacts and not teams. In the default configuration, without team flattening, the team object itself will be saved as a participant and changes to the team membership will automatically be reflected in the scheduler (which will not happen with team flattening enabled). Team flattening is most useful in conjunction with the participant role feature.

Extended Attributes

Extended attributes allow for the definition of site specific attributes of an appointment. Since the definition of extended attributes for appointments also applies to the definition of extended attributed for contacts, enterprises, and projects this topic is covered in the chapter entitled “Customization”.

Default Read Access

By default, unless a user specifies otherwise when creating an appointment, the read access of an appointment is “private”. Currently there is no way for a user to specify an alternative read access default other than private.

Default Write Access

A user can change their own write access default via the scheduler section of the preferences.

Appointment Types

Appointments have a type attribute, by default the following types are available: birthday , tradeshow, meeting, vacation, due date, outward appointment, at home, phone call, ill, and uncategorized. The uncategorized psuedo-type actually indicates no type and is the default for a new appointment in the web interface. In the database appointment types are stored in the apt_type column of the date_x as the following values, respectively: “birthday”, “tradeshow”, “meeting”, “holiday”, “duedate”, “outward”, “home”, “call”, and “ill”. An uncategorized appointment has a NULL apt_type value. This value in the database is easily confused with the “type” field in the same table, but the “type” field contains recurrence information about the appointment.
Additional appointment types can be defined via the “SkyScheduler_customAppointmentTypes” default. This default is an array of dictionary, one dictionary for every additional appointment type; each dictionary has three keys: “type”. “label”, and “icon”.

Roles

The iCalendar format, frequently referred to as just “iCal”, describes a set of attendee roles for use in group scheduling. In an iCalendar file the role is an element of the “attendee” value. To support this pervasive standard OpenGroupware's schedular can assign these roles to participants of appointments and stores them in its database. The iCalendar reference document provides four roles: Chairperson, Required Participant, Optional Participant, and non-Participant. The chairperson is the chair or leader of the meeting, a required participant is an attendee whose presence is required for the meeting to proceed or succeed, and an optional participant is an one whose presence is desired but not required for the meeting to proceed.

The purpose of the non-participant role, while very useful, is initially confusing to many people. By placing a user in the non-participant role you can cause the appointment to appear on their default calendar view without creating scheduling conflicts. This is very useful if there is an event that a user or users should be aware of but do not participate in (hence the “non-participant” role). By placing the event on the users calendar view they can easily check the comment, notes, and links of the appointment without the meeting organizer having to user explicit notification like an e-mail message. The non-participant role also does not effect the availability of the user or free-busy information requested by clients from the server; most significantly, meetings with a non-participant role for the user are ignored for conflicts and when generating meeting proposals.

Conflicts

ogo-check-aptconflicts

The command line utility can be used to check for conflicts relating to a specific login for a specified time frame. OpenGroupware command line utilities must be executed as the OpenGroupware user. The utility will report each of the appointments that has a conflict. The login and password of a valid user must be provided via the “-login” and “-password” parameters. The range of time to check is then specified as start and end dates in YYYYMMDD format and the login of the user to check for conflicts.

$ ogo-check-aptconflicts -login adam -password ******* 20080101 20081231 adam 
Found 1 conflicting appointments (20080101 - 20081231): 
hfhfdhd (11170) 
time: 2008-07-08 23:00:00 -0400 - 2008-07-09 00:00:00 -0400 
conflicts: 10102    (status=<null>, role=REQ-PARTICIPANT) 
conflicts: 10102    (status=NEEDS-ACTION, role=REQ-PARTICIPANT)

The output of ogo-check-aptconflicts will list each appointment by its title and object Id#, followed by that appointments start and end time. Subsequently each conflict for that appointment is listed. An individual appointment may have multiple conflicts. The object Id# of the conflicting objects is listed.

Free Busy Information

The ZideStore integration server can provide free/busy information to groupware clients via an HTTP request. The URL to request free/busy information is: http://{server:port}/zidestore/so/freebusy. Parameters are added to the request URL in order to specify the account being queried and optionally the desired date range of the response.

Date Range

To specify the date range of the request add “start” and “end” parameters to the URL1. The format of the date must be in YYYY-MM-DD format. You can also specify a time using a format of “YYYY-MM-DDTHH:MM:00” where the “T” is a literal character that separates the date and time values. If specifying a time the seconds field must be included in the time string although the value is discarded. Times must also be GMT2.

If no start or end value is specified then 121 days of free/busy information is returned in the request response, sixty days prior to the current date and sixty days following the current date3. If only a start date is specified then from that date to sixty days following the current date is returned to the client. If only an end date is specified then sixty days prior to the current date up to the provided end date is returned to the client. If the start and or end date is improperly formatted then ZideStore will revert to the sixty day default and calculate a date to use in place of the improperly formatted value.

“name” & “server”

The client must specify the name of the account with two parameters: “name” and “server”. The “name” is the left portion of the e-mail address while the “server” is the right portion (domain) of the e-mail address. The e-mail address searched for must correspond to the value of the “email1” attribute, “email2” is not searched. To find the freebusy information for the account with the e-mail address of “awilliam@whitemice.org” the parameter string would be “name=awilliam&server=whitemice.org”.

Response

Freebusy results are provided in the standard VFREEBUSY format1 from the IETF iCalendar specification. The “mailto” attribute of the attendee and organizer values will the the e-mail address that was searched for.
One limitation of the current iCalendar response is that the FBTYPE attribute of each FREEBUSY line will always be “BUSY” regardless of the participant status and role of the contact in relation to the appointment. For instance, a non-participant participant will still appear as busy in the free/busy response although a non-participant participant should appear as available for that time.

Holidays