Resources

In imip-agent, resources are a special kind of user that act upon requests to schedule events and that perform such scheduling autonomously, meaning that no human intervention is necessary when such resources receive messages containing invitations.

By default, the agent program responsible for resources merely attempts to fit a received event into the resource's schedule. However, in some organisations and environments, it is likely to be the case that other policies are needed to ensure that a resource is not misused, overused or made unnecessarily unavailable.

The preferences provide a way of controlling the behaviour of resources, just as with any other kind of user, but certain preferences are central to the configuration of resources.

  1. Scheduling Functions
    1. Concurrent Reservations
    2. Identity Controls
      1. Same Domain Membership
      2. Access Control Lists
    3. Quota Controls
      1. Initialising Quotas
      2. Sharing Quotas Across Users
      3. Individual Resource Quotas
      4. Common Resource Quotas
      5. Collective Scheduling
      6. Delegating Attendance

Scheduling Functions

The scheduling_function setting indicates the behaviour of a resource when a valid request to schedule an event has been received. By default, a value equivalent to the following is employed:

Scheduling Functions

Decision Process

schedule_in_freebusy

scheduling_decisionsIncoming mailCan schedule in free/busy?Schedule event for resourceDeclineFree/busyAccept

As described above, this merely attempts to schedule an event in the free periods of the resource's schedule. However, no attempt is made to reject the booking of the resource according to the identity of the organiser.

Concurrent Reservations

The schedule_in_freebusy function causes a resource to attempt to schedule an event, and by default it rejects requests that involve periods for which the resource is otherwise committed. However, a resource can be allowed to attend (or commit to) multiple concurrent events.

By indicating a value as an argument to the function, a kind of capacity or commitment level can be assigned to a resource. For example:

schedule_in_freebusy 5

This example indicates that a resource can support five different events occupying the same point in time. Applications of such concurrent reservations include things like rooms or resources that can be shared and which have a notion of a capacity that is not immediately exhausted as soon as one event seeks to reserve such a room or resource.

Identity Controls

Although identity controls may be implemented in the e-mail system, effectively preventing the messages from addresses other than those within an organisation (for example) from being delivered to the resource, it is possible to use scheduling functions to implement such controls instead.

Same Domain Membership

For instance, the following combines the default free/busy check with a test that the organiser belongs to the same Internet mail domain (by using the organiser's address):

Scheduling Functions

Decision Process

schedule_in_freebusy
same_domain_only

scheduling_decisionsIncoming mailCan schedule in free/busy?Organiser has resource domain?DeclineFree/busySchedule event for resourceAccept

Note that if the first function is omitted, no check against the resource's schedule will occur, so it is necessary to mention any such function in the list.

Access Control Lists

A simple domain-related test may not be sufficient to control access to a resource. Thus, another function is provided to exercise a finer degree of control over event participants. For example:

Scheduling Functions and Data

Decision Process

schedule_in_freebusy
access_control_list

Access control list:

accept

scheduling_decisionsIncoming mailCan schedule in free/busy?Access control list permits booking?DeclineFree/busyAccept invitation by defaultacl settingendSchedule event for resourceAccept

To accompany the scheduling functions, the acl setting in the resource's preferences must be set, or if a separate file is more appropriate, its full path may be given as an argument to access_control_list:

schedule_in_freebusy
access_control_list /etc/imip-agent/resources.acl

Within the file provided by the setting or separate file, a list of rules must describe the handling procedure for an event. For example, the following was given in the above example:

accept

This will merely accept all invitations, anyway. However, it may be appropriate to prevent certain users from using resources. For example:

Scheduling Functions and Data

Decision Process

schedule_in_freebusy
access_control_list

Access control list:

accept
decline attendee simon.skunk@example.com

scheduling_decisionsIncoming mailCan schedule in free/busy?Access control list permits booking?DeclineFree/busyAccept invitation by defaultacl settingIs attendee simon.skunk@example.com?endSchedule event for resourceAccept

This example indicates that by default, invitations will be accepted, but if one of the attendees of an event is simon.skunk@example.com, the invitation will be declined. However, it may be the case that this rule should be overridden under certain circumstances. For example:

Scheduling Functions and Data

Decision Process

schedule_in_freebusy
access_control_list

Access control list:

accept
decline attendee simon.skunk@example.com
accept organiser paul.boddie@example.com

scheduling_decisionsIncoming mailCan schedule in free/busy?Access control list permits booking?DeclineFree/busyAccept invitation by defaultacl settingIs attendee simon.skunk@example.com?Is organiser paul.boddie@example.com?endSchedule event for resourceAccept

Here, the stated organiser may still arrange a booking of the resource where the previously-mentioned attendee is involved.

Quota Controls

In contrast to each user's stored information which consolidates information related to that user's own schedule in a section of the data store, the quota system consolidates information related to the schedules of one or more resources in a repository known as the journal, thus enabling observations to be made about their collective usage.

First, consider a resource such as a car where an organiser of an event may be booking the car for travel purposes. A quota prevents the organiser from booking the resource too much and denying other users access to it.

quota_usersReservation from oliver.otter@example.comMonday at 10amWithin quota?Reservation from oliver.otter@example.comTuesday at 10amWithin quota?Reservation from oliver.otter@example.comWednesday at 10amWithin quota?Quota for resource-car-pontiac@example.com

Now consider a number of separate car resources. An organiser might attempt to get around any individual resource quota by booking a number of different cars. Since each car is only aware of its own usage, it would be unaware of the undesirable cumulative usage of all cars by the organiser.

By grouping the resources together, the organiser will exhaust any quota set on the group of resources as they try and make reservations for the different members of the quota group. Some additional measures are introduced as follows:

quota_usersReservation from oliver.otter@example.comMonday at 10amresource-car-pontiac@example.comReservation from oliver.otter@example.comTuesday at 10amresource-car-cadillac@example.comReservation from oliver.otter@example.comWednesday at 10amresource-car-lexus@example.comWithin common quota?Quota for cars

Initialising Quotas

Within the journal storage area, a quota may be initialised with limits indicating the amount of time that can be occupied by the cumulative total of all events scheduled by an individual user or a group of which they are a member.

Such limits may be set directly using the limits file in a quota directory (described in the filesystem guide) or in the quota_limits table (described in the database guide), but a tool is also provided to set such limits. For example:

cat <<EOF | set_quota_limits.py 'mailto:resource-car-cadillac@example.com'
mailto:vincent.vole@example.com PT10H
EOF

In the above example, shell syntax is used to indicate a here document providing a kind of "inline" file that is terminated by the final EOF. The contents of this file are piped to the tool with a single argument given indicating the quota involved.

You could also just invoke the tool and then enter the limit descriptions, ending the input with Ctrl-D or equivalent end-of-file keystroke, or save the descriptions in a file and then use input redirection with the filename.

The above example indicates that the given user may only reserve 10 hours of events or less time within the given quota (corresponding to a specific resource in the above example). Attempts to schedule more time will be declined.

To impose a general quota, the special * identity can be used:

cat <<EOF | set_quota_limits.py 'mailto:resource-car-cadillac@example.com'
* PT10H
EOF

Note that this general quota applies to each individual identity and not collectively to all unspecified identities. To impose such a collective quota, a group may be defined for this purpose as described below.

When a user identity is not listed and no general quota is defined, that particular user will be unable to reserve the resource unless defined as a member of a group listed in the limits file, as described below.

It may be useful to define unlimited quotas for certain identities or groups in order to effectively exclude them from limits. For example:

cat <<EOF | set_quota_limits.py 'mailto:resource-car-cadillac@example.com'
mailto:vincent.vole@example.com *
EOF

Sharing Quotas Across Users

When the use of resources is to be shared between users in such a way that groups of users will be sharing a single quota, a groups file in a quota directory (or records in the quota_groups table) must be defined, mapping each user identity to the group to which they will belong.

A tool is provided to define groups and is used as follows:

cat <<EOF | tools/set_quota_groups.py 'mailto:resource-car-cadillac@example.com'
mailto:vincent.vole@example.com developers
* others
EOF

Here, otherwise unrecognised organisers are mapped to the others group. Thus, all scheduling performed by such organisers will be done in a common journal with this label.

The process of determining where an organiser's usage of resources is recorded is illustrated by the following example:

Scheduling Data

Decision Process

The groups are defined as follows in the groups file:

mailto:vincent.vole@example.com developers
mailto:harvey.horse@example.com developers
mailto:paul.boddie@example.com developers
mailto:simon.skunk@example.com testers

The group identity can then be employed in the limits file:

developers PT10H
testers PT20H

quota_usersUser is vincent.vole@example.comHave group for quota?User is oliver.otter@example.comHave group for user in quota?User is vincent.vole@example.comGroup is developersUser is oliver.otter@example.comHave limit for group?Have limit for user?Have general limit?QuotaHave general limit?No quota

Where individuals are not assigned to groups, any individual limit will apply to them; otherwise, the general quota applies. Where individuals are assigned to groups, any group limit will apply; otherwise, the general quota applies.

Individual Resource Quotas

The trivial case of applying quotas is to give a resource its own quota. This is achieved by not specifying any arguments to the check_quota scheduling function or to the add_to_quota and remove_from_quota functions.

Scheduling Functions

Decision Process

check_quota

scheduling_decisionsIncoming mailfrom vincent.vole@example.comIs allowed by quota?Incoming cancellationRemove from quotaSchedule event for resourceDeclineQuota for resource...applying tovincent.vole@example.comAcceptAdd to quota

Common Resource Quotas

By indicating an argument to the different functions, a common quota can be employed. In the following example, both resources would employ the given function invocations to pool their knowledge about their schedules.

Scheduling Functions

Decision Process

check_quota cars

scheduling_decisionsIncoming mailfrom vincent.vole@example.comto resource-car-cadillac@example.comIs allowed by quota?Incoming mailfrom vincent.vole@example.comto resource-car-pontiac@example.comIncoming cancellationRemove from quotaSchedule event for resourceDeclineQuota for cars...applying tovincent.vole@example.comAcceptAdd to quota

Collective Scheduling

Consider two separate resources: both may be reserved at the same time by the same organiser; neither resource would normally decline the reservation on the basis of schedule availability, should the period concerned be free. However, it may be undesirable for one organiser to occupy both resources at the same time.

Consequently, a mechanism is required to pool the resource schedules in such a way that any reservation performed for one resource at a given point in time prohibits another reservation performed for a related resource at the same point in time by the same user.

The free/busy records held for a given quota group permit such collective scheduling decisions and are employed as follows:

Scheduling Functions

Decision Process

schedule_across_quota cars

scheduling_decisionsIncoming mailfrom vincent.vole@example.comto resource-car-cadillac@example.comCan be scheduled within the quota?Incoming mailfrom vincent.vole@example.comto resource-car-pontiac@example.comIncoming cancellationRemove from quota free/busySchedule event for resourceDeclineQuota for cars...recording schedule forvincent.vole@example.comAcceptAdd to quota free/busy

Delegating Attendance

A number of resources may be regarded as interchangeable and can therefore stand in for each other when they are unavailable. The iCalendar specification supports the notion of delegation: the recipient of an event invitation may delegate their attendance to other calendar user, informing that user and the event organiser of this decision.

To define such delegation relationships, a quota is first selected as the repository of common scheduling information for a group of resources. Then, the members of the group are defined as delegates. This can be done using a tool provided for this purpose. For example:

cat <<EOF | tools/set_delegates.py 'cars'
mailto:resource-car-cadillac@example.com
mailto:resource-car-pontiac@example.com
EOF

Here, two resources are defined that will delegate to each other if they cannot attend an event according to their own schedule.

Scheduling Functions

Decision Process

schedule_for_delegate cars

scheduling_decisionsIncoming mailfrom vincent.vole@example.comto resource-car-cadillac@example.comCan be scheduled or delegated?Incoming mailfrom vincent.vole@example.comto resource-car-pontiac@example.comIncoming cancellationRemove from quotaSchedule event for resourceDelegateDeclineQuota for cars...recording schedule forvincent.vole@example.comAcceptAdd to quota

Note that it is generally more useful to have delegation decisions made on the basis of many resources, which is what the journal entries for each quota provides, but also considering organisers attempting to reserve those resources as a single group whose reservations are consolidated and assessed collectively. Thus, a single group of users would be defined:

cat <<EOF | tools/set_quota_groups.py 'cars'
* all
EOF

Although the journal for each quota may be divided up to administer quotas for multiple groups of organisers, for the purposes of delegation - deciding whether a resource is generally available, and deciding which other resource would be available instead - a single group of all organisers is more desirable.

If limits need to be imposed alongside delegation, separate quotas may be used to achieve this.

Scheduling Functions

Decision Process

check_quota cars
schedule_for_delegate car_delegation

scheduling_decisionsIncoming mailfrom vincent.vole@example.comto resource-car-cadillac@example.comIs allowed by quota?Incoming mailfrom vincent.vole@example.comto resource-car-pontiac@example.comIncoming cancellationRemove from quotaCan be scheduled or delegated?DeclineQuota for cars...applying tovincent.vole@example.comSchedule event for resourceDelegateQuota for cars_delegation...recording schedule forvincent.vole@example.comAcceptAdd to quota