imip-agent

Annotated docs/wiki/Preferences

1032:abbfbee0f858
1030:6e8f43c29e71
1025:39efcf72d853
2016-01-30 Paul Boddie file changeset files shortlog Added the domain-related scheduling function to the documentation.
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@961     54 
=== add_method_response ===
 
 paul@961     55 
 
 paul@961     56 
 Default:: `refresh`
 
 paul@961     57 
 Alternatives:: (see below)
 
 paul@961     58 
 
 paul@961     59 
Indicate how `ADD` methods shall be responded to when received by a recipient:
 
 paul@961     60 
 
 paul@961     61 
{{{#!table
 
 paul@961     62 
`add`     || apply them to events as received
 
 paul@961     63 
==
 
 paul@961     64 
`ignore`  || ignore attempts to add event occurrences
 
 paul@961     65 
==
 
 paul@961     66 
`refresh` || respond with a `REFRESH` message to obtain a proper request with
 
 paul@961     67 
          .. all event details
 
 paul@961     68 
}}}
 
 paul@961     69 
 
 paul@961     70 
=== event_refreshing ===
 
 paul@961     71 
 
 paul@961     72 
 Default:: `never`
 
 paul@961     73 
 Alternative:: `always`
 
 paul@961     74 
 
 paul@961     75 
Indicate whether messages requesting a refresh of event details shall be
 
 paul@961     76 
handled automatically. If not, such messages will be passed on to the
 
 paul@961     77 
recipient for their mail program to handle.
 
 paul@961     78 
 
 paul@961     79 
=== freebusy_bundling ===
 
 paul@961     80 
 
 paul@961     81 
 Default:: `never`
 
 paul@961     82 
 Alternative:: `always`
 
 paul@961     83 
 
 paul@961     84 
Indicate whether to bundle free/busy details with other payloads such as
 
 paul@961     85 
event and free/busy objects. The `freebusy_sharing` setting must be
 
 paul@961     86 
configured for bundling to operate.
 
 paul@961     87 
 
 paul@961     88 
=== freebusy_messages ===
 
 paul@961     89 
 
 paul@961     90 
 Default:: `none`
 
 paul@961     91 
 Alternative:: `notify`
 
 paul@961     92 
 
 paul@961     93 
Indicate whether recipients are notified about received free/busy payloads.
 
 paul@961     94 
 
 paul@961     95 
=== freebusy_offers ===
 
 paul@961     96 
 
 paul@961     97 
 Default:: (none)
 
 paul@961     98 
 Alternative:: (see below)
 
 paul@961     99 
 
 paul@961    100 
Define the period for which free/busy offers are extended by participants
 
 paul@961    101 
supporting this setting when counter-proposals are made during event
 
 paul@961    102 
scheduling.
 
 paul@961    103 
 
 paul@961    104 
This setting requires a value indicating a duration as described in the
 
 paul@961    105 
iCalendar format specification:
 
 paul@961    106 
 
 paul@961    107 
http://tools.ietf.org/html/rfc5545#section-3.3.6
 
 paul@961    108 
 
 paul@961    109 
For example:
 
 paul@961    110 
 
 paul@961    111 
|| `PT10M`  || extend scheduling offers for 10 minutes ||
 
 paul@961    112 
|| `PT600S` || extend scheduling offers for 600 seconds (10 minutes) ||
 
 paul@961    113 
|| `PT1D`   || extend offers for 1 day ||
 
 paul@961    114 
 
 paul@961    115 
=== freebusy_publishing ===
 
 paul@961    116 
 
 paul@961    117 
 Default:: `no`
 
 paul@961    118 
 Alternative:: `publish`
 
 paul@961    119 
 
 paul@961    120 
Indicate whether to publish free/busy details as Web resources. The
 
 paul@961    121 
`freebusy_sharing` setting must be configured for publishing to operate.
 
 paul@961    122 
 
 paul@961    123 
=== freebusy_sharing ===
 
 paul@961    124 
 
 paul@961    125 
 Default:: `no`
 
 paul@961    126 
 Alternative:: `share`
 
 paul@961    127 
 
 paul@961    128 
Share free/busy details generally:
 
 paul@961    129 
 
 paul@961    130 
  * bundling in e-mail messages if bundling is configured
 
 paul@961    131 
  * responding to free/busy requests via e-mail
 
 paul@961    132 
  * publishing as Web resources if a static Web resource is configured and if
 
 paul@961    133 
  publishing is configured
 
 paul@961    134 
 
 paul@961    135 
=== incoming ===
 
 paul@961    136 
 
 paul@961    137 
 Default:: `summary-wraps-message`
 
 paul@961    138 
 Alternatives:: (see below)
 
 paul@961    139 
 
 paul@961    140 
Define how incoming event messages are delivered to recipients:
 
 paul@961    141 
 
 paul@961    142 
{{{#!table
 
 paul@961    143 
`message-only`
 
 paul@961    144 
|| deliver only the incoming message as it was received
 
 paul@961    145 
==
 
 paul@961    146 
`message-then-summary`
 
 paul@961    147 
|| deliver the message first followed by a summary message
 
 paul@961    148 
==
 
 paul@961    149 
`summary-then-message`
 
 paul@961    150 
|| deliver a summary first followed by the message
 
 paul@961    151 
==
 
 paul@961    152 
`summary-only`
 
 paul@961    153 
|| deliver only a summary of the message
 
 paul@961    154 
==
 
 paul@961    155 
`summary-wraps-message`
 
 paul@961    156 
|| deliver a summary that includes the original message as an attachment
 
 paul@961    157 
}}}
 
 paul@961    158 
 
 paul@961    159 
=== organiser_replacement ===
 
 paul@961    160 
 
 paul@961    161 
 Default:: `attendee`
 
 paul@961    162 
 Alternatives:: (see below)
 
 paul@961    163 
 
 paul@961    164 
Indicate whether the organiser of an event can be replaced and the nature of
 
 paul@961    165 
any replacement:
 
 paul@961    166 
 
 paul@961    167 
{{{#!table
 
 paul@961    168 
`any` || any identity, regardless of whether it is already present or even
 
 paul@961    169 
      .. previously unknown, may become the organiser
 
 paul@961    170 
==
 
 paul@961    171 
`attendee` || any new organiser must be a previously-recognised attendee
 
 paul@961    172 
==
 
 paul@961    173 
`never` || forbid the replacement of an event's organiser
 
 paul@961    174 
}}}
 
 paul@961    175 
 
 paul@961    176 
=== participating ===
 
 paul@961    177 
 
 paul@961    178 
 Default:: `participate`
 
 paul@961    179 
 Alternative:: `no`
 
 paul@961    180 
 
 paul@961    181 
Indicate whether a recipient participates in the calendar system. Note that
 
 paul@961    182 
participation by default occurs because the handler programs will be defined
 
 paul@961    183 
in the mail system for recipients fulfilling certain criteria; other
 
 paul@961    184 
recipients will be handled in other ways. Thus, initial non-participation must
 
 paul@961    185 
be defined by initialising this setting to "no" for all eligible users, if
 
 paul@961    186 
this is the general policy on initial calendar system participation.
 
 paul@961    187 
 
 paul@961    188 
=== permitted_times ===
 
 paul@961    189 
 
 paul@961    190 
 Default:: (none)
 
 paul@961    191 
 Alternatives:: (see below)
 
 paul@961    192 
 
 paul@961    193 
Define the time values at which events can be scheduled. In its simplest form,
 
 paul@961    194 
this indicates the resolution of a calendar for a participant supporting this
 
 paul@961    195 
setting, with the given minute values being those allowed for the start and
 
 paul@961    196 
end of an event. This setting requires a value of one of the following forms:
 
 paul@961    197 
 
 paul@961    198 
{{{
 
 paul@961    199 
<minute values>
 
 paul@961    200 
<hour values>:<minute values>
 
 paul@961    201 
<hour values>:<minute values>:<second values>
 
 paul@961    202 
}}}
 
 paul@961    203 
 
 paul@961    204 
Each list of values is a comma-separated collection of permissible values for
 
 paul@961    205 
the unit of time being constrained. Any unspecified list is taken to permit
 
 paul@961    206 
all normally permissible values for that unit of time. For example:
 
 paul@961    207 
 
 paul@961    208 
{{{#!table
 
 paul@961    209 
`0,15,30,45`          || every 15 minutes from the start of each hour
 
 paul@961    210 
==
 
 paul@961    211 
`10,12,14,16:0,20,40` || every 20 minutes from 10:00 until 16:40 inclusive
 
 paul@961    212 
==
 
 paul@961    213 
`12::0,30`            ||  every 30 seconds from the start of each minute
 
 paul@961    214 
                      .. during the period from 12:00:00 until 12:59:30
 
 paul@961    215 
                      .. inclusive
 
 paul@961    216 
}}}
 
 paul@961    217 
 
 paul@961    218 
The purpose of this setting is not necessarily to impose availability
 
 paul@961    219 
constraints but instead to impose a "grid" to which event start and end points
 
 paul@961    220 
shall be "locked".
 
 paul@961    221 
 
 paul@961    222 
The values are interpreted in the local time of the participant. Thus, a time
 
 paul@961    223 
represented in UTC may have apparently inappropriate hour (and for some zones)
 
 paul@961    224 
minute values that correspond to permitted values in this participant's own
 
 paul@961    225 
time zone.
 
 paul@961    226 
 
 paul@961    227 
=== scheduling_function ===
 
 paul@961    228 
 
 paul@961    229 
 Default:: `schedule_in_freebusy`
 
 paul@961    230 
 Alternatives:: (see below)
 
 paul@961    231 
 
 paul@1025    232 
Indicates the scheduling functions used by resources to find an appropriate
 
 paul@1025    233 
period for an event, with each function to be applied to a scheduling request
 
 paul@1025    234 
appearing on a separate line.
 
 paul@1025    235 
 
 paul@1025    236 
The imiptools.handlers.scheduling module contains the built-in scheduling
 
 paul@1025    237 
functions which include the following:
 
 paul@961    238 
 
 paul@961    239 
{{{#!table
 
 paul@1030    240 
`same_domain_only` || accept an invitation only if the organiser employs an
 
 paul@1030    241 
                   .. address in the same domain as the resource
 
 paul@1030    242 
==
 
 paul@961    243 
`schedule_in_freebusy` || accept an invitation if the event periods are free
 
 paul@961    244 
                       .. according to the free/busy records for the resource;
 
 paul@961    245 
                       .. decline otherwise
 
 paul@961    246 
==
 
 paul@961    247 
`schedule_corrected_in_freebusy` || correct periods in an event according to
 
 paul@961    248 
                                 .. the permitted_times setting (see above),
 
 paul@961    249 
                       .. then attempt to schedule the event according to the
 
 paul@961    250 
                       .. free/busy records for the resource
 
 paul@961    251 
==
 
 paul@961    252 
`schedule_next_available_in_freebusy` || correct periods in an event according
 
 paul@961    253 
                                      .. to the permitted_times setting (see
 
 paul@961    254 
                       .. above), if configured, and attempt to schedule the
 
 paul@961    255 
                       .. event according to the free/busy records for the
 
 paul@961    256 
                       .. resource and for any attendees for whom records are
 
 paul@961    257 
                       .. available, seeking the next available free period for
 
 paul@961    258 
                       .. each period that conflicts with an existing event
 
 paul@961    259 
}}}
 
 paul@961    260 
 
 paul@961    261 
The scheduling mechanism can be extended by implementing additional scheduling
 
 paul@961    262 
functions or by extending the handler framework directly.