1.1 --- a/docs/wiki/Resources Sun Feb 07 23:35:20 2016 +0100
1.2 +++ b/docs/wiki/Resources Mon Feb 08 00:14:53 2016 +0100
1.3 @@ -17,6 +17,92 @@
1.4
1.5 <<TableOfContents(2,4)>>
1.6
1.7 +== Confirmation and Retraction Functions ==
1.8 +
1.9 +Confirmation and retraction functions are used to update other resources and
1.10 +systems with the details of scheduled events. When an event is successfully
1.11 +scheduled (according to the scheduling functions), all registered confirmation
1.12 +functions are invoked to perform such notifications. Similarly, when an event
1.13 +is cancelled, all registered retraction functions are invoked to inform other
1.14 +components of the removal of the event from schedules.
1.15 +
1.16 +The [[../Preferences#confirmation_function|confirmation_function]] and
1.17 +[[../Preferences#retraction_function|retraction_function]] settings indicate
1.18 +the behaviour of a resource when such circumstances arise. By themselves,
1.19 +these settings do no more than keep a kind of journal of scheduling events,
1.20 +but certain scheduling functions may build upon such journals to make
1.21 +scheduling decisions. For example:
1.22 +
1.23 +{{{{#!table
1.24 +'''All Functions''' || '''Decision Process'''
1.25 +==
1.26 +<style="vertical-align: top;">
1.27 +
1.28 +Scheduling functions:
1.29 +
1.30 +{{{
1.31 +check_quota
1.32 +}}}
1.33 +
1.34 +Confirmation functions:
1.35 +
1.36 +{{{
1.37 +add_to_quota
1.38 +}}}
1.39 +
1.40 +Retraction functions:
1.41 +
1.42 +{{{
1.43 +remove_from_quota
1.44 +}}}
1.45 +
1.46 +||
1.47 +
1.48 +{{{#!graphviz
1.49 +//format=svg
1.50 +//transform=notugly
1.51 +digraph scheduling_decisions {
1.52 + node [shape=box,fontsize="13.0",fontname="Helvetica",tooltip="Scheduling decisions"];
1.53 + edge [tooltip="Scheduling decisions"];
1.54 +
1.55 + subgraph {
1.56 + rank=same;
1.57 + mail [label="Incoming mail\nfrom vincent.vole@example.com",shape=folder,style=filled,fillcolor=cyan];
1.58 + cancel [label="Incoming cancellation",shape=folder,style=filled,fillcolor=cyan];
1.59 + }
1.60 +
1.61 + subgraph {
1.62 + rank=same;
1.63 + check_quota [label="Is allowed by quota?",shape=ellipse,style=filled,fillcolor=gold];
1.64 + quota [label="Quota for resource",shape=folder];
1.65 + quota_for_vole [label="...applying to\nvincent.vole@example.com",shape=folder];
1.66 + }
1.67 +
1.68 + schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
1.69 +
1.70 + subgraph {
1.71 + rank=same;
1.72 + accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.73 + decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.74 + }
1.75 +
1.76 + add_to_quota [label="Add to quota",shape=ellipse,style=filled,fillcolor=darkorange];
1.77 + remove_from_quota [label="Remove from quota",shape=ellipse,style=filled,fillcolor=darkorange];
1.78 +
1.79 + mail -> check_quota -> schedule -> accept;
1.80 + check_quota -> decline [style=dashed];
1.81 + schedule -> add_to_quota -> quota;
1.82 + quota -> quota_for_vole -> check_quota;
1.83 +
1.84 + cancel -> remove_from_quota -> quota;
1.85 +}
1.86 +}}}
1.87 +
1.88 +}}}}
1.89 +
1.90 +See the [[#Quota_Controls|quota controls]] documentation for more information
1.91 +about applying quotas to resources.
1.92 +
1.93 == Scheduling Functions ==
1.94
1.95 The [[../Preferences#scheduling_function|scheduling_function]] setting
1.96 @@ -51,8 +137,12 @@
1.97 }
1.98
1.99 schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
1.100 - accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.101 - decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.102 +
1.103 + subgraph {
1.104 + rank=same;
1.105 + accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.106 + decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.107 + }
1.108
1.109 mail -> schedule_in_freebusy -> schedule -> accept;
1.110 schedule_in_freebusy -> decline [style=dashed];
1.111 @@ -109,8 +199,12 @@
1.112 same_domain_only [label="Organiser has resource domain?",shape=ellipse,style=filled,fillcolor=gold];
1.113
1.114 schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
1.115 - accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.116 - decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.117 +
1.118 + subgraph {
1.119 + rank=same;
1.120 + accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.121 + decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.122 + }
1.123
1.124 mail -> schedule_in_freebusy -> same_domain_only -> schedule -> accept;
1.125 schedule_in_freebusy -> decline [style=dashed];
1.126 @@ -174,8 +268,12 @@
1.127 end_acl [label="end",shape=ellipse,style=filled,fillcolor=darkorange];
1.128
1.129 schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
1.130 - accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.131 - decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.132 +
1.133 + subgraph {
1.134 + rank=same;
1.135 + accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.136 + decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.137 + }
1.138
1.139 mail -> schedule_in_freebusy -> access_control_list -> accept_default -> end_acl -> schedule -> accept;
1.140 end_acl -> decline [style=dashed];
1.141 @@ -252,8 +350,12 @@
1.142 end_acl [label="end",shape=ellipse,style=filled,fillcolor=darkorange];
1.143
1.144 schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
1.145 - accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.146 - decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.147 +
1.148 + subgraph {
1.149 + rank=same;
1.150 + accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.151 + decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.152 + }
1.153
1.154 mail -> schedule_in_freebusy -> access_control_list -> accept_default -> decline_attendee -> end_acl -> schedule -> accept;
1.155 end_acl -> decline [style=dashed];
1.156 @@ -317,8 +419,12 @@
1.157 end_acl [label="end",shape=ellipse,style=filled,fillcolor=darkorange];
1.158
1.159 schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
1.160 - accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.161 - decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.162 +
1.163 + subgraph {
1.164 + rank=same;
1.165 + accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.166 + decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.167 + }
1.168
1.169 mail -> schedule_in_freebusy -> access_control_list -> accept_default -> decline_attendee -> accept_organiser -> end_acl -> schedule -> accept;
1.170 end_acl -> decline [style=dashed];
1.171 @@ -332,3 +438,243 @@
1.172
1.173 Here, the stated organiser may still arrange a booking of the resource where
1.174 the previously-mentioned attendee is involved.
1.175 +
1.176 +=== Quota Controls ===
1.177 +
1.178 +The [[#Confirmation_and_Retraction_Functions|confirmation and retraction functions]]
1.179 +section provides an example of applying quotas to event participants. However,
1.180 +this section describes the operation of the quota system in more detail.
1.181 +
1.182 +In contrast to each user's stored information which consolidates information
1.183 +related to that user's own schedule, the quota system consolidates information
1.184 +related to the schedules of one or more resources, thus enabling observations
1.185 +to be made about their collective usage.
1.186 +
1.187 +First, consider a resource such as a car where an organiser of an event may be
1.188 +booking the car for travel purposes. A quota prevents the organiser from
1.189 +booking the resource too much and denying other users access to it.
1.190 +
1.191 +Now consider a number of separate car resources. An organiser might attempt to
1.192 +get around any individual resource quota by booking a number of different cars.
1.193 +By grouping the resources together, the organiser will exhaust a quota set on
1.194 +the group of resources as reservations are made for the different members of
1.195 +the group.
1.196 +
1.197 +==== Initialising Quotas ====
1.198 +
1.199 +Within the journal storage area (described in the [[../FilesystemUsage|filesystem guide]]),
1.200 +a quota group directory must be initialised with a `limits` file indicating
1.201 +the amount of time that can be occupied by the cumulative total of all events
1.202 +scheduled by an individual user or a group of which they are a member. For
1.203 +example:
1.204 +
1.205 +{{{
1.206 +mailto:vincent.vole@example.com PT10H
1.207 +}}}
1.208 +
1.209 +This indicates that the given user may only reserve 10 hours of events or less.
1.210 +Attempts to schedule more time will be declined.
1.211 +
1.212 +To impose a general quota, the special `*` identity can be used:
1.213 +
1.214 +{{{
1.215 +* PT10H
1.216 +}}}
1.217 +
1.218 +When a user identity is not listed and no general quota is defined, that
1.219 +particular user will be unable to reserve the resource unless defined as a
1.220 +member of a group listed in the `limits` file, as described below.
1.221 +
1.222 +==== Sharing Quotas Across Users ====
1.223 +
1.224 +When the use of resources is to be shared between users in such a way that
1.225 +groups of users will be sharing a single quota, the `groups` file in the
1.226 +quota directory must be defined, mapping each user identity to the group to
1.227 +which they will belong. For example:
1.228 +
1.229 +{{{
1.230 +mailto:vincent.vole@example.com developers
1.231 +mailto:harvey.horse@example.com developers
1.232 +mailto:paul.boddie@example.com developers
1.233 +mailto:simon.skunk@example.com testers
1.234 +}}}
1.235 +
1.236 +The group identity can then be employed in the `limits` file:
1.237 +
1.238 +{{{
1.239 +developers PT10H
1.240 +testers PT20H
1.241 +}}}
1.242 +
1.243 +Limits apply to individuals, then to groups, then the general quota applies.
1.244 +Thus, when a group is not listed, the general quota applies; without a general
1.245 +quota (and without matching individually), a group member will be unable to
1.246 +reserve the resource.
1.247 +
1.248 +==== Individual Resource Quotas ====
1.249 +
1.250 +The trivial case of applying quotas is to give a resource its own quota. This
1.251 +is achieved by not specifying any arguments to the `check_quota` scheduling
1.252 +function or to the `add_to_quota` and `remove_from_quota` functions. See the
1.253 +[[#Confirmation_and_Retraction_Functions|confirmation and retraction functions]]
1.254 +section for an example of this.
1.255 +
1.256 +==== Common Resource Quotas ====
1.257 +
1.258 +By indicating an argument to the different functions, a common quota can be
1.259 +employed. In the following example, both resources would employ the given
1.260 +function invocations to pool their knowledge about their schedules.
1.261 +
1.262 +{{{{#!table
1.263 +'''All Functions''' || '''Decision Process'''
1.264 +==
1.265 +<style="vertical-align: top;">
1.266 +
1.267 +Scheduling functions:
1.268 +
1.269 +{{{
1.270 +check_quota cars
1.271 +}}}
1.272 +
1.273 +Confirmation functions:
1.274 +
1.275 +{{{
1.276 +add_to_quota cars
1.277 +}}}
1.278 +
1.279 +Retraction functions:
1.280 +
1.281 +{{{
1.282 +remove_from_quota cars
1.283 +}}}
1.284 +
1.285 +||
1.286 +
1.287 +{{{#!graphviz
1.288 +//format=svg
1.289 +//transform=notugly
1.290 +digraph scheduling_decisions {
1.291 + node [shape=box,fontsize="13.0",fontname="Helvetica",tooltip="Scheduling decisions"];
1.292 + edge [tooltip="Scheduling decisions"];
1.293 +
1.294 + subgraph {
1.295 + rank=same;
1.296 + mail_cadillac [label="Incoming mail\nfrom vincent.vole@example.com\nto resource-car-cadillac@example.com",shape=folder,style=filled,fillcolor=cyan];
1.297 + mail_pontiac [label="Incoming mail\nfrom vincent.vole@example.com\nto resource-car-pontiac@example.com",shape=folder,style=filled,fillcolor=cyan];
1.298 + cancel [label="Incoming cancellation",shape=folder,style=filled,fillcolor=cyan];
1.299 + }
1.300 +
1.301 + subgraph {
1.302 + rank=same;
1.303 + check_quota [label="Is allowed by quota?",shape=ellipse,style=filled,fillcolor=gold];
1.304 + quota_cars [label="Quota for cars",shape=folder];
1.305 + quota_cars_vole [label="...applying to\nvincent.vole@example.com",shape=folder];
1.306 + }
1.307 +
1.308 + schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
1.309 +
1.310 + subgraph {
1.311 + rank=same;
1.312 + accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.313 + decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.314 + }
1.315 +
1.316 + add_to_quota [label="Add to quota",shape=ellipse,style=filled,fillcolor=darkorange];
1.317 + remove_from_quota [label="Remove from quota",shape=ellipse,style=filled,fillcolor=darkorange];
1.318 +
1.319 + mail_cadillac -> check_quota;
1.320 + mail_pontiac -> check_quota -> schedule -> accept;
1.321 + check_quota -> decline [style=dashed];
1.322 + schedule -> add_to_quota -> quota_cars;
1.323 + quota_cars -> quota_cars_vole -> check_quota;
1.324 +
1.325 + cancel -> remove_from_quota -> quota_cars;
1.326 +}
1.327 +}}}
1.328 +
1.329 +}}}}
1.330 +
1.331 +==== Collective Scheduling ====
1.332 +
1.333 +Consider two separate resources: both may be reserved at the same time by the
1.334 +same organiser; neither resource would normally decline the reservation on the
1.335 +basis of schedule availability, should the period concerned be free. However,
1.336 +it may be undesirable for one organiser to occupy both resources at the same
1.337 +time.
1.338 +
1.339 +Consequently, a mechanism is required to pool the resource schedules in such a
1.340 +way that any reservation performed for one resource at a given point in time
1.341 +prohibits another reservation performed for a related resource at the same
1.342 +point in time by the same user.
1.343 +
1.344 +The free/busy records held for a given quota group permit such collective
1.345 +scheduling decisions and are employed as follows:
1.346 +
1.347 +{{{{#!table
1.348 +'''All Functions''' || '''Decision Process'''
1.349 +==
1.350 +<style="vertical-align: top;">
1.351 +
1.352 +Scheduling functions:
1.353 +
1.354 +{{{
1.355 +schedule_within_quota cars
1.356 +}}}
1.357 +
1.358 +Confirmation functions:
1.359 +
1.360 +{{{
1.361 +add_to_quota_freebusy cars
1.362 +}}}
1.363 +
1.364 +Retraction functions:
1.365 +
1.366 +{{{
1.367 +remove_from_quota_freebusy cars
1.368 +}}}
1.369 +
1.370 +||
1.371 +
1.372 +{{{#!graphviz
1.373 +//format=svg
1.374 +//transform=notugly
1.375 +digraph scheduling_decisions {
1.376 + node [shape=box,fontsize="13.0",fontname="Helvetica",tooltip="Scheduling decisions"];
1.377 + edge [tooltip="Scheduling decisions"];
1.378 +
1.379 + subgraph {
1.380 + rank=same;
1.381 + mail_cadillac [label="Incoming mail\nfrom vincent.vole@example.com\nto resource-car-cadillac@example.com",shape=folder,style=filled,fillcolor=cyan];
1.382 + mail_pontiac [label="Incoming mail\nfrom vincent.vole@example.com\nto resource-car-pontiac@example.com",shape=folder,style=filled,fillcolor=cyan];
1.383 + cancel [label="Incoming cancellation",shape=folder,style=filled,fillcolor=cyan];
1.384 + }
1.385 +
1.386 + subgraph {
1.387 + rank=same;
1.388 + schedule_across_quota [label="Can be scheduled within the quota?",shape=ellipse,style=filled,fillcolor=gold];
1.389 + quota_cars [label="Quota for cars",shape=folder];
1.390 + freebusy_cars_vole [label="...recording schedule for\nvincent.vole@example.com",shape=folder];
1.391 + }
1.392 +
1.393 + schedule [label="Schedule event for resource",shape=ellipse,style=filled,fillcolor=gold];
1.394 +
1.395 + subgraph {
1.396 + rank=same;
1.397 + accept [label="Accept",shape=folder,style=filled,fillcolor=cyan];
1.398 + decline [label="Decline",shape=folder,style=filled,fillcolor=cyan];
1.399 + }
1.400 +
1.401 + add_to_quota_freebusy [label="Add to quota free/busy",shape=ellipse,style=filled,fillcolor=darkorange];
1.402 + remove_from_quota_freebusy [label="Remove from quota free/busy",shape=ellipse,style=filled,fillcolor=darkorange];
1.403 +
1.404 + mail_cadillac -> schedule_across_quota;
1.405 + mail_pontiac -> schedule_across_quota -> schedule -> accept;
1.406 + schedule_across_quota -> decline [style=dashed];
1.407 + schedule -> add_to_quota_freebusy -> quota_cars -> freebusy_cars_vole;
1.408 + freebusy_cars_vole -> schedule_across_quota;
1.409 +
1.410 + cancel -> remove_from_quota_freebusy -> freebusy_cars_vole;
1.411 +}
1.412 +}}}
1.413 +
1.414 +}}}}