1.1 --- a/docs/wiki/Administration Sun Jan 31 00:45:26 2016 +0100
1.2 +++ b/docs/wiki/Administration Sun Jan 31 00:46:29 2016 +0100
1.3 @@ -69,6 +69,9 @@
1.4 other resources to give more time to event organisers to respond to their
1.5 counter-proposals.
1.6
1.7 +See the [[../Resources|resources guide]] for more information about configuring
1.8 +resources.
1.9 +
1.10 === Adjusting Preferences ===
1.11
1.12 Once initialised, the user preferences can be adjusted by adding files to the
2.1 --- a/docs/wiki/AgentPrograms Sun Jan 31 00:45:26 2016 +0100
2.2 +++ b/docs/wiki/AgentPrograms Sun Jan 31 00:46:29 2016 +0100
2.3 @@ -6,7 +6,7 @@
2.4 || '''Program''' || '''Purpose''' ||
2.5 || `imip_person.py` ||<|2> Maintain scheduling information on behalf of people ||
2.6 || `imip_person_outgoing.py` ||
2.7 -|| `imip_resource.py` || Act as an autonomous resource that can be reserved ||
2.8 +|| `imip_resource.py` || Act as an autonomous [[../Resources|resource]] that can be reserved ||
2.9
2.10 For people, the role of the agent programs concerned is to construct a schedule
2.11 that can be accessed via the [[../CalendarManager|management interface]] and to
2.12 @@ -58,8 +58,8 @@
2.13 potentially-implementable ideas.
2.14
2.15 Meanwhile, the resource handler, `imip_resource.py`, is responsible not only
2.16 -for maintaining a schedule for a resource, but it must also make scheduling
2.17 -decisions itself without human involvement. How it may behave is determined
2.18 -by a number of policies set in the [[../Preferences|preferences]] so that,
2.19 -for example, it may suggest alternative event periods when those requested
2.20 -in an invitation are unavailable.
2.21 +for maintaining a schedule for a [[../Resources|resource]], but it must also
2.22 +make scheduling decisions itself without human involvement. How it may behave
2.23 +is determined by a number of policies set in the [[../Preferences|preferences]]
2.24 +so that, for example, it may suggest alternative event periods when those
2.25 +requested in an invitation are unavailable.
3.1 --- a/docs/wiki/FrontPage Sun Jan 31 00:45:26 2016 +0100
3.2 +++ b/docs/wiki/FrontPage Sun Jan 31 00:46:29 2016 +0100
3.3 @@ -25,9 +25,9 @@
3.4 [[/MailClients|mail software]] with calendaring support. This is optional
3.5 and your users can choose to adjust, ignore or disable this functionality.
3.6
3.7 - * It supports autonomous entities such as meeting rooms and resources,
3.8 - automatically accepting or declining invitations according to their
3.9 - schedules. You can adjust this behaviour to implement your own policies.
3.10 + * It supports autonomous entities such as meeting rooms and [[/Resources|resources]],
3.11 + automatically accepting or declining invitations according to their schedules.
3.12 + You can adjust this behaviour to implement your own policies.
3.13
3.14 * It is [[https://www.fsf.org/about/what-is-free-software|Free Software]],
3.15 giving you the freedom to see what the software does, as well as the freedom
4.1 --- a/docs/wiki/Preferences Sun Jan 31 00:45:26 2016 +0100
4.2 +++ b/docs/wiki/Preferences Sun Jan 31 00:46:29 2016 +0100
4.3 @@ -51,6 +51,49 @@
4.4
4.5 The default time zone/regime for calendars, new events and local times.
4.6
4.7 +=== acl ===
4.8 +
4.9 + Default:: (none)
4.10 + Alternatives:: (see below)
4.11 +
4.12 +Provides an access control list for the `access_control_list` scheduling
4.13 +function, invoked using the `scheduling_functions` setting. An access control
4.14 +list consists of a collection of lines of text describing the handling policy
4.15 +for an incoming invitation.
4.16 +
4.17 +{{{#!table
4.18 +`accept` || indicates that if no rule matches, the invitation will be accepted
4.19 + .. (provisionally)
4.20 +==
4.21 +`decline` ||<rowspan="2"> indicates that if no rule matches, the invitation
4.22 + .. will be declined (provisionally)
4.23 +==
4.24 +`reject`
4.25 +==
4.26 +`accept` ''`role`'' ''`identity`'' || indicates that where the given
4.27 + .. ''`identity`'' exists in the given
4.28 + .. ''`role`'' in the event, and unless a subsequent rule contradicts
4.29 + .. this result, the invitation will be accepted (provisionally)
4.30 +==
4.31 +`decline` ''`role`'' ''`identity`'' ||<rowspan="2"> indicates that where the
4.32 + .. given ''`identity`'' exists
4.33 + .. in the given ''`role`'' in the event, and unless a subsequent rule
4.34 + .. contradicts this result, the invitation will be declined
4.35 + .. (provisionally)
4.36 +
4.37 +==
4.38 +`reject` ''`role`'' ''`identity`''
4.39 +}}}
4.40 +
4.41 +In the above, `role` is either `organiser` (or `organizer`) or `attendee`;
4.42 +`identity` is an address or URL.
4.43 +
4.44 +Note that even if an accepted result is returned by the `access_control_list`
4.45 +scheduling function, other functions that follow it in the list of functions
4.46 +may overturn this result.
4.47 +
4.48 +See the [[../Resources|resources guide]] for examples and more information.
4.49 +
4.50 === add_method_response ===
4.51
4.52 Default:: `refresh`
4.53 @@ -229,16 +272,22 @@
4.54 Default:: `schedule_in_freebusy`
4.55 Alternatives:: (see below)
4.56
4.57 -Indicates the scheduling functions used by resources to find an appropriate
4.58 -period for an event, with each function to be applied to a scheduling request
4.59 -appearing on a separate line.
4.60 +Indicates the scheduling functions used by [[../Resources|resources]] to find
4.61 +an appropriate period for an event, with each function to be applied to a
4.62 +scheduling request appearing on a separate line, optionally accompanied by
4.63 +arguments controlling the behaviour of the function.
4.64
4.65 The imiptools.handlers.scheduling module contains the built-in scheduling
4.66 functions which include the following:
4.67
4.68 {{{#!table
4.69 -`same_domain_only` || accept an invitation only if the organiser employs an
4.70 - .. address in the same domain as the resource
4.71 +`access_control_list` || use an access control list provided by a file whose
4.72 + .. name is given as an argument, accepting or declining
4.73 + .. the invitation according to the indicated rules
4.74 + .. (described in the [[../Resources|resources guide]])
4.75 +==
4.76 +`same_domain_only` || accept an invitation only if the organiser employs an
4.77 + .. address in the same domain as the resource
4.78 ==
4.79 `schedule_in_freebusy` || accept an invitation if the event periods are free
4.80 .. according to the free/busy records for the resource;
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/wiki/Resources Sun Jan 31 00:46:29 2016 +0100
5.3 @@ -0,0 +1,104 @@
5.4 += Resources =
5.5 +
5.6 +In imip-agent, resources are a special kind of user that act upon requests
5.7 +to schedule events and that perform such scheduling autonomously, meaning
5.8 +that no human intervention is necessary when such resources receive messages
5.9 +containing invitations.
5.10 +
5.11 +By default, the [[../AgentPrograms|agent program]] responsible for resources
5.12 +merely attempts to fit a received event into the resource's schedule. However,
5.13 +in some organisations and environments, it is likely to be the case that other
5.14 +policies are needed to ensure that a resource is not misused, overused or made
5.15 +unnecessarily unavailable.
5.16 +
5.17 +The [[../Preferences|preferences]] provide a way of controlling the behaviour
5.18 +of resources, just as with any other kind of user, but certain preferences
5.19 +are central to the configuration of resources.
5.20 +
5.21 +<<TableOfContents(2,4)>>
5.22 +
5.23 +== Scheduling Functions ==
5.24 +
5.25 +The [[../Preferences#scheduling_function|scheduling_function]] setting
5.26 +indicates the behaviour of a resource when a valid request to schedule an
5.27 +event has been received. By default, a value equivalent to the following is
5.28 +employed:
5.29 +
5.30 +{{{
5.31 +schedule_in_freebusy
5.32 +}}}
5.33 +
5.34 +As described above, this merely attempts to schedule an event in the free
5.35 +periods of the resource's schedule. However, no attempt is made to reject the
5.36 +booking of the resource according to the identity of the organiser.
5.37 +
5.38 +=== Identity Controls ===
5.39 +
5.40 +Although identity controls may be implemented in the e-mail system,
5.41 +effectively preventing the messages from addresses other than those within
5.42 +an organisation (for example) from being delivered to the resource, it is
5.43 +possible to use scheduling functions to implement such controls instead.
5.44 +
5.45 +==== Same Domain Membership ====
5.46 +
5.47 +For instance, the following combines the default free/busy check with a
5.48 +test that the organiser belongs to the same Internet mail domain (by using
5.49 +the organiser's address):
5.50 +
5.51 +{{{
5.52 +schedule_in_freebusy
5.53 +same_domain_only
5.54 +}}}
5.55 +
5.56 +Note that if the first function is omitted, no check against the resource's
5.57 +schedule will occur, so it is necessary to mention any such function in the
5.58 +list.
5.59 +
5.60 +==== Access Control Lists ====
5.61 +
5.62 +A simple domain-related test may not be sufficient to control access to a
5.63 +resource. Thus, another function is provided to exercise a finer degree of
5.64 +control over event participants. For example:
5.65 +
5.66 +{{{
5.67 +schedule_in_freebusy
5.68 +access_control_list
5.69 +}}}
5.70 +
5.71 +To accompany this, the [[../Preferences#acl|acl]] setting in the
5.72 +resource's preferences must be set, or if a separate file is more appropriate,
5.73 +its full path may be given as an argument:
5.74 +
5.75 +{{{
5.76 +schedule_in_freebusy
5.77 +access_control_list /etc/imip-agent/resources.acl
5.78 +}}}
5.79 +
5.80 +Within the file provided by the setting or separate file, a list of rules
5.81 +must describe the handling procedure for an event. For example:
5.82 +
5.83 +{{{
5.84 +accept
5.85 +}}}
5.86 +
5.87 +This will merely accept all invitations, anyway. However, it may be
5.88 +appropriate to prevent certain users from using resources. For example:
5.89 +
5.90 +{{{
5.91 +accept
5.92 +decline attendee simon.skunk@example.com
5.93 +}}}
5.94 +
5.95 +This example indicates that by default, invitations will be accepted, but if
5.96 +one of the attendees of an event is `simon.skunk@example.com`, the invitation
5.97 +will be declined. However, it may be the case that this rule should be
5.98 +overridden under certain circumstances. For example:
5.99 +
5.100 +{{{
5.101 +accept
5.102 +decline attendee simon.skunk@example.com
5.103 +accept organiser paul.boddie@example.com
5.104 +}}}
5.105 +
5.106 +Here, the stated organiser may still arrange a booking of the resource where
5.107 +the previously-mentioned attendee is involved.