# HG changeset patch # User Paul Boddie # Date 1454197589 -3600 # Node ID abbfbee0f858f3a9ec893903def799b3fe9e75b9 # Parent fc1efc973849fbb1047fb43910529b15782998c7 Added a page about resources plus details of new scheduling functions. diff -r fc1efc973849 -r abbfbee0f858 docs/wiki/Administration --- a/docs/wiki/Administration Sun Jan 31 00:45:26 2016 +0100 +++ b/docs/wiki/Administration Sun Jan 31 00:46:29 2016 +0100 @@ -69,6 +69,9 @@ other resources to give more time to event organisers to respond to their counter-proposals. +See the [[../Resources|resources guide]] for more information about configuring +resources. + === Adjusting Preferences === Once initialised, the user preferences can be adjusted by adding files to the diff -r fc1efc973849 -r abbfbee0f858 docs/wiki/AgentPrograms --- a/docs/wiki/AgentPrograms Sun Jan 31 00:45:26 2016 +0100 +++ b/docs/wiki/AgentPrograms Sun Jan 31 00:46:29 2016 +0100 @@ -6,7 +6,7 @@ || '''Program''' || '''Purpose''' || || `imip_person.py` ||<|2> Maintain scheduling information on behalf of people || || `imip_person_outgoing.py` || -|| `imip_resource.py` || Act as an autonomous resource that can be reserved || +|| `imip_resource.py` || Act as an autonomous [[../Resources|resource]] that can be reserved || For people, the role of the agent programs concerned is to construct a schedule that can be accessed via the [[../CalendarManager|management interface]] and to @@ -58,8 +58,8 @@ potentially-implementable ideas. Meanwhile, the resource handler, `imip_resource.py`, is responsible not only -for maintaining a schedule for a resource, but it must also make scheduling -decisions itself without human involvement. How it may behave is determined -by a number of policies set in the [[../Preferences|preferences]] so that, -for example, it may suggest alternative event periods when those requested -in an invitation are unavailable. +for maintaining a schedule for a [[../Resources|resource]], but it must also +make scheduling decisions itself without human involvement. How it may behave +is determined by a number of policies set in the [[../Preferences|preferences]] +so that, for example, it may suggest alternative event periods when those +requested in an invitation are unavailable. diff -r fc1efc973849 -r abbfbee0f858 docs/wiki/FrontPage --- a/docs/wiki/FrontPage Sun Jan 31 00:45:26 2016 +0100 +++ b/docs/wiki/FrontPage Sun Jan 31 00:46:29 2016 +0100 @@ -25,9 +25,9 @@ [[/MailClients|mail software]] with calendaring support. This is optional and your users can choose to adjust, ignore or disable this functionality. - * It supports autonomous entities such as meeting rooms and resources, - automatically accepting or declining invitations according to their - schedules. You can adjust this behaviour to implement your own policies. + * It supports autonomous entities such as meeting rooms and [[/Resources|resources]], + automatically accepting or declining invitations according to their schedules. + You can adjust this behaviour to implement your own policies. * It is [[https://www.fsf.org/about/what-is-free-software|Free Software]], giving you the freedom to see what the software does, as well as the freedom diff -r fc1efc973849 -r abbfbee0f858 docs/wiki/Preferences --- a/docs/wiki/Preferences Sun Jan 31 00:45:26 2016 +0100 +++ b/docs/wiki/Preferences Sun Jan 31 00:46:29 2016 +0100 @@ -51,6 +51,49 @@ The default time zone/regime for calendars, new events and local times. +=== acl === + + Default:: (none) + Alternatives:: (see below) + +Provides an access control list for the `access_control_list` scheduling +function, invoked using the `scheduling_functions` setting. An access control +list consists of a collection of lines of text describing the handling policy +for an incoming invitation. + +{{{#!table +`accept` || indicates that if no rule matches, the invitation will be accepted + .. (provisionally) +== +`decline` || indicates that if no rule matches, the invitation + .. will be declined (provisionally) +== +`reject` +== +`accept` ''`role`'' ''`identity`'' || indicates that where the given + .. ''`identity`'' exists in the given + .. ''`role`'' in the event, and unless a subsequent rule contradicts + .. this result, the invitation will be accepted (provisionally) +== +`decline` ''`role`'' ''`identity`'' || indicates that where the + .. given ''`identity`'' exists + .. in the given ''`role`'' in the event, and unless a subsequent rule + .. contradicts this result, the invitation will be declined + .. (provisionally) + +== +`reject` ''`role`'' ''`identity`'' +}}} + +In the above, `role` is either `organiser` (or `organizer`) or `attendee`; +`identity` is an address or URL. + +Note that even if an accepted result is returned by the `access_control_list` +scheduling function, other functions that follow it in the list of functions +may overturn this result. + +See the [[../Resources|resources guide]] for examples and more information. + === add_method_response === Default:: `refresh` @@ -229,16 +272,22 @@ Default:: `schedule_in_freebusy` Alternatives:: (see below) -Indicates the scheduling functions used by resources to find an appropriate -period for an event, with each function to be applied to a scheduling request -appearing on a separate line. +Indicates the scheduling functions used by [[../Resources|resources]] to find +an appropriate period for an event, with each function to be applied to a +scheduling request appearing on a separate line, optionally accompanied by +arguments controlling the behaviour of the function. The imiptools.handlers.scheduling module contains the built-in scheduling functions which include the following: {{{#!table -`same_domain_only` || accept an invitation only if the organiser employs an - .. address in the same domain as the resource +`access_control_list` || use an access control list provided by a file whose + .. name is given as an argument, accepting or declining + .. the invitation according to the indicated rules + .. (described in the [[../Resources|resources guide]]) +== +`same_domain_only` || accept an invitation only if the organiser employs an + .. address in the same domain as the resource == `schedule_in_freebusy` || accept an invitation if the event periods are free .. according to the free/busy records for the resource; diff -r fc1efc973849 -r abbfbee0f858 docs/wiki/Resources --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Resources Sun Jan 31 00:46:29 2016 +0100 @@ -0,0 +1,104 @@ += 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 [[../AgentPrograms|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|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. + +<> + +== Scheduling Functions == + +The [[../Preferences#scheduling_function|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: + +{{{ +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. + +=== 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): + +{{{ +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. + +==== 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: + +{{{ +schedule_in_freebusy +access_control_list +}}} + +To accompany this, the [[../Preferences#acl|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: + +{{{ +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: + +{{{ +accept +}}} + +This will merely accept all invitations, anyway. However, it may be +appropriate to prevent certain users from using resources. For example: + +{{{ +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: + +{{{ +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.