= Preferences =

The correspondence between user preferences (stored in user preference
directories) and the default settings (stored in `config.txt`) is described
below.

|| '''Preference'''        || '''Default Setting''' ||
|| `LANG`                  || `LANG` ||
|| `add_method_response`   || `ADD_RESPONSE_DEFAULT` ||
|| `event_refreshing`      || `REFRESHING_DEFAULT` ||
|| `freebusy_bundling`     || `BUNDLING_DEFAULT` ||
|| `freebusy_messages`     || `NOTIFYING_DEFAULT` ||
|| `freebusy_offers`       || `FREEBUSY_OFFER_DEFAULT` ||
|| `freebusy_publishing`   || `PUBLISHING_DEFAULT` ||
|| `freebusy_sharing`      || `SHARING_DEFAULT` ||
|| `incoming`              || `INCOMING_DEFAULT` ||
|| `organiser_replacement` || `ORGANISER_REPLACEMENT_DEFAULT` ||
|| `participating`         || `PARTICIPATING_DEFAULT` ||

See the [[../Configuration|configuration guide]] for more information about
the `config.txt` file.

{{{#!wiki tip
=== Text Encoding ===
The textual encoding employed by all preferences files is UTF-8.
}}}

== User Preference Settings ==

<<TableOfContents(3,3)>>

Each of the user preferences or settings are stored in a separate file within
a dedicated preferences directory for each user, with the filename bearing the
name of the setting concerned. See the [[../FilesystemUsage|filesystem guide]]
for more information.

=== CN ===

 Default:: (none)
 Alternatives:: (see below)

The common name of the user, employed in iCalendar objects and user
interfaces.

=== LANG ===

 Default:: `en` (English)
 Alternatives:: (any recognised and supported locale)

The language for messages and user interface text.

=== TZID ===

 Default:: system timezone (see `/etc/timezone`)
 Alternatives:: (any recognised Olson time zone identifier)

The default time zone/regime for calendars, new events and local times.

=== acl ===

 Default:: (none)
 Alternatives:: (see below)

Provides an access control list for the `access_control_list` scheduling
function, invoked using the `scheduling_functions` setting. An access control
list consists of a collection of lines of text describing the handling policy
for an incoming invitation.

{{{#!table
`accept` || indicates that if no rule matches, the invitation will be accepted
         .. (provisionally)
==
`decline` ||<rowspan="2"> indicates that if no rule matches, the invitation
                       .. will be declined (provisionally)
==
`reject`
==
`accept` ''`role`'' ''`identity`'' || indicates that where the given
                                   .. ''`identity`'' exists in the given
         .. ''`role`'' in the event, and unless a subsequent rule contradicts
         .. this result, the invitation will be accepted (provisionally)
==
`decline` ''`role`'' ''`identity`'' ||<rowspan="2"> indicates that where the
                                                 .. given ''`identity`'' exists
         .. in the given ''`role`'' in the event, and unless a subsequent rule
         .. contradicts this result, the invitation will be declined
         .. (provisionally)

==
`reject` ''`role`'' ''`identity`''
}}}

In the above, `role` is either `organiser` (or `organizer`) or `attendee`;
`identity` is an address or URL.

Note that even if an accepted result is returned by the `access_control_list`
scheduling function, other functions that follow it in the list of functions
may overturn this result.

See the [[../Resources|resources guide]] for examples and more information.

=== add_method_response ===

 Default:: `refresh`
 Alternatives:: (see below)

Indicate how `ADD` methods shall be responded to when received by a recipient:

{{{#!table
`add`     || apply them to events as received
==
`ignore`  || ignore attempts to add event occurrences
==
`refresh` || respond with a `REFRESH` message to obtain a proper request with
          .. all event details
}}}

=== event_refreshing ===

 Default:: `never`
 Alternative:: `always`

Indicate whether messages requesting a refresh of event details shall be
handled automatically. If not, such messages will be passed on to the
recipient for their mail program to handle.

=== freebusy_bundling ===

 Default:: `never`
 Alternative:: `always`

Indicate whether to bundle free/busy details with other payloads such as
event and free/busy objects. The `freebusy_sharing` setting must be
configured for bundling to operate.

=== freebusy_messages ===

 Default:: `none`
 Alternative:: `notify`

Indicate whether recipients are notified about received free/busy payloads.

=== freebusy_offers ===

 Default:: (none)
 Alternative:: (see below)

Define the period for which free/busy offers are extended by participants
supporting this setting when counter-proposals are made during event
scheduling.

This setting requires a value indicating a duration as described in the
iCalendar format specification:

http://tools.ietf.org/html/rfc5545#section-3.3.6

For example:

|| `PT10M`  || extend scheduling offers for 10 minutes ||
|| `PT600S` || extend scheduling offers for 600 seconds (10 minutes) ||
|| `PT1D`   || extend offers for 1 day ||

=== freebusy_publishing ===

 Default:: `no`
 Alternative:: `publish`

Indicate whether to publish free/busy details as Web resources. The
`freebusy_sharing` setting must be configured for publishing to operate.

=== freebusy_sharing ===

 Default:: `no`
 Alternative:: `share`

Share free/busy details generally:

  * bundling in e-mail messages if bundling is configured
  * responding to free/busy requests via e-mail
  * publishing as Web resources if a static Web resource is configured and if
  publishing is configured

=== incoming ===

 Default:: `summary-wraps-message`
 Alternatives:: (see below)

Define how incoming event messages are delivered to recipients:

{{{#!table
`message-only`
|| deliver only the incoming message as it was received
==
`message-then-summary`
|| deliver the message first followed by a summary message
==
`summary-then-message`
|| deliver a summary first followed by the message
==
`summary-only`
|| deliver only a summary of the message
==
`summary-wraps-message`
|| deliver a summary that includes the original message as an attachment
}}}

=== organiser_replacement ===

 Default:: `attendee`
 Alternatives:: (see below)

Indicate whether the organiser of an event can be replaced and the nature of
any replacement:

{{{#!table
`any` || any identity, regardless of whether it is already present or even
      .. previously unknown, may become the organiser
==
`attendee` || any new organiser must be a previously-recognised attendee
==
`never` || forbid the replacement of an event's organiser
}}}

=== participating ===

 Default:: `participate`
 Alternative:: `no`

Indicate whether a recipient participates in the calendar system. Note that
participation by default occurs because the handler programs will be defined
in the mail system for recipients fulfilling certain criteria; other
recipients will be handled in other ways. Thus, initial non-participation must
be defined by initialising this setting to "no" for all eligible users, if
this is the general policy on initial calendar system participation.

=== permitted_times ===

 Default:: (none)
 Alternatives:: (see below)

Define the time values at which events can be scheduled. In its simplest form,
this indicates the resolution of a calendar for a participant supporting this
setting, with the given minute values being those allowed for the start and
end of an event. This setting requires a value of one of the following forms:

{{{
<minute values>
<hour values>:<minute values>
<hour values>:<minute values>:<second values>
}}}

Each list of values is a comma-separated collection of permissible values for
the unit of time being constrained. Any unspecified list is taken to permit
all normally permissible values for that unit of time. For example:

{{{#!table
`0,15,30,45`          || every 15 minutes from the start of each hour
==
`10,12,14,16:0,20,40` || every 20 minutes from 10:00 until 16:40 inclusive
==
`12::0,30`            ||  every 30 seconds from the start of each minute
                      .. during the period from 12:00:00 until 12:59:30
                      .. inclusive
}}}

The purpose of this setting is not necessarily to impose availability
constraints but instead to impose a "grid" to which event start and end points
shall be "locked".

The values are interpreted in the local time of the participant. Thus, a time
represented in UTC may have apparently inappropriate hour (and for some zones)
minute values that correspond to permitted values in this participant's own
time zone.

=== scheduling_function ===

 Default:: `schedule_in_freebusy`
 Alternatives:: (see below)

Indicates the scheduling functions used by [[../Resources|resources]] to find
an appropriate period for an event, with each function to be applied to a
scheduling request appearing on a separate line, optionally accompanied by
arguments controlling the behaviour of the function.

The `imiptools.handlers.scheduling` module contains the built-in scheduling
functions which include the following:

{{{#!table
`access_control_list`  || use an access control list provided by a file whose
                       .. name is given as an argument, accepting or declining
                       .. the invitation according to the indicated rules
                       .. (described in the [[../Resources|resources guide]])
==
`check_quota`          || accept an invitation only if the organiser does not
                       .. exceed their quota allowance for bookings for the
                       .. indicated quota group
                       .. (described in the [[../Resources|resources guide]])
==
`same_domain_only`     || accept an invitation only if the organiser employs an
                       .. address in the same domain as the resource
==
`schedule_across_quota`|| accept an invitation only if the organiser has not
                       .. reserved a resource for a conflicting period in any
                       .. other resource belonging to the indicated quota group
                       .. (described in the [[../Resources|resources guide]])
==
`schedule_for_delegate`|| accept an invitation only if the organiser can
                       .. reserve the resource according to the common quota
                       .. schedule, delegating to any other available resource
                       .. defined as a potential delegate, declining if no
                       .. resource is available
                       .. (described in the [[../Resources|resources guide]])
==
`schedule_in_freebusy` || accept an invitation if the event periods are free
                       .. according to the free/busy records for the resource;
                       .. decline otherwise
==
`schedule_corrected_in_freebusy` || correct periods in an event according to
                                 .. the permitted_times setting (see above),
                       .. then attempt to schedule the event according to the
                       .. free/busy records for the resource
==
`schedule_next_available_in_freebusy` || correct periods in an event according
                                      .. to the permitted_times setting (see
                       .. above), if configured, and attempt to schedule the
                       .. event according to the free/busy records for the
                       .. resource and for any attendees for whom records are
                       .. available, seeking the next available free period for
                       .. each period that conflicts with an existing event
}}}

The scheduling mechanism can be extended by implementing additional scheduling
functions or by extending the handler framework directly.