1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/docs/wiki/Resources	Sun Jan 31 00:46:29 2016 +0100
     1.3 @@ -0,0 +1,104 @@
     1.4 += Resources =
     1.5 +
     1.6 +In imip-agent, resources are a special kind of user that act upon requests
     1.7 +to schedule events and that perform such scheduling autonomously, meaning
     1.8 +that no human intervention is necessary when such resources receive messages
     1.9 +containing invitations.
    1.10 +
    1.11 +By default, the [[../AgentPrograms|agent program]] responsible for resources
    1.12 +merely attempts to fit a received event into the resource's schedule. However,
    1.13 +in some organisations and environments, it is likely to be the case that other
    1.14 +policies are needed to ensure that a resource is not misused, overused or made
    1.15 +unnecessarily unavailable.
    1.16 +
    1.17 +The [[../Preferences|preferences]] provide a way of controlling the behaviour
    1.18 +of resources, just as with any other kind of user, but certain preferences
    1.19 +are central to the configuration of resources.
    1.20 +
    1.21 +<<TableOfContents(2,4)>>
    1.22 +
    1.23 +== Scheduling Functions ==
    1.24 +
    1.25 +The [[../Preferences#scheduling_function|scheduling_function]] setting
    1.26 +indicates the behaviour of a resource when a valid request to schedule an
    1.27 +event has been received. By default, a value equivalent to the following is
    1.28 +employed:
    1.29 +
    1.30 +{{{
    1.31 +schedule_in_freebusy
    1.32 +}}}
    1.33 +
    1.34 +As described above, this merely attempts to schedule an event in the free
    1.35 +periods of the resource's schedule. However, no attempt is made to reject the
    1.36 +booking of the resource according to the identity of the organiser.
    1.37 +
    1.38 +=== Identity Controls ===
    1.39 +
    1.40 +Although identity controls may be implemented in the e-mail system,
    1.41 +effectively preventing the messages from addresses other than those within
    1.42 +an organisation (for example) from being delivered to the resource, it is
    1.43 +possible to use scheduling functions to implement such controls instead.
    1.44 +
    1.45 +==== Same Domain Membership ====
    1.46 +
    1.47 +For instance, the following combines the default free/busy check with a
    1.48 +test that the organiser belongs to the same Internet mail domain (by using
    1.49 +the organiser's address):
    1.50 +
    1.51 +{{{
    1.52 +schedule_in_freebusy
    1.53 +same_domain_only
    1.54 +}}}
    1.55 +
    1.56 +Note that if the first function is omitted, no check against the resource's
    1.57 +schedule will occur, so it is necessary to mention any such function in the
    1.58 +list.
    1.59 +
    1.60 +==== Access Control Lists ====
    1.61 +
    1.62 +A simple domain-related test may not be sufficient to control access to a
    1.63 +resource. Thus, another function is provided to exercise a finer degree of
    1.64 +control over event participants. For example:
    1.65 +
    1.66 +{{{
    1.67 +schedule_in_freebusy
    1.68 +access_control_list
    1.69 +}}}
    1.70 +
    1.71 +To accompany this, the [[../Preferences#acl|acl]] setting in the
    1.72 +resource's preferences must be set, or if a separate file is more appropriate,
    1.73 +its full path may be given as an argument:
    1.74 +
    1.75 +{{{
    1.76 +schedule_in_freebusy
    1.77 +access_control_list /etc/imip-agent/resources.acl
    1.78 +}}}
    1.79 +
    1.80 +Within the file provided by the setting or separate file, a list of rules
    1.81 +must describe the handling procedure for an event. For example:
    1.82 +
    1.83 +{{{
    1.84 +accept
    1.85 +}}}
    1.86 +
    1.87 +This will merely accept all invitations, anyway. However, it may be
    1.88 +appropriate to prevent certain users from using resources. For example:
    1.89 +
    1.90 +{{{
    1.91 +accept
    1.92 +decline attendee simon.skunk@example.com
    1.93 +}}}
    1.94 +
    1.95 +This example indicates that by default, invitations will be accepted, but if
    1.96 +one of the attendees of an event is `simon.skunk@example.com`, the invitation
    1.97 +will be declined. However, it may be the case that this rule should be
    1.98 +overridden under certain circumstances. For example:
    1.99 +
   1.100 +{{{
   1.101 +accept
   1.102 +decline attendee simon.skunk@example.com
   1.103 +accept organiser paul.boddie@example.com
   1.104 +}}}
   1.105 +
   1.106 +Here, the stated organiser may still arrange a booking of the resource where
   1.107 +the previously-mentioned attendee is involved.