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.
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 |
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.
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.
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.
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 |
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.
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 |
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 |
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 |
Here, the stated organiser may still arrange a booking of the resource where the previously-mentioned attendee is involved.
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.
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:
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
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 |
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.
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 |
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 |
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 |
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 |
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 |