# HG changeset patch # User Paul Boddie # Date 1445864725 -3600 # Node ID 2caa4627f3aadef50a445a9ad6a684721ba83e4f # Parent fbef8dc092d3010b5335bb1675ad1704c945a635 Reformatted the wiki pages to hopefully make them more readable as plain text as well as being correctly formatted for MoinMoin. diff -r fbef8dc092d3 -r 2caa4627f3aa docs/wiki/CounterProposals --- a/docs/wiki/CounterProposals Mon Oct 26 13:49:51 2015 +0100 +++ b/docs/wiki/CounterProposals Mon Oct 26 14:05:25 2015 +0100 @@ -1,11 +1,31 @@ = Counter-Proposals and Offers = -When attempting to schedule an event, an attendee may suggest an alternative time by issuing a counter-proposal in the form of a `COUNTER` message. Upon receiving a counter-proposal, an organiser may then issue an updated invitation with new details (potentially matching those suggested in the counter-proposal, but not necessarily) for attendees to accept or decline. Alternatively, an organiser may refuse to consider other times and send the attendee concerned a `DECLINECOUNTER` message. +When attempting to schedule an event, an attendee may suggest an alternative +time by issuing a counter-proposal in the form of a `COUNTER` message. Upon +receiving a counter-proposal, an organiser may then issue an updated +invitation with new details (potentially matching those suggested in the +counter-proposal, but not necessarily) for attendees to accept or decline. +Alternatively, an organiser may refuse to consider other times and send the +attendee concerned a `DECLINECOUNTER` message. == Offers to Schedule == -It can be useful for an attendee issuing such a counter-proposal to mark the periods involved as tentatively occupied until they know that their proposal has been accepted or not; it is also useful for the organiser to be able to rely on such periods being temporarily reserved by attendees so that any acceptance of a counter-proposal will succeed instead of failing because an attendee has chosen to dedicate those periods to something else. Thus, an attendee will make a temporary offer of scheduling for periods of time associated with an event, expiring such an offer in case the organiser chooses not to respond in a timely fashion (or at all). +It can be useful for an attendee issuing such a counter-proposal to mark the +periods involved as tentatively occupied until they know that their proposal +has been accepted or not; it is also useful for the organiser to be able to +rely on such periods being temporarily reserved by attendees so that any +acceptance of a counter-proposal will succeed instead of failing because an +attendee has chosen to dedicate those periods to something else. Thus, an +attendee will make a temporary offer of scheduling for periods of time +associated with an event, expiring such an offer in case the organiser chooses +not to respond in a timely fashion (or at all). == Managing Counter-Proposals == -Each attendee invited to an event may respond with a counter-proposal. Thus, an organiser needs to be able to collect multiple counter-proposals for each event and to choose one to accept, if any are to be accepted at all. In principle, an organiser could merge details of different proposals, particularly if multiple periods are involved (and also if different attendees are suggested in different proposals), with the resulting combination of details being issued as a new request to all attendees. +Each attendee invited to an event may respond with a counter-proposal. Thus, +an organiser needs to be able to collect multiple counter-proposals for each +event and to choose one to accept, if any are to be accepted at all. In +principle, an organiser could merge details of different proposals, +particularly if multiple periods are involved (and also if different attendees +are suggested in different proposals), with the resulting combination of +details being issued as a new request to all attendees. diff -r fbef8dc092d3 -r 2caa4627f3aa docs/wiki/EventRecurrences --- a/docs/wiki/EventRecurrences Mon Oct 26 13:49:51 2015 +0100 +++ b/docs/wiki/EventRecurrences Mon Oct 26 14:05:25 2015 +0100 @@ -1,36 +1,99 @@ = Event Recurrences = -Events defined by iCalendar objects may recur when [[http://tools.ietf.org/html/rfc5545#section-3.8.5|recurrence component properties]] such as `RDATE` and `RRULE` are employed. Each recurrence of an event may then be referenced using [[http://tools.ietf.org/html/rfc5545#section-3.8.4.4|recurrence identifiers]], and such identifiers indicate the originally-specified start point of a particular recurrence (either implicitly specified by `RRULE` properties or explicitly specified by `RDATE` properties). +Events defined by iCalendar objects may recur when +[[http://tools.ietf.org/html/rfc5545#section-3.8.5|recurrence component properties]] +such as `RDATE` and `RRULE` are employed. Each recurrence of an event may then +be referenced using +[[http://tools.ietf.org/html/rfc5545#section-3.8.4.4|recurrence identifiers]], +and such identifiers indicate the originally-specified start point of a +particular recurrence (either implicitly specified by `RRULE` properties or +explicitly specified by `RDATE` properties). == Recurrence Identifier Stability == -A recurrence retains the same identifier throughout its lifetime. Even if a recurrence's start date or time changes, it will still retain the same identifier in its `RECURRENCE-ID` property which will no longer reflect the currently-specified start point of the recurrence. Such identifier stability is intended to provide a means of identifying the original recurrence so that it can be hidden from any calendar or event descriptions and replaced with the modified version. +A recurrence retains the same identifier throughout its lifetime. Even if a +recurrence's start date or time changes, it will still retain the same +identifier in its `RECURRENCE-ID` property which will no longer reflect the +currently-specified start point of the recurrence. Such identifier stability +is intended to provide a means of identifying the original recurrence so that +it can be hidden from any calendar or event descriptions and replaced with the +modified version. == Recurrences and Time Zones == -Since recurrence identifiers may be defined using time zone information, imip-agent normalises the specified recurrence identifiers to UTC-based datetimes to minimise ambiguity. For example: +Since recurrence identifiers may be defined using time zone information, +imip-agent normalises the specified recurrence identifiers to UTC-based +datetimes to minimise ambiguity. For example: + +|| '''iCalendar Property''' || '''Normalised Value''' || '''UTC Datetime?''' || +|| `RECURRENCE-ID:20141114` || `20141114` || No || +|| `RECURRENCE-ID:20141114T000000` || `20141114T000000` || No || +|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114` || `20141113T230000Z` || Yes || +|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114T000000` || `20141113T230000Z` || Yes || +|| `RECURRENCE-ID:20141114T000000Z` || `20141114T000000Z` || Yes || -|| '''iCalendar Property''' || '''Normalised Value''' || '''UTC Datetime?''' || -|| `RECURRENCE-ID:20141114` || `20141114` || No || -|| `RECURRENCE-ID:20141114T000000` || `20141114T000000` || No || -|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114` || `20141113T230000Z` || Yes || -|| `RECURRENCE-ID;TZID=Europe/Oslo:20141114T000000` || `20141113T230000Z` || Yes || -|| `RECURRENCE-ID:20141114T000000Z` || `20141114T000000Z` || Yes || +Identifiers without time zone information are not in themselves sufficient to +unambiguously define points in time, and thus additional time zone information +must be provided to obtain such time periods for such purposes as detecting +conflicts with other events. In the above examples, those normalised values +not providing a UTC datetime representation need further conversion to be +usable for period comparisons. Such further conversion would be done by +nominating a disambiguating time zone, such as the user's configured time +zone. -Identifiers without time zone information are not in themselves sufficient to unambiguously define points in time, and thus additional time zone information must be provided to obtain such time periods for such purposes as detecting conflicts with other events. In the above examples, those normalised values not providing a UTC datetime representation need further conversion to be usable for period comparisons. Such further conversion would be done by nominating a disambiguating time zone, such as the user's configured time zone. +By normalising identifiers using any object-resident time zone information, +imip-agent can use the resulting values without needing to consult the object +providing any redefined recurrence, knowing that any time zone information has +already been taken into consideration. Thus, all UTC-based datetimes used as +recurrence identifiers are readily usable for comparison purposes, whereas any +floating date or datetime values used as recurrence identifiers must need +additional conversion using the user's time zone to be usable. -By normalising identifiers using any object-resident time zone information, imip-agent can use the resulting values without needing to consult the object providing any redefined recurrence, knowing that any time zone information has already been taken into consideration. Thus, all UTC-based datetimes used as recurrence identifiers are readily usable for comparison purposes, whereas any floating date or datetime values used as recurrence identifiers must need additional conversion using the user's time zone to be usable. - -It might be thought that there would be correspondence between a recurrence identifier and the time zone details employed by the original object describing the redefined recurrence (such as the `TZID` attribute specified on an object's `DTSTART` property), and so any unqualified recurrence identifier might be converted to a UTC-based datetime using such time zone details. However, an assumption could equally be made that the recurrence identifier should inherit time zone details from the redefined recurrence instead. The only reasonable choice to be made when confronted with such ambiguity is to treat any unqualified identifier as a genuine floating date or datetime, and the normalisation process facilitates this strategy. +It might be thought that there would be correspondence between a recurrence +identifier and the time zone details employed by the original object +describing the redefined recurrence (such as the `TZID` attribute specified on +an object's `DTSTART` property), and so any unqualified recurrence identifier +might be converted to a UTC-based datetime using such time zone details. +However, an assumption could equally be made that the recurrence identifier +should inherit time zone details from the redefined recurrence instead. The +only reasonable choice to be made when confronted with such ambiguity is to +treat any unqualified identifier as a genuine floating date or datetime, and +the normalisation process facilitates this strategy. == Recurrences and Free/Busy Information == -Events employing recurrences on fixed occasions can be readily recorded in the free/busy information for a calendar user. However, iCalendar also permits recurrences that may potentially continue forever, and yet providing free/busy information for arbitrary periods in the future may either result in substantial computation or substantial demands on storage resources. Consequently, free/busy information may only be generated for a period ending at a certain point in the future defined in terms of days from the present. Within this period scheduling would make sense, and attempts to schedule events outside this period would succeed at the participant's own risk. +Events employing recurrences on fixed occasions can be readily recorded in the +free/busy information for a calendar user. However, iCalendar also permits +recurrences that may potentially continue forever, and yet providing free/busy +information for arbitrary periods in the future may either result in +substantial computation or substantial demands on storage resources. +Consequently, free/busy information may only be generated for a period ending +at a certain point in the future defined in terms of days from the present. +Within this period scheduling would make sense, and attempts to schedule +events outside this period would succeed at the participant's own risk. -Such a period where participant availability is known must be necessarily expanded as time progresses. One-off events, once recorded in the free/busy records, will not contribute further to expansions of those records. Recurring events, however, may provide additional periods of interest as the availability window moves forward in time. +Such a period where participant availability is known must be necessarily +expanded as time progresses. One-off events, once recorded in the free/busy +records, will not contribute further to expansions of those records. Recurring +events, however, may provide additional periods of interest as the +availability window moves forward in time. -To determine which events contribute recurrences, a list of objects (initially all objects known to a user that have not been cancelled) is consulted and their recurrence properties inspected. With such knowledge of recurring events, upon expanding the availability window, only these "known recurring" events need to be inspected for further contributions to the free/busy records, and those no longer contributing after a given point can be discarded from the list for future expansion of the window. Meanwhile, new events would need to be added to the list, at least if they were defined as providing recurrences that may occur in future availability periods. +To determine which events contribute recurrences, a list of objects (initially +all objects known to a user that have not been cancelled) is consulted and +their recurrence properties inspected. With such knowledge of recurring +events, upon expanding the availability window, only these "known recurring" +events need to be inspected for further contributions to the free/busy +records, and those no longer contributing after a given point can be discarded +from the list for future expansion of the window. Meanwhile, new events would +need to be added to the list, at least if they were defined as providing +recurrences that may occur in future availability periods. === Updating Free/Busy Records === -To update and thus expand availability information, it is suggested that a regularly scheduled task be used to consult the events known (or thought) to provide additional free/busy periods and to record such additional periods for each user. This can be done using a system's `cron` daemon and a suitable script in `/etc/cron.daily` or equivalent. Such a script is provided in the imip-agent distribution along with a program that can expand availability information for all known recipients of calendar information. +To update and thus expand availability information, it is suggested that a +regularly scheduled task be used to consult the events known (or thought) to +provide additional free/busy periods and to record such additional periods for +each user. This can be done using a system's `cron` daemon and a suitable +script in `/etc/cron.daily` or equivalent. Such a script is provided in the +imip-agent distribution along with a program that can expand availability +information for all known recipients of calendar information. diff -r fbef8dc092d3 -r 2caa4627f3aa docs/wiki/FrontPage --- a/docs/wiki/FrontPage Mon Oct 26 13:49:51 2015 +0100 +++ b/docs/wiki/FrontPage Mon Oct 26 14:05:25 2015 +0100 @@ -1,55 +1,97 @@ = imip-agent = -imip-agent is an extension for existing mail systems (such as Exim and Postfix) providing extra support for calendaring and scheduling. +imip-agent is an extension for existing mail systems (such as Exim and +Postfix) providing extra support for calendaring and scheduling. - * It uses the [[https://tools.ietf.org/html/rfc5545|iCalendar]], [[https://tools.ietf.org/html/rfc5546|iTIP]] and [[https://tools.ietf.org/html/rfc6047|iMIP]] Internet standards. + * It uses the [[https://tools.ietf.org/html/rfc5545|iCalendar]], + [[https://tools.ietf.org/html/rfc5546|iTIP]] and + [[https://tools.ietf.org/html/rfc6047|iMIP]] Internet standards. - * It can inspect messages containing calendar objects and extract availability information for sharing and publication. You and your users decide exactly which kind of messages it will inspect, whose messages it will inspect, and for whom no inspection or sharing will occur at all. + * It can inspect messages containing calendar objects and extract + availability information for sharing and publication. You and your users + decide exactly which kind of messages it will inspect, whose messages it + will inspect, and for whom no inspection or sharing will occur at all. - * It can provide a Web-based interface to calendar information for users who cannot or choose not to use mail software with calendaring support. This is optional and your users can choose to adjust, ignore or disable this functionality. + * It can provide a Web-based interface to calendar information for users who + cannot or choose not to use mail software with calendaring support. This is + optional and your users can choose to adjust, ignore or disable this + functionality. - * It supports autonomous entities such as meeting rooms and resources, automatically accepting or declining invitations according to their schedules. You can adjust this behaviour to implement your own policies. + * It supports autonomous entities such as meeting rooms and resources, + automatically accepting or declining invitations according to their + schedules. You can adjust this behaviour to implement your own policies. - * It is licensed as Free Software, giving you the freedom to see what the software does, as well as the freedom to modify and share the software with others. + * It is licensed as Free Software, giving you the freedom to see what the + software does, as well as the freedom to modify and share the software with + others. Unlike some monolithic groupware solutions... - * It does not require you to change your mail delivery software or your mail storage software (subject to existing support provided by imip-agent; support for other software can always be added). + * It does not require you to change your mail delivery software or your mail + storage software (subject to existing support provided by imip-agent; + support for other software can always be added). * It does not require your users to change their mail client software. - * It does not insist that everybody must store their schedules on a single server in order to collaboratively schedule events. + * It does not insist that everybody must store their schedules on a single + server in order to collaboratively schedule events. - * Instead, imip-agent takes advantage of the decentralized nature of the [[http://tools.ietf.org/html/rfc5545|iCalendar]] and [[http://tools.ietf.org/html/rfc5546|iMIP]] Internet standards. + * Instead, imip-agent takes advantage of the decentralized nature of the + [[http://tools.ietf.org/html/rfc5545|iCalendar]] and + [[http://tools.ietf.org/html/rfc5546|iMIP]] Internet standards. - * It allows people in your organisation to collaborate with people outside your organisation without insisting that they join your infrastructure or that everybody join some cloud service that keeps everyone's information within a single, typically proprietary, remote service (that may also be potentially vulnerable to intrusion and surveillance). + * It allows people in your organisation to collaborate with people outside + your organisation without insisting that they join your infrastructure or + that everybody join some cloud service that keeps everyone's information + within a single, typically proprietary, remote service (that may also be + potentially vulnerable to intrusion and surveillance). -The role of imip-agent is to bridge the gap between plain e-mail and "full-stack" groupware solutions, thus allowing organisations and individuals to augment their existing infrastructure instead of being compelled to perform costly and unnecessary migrations and infrastructure transformations. +The role of imip-agent is to bridge the gap between plain e-mail and +"full-stack" groupware solutions, thus allowing organisations and individuals +to augment their existing infrastructure instead of being compelled to perform +costly and unnecessary migrations and infrastructure transformations. == Adding Calendaring to E-Mail == -With just an e-mail system, users can already create and schedule calendar events using any mail or groupware client software that supports calendars and that already supports [[http://tools.ietf.org/html/rfc5545|iCalendar]] and [[http://tools.ietf.org/html/rfc6047|iMIP]]. +With just an e-mail system, users can already create and schedule calendar +events using any mail or groupware client software that supports calendars and +that already supports [[http://tools.ietf.org/html/rfc5545|iCalendar]] and +[[http://tools.ietf.org/html/rfc6047|iMIP]]. -Starting with an e-mail system, imip-agent can be used to add further support for calendaring: +Starting with an e-mail system, imip-agent can be used to add further support +for calendaring: {{{#!table '''Requirement''' || '''Solution''' == -Your users probably want to know when other people are available and when they are busy. -|| Although [[https://tools.ietf.org/html/rfc6047|iMIP]] supports this, most mail programs do not, so imip-agent will gather information about events and publish it for retrieval via HTTP. It will also respond to any iMIP requests for free/busy information via mail. +Your users probably want to know when other people are available and when they +are busy. +|| +Although [[https://tools.ietf.org/html/rfc6047|iMIP]] supports this, most mail +programs do not, so imip-agent will gather information about events and +publish it for retrieval via HTTP. It will also respond to any iMIP requests +for free/busy information via mail. == Organisations may want to coordinate access to resources using calendaring. -|| Here, imip-agent can provide autonomous agents that can respond to event invitations, allowing users to book resources and to see published availability information for those resources. +|| +Here, imip-agent can provide autonomous agents that can respond to event +invitations, allowing users to book resources and to see published +availability information for those resources. == -Some users may not be using mail programs that understand calendars and events. -|| Here, imip-agent can provide a Web interface to let them respond to invitations and to create and schedule their own events. +Some users may not be using mail programs that understand calendars and +events. +|| +Here, imip-agent can provide a Web interface to let them respond to +invitations and to create and schedule their own events. }}} -According to your requirements, any or all of the above solutions can be implemented, providing as much of a groupware solution as you need. +According to your requirements, any or all of the above solutions can be +implemented, providing as much of a groupware solution as you need. == Design and Implementation Notes == -Details of the mechanisms employed by imip-agent are described in the following documents: +Details of the mechanisms employed by imip-agent are described in the +following documents: * [[/CounterProposals|Counter-Proposals and Offers]] * [[/MailIntegration|E-Mail Integration]] diff -r fbef8dc092d3 -r 2caa4627f3aa docs/wiki/IncomingMessages --- a/docs/wiki/IncomingMessages Mon Oct 26 13:49:51 2015 +0100 +++ b/docs/wiki/IncomingMessages Mon Oct 26 14:05:25 2015 +0100 @@ -1,6 +1,9 @@ = Incoming Messages = -When messages are received by the MTA for a recipient, imip-agent employs message rules in the MTA to provide handlers to inspect any calendar-related content and to update its records. Different handlers are provided to process incoming messages depending on the nature of the eventual recipient: +When messages are received by the MTA for a recipient, imip-agent employs +message rules in the MTA to provide handlers to inspect any calendar-related +content and to update its records. Different handlers are provided to process +incoming messages depending on the nature of the eventual recipient: People:: Handled by the person handler Resources:: Handled by the resource handler @@ -12,62 +15,74 @@ For people, the operation of the person handler is as follows: {{{#!table - '''Method''' || - '''Effect on Objects''' || - '''Effect on Free/Busy''' || - '''Effect on Request Queue''' + '''Method''' +|| '''Effect on Objects''' +|| '''Effect on Free/Busy''' +|| '''Effect on Request Queue''' == ''for recipient's own record'' || ''for recipient's record of others'' == -`CANCEL` || -Set the state of the cancelled event, retaining it for future reference || -Remove record if the event is cancelled for the attendee (even if the event is not completely cancelled) || - Update the recipient's free/busy record for the organiser || -Remove any queue entry +`CANCEL` +|| Set the state of the cancelled event, retaining it for future reference +|| Remove record if the event is cancelled for the attendee (even if the event +.. is not completely cancelled) +|| Update the recipient's free/busy record for the organiser +|| Remove any queue entry == -`PUBLISH` || - Add or update object, removing specific recurrences of recurring events || - || -No modification to the queue +`PUBLISH` +|| Add or update object, removing specific recurrences of + .. recurring events +|| +|| No modification to the queue == -`REQUEST` || -Add a queue entry for the event +`REQUEST` +|| Add a queue entry for the event == -`REPLY` || -Merge attendee participation information || -Update the recipient's free/busy record for each of the attendees || -No modification to the queue +`REPLY` +|| Merge attendee participation information +|| Update the recipient's free/busy record for each of the attendees +|| No modification to the queue }}} -The effect of the person handler is to ensure that the user's record of the free/busy status for ''other participants'' reflects the consequences of those participants' stated attendance of events, and for the object records to reflect the most recent state of each event. +The effect of the person handler is to ensure that the user's record of the +free/busy status for ''other participants'' reflects the consequences of those +participants' stated attendance of events, and for the object records to +reflect the most recent state of each event. -Note that the free/busy information for a recipient of an event is not generally changed when receiving a message. Such information is only definitively changed by recipients themselves when responding to incoming messages, and the [[../OutgoingMessages|outgoing messages]] processing is concerned with updating that information as such responses are sent. +Note that the free/busy information for a recipient of an event is not +generally changed when receiving a message. Such information is only +definitively changed by recipients themselves when responding to incoming +messages, and the [[../OutgoingMessages|outgoing messages]] processing is +concerned with updating that information as such responses are sent. For resources, the operation of the resource handler is as follows: {{{#!table - '''Method''' || - '''Effect on Objects''' || - '''Effect on Free/Busy''' || - '''Effect on Request Queue''' + '''Method''' +|| '''Effect on Objects''' +|| '''Effect on Free/Busy''' +|| '''Effect on Request Queue''' == ''for recipient's own record'' || ''for recipient's record of others'' == -`CANCEL` || -Set the state of the cancelled event, retaining it for future reference || -Remove record if the event is cancelled for the attendee (even if the event is not completely cancelled) || - No records of other participants are employed by the resource handler || - No queue is employed by the resource handler +`CANCEL` +|| Set the state of the cancelled event, retaining it for future reference +|| Remove record if the event is cancelled for the attendee (even if the event +.. is not completely cancelled) +|| No records of other participants are employed by the resource + .. handler +|| No queue is employed by the resource handler == -`PUBLISH` || - Ignored by the resource handler +`PUBLISH` +|| Ignored by the resource handler == -`REQUEST` || -Add or update object, removing specific recurrences of recurring events || -Attempt to schedule the event, creating or updating records for the recipient +`REQUEST` +|| Add or update object, removing specific recurrences of recurring events +|| Attempt to schedule the event, creating or updating records for the +.. recipient == -`REPLY` || - Ignored by the resource handler +`REPLY` +|| Ignored by the resource handler }}} == Other Object Types == diff -r fbef8dc092d3 -r 2caa4627f3aa docs/wiki/MailIntegration --- a/docs/wiki/MailIntegration Mon Oct 26 13:49:51 2015 +0100 +++ b/docs/wiki/MailIntegration Mon Oct 26 14:05:25 2015 +0100 @@ -1,12 +1,24 @@ = E-Mail Integration = -To act as a part of an e-mail system, imip-agent provides a number of programs that may be invoked by mail transfer agents (MTAs) upon sending or receiving messages. In order to uphold portability and to minimise configuration issues, these programs need only be registered as simple mail handlers or transports, thus potentially supporting a wide range of MTAs. +To act as a part of an e-mail system, imip-agent provides a number of programs +that may be invoked by mail transfer agents (MTAs) upon sending or receiving +messages. In order to uphold portability and to minimise configuration issues, +these programs need only be registered as simple mail handlers or transports, +thus potentially supporting a wide range of MTAs. -Once imip-agent has processed a message, it may then deliver it to its intended recipient. The mail storage systems that may receive messages from imip-agent need only support the delivery mechanisms used by imip-agent. Otherwise, few constraints should be imposed by each kind of system on the other. +Once imip-agent has processed a message, it may then deliver it to its +intended recipient. The mail storage systems that may receive messages from +imip-agent need only support the delivery mechanisms used by imip-agent. +Otherwise, few constraints should be imposed by each kind of system on the +other. == MTAs == -Currently, imip-agent supports [[http://exim.org/|Exim]] and [[http://www.postfix.org/|Postfix]], although this support should be readily broadened, and offers configuration resources for these supported systems so as to allow imip-agent to be deployed within existing mail-sending and delivery infrastructures. +Currently, imip-agent supports [[http://exim.org/|Exim]] and +[[http://www.postfix.org/|Postfix]], although this support should be readily +broadened, and offers configuration resources for these supported systems so +as to allow imip-agent to be deployed within existing mail-sending and +delivery infrastructures. {{{#!table || '''Identifying Recipients''' || '''Integrating imip-agent''' || '''Notes''' @@ -14,17 +26,22 @@ '''Exim''' || Routers identify recipients of mail that shall be handled by imip-agent || Transports invoke imip-agent programs -|| Exim is widely deployed as the default MTA for Debian. Consequently, it is desirable to support this software in imip-agent. +|| Exim is widely deployed as the default MTA for Debian. Consequently, it is + desirable to support this software in imip-agent. == '''Postfix''' -|| Virtual aliases identify recipients of mail that shall be handled by imip-agent +|| Virtual aliases identify recipients of mail that shall be handled by +.. imip-agent || Transports invoke imip-agent programs || Postfix is also widely deployed and is sometimes preferred by administrators. }}} == Identification of Recipients == -In principle, any mechanism supported by the MTA can be used to identify recipients; imip-agent does not employ identification mechanisms of its own. Thus, the task of identifying recipients is one of MTA configuration, with the following mechanisms tested: +In principle, any mechanism supported by the MTA can be used to identify +recipients; imip-agent does not employ identification mechanisms of its own. +Thus, the task of identifying recipients is one of MTA configuration, with the +following mechanisms tested: {{{#!table '''Identification Mechanisms''' || '''Tested with...''' @@ -36,4 +53,9 @@ == Delivery == -To deliver messages to their ultimate recipients after having processed them, imip-agent currently employs either local SMTP connections or [[https://tools.ietf.org/html/rfc2033|LMTP]]. There is nothing in principle preventing imip-agent from also supporting other common delivery mechanisms, however. Currently, Cyrus-IMAP and Dovecot have both been tested with imip-agent, along with delivery to local system users. +To deliver messages to their ultimate recipients after having processed them, +imip-agent currently employs either local SMTP connections or +[[https://tools.ietf.org/html/rfc2033|LMTP]]. There is nothing in principle +preventing imip-agent from also supporting other common delivery mechanisms, +however. Currently, Cyrus-IMAP and Dovecot have both been tested with +imip-agent, along with delivery to local system users. diff -r fbef8dc092d3 -r 2caa4627f3aa docs/wiki/OutgoingMessages --- a/docs/wiki/OutgoingMessages Mon Oct 26 13:49:51 2015 +0100 +++ b/docs/wiki/OutgoingMessages Mon Oct 26 14:05:25 2015 +0100 @@ -1,32 +1,47 @@ = Outgoing Messages = -When messages are sent by a mail client, imip-agent employs an outgoing message rule in the MTA to provide a handler to inspect any calendar-related content and to update its records. +When messages are sent by a mail client, imip-agent employs an outgoing +message rule in the MTA to provide a handler to inspect any calendar-related +content and to update its records. -The management interface does not use this outgoing message rule because it sends messages from the general calendar address (for example, `calendar@example.com`), and there is no trivial way of deducing the identity of the real sender. Instead, the manager explicitly sends suitably-modified messages to the address of the user operating the interface to achieve the same effect as the outgoing message rule, as well as to notify any mail clients that would normally be managing calendar events on behalf of the user. +The management interface does not use this outgoing message rule because it +sends messages from the general calendar address (for example, +`calendar@example.com`), and there is no trivial way of deducing the identity +of the real sender. Instead, the manager explicitly sends suitably-modified +messages to the address of the user operating the interface to achieve the +same effect as the outgoing message rule, as well as to notify any mail +clients that would normally be managing calendar events on behalf of the user. == Events == {{{#!table -'''Method''' || '''Effect on Objects''' || '''Effect on Free/Busy''' || '''Effect on Request Queue''' +'''Method''' || '''Effect on Objects''' || '''Effect on Free/Busy''' +|| '''Effect on Request Queue''' == -`CANCEL` || -Remove selected attendees or an entire event || -Remove record if entire event is cancelled || - Remove any queue entry +`CANCEL` +|| Remove selected attendees or an entire event +|| Remove record if entire event is cancelled +|| Remove any queue entry == -`PUBLISH` || - Add or update object, removing specific recurrences of recurring events || - Add record for the event, removing records for specific recurrences of an event +`PUBLISH` +|| Add or update object, removing specific recurrences of + .. recurring events +|| Add record for the event, removing records for specific + .. recurrences of an event == `REQUEST` == -`REPLY` || -Merge attendee participation information || -Update records for the event, preserving specific recurrence records when changing a recurring event +`REPLY` +|| Merge attendee participation information +|| Update records for the event, preserving specific recurrence records when +.. changing a recurring event }}} -The effect of the outgoing handler is to ensure that the user's free/busy status reflects the consequences of their stated attendance of events, and for the object records to reflect the most recent state of each event. +The effect of the outgoing handler is to ensure that the user's free/busy +status reflects the consequences of their stated attendance of events, and for +the object records to reflect the most recent state of each event. == Other Object Types == -Other object types are not handled. Free/busy information, if exchanged, is not obtained by the handler to replace its own records. +Other object types are not handled. Free/busy information, if exchanged, is +not obtained by the handler to replace its own records. diff -r fbef8dc092d3 -r 2caa4627f3aa docs/wiki/UseCases --- a/docs/wiki/UseCases Mon Oct 26 13:49:51 2015 +0100 +++ b/docs/wiki/UseCases Mon Oct 26 14:05:25 2015 +0100 @@ -1,13 +1,20 @@ = Use Cases = -Some situations where the imip-agent framework can provide automation opportunities. +Some situations where the imip-agent framework can provide automation +opportunities. == Room and Resource Booking == * Enforce booking privileges - * Enforce booking "budgets" to prevent people booking too many things or booking things simultaneously that they will attend - * Support pools of resources where one address may be responsible for multiple units that are not individually identified at the time of booking - * Support duration limits and start/end time granularity, using `COUNTER` to suggest acceptable periods + + * Enforce booking "budgets" to prevent people booking too many things or + booking things simultaneously that they will attend + + * Support pools of resources where one address may be responsible for + multiple units that are not individually identified at the time of booking + + * Support duration limits and start/end time granularity, using `COUNTER` to + suggest acceptable periods == Appointment Booking == @@ -20,11 +27,19 @@ == Event Polls == -Event voting is effectively the gathering of free/busy information from participants followed by the selection of a specific period by an organiser. +Event voting is effectively the gathering of free/busy information from +participants followed by the selection of a specific period by an organiser. + + 1. Free/busy information is solicited from potential recipients by the + organiser. - 1. Free/busy information is solicited from potential recipients by the organiser. - 1. Recipients respond with details of their availability (typically emphasising when they are free for the event, busy otherwise). - 1. The organiser then decides on a free period and notifies all free participants as normal. + 1. Recipients respond with details of their availability (typically + emphasising when they are free for the event, busy otherwise). + + 1. The organiser then decides on a free period and notifies all free + participants as normal. + 1. Recipients respond as normal to the event invitation. -A Web interface would merely provide a direct means of indicating event-specific free/busy information. +A Web interface would merely provide a direct means of indicating +event-specific free/busy information. diff -r fbef8dc092d3 -r 2caa4627f3aa docs/wiki/WebServerIntegration --- a/docs/wiki/WebServerIntegration Mon Oct 26 13:49:51 2015 +0100 +++ b/docs/wiki/WebServerIntegration Mon Oct 26 14:05:25 2015 +0100 @@ -1,12 +1,19 @@ = Web Server Integration = -Although imip-agent is mostly concerned with e-mail messaging, it can integrate with a Web server for the following purposes: +Although imip-agent is mostly concerned with e-mail messaging, it can +integrate with a Web server for the following purposes: * To publish free/busy information for calendar users * To provide a management interface for calendar users -Currently, imip-agent provides configuration files for Apache, but other Web servers may also be supported. +Currently, imip-agent provides configuration files for Apache, but other Web +servers may also be supported. == Authentication and Access Control == -Apache supports a range of mechanisms for protecting resources and authenticating users. Most usefully for imip-agent given the [[../MailIntegration|e-mail integration]] requirements, modules supporting [[http://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html|LDAP]] and [[http://httpd.apache.org/docs/2.4/mod/mod_auth_basic.html|simple text-based lists of users]] are available for such purposes. +Apache supports a range of mechanisms for protecting resources and +authenticating users. Most usefully for imip-agent given the +[[../MailIntegration|e-mail integration]] requirements, modules supporting +[[http://httpd.apache.org/docs/2.4/mod/mod_authnz_ldap.html|LDAP]] and +[[http://httpd.apache.org/docs/2.4/mod/mod_auth_basic.html|simple text-based +lists of users]] are available for such purposes.