imip-agent

Annotated docs/wiki/Preferences

1058:bb1b8e13ef4d
1053:068aa85f0c45
1042:865aaba26b24
2016-02-08 Paul Boddie file changeset files shortlog Made the retraction operation a complete transaction. Tidied up the locking and unlocking function application.
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@1042    126 
`add_to_quota`         ||<rowspan="2"> add the details of an event to quota
 
 paul@1042    127 
                       .. records for the indicated quota group
 
 paul@1042    128 
==
 
 paul@1042    129 
`add_to_quota` ''`quota-group`''
 
 paul@1042    130 
==
 
 paul@1042    131 
`add_to_quota_freebusy` ||<rowspan="2"> add the details of an event to
 
 paul@1042    132 
                        .. free/busy records stored by the indicated quota
 
 paul@1042    133 
                        .. group
 
 paul@1042    134 
==
 
 paul@1042    135 
`add_to_quota_freebusy` ''`quota-group`''
 
 paul@1039    136 
}}}
 
 paul@1039    137 
 
 paul@1039    138 
See also `retraction_function` and `scheduling_function`.
 
 paul@1039    139 
 
 paul@961    140 
=== event_refreshing ===
 
 paul@961    141 
 
 paul@961    142 
 Default:: `never`
 
 paul@961    143 
 Alternative:: `always`
 
 paul@961    144 
 
 paul@961    145 
Indicate whether messages requesting a refresh of event details shall be
 
 paul@961    146 
handled automatically. If not, such messages will be passed on to the
 
 paul@961    147 
recipient for their mail program to handle.
 
 paul@961    148 
 
 paul@961    149 
=== freebusy_bundling ===
 
 paul@961    150 
 
 paul@961    151 
 Default:: `never`
 
 paul@961    152 
 Alternative:: `always`
 
 paul@961    153 
 
 paul@961    154 
Indicate whether to bundle free/busy details with other payloads such as
 
 paul@961    155 
event and free/busy objects. The `freebusy_sharing` setting must be
 
 paul@961    156 
configured for bundling to operate.
 
 paul@961    157 
 
 paul@961    158 
=== freebusy_messages ===
 
 paul@961    159 
 
 paul@961    160 
 Default:: `none`
 
 paul@961    161 
 Alternative:: `notify`
 
 paul@961    162 
 
 paul@961    163 
Indicate whether recipients are notified about received free/busy payloads.
 
 paul@961    164 
 
 paul@961    165 
=== freebusy_offers ===
 
 paul@961    166 
 
 paul@961    167 
 Default:: (none)
 
 paul@961    168 
 Alternative:: (see below)
 
 paul@961    169 
 
 paul@961    170 
Define the period for which free/busy offers are extended by participants
 
 paul@961    171 
supporting this setting when counter-proposals are made during event
 
 paul@961    172 
scheduling.
 
 paul@961    173 
 
 paul@961    174 
This setting requires a value indicating a duration as described in the
 
 paul@961    175 
iCalendar format specification:
 
 paul@961    176 
 
 paul@961    177 
http://tools.ietf.org/html/rfc5545#section-3.3.6
 
 paul@961    178 
 
 paul@961    179 
For example:
 
 paul@961    180 
 
 paul@961    181 
|| `PT10M`  || extend scheduling offers for 10 minutes ||
 
 paul@961    182 
|| `PT600S` || extend scheduling offers for 600 seconds (10 minutes) ||
 
 paul@961    183 
|| `PT1D`   || extend offers for 1 day ||
 
 paul@961    184 
 
 paul@961    185 
=== freebusy_publishing ===
 
 paul@961    186 
 
 paul@961    187 
 Default:: `no`
 
 paul@961    188 
 Alternative:: `publish`
 
 paul@961    189 
 
 paul@961    190 
Indicate whether to publish free/busy details as Web resources. The
 
 paul@961    191 
`freebusy_sharing` setting must be configured for publishing to operate.
 
 paul@961    192 
 
 paul@961    193 
=== freebusy_sharing ===
 
 paul@961    194 
 
 paul@961    195 
 Default:: `no`
 
 paul@961    196 
 Alternative:: `share`
 
 paul@961    197 
 
 paul@961    198 
Share free/busy details generally:
 
 paul@961    199 
 
 paul@961    200 
  * bundling in e-mail messages if bundling is configured
 
 paul@961    201 
  * responding to free/busy requests via e-mail
 
 paul@961    202 
  * publishing as Web resources if a static Web resource is configured and if
 
 paul@961    203 
  publishing is configured
 
 paul@961    204 
 
 paul@961    205 
=== incoming ===
 
 paul@961    206 
 
 paul@961    207 
 Default:: `summary-wraps-message`
 
 paul@961    208 
 Alternatives:: (see below)
 
 paul@961    209 
 
 paul@961    210 
Define how incoming event messages are delivered to recipients:
 
 paul@961    211 
 
 paul@961    212 
{{{#!table
 
 paul@961    213 
`message-only`
 
 paul@961    214 
|| deliver only the incoming message as it was received
 
 paul@961    215 
==
 
 paul@961    216 
`message-then-summary`
 
 paul@961    217 
|| deliver the message first followed by a summary message
 
 paul@961    218 
==
 
 paul@961    219 
`summary-then-message`
 
 paul@961    220 
|| deliver a summary first followed by the message
 
 paul@961    221 
==
 
 paul@961    222 
`summary-only`
 
 paul@961    223 
|| deliver only a summary of the message
 
 paul@961    224 
==
 
 paul@961    225 
`summary-wraps-message`
 
 paul@961    226 
|| deliver a summary that includes the original message as an attachment
 
 paul@961    227 
}}}
 
 paul@961    228 
 
 paul@961    229 
=== organiser_replacement ===
 
 paul@961    230 
 
 paul@961    231 
 Default:: `attendee`
 
 paul@961    232 
 Alternatives:: (see below)
 
 paul@961    233 
 
 paul@961    234 
Indicate whether the organiser of an event can be replaced and the nature of
 
 paul@961    235 
any replacement:
 
 paul@961    236 
 
 paul@961    237 
{{{#!table
 
 paul@961    238 
`any` || any identity, regardless of whether it is already present or even
 
 paul@961    239 
      .. previously unknown, may become the organiser
 
 paul@961    240 
==
 
 paul@961    241 
`attendee` || any new organiser must be a previously-recognised attendee
 
 paul@961    242 
==
 
 paul@961    243 
`never` || forbid the replacement of an event's organiser
 
 paul@961    244 
}}}
 
 paul@961    245 
 
 paul@961    246 
=== participating ===
 
 paul@961    247 
 
 paul@961    248 
 Default:: `participate`
 
 paul@961    249 
 Alternative:: `no`
 
 paul@961    250 
 
 paul@961    251 
Indicate whether a recipient participates in the calendar system. Note that
 
 paul@961    252 
participation by default occurs because the handler programs will be defined
 
 paul@961    253 
in the mail system for recipients fulfilling certain criteria; other
 
 paul@961    254 
recipients will be handled in other ways. Thus, initial non-participation must
 
 paul@961    255 
be defined by initialising this setting to "no" for all eligible users, if
 
 paul@961    256 
this is the general policy on initial calendar system participation.
 
 paul@961    257 
 
 paul@961    258 
=== permitted_times ===
 
 paul@961    259 
 
 paul@961    260 
 Default:: (none)
 
 paul@961    261 
 Alternatives:: (see below)
 
 paul@961    262 
 
 paul@961    263 
Define the time values at which events can be scheduled. In its simplest form,
 
 paul@961    264 
this indicates the resolution of a calendar for a participant supporting this
 
 paul@961    265 
setting, with the given minute values being those allowed for the start and
 
 paul@961    266 
end of an event. This setting requires a value of one of the following forms:
 
 paul@961    267 
 
 paul@961    268 
{{{
 
 paul@961    269 
<minute values>
 
 paul@961    270 
<hour values>:<minute values>
 
 paul@961    271 
<hour values>:<minute values>:<second values>
 
 paul@961    272 
}}}
 
 paul@961    273 
 
 paul@961    274 
Each list of values is a comma-separated collection of permissible values for
 
 paul@961    275 
the unit of time being constrained. Any unspecified list is taken to permit
 
 paul@961    276 
all normally permissible values for that unit of time. For example:
 
 paul@961    277 
 
 paul@961    278 
{{{#!table
 
 paul@961    279 
`0,15,30,45`          || every 15 minutes from the start of each hour
 
 paul@961    280 
==
 
 paul@961    281 
`10,12,14,16:0,20,40` || every 20 minutes from 10:00 until 16:40 inclusive
 
 paul@961    282 
==
 
 paul@961    283 
`12::0,30`            ||  every 30 seconds from the start of each minute
 
 paul@961    284 
                      .. during the period from 12:00:00 until 12:59:30
 
 paul@961    285 
                      .. inclusive
 
 paul@961    286 
}}}
 
 paul@961    287 
 
 paul@961    288 
The purpose of this setting is not necessarily to impose availability
 
 paul@961    289 
constraints but instead to impose a "grid" to which event start and end points
 
 paul@961    290 
shall be "locked".
 
 paul@961    291 
 
 paul@961    292 
The values are interpreted in the local time of the participant. Thus, a time
 
 paul@961    293 
represented in UTC may have apparently inappropriate hour (and for some zones)
 
 paul@961    294 
minute values that correspond to permitted values in this participant's own
 
 paul@961    295 
time zone.
 
 paul@961    296 
 
 paul@1039    297 
=== retraction_function ===
 
 paul@1039    298 
 
 paul@1039    299 
 Default:: (none)
 
 paul@1039    300 
 Alternatives:: (see below)
 
 paul@1039    301 
 
 paul@1039    302 
Indicates the retraction functions used by [[../Resources|resources]] to be
 
 paul@1039    303 
invoked when an event is cancelled. Such functions support certain scheduling
 
 paul@1039    304 
functions that require a record of scheduling activity.
 
 paul@1039    305 
 
 paul@1039    306 
The `imiptools.handlers.scheduling` module contains the built-in retraction
 
 paul@1039    307 
functions which include the following:
 
 paul@1039    308 
 
 paul@1039    309 
{{{#!table
 
 paul@1042    310 
`remove_from_quota`    ||<rowspan="2"> remove the details of an event from
 
 paul@1042    311 
                       .. quota records for the indicated quota group
 
 paul@1042    312 
==
 
 paul@1042    313 
`remove_from_quota` ''`quota-group`''
 
 paul@1042    314 
==
 
 paul@1042    315 
`remove_from_quota_freebusy` ||<rowspan="2"> remove the details of an event
 
 paul@1042    316 
                             .. from free/busy records stored by the
 
 paul@1042    317 
                             .. indicated quota group
 
 paul@1042    318 
==
 
 paul@1042    319 
`remove_from_quota_freebusy` ''`quota-group`''
 
 paul@1039    320 
}}}
 
 paul@1039    321 
 
 paul@1039    322 
See also `confirmation_function` and `scheduling_function`.
 
 paul@1039    323 
 
 paul@961    324 
=== scheduling_function ===
 
 paul@961    325 
 
 paul@961    326 
 Default:: `schedule_in_freebusy`
 
 paul@961    327 
 Alternatives:: (see below)
 
 paul@961    328 
 
 paul@1032    329 
Indicates the scheduling functions used by [[../Resources|resources]] to find
 
 paul@1032    330 
an appropriate period for an event, with each function to be applied to a
 
 paul@1032    331 
scheduling request appearing on a separate line, optionally accompanied by
 
 paul@1032    332 
arguments controlling the behaviour of the function.
 
 paul@1025    333 
 
 paul@1039    334 
The `imiptools.handlers.scheduling` module contains the built-in scheduling
 
 paul@1025    335 
functions which include the following:
 
 paul@961    336 
 
 paul@961    337 
{{{#!table
 
 paul@1032    338 
`access_control_list`  || use an access control list provided by a file whose
 
 paul@1032    339 
                       .. name is given as an argument, accepting or declining
 
 paul@1032    340 
                       .. the invitation according to the indicated rules
 
 paul@1032    341 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1032    342 
==
 
 paul@1039    343 
`check_quota`          || accept an invitation only if the organiser does not
 
 paul@1042    344 
                       .. exceed their quota allowance for bookings for the
 
 paul@1042    345 
                       .. indicated quota group
 
 paul@1042    346 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1042    347 
==
 
 paul@1042    348 
`schedule_across_quota`|| accept an invitation only if the organiser has not
 
 paul@1042    349 
                       .. reserved a resource for a conflicting period in any
 
 paul@1042    350 
                       .. other resource belonging to the indicated quota group
 
 paul@1039    351 
                       .. (described in the [[../Resources|resources guide]])
 
 paul@1039    352 
==
 
 paul@1032    353 
`same_domain_only`     || accept an invitation only if the organiser employs an
 
 paul@1032    354 
                       .. address in the same domain as the resource
 
 paul@1030    355 
==
 
 paul@961    356 
`schedule_in_freebusy` || accept an invitation if the event periods are free
 
 paul@961    357 
                       .. according to the free/busy records for the resource;
 
 paul@961    358 
                       .. decline otherwise
 
 paul@961    359 
==
 
 paul@961    360 
`schedule_corrected_in_freebusy` || correct periods in an event according to
 
 paul@961    361 
                                 .. the permitted_times setting (see above),
 
 paul@961    362 
                       .. then attempt to schedule the event according to the
 
 paul@961    363 
                       .. free/busy records for the resource
 
 paul@961    364 
==
 
 paul@961    365 
`schedule_next_available_in_freebusy` || correct periods in an event according
 
 paul@961    366 
                                      .. to the permitted_times setting (see
 
 paul@961    367 
                       .. above), if configured, and attempt to schedule the
 
 paul@961    368 
                       .. event according to the free/busy records for the
 
 paul@961    369 
                       .. resource and for any attendees for whom records are
 
 paul@961    370 
                       .. available, seeking the next available free period for
 
 paul@961    371 
                       .. each period that conflicts with an existing event
 
 paul@961    372 
}}}
 
 paul@961    373 
 
 paul@961    374 
The scheduling mechanism can be extended by implementing additional scheduling
 
 paul@961    375 
functions or by extending the handler framework directly.
 
 paul@1039    376 
 
 paul@1039    377 
See also `confirmation_function` and `retraction_function`.