imip-agent

Annotated docs/wiki/Preferences

1042:865aaba26b24
1039:a12150034cbd
1032:abbfbee0f858
2016-02-08 Paul Boddie file changeset files shortlog Added a journal storage area, maintaining quota and collective scheduling data for scheduling decisions. Introduced confirmation and retraction functions for resource scheduling so that quotas and collective schedules can be maintained and thus queried by scheduling functions. Updated the documentation, tools and tests.
paul@961 1 
= Preferences =
paul@961 2 
 
 paul@961      3 
The correspondence between user preferences (stored in user preference
 
 paul@961      4 
directories) and the default settings (stored in `config.py`) is described
 
 paul@961      5 
below.
 
 paul@961      6 
 
 paul@961      7 
|| '''Preference'''        || '''Default Setting''' ||
 
 paul@961      8 
|| `LANG`                  || `LANG` ||
 
 paul@961      9 
|| `add_method_response`   || `ADD_RESPONSE_DEFAULT` ||
 
 paul@961     10 
|| `event_refreshing`      || `REFRESHING_DEFAULT` ||
 
 paul@961     11 
|| `freebusy_bundling`     || `BUNDLING_DEFAULT` ||
 
 paul@961     12 
|| `freebusy_messages`     || `NOTIFYING_DEFAULT` ||
 
 paul@961     13 
|| `freebusy_offers`       || `FREEBUSY_OFFER_DEFAULT` ||
 
 paul@961     14 
|| `freebusy_publishing`   || `PUBLISHING_DEFAULT` ||
 
 paul@961     15 
|| `freebusy_sharing`      || `SHARING_DEFAULT` ||
 
 paul@961     16 
|| `incoming`              || `INCOMING_DEFAULT` ||
 
 paul@961     17 
|| `organiser_replacement` || `ORGANISER_REPLACEMENT_DEFAULT` ||
 
 paul@961     18 
|| `participating`         || `PARTICIPATING_DEFAULT` ||
 
 paul@961     19 
 
 paul@961     20 
See the [[../Configuration|configuration guide]] for more information about
 
 paul@961     21 
the `config.py` file.
 
 paul@961     22 
 
 paul@961     23 
== User Preference Settings ==
 
 paul@961     24 
 
 paul@961     25 
<<TableOfContents(3,3)>>
 
 paul@961     26 
 
 paul@961     27 
Each of the user preferences or settings are stored in a separate file within
 
 paul@961     28 
a dedicated preferences directory for each user, with the filename bearing the
 
 paul@988     29 
name of the setting concerned. See the [[../FilesystemUsage|filesystem guide]]
 
 paul@988     30 
for more information.
 
 paul@961     31 
 
 paul@961     32 
=== CN ===
 
 paul@961     33 
 
 paul@961     34 
 Default:: (none)
 
 paul@961     35 
 Alternatives:: (see below)
 
 paul@961     36 
 
 paul@961     37 
The common name of the user, employed in iCalendar objects and user
 
 paul@961     38 
interfaces.
 
 paul@961     39 
 
 paul@961     40 
=== LANG ===
 
 paul@961     41 
 
 paul@961     42 
 Default:: `en` (English)
 
 paul@961     43 
 Alternatives:: (any recognised and supported locale)
 
 paul@961     44 
 
 paul@961     45 
The language for messages and user interface text.
 
 paul@961     46 
 
 paul@961     47 
=== TZID ===
 
 paul@961     48 
 
 paul@961     49 
 Default:: system timezone (see `/etc/timezone`)
 
 paul@961     50 
 Alternatives:: (any recognised Olson time zone identifier)
 
 paul@961     51 
 
 paul@961     52 
The default time zone/regime for calendars, new events and local times.
 
 paul@961     53 
 
 paul@1032     54 
=== acl ===
 
 paul@1032     55 
 
 paul@1032     56 
 Default:: (none)
 
 paul@1032     57 
 Alternatives:: (see below)
 
 paul@1032     58 
 
 paul@1032     59 
Provides an access control list for the `access_control_list` scheduling
 
 paul@1032     60 
function, invoked using the `scheduling_functions` setting. An access control
 
 paul@1032     61 
list consists of a collection of lines of text describing the handling policy
 
 paul@1032     62 
for an incoming invitation.
 
 paul@1032     63 
 
 paul@1032     64 
{{{#!table
 
 paul@1032     65 
`accept` || indicates that if no rule matches, the invitation will be accepted
 
 paul@1032     66 
         .. (provisionally)
 
 paul@1032     67 
==
 
 paul@1032     68 
`decline` ||<rowspan="2"> indicates that if no rule matches, the invitation
 
 paul@1032     69 
                       .. will be declined (provisionally)
 
 paul@1032     70 
==
 
 paul@1032     71 
`reject`
 
 paul@1032     72 
==
 
 paul@1032     73 
`accept` ''`role`'' ''`identity`'' || indicates that where the given
 
 paul@1032     74 
                                   .. ''`identity`'' exists in the given
 
 paul@1032     75 
         .. ''`role`'' in the event, and unless a subsequent rule contradicts
 
 paul@1032     76 
         .. this result, the invitation will be accepted (provisionally)
 
 paul@1032     77 
==
 
 paul@1032     78 
`decline` ''`role`'' ''`identity`'' ||<rowspan="2"> indicates that where the
 
 paul@1032     79 
                                                 .. given ''`identity`'' exists
 
 paul@1032     80 
         .. in the given ''`role`'' in the event, and unless a subsequent rule
 
 paul@1032     81 
         .. contradicts this result, the invitation will be declined
 
 paul@1032     82 
         .. (provisionally)
 
 paul@1032     83 
 
 paul@1032     84 
==
 
 paul@1032     85 
`reject` ''`role`'' ''`identity`''
 
 paul@1032     86 
}}}
 
 paul@1032     87 
 
 paul@1032     88 
In the above, `role` is either `organiser` (or `organizer`) or `attendee`;
 
 paul@1032     89 
`identity` is an address or URL.
 
 paul@1032     90 
 
 paul@1032     91 
Note that even if an accepted result is returned by the `access_control_list`
 
 paul@1032     92 
scheduling function, other functions that follow it in the list of functions
 
 paul@1032     93 
may overturn this result.
 
 paul@1032     94 
 
 paul@1032     95 
See the [[../Resources|resources guide]] for examples and more information.
 
 paul@1032     96 
 
 paul@961     97 
=== add_method_response ===
 
 paul@961     98 
 
 paul@961     99 
 Default:: `refresh`
 
 paul@961    100 
 Alternatives:: (see below)
 
 paul@961    101 
 
 paul@961    102 
Indicate how `ADD` methods shall be responded to when received by a recipient:
 
 paul@961    103 
 
 paul@961    104 
{{{#!table
 
 paul@961    105 
`add`     || apply them to events as received
 
 paul@961    106 
==
 
 paul@961    107 
`ignore`  || ignore attempts to add event occurrences
 
 paul@961    108 
==
 
 paul@961    109 
`refresh` || respond with a `REFRESH` message to obtain a proper request with
 
 paul@961    110 
          .. all event details
 
 paul@961    111 
}}}
 
 paul@961    112 
 
 paul@1039    113 
=== confirmation_function ===
 
 paul@1039    114 
 
 paul@1039    115 
 Default:: (none)
 
 paul@1039    116 
 Alternatives:: (see below)
 
 paul@1039    117 
 
 paul@1039    118 
Indicates the confirmation functions used by [[../Resources|resources]] to be
 
 paul@1039    119 
invoked when an event is scheduled. Such functions support certain scheduling
 
 paul@1039    120 
functions that require a record of scheduling activity.
 
 paul@1039    121 
 
 paul@1039    122 
The `imiptools.handlers.scheduling` module contains the built-in confirmation
 
 paul@1039    123 
functions which include the following:
 
 paul@1039    124 
 
 paul@1039    125 
{{{#!table
 
 paul@1039    126 
`add_to_quota`         || add the details of an event to quota records
 
 paul@1039    127 
}}}
 
 paul@1039    128 
 
 paul@1039    129 
See also `retraction_function` and `scheduling_function`.
 
 paul@1039    130 
 
 paul@961    131 
=== event_refreshing ===
 
 paul@961    132 
 
 paul@961    133 
 Default:: `never`
 
 paul@961    134 
 Alternative:: `always`
 
 paul@961    135 
 
 paul@961    136 
Indicate whether messages requesting a refresh of event details shall be
 
 paul@961    137 
handled automatically. If not, such messages will be passed on to the
 
 paul@961    138 
recipient for their mail program to handle.
 
 paul@961    139 
 
 paul@961    140 
=== freebusy_bundling ===
 
 paul@961    141 
 
 paul@961    142 
 Default:: `never`
 
 paul@961    143 
 Alternative:: `always`
 
 paul@961    144 
 
 paul@961    145 
Indicate whether to bundle free/busy details with other payloads such as
 
 paul@961    146 
event and free/busy objects. The `freebusy_sharing` setting must be
 
 paul@961    147 
configured for bundling to operate.
 
 paul@961    148 
 
 paul@961    149 
=== freebusy_messages ===
 
 paul@961    150 
 
 paul@961    151 
 Default:: `none`
 
 paul@961    152 
 Alternative:: `notify`
 
 paul@961    153 
 
 paul@961    154 
Indicate whether recipients are notified about received free/busy payloads.
 
 paul@961    155 
 
 paul@961    156 
=== freebusy_offers ===
 
 paul@961    157 
 
 paul@961    158 
 Default:: (none)
 
 paul@961    159 
 Alternative:: (see below)
 
 paul@961    160 
 
 paul@961    161 
Define the period for which free/busy offers are extended by participants
 
 paul@961    162 
supporting this setting when counter-proposals are made during event
 
 paul@961    163 
scheduling.
 
 paul@961    164 
 
 paul@961    165 
This setting requires a value indicating a duration as described in the
 
 paul@961    166 
iCalendar format specification:
 
 paul@961    167 
 
 paul@961    168 
http://tools.ietf.org/html/rfc5545#section-3.3.6
 
 paul@961    169 
 
 paul@961    170 
For example:
 
 paul@961    171 
 
 paul@961    172 
|| `PT10M`  || extend scheduling offers for 10 minutes ||
 
 paul@961    173 
|| `PT600S` || extend scheduling offers for 600 seconds (10 minutes) ||
 
 paul@961    174 
|| `PT1D`   || extend offers for 1 day ||
 
 paul@961    175 
 
 paul@961    176 
=== freebusy_publishing ===
 
 paul@961    177 
 
 paul@961    178 
 Default:: `no`
 
 paul@961    179 
 Alternative:: `publish`
 
 paul@961    180 
 
 paul@961    181 
Indicate whether to publish free/busy details as Web resources. The
 
 paul@961    182 
`freebusy_sharing` setting must be configured for publishing to operate.
 
 paul@961    183 
 
 paul@961    184 
=== freebusy_sharing ===
 
 paul@961    185 
 
 paul@961    186 
 Default:: `no`
 
 paul@961    187 
 Alternative:: `share`
 
 paul@961    188 
 
 paul@961    189 
Share free/busy details generally:
 
 paul@961    190 
 
 paul@961    191 
  * bundling in e-mail messages if bundling is configured
 
 paul@961    192 
  * responding to free/busy requests via e-mail
 
 paul@961    193 
  * publishing as Web resources if a static Web resource is configured and if
 
 paul@961    194 
  publishing is configured
 
 paul@961    195 
 
 paul@961    196 
=== incoming ===
 
 paul@961    197 
 
 paul@961    198 
 Default:: `summary-wraps-message`
 
 paul@961    199 
 Alternatives:: (see below)
 
 paul@961    200 
 
 paul@961    201 
Define how incoming event messages are delivered to recipients:
 
 paul@961    202 
 
 paul@961    203 
{{{#!table
 
 paul@961    204 
`message-only`
 
 paul@961    205 
|| deliver only the incoming message as it was received
 
 paul@961    206 
==
 
 paul@961    207 
`message-then-summary`
 
 paul@961    208 
|| deliver the message first followed by a summary message
 
 paul@961    209 
==
 
 paul@961    210 
`summary-then-message`
 
 paul@961    211 
|| deliver a summary first followed by the message
 
 paul@961    212 
==
 
 paul@961    213 
`summary-only`
 
 paul@961    214 
|| deliver only a summary of the message
 
 paul@961    215 
==
 
 paul@961    216 
`summary-wraps-message`
 
 paul@961    217 
|| deliver a summary that includes the original message as an attachment
 
 paul@961    218 
}}}
 
 paul@961    219 
 
 paul@961    220 
=== organiser_replacement ===
 
 paul@961    221 
 
 paul@961    222 
 Default:: `attendee`
 
 paul@961    223 
 Alternatives:: (see below)
 
 paul@961    224 
 
 paul@961    225 
Indicate whether the organiser of an event can be replaced and the nature of
 
 paul@961    226 
any replacement:
 
 paul@961    227 
 
 paul@961    228 
{{{#!table
 
 paul@961    229 
`any` || any identity, regardless of whether it is already present or even
 
 paul@961    230 
      .. previously unknown, may become the organiser
 
 paul@961    231 
==
 
 paul@961    232 
`attendee` || any new organiser must be a previously-recognised attendee
 
 paul@961    233 
==
 
 paul@961    234 
`never` || forbid the replacement of an event's organiser
 
 paul@961    235 
}}}
 
 paul@961    236 
 
 paul@961    237 
=== participating ===
 
 paul@961    238 
 
 paul@961    239 
 Default:: `participate`
 
 paul@961    240 
 Alternative:: `no`
 
 paul@961    241 
 
 paul@961    242 
Indicate whether a recipient participates in the calendar system. Note that
 
 paul@961    243 
participation by default occurs because the handler programs will be defined
 
 paul@961    244 
in the mail system for recipients fulfilling certain criteria; other
 
 paul@961    245 
recipients will be handled in other ways. Thus, initial non-participation must
 
 paul@961    246 
be defined by initialising this setting to "no" for all eligible users, if
 
 paul@961    247 
this is the general policy on initial calendar system participation.
 
 paul@961    248 
 
 paul@961    249 
=== permitted_times ===
 
 paul@961    250 
 
 paul@961    251 
 Default:: (none)
 
 paul@961    252 
 Alternatives:: (see below)
 
 paul@961    253 
 
 paul@961    254 
Define the time values at which events can be scheduled. In its simplest form,
 
 paul@961    255 
this indicates the resolution of a calendar for a participant supporting this
 
 paul@961    256 
setting, with the given minute values being those allowed for the start and
 
 paul@961    257 
end of an event. This setting requires a value of one of the following forms:
 
 paul@961    258 
 
 paul@961    259 
{{{
 
 paul@961    260 
<minute values>
 
 paul@961    261 
<hour values>:<minute values>
 
 paul@961    262 
<hour values>:<minute values>:<second values>
 
 paul@961    263 
}}}
 
 paul@961    264 
 
 paul@961    265 
Each list of values is a comma-separated collection of permissible values for
 
 paul@961    266 
the unit of time being constrained. Any unspecified list is taken to permit
 
 paul@961    267 
all normally permissible values for that unit of time. For example:
 
 paul@961    268 
 
 paul@961    269 
{{{#!table
 
 paul@961    270 
`0,15,30,45`          || every 15 minutes from the start of each hour
 
 paul@961    271 
==
 
 paul@961    272 
`10,12,14,16:0,20,40` || every 20 minutes from 10:00 until 16:40 inclusive
 
 paul@961    273 
==
 
 paul@961    274 
`12::0,30`            ||  every 30 seconds from the start of each minute
 
 paul@961    275 
                      .. during the period from 12:00:00 until 12:59:30
 
 paul@961    276 
                      .. inclusive
 
 paul@961    277 
}}}
 
 paul@961    278 
 
 paul@961    279 
The purpose of this setting is not necessarily to impose availability
 
 paul@961    280 
constraints but instead to impose a "grid" to which event start and end points
 
 paul@961    281 
shall be "locked".
 
 paul@961    282 
 
 paul@961    283 
The values are interpreted in the local time of the participant. Thus, a time
 
 paul@961    284 
represented in UTC may have apparently inappropriate hour (and for some zones)
 
 paul@961    285 
minute values that correspond to permitted values in this participant's own
 
 paul@961    286 
time zone.
 
 paul@961    287 
 
 paul@1039    288 
=== retraction_function ===
 
 paul@1039    289 
 
 paul@1039    290 
 Default:: (none)
 
 paul@1039    291 
 Alternatives:: (see below)
 
 paul@1039    292 
 
 paul@1039    293 
Indicates the retraction functions used by [[../Resources|resources]] to be
 
 paul@1039    294 
invoked when an event is cancelled. Such functions support certain scheduling
 
 paul@1039    295 
functions that require a record of scheduling activity.
 
 paul@1039    296 
 
 paul@1039    297 
The `imiptools.handlers.scheduling` module contains the built-in retraction
 
 paul@1039    298 
functions which include the following:
 
 paul@1039    299 
 
 paul@1039    300 
{{{#!table
 
 paul@1039    301 
`remove_from_quota`    || remove the details of an event from quota records
 
 paul@1039    302 
}}}
 
 paul@1039    303 
 
 paul@1039    304 
See also `confirmation_function` and `scheduling_function`.
 
 paul@1039    305 
 
 paul@961    306 
=== scheduling_function ===
 
 paul@961    307 
 
 paul@961    308 
 Default:: `schedule_in_freebusy`
 
 paul@961    309 
 Alternatives:: (see below)
 
 paul@961    310 
 
 paul@1032    311 
Indicates the scheduling functions used by [[../Resources|resources]] to find
 
 paul@1032    312 
an appropriate period for an event, with each function to be applied to a
 
 paul@1032    313 
scheduling request appearing on a separate line, optionally accompanied by
 
 paul@1032    314 
arguments controlling the behaviour of the function.
 
 paul@1025    315 
 
 paul@1039    316 
The `imiptools.handlers.scheduling` module contains the built-in scheduling
 
 paul@1025    317 
functions which include the following:
 
 paul@961    318 
 
 paul@961    319 
{{{#!table
 
 paul@1032    320 
`access_control_list`  || use an access control list provided by a file whose
 
 paul@1032    321 
                       .. name is given as an argument, accepting or declining
 
 paul@1032    322 
                       .. the invitation according to the indicated rules
 
 paul@1032    323 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1032    324 
==
 
 paul@1039    325 
`check_quota`          || accept an invitation only if the organiser does not
 
 paul@1039    326 
                       .. exceed their quota allowance for bookings
 
 paul@1039    327 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1039    328 
==
 
 paul@1032    329 
`same_domain_only`     || accept an invitation only if the organiser employs an
 
 paul@1032    330 
                       .. address in the same domain as the resource
 
 paul@1030    331 
==
 
 paul@961    332 
`schedule_in_freebusy` || accept an invitation if the event periods are free
 
 paul@961    333 
                       .. according to the free/busy records for the resource;
 
 paul@961    334 
                       .. decline otherwise
 
 paul@961    335 
==
 
 paul@961    336 
`schedule_corrected_in_freebusy` || correct periods in an event according to
 
 paul@961    337 
                                 .. the permitted_times setting (see above),
 
 paul@961    338 
                       .. then attempt to schedule the event according to the
 
 paul@961    339 
                       .. free/busy records for the resource
 
 paul@961    340 
==
 
 paul@961    341 
`schedule_next_available_in_freebusy` || correct periods in an event according
 
 paul@961    342 
                                      .. to the permitted_times setting (see
 
 paul@961    343 
                       .. above), if configured, and attempt to schedule the
 
 paul@961    344 
                       .. event according to the free/busy records for the
 
 paul@961    345 
                       .. resource and for any attendees for whom records are
 
 paul@961    346 
                       .. available, seeking the next available free period for
 
 paul@961    347 
                       .. each period that conflicts with an existing event
 
 paul@961    348 
}}}
 
 paul@961    349 
 
 paul@961    350 
The scheduling mechanism can be extended by implementing additional scheduling
 
 paul@961    351 
functions or by extending the handler framework directly.
 
 paul@1039    352 
 
 paul@1039    353 
See also `confirmation_function` and `retraction_function`.