imip-agent

Annotated docs/preferences.txt

945:2963ca0b67b2
2015-10-27 Paul Boddie Added support for scheduling events using free/busy details for all attendees, instead of just for the requested resource.
paul@667 1
Preferences and Settings
paul@667 2
========================
paul@667 3
paul@791 4
CN
paul@791 5
--
paul@791 6
paul@791 7
Default: (none)
paul@791 8
Alternatives: (see below)
paul@791 9
paul@791 10
The common name of the user, employed in iCalendar objects and user
paul@791 11
interfaces.
paul@791 12
paul@667 13
LANG
paul@667 14
----
paul@463 15
paul@667 16
Default: en (English)
paul@667 17
Alternatives: (any recognised and supported locale)
paul@667 18
paul@667 19
The language for messages and user interface text.
paul@667 20
paul@667 21
TZID
paul@667 22
----
paul@667 23
paul@667 24
Default: system timezone (see /etc/timezone)
paul@667 25
Alternatives: (any recognised Olson time zone identifier)
paul@463 26
paul@667 27
The default time zone/regime for calendars, new events and local times.
paul@667 28
paul@734 29
add_method_response
paul@734 30
-------------------
paul@734 31
paul@734 32
Default: refresh
paul@740 33
Alternatives: (see below)
paul@734 34
paul@734 35
Indicate how ADD methods shall be responded to when received by a recipient:
paul@734 36
paul@734 37
  add                   apply them to events as received
paul@734 38
paul@734 39
  ignore                ignore attempts to add event occurrences
paul@734 40
paul@734 41
  refresh               respond with a REFRESH message to obtain a proper
paul@734 42
                        request will all event details
paul@734 43
paul@688 44
event_refreshing
paul@688 45
----------------
paul@688 46
paul@688 47
Default: never
paul@688 48
Alternative: always
paul@688 49
paul@688 50
Indicate whether messages requesting a refresh of event details shall be
paul@688 51
handled automatically. If not, such messages will be passed on to the
paul@688 52
recipient for their mail program to handle.
paul@688 53
paul@667 54
freebusy_bundling
paul@667 55
-----------------
paul@667 56
paul@667 57
Default: never
paul@667 58
Alternative: always
paul@463 59
paul@667 60
Indicate whether to bundle free/busy details with other payloads such as
paul@748 61
event and free/busy objects. The freebusy_sharing setting must be configured
paul@748 62
for bundling to operate.
paul@667 63
paul@667 64
freebusy_messages
paul@667 65
-----------------
paul@667 66
paul@667 67
Default: none
paul@667 68
Alternative: notify
paul@667 69
paul@667 70
Indicate whether recipients are notified about received free/busy payloads.
paul@463 71
paul@740 72
freebusy_offers
paul@740 73
---------------
paul@740 74
paul@740 75
Default: (none)
paul@740 76
Alternative: (see below)
paul@740 77
paul@740 78
Define the period for which free/busy offers are extended by participants
paul@740 79
supporting this setting when counter-proposals are made during event
paul@740 80
scheduling.
paul@740 81
paul@759 82
This setting requires a value indicating a duration as described in the
paul@759 83
iCalendar format specification:
paul@740 84
paul@759 85
http://tools.ietf.org/html/rfc5545#section-3.3.6
paul@740 86
paul@740 87
For example:
paul@740 88
paul@759 89
  PT10M                 extend scheduling offers for 10 minutes
paul@759 90
  PT600S                extend scheduling offers for 600 seconds (10 minutes)
paul@759 91
  PT1D                  extend offers for 1 day
paul@740 92
paul@748 93
freebusy_publishing
paul@748 94
-------------------
paul@748 95
paul@748 96
Default: no
paul@748 97
Alternative: publish
paul@748 98
paul@748 99
Indicate whether to publish free/busy details as Web resources. The
paul@748 100
freebusy_sharing setting must be configured for publishing to operate.
paul@748 101
paul@667 102
freebusy_sharing
paul@667 103
----------------
paul@667 104
paul@667 105
Default: no
paul@667 106
Alternative: share
paul@667 107
paul@667 108
Share free/busy details generally:
paul@667 109
paul@667 110
  * bundling in e-mail messages if bundling is configured
paul@667 111
  * responding to free/busy requests via e-mail
paul@748 112
  * publishing as Web resources if a static Web resource is configured and if
paul@748 113
    publishing is configured
paul@667 114
paul@667 115
incoming
paul@667 116
--------
paul@667 117
paul@667 118
Default: summary-wraps-message
paul@667 119
Alternatives: (see below)
paul@463 120
paul@667 121
Define how incoming event messages are delivered to recipients:
paul@667 122
paul@669 123
  message-only          deliver only the incoming message as it was received
paul@669 124
paul@669 125
  message-then-summary  deliver the message first followed by a summary
paul@669 126
                        message
paul@669 127
paul@669 128
  summary-then-message  deliver a summary first followed by the message
paul@669 129
paul@669 130
  summary-only          deliver only a summary of the message
paul@667 131
paul@728 132
  summary-wraps-message deliver a summary that includes the original message
paul@728 133
                        as an attachment
paul@728 134
paul@728 135
organiser_replacement
paul@728 136
---------------------
paul@728 137
paul@728 138
Default: attendee
paul@728 139
Alternatives: (see below)
paul@728 140
paul@728 141
Indicate whether the organiser of an event can be replaced and the nature of
paul@728 142
any replacement:
paul@728 143
paul@728 144
  any                   any identity, regardless of whether it is already
paul@728 145
                        present or even previously unknown, may become the
paul@728 146
                        organiser
paul@728 147
paul@728 148
  attendee              any new organiser must be a previously-recognised
paul@728 149
                        attendee
paul@728 150
paul@728 151
  never                 forbid the replacement of an event's organiser
paul@728 152
paul@667 153
participating
paul@667 154
-------------
paul@667 155
paul@667 156
Default: participate
paul@667 157
Alternative: no
paul@667 158
paul@667 159
Indicate whether a recipient participates in the calendar system. Note that
paul@667 160
participation by default occurs because the handler programs will be defined
paul@667 161
in the mail system for recipients fulfilling certain criteria; other
paul@667 162
recipients will be handled in other ways. Thus, initial non-participation must
paul@667 163
be defined by initialising this setting to "no" for all eligible users, if
paul@667 164
this is the general policy on initial calendar system participation.
paul@669 165
paul@669 166
permitted_times
paul@669 167
---------------
paul@669 168
paul@669 169
Default: (none)
paul@669 170
Alternatives: (see below)
paul@669 171
paul@669 172
Define the time values at which events can be scheduled. In its simplest form,
paul@669 173
this indicates the resolution of a calendar for a participant supporting this
paul@669 174
setting, with the given minute values being those allowed for the start and
paul@669 175
end of an event. This setting requires a value of one of the following forms:
paul@669 176
paul@669 177
  <minute values>
paul@669 178
  <hour values>:<minute values>
paul@669 179
  <hour values>:<minute values>:<second values>
paul@669 180
paul@669 181
Each list of values is a comma-separated collection of permissible values for
paul@669 182
the unit of time being constrained. Any unspecified list is taken to permit
paul@669 183
all normally permissible values for that unit of time. For example:
paul@669 184
paul@669 185
  0,15,30,45            every 15 minutes from the start of each hour
paul@669 186
  10,12,14,16:0,20,40   every 20 minutes from 10:00 until 16:40 inclusive
paul@669 187
  12::0,30              every 30 seconds from the start of each minute during
paul@669 188
                        the period from 12:00:00 until 12:59:30 inclusive
paul@669 189
paul@669 190
The purpose of this setting is not necessarily to impose availability
paul@669 191
constraints but instead to impose a "grid" to which event start and end points
paul@669 192
shall be "locked".
paul@707 193
paul@707 194
The values are interpreted in the local time of the participant. Thus, a time
paul@707 195
represented in UTC may have apparently inappropriate hour (and for some zones)
paul@707 196
minute values that correspond to permitted values in this participant's own
paul@707 197
time zone.
paul@938 198
paul@938 199
scheduling_function
paul@938 200
-------------------
paul@938 201
paul@938 202
Default: schedule_in_freebusy
paul@938 203
Alternatives: (see below)
paul@938 204
paul@938 205
Indicates the scheduling function used by resources to find an appropriate
paul@938 206
period for an event. The imiptools.handlers.scheduling module contains the
paul@938 207
built-in scheduling functions which include the following:
paul@938 208
paul@942 209
  schedule_in_freebusy  accept an invitation if the event periods are free
paul@942 210
                        according to the free/busy records for the resource;
paul@942 211
                        decline otherwise
paul@938 212
paul@938 213
  schedule_corrected_in_freebusy    correct periods in an event according to
paul@938 214
                                    the permitted_times setting (see above),
paul@942 215
                        then attempt to schedule the event according to the
paul@942 216
                        free/busy records for the resource
paul@942 217
paul@942 218
  schedule_next_available_in_freebusy   correct periods in an event according
paul@942 219
                                        to the permitted_times setting (see
paul@942 220
                        above), if configured, and attempt to schedule the
paul@942 221
                        event according to the free/busy records for the
paul@945 222
                        resource and for any attendees for whom records are
paul@945 223
                        available, seeking the next available free period for
paul@942 224
                        each period that conflicts with an existing event
paul@938 225
paul@938 226
The scheduling mechanism can be extended by implementing additional scheduling
paul@938 227
functions or by extending the handler framework directly.