# HG changeset patch # User Paul Boddie # Date 1446571940 -3600 # Node ID 1bb2fa5e2dd4f437a869857f2c758ade4939bd1e # Parent d72c57e949d8d5a8778c32e4d6fc5f4a2e44af9c# Parent 4f54b5b465cac05d82e6737c8d07134c2f8ef4d1 Merged temporary branches. diff -r d72c57e949d8 -r 1bb2fa5e2dd4 docs/images/imip-agent-logo.svg --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/images/imip-agent-logo.svg Tue Nov 03 18:32:20 2015 +0100 @@ -0,0 +1,208 @@ + + + + diff -r d72c57e949d8 -r 1bb2fa5e2dd4 docs/wiki/Administration --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Administration Tue Nov 03 18:32:20 2015 +0100 @@ -0,0 +1,93 @@ += Administering imip-agent = + +With imip-agent deployed, usage of the software should occur automatically. +However, evidence of its operation will only emerge when calendar-related +messages are exchanged between e-mail users. This will cause a few different +things to happen: + + * Summary messages may be sent by the calendar system to mail recipients + + * Replies to calendar-related messages may be received by the senders of + those messages + + * Free/busy information will become available, either in responses to + requests sent over e-mail, or [[../FreeBusyPublishing|over the Web]] + +In the background, imip-agent uses and updates information as described in the +[[../FilesystemUsage|filesystem usage guide]]. + +== Creating User Data Stores == + +The [[../MailIntegration|mail system]] mechanisms are responsible for +determining whether a valid recipient has been specified in any given message, +and imip-agent does not attempt to validate such information again. Therefore, +when a message is received for a calendar user for whom no data store has been +initialised in the [[../FilesystemUsage|filesystem]], the software will +automatically create one. + +Consequently, users for whom such data stores have been created will experience +the software using the default configuration, described in the +[[../Preferences|preferences guide]]. It is for this reason that the default +values in the [[../Configuration|configuration]] should be adjusted according +to the policies decided for the deployment of this software. + +However, it is possible to create data stores for users in advance using the +`tools/init_user.sh` script as in the following example: + +{{{ +tools/init_user.sh mailto:vincent.vole@example.com +}}} + +Here, the user identity is given as a URI since this is how iCalendar references +participants in scheduling operations. The result of the above command should be +some new directories in the [[../FilesystemUsage|filesystem area]] dedicated to +calendar information storage. + +=== Initialising Resources === + +Resources belong to a class of user whose preferences should be configured in +advance because their policies may differ on a case-by-case basis. For example, +some resources may benefit from employing the `permitted_times` setting so that +a granularity on event times may be imposed, meaning that such resources would +be "handed over" at regular intervals. + +The `freebusy_offers` setting, together with the `scheduling_function` setting, +would allow different kinds of resources to "keep open" tentatively-suggested +periods for different lengths of time, allowing frequently-requested resources +to respond to scheduling requests in a timely fashion, whilst also allowing +other resources to give more time to event organisers to respond to their +counter-proposals. + +=== Adjusting Preferences === + +Once initialised, the user preferences can be adjusted by adding files to the +`preferences` directory created by the above command. For example, if a user has +elected to not participate in the calendar system, a file called `participating` +can be added as follows: + +{{{ +echo 'no' > '/var/lib/imip-agent/preferences/mailto:vincent.vole@example.com/participating' +}}} + +Here, the default storage location has been given in the filename. + +Normally, users should visit the [[../CalendarManager|management interface]] to +change their preferences, but modifications done by administrators are more +efficiently performed by directly interacting with the filesystem. For example, +an administrator might initialise the common names of users by scripting changes +to the `CN` file for each user, obtaining such names from some kind of database. + +== Excluding Users Entirely == + +Since the [[../AgentPrograms|agent programs]] are installed as part of the mail +handling workflow, even the configuration of non-participation in the calendar +system for users will still result in those users' messages being passed along +the workflow by imip-agent, which may result in a decrease in general mail +delivery performance. + +To exclude users entirely, the routing configuration of the +[[../MailIntegration|MTA]] needs to be changed so that such users identities are +not recognised as calendar system participants, thus preventing their messages +from being routed via imip-agent. This is as simple as either not listing the +identity in [[../MailIntegration/Simple|lists of addresses]] or by adjusting +[[../MailIntegration/LDAP|queries yielding calendar users]]. diff -r d72c57e949d8 -r 1bb2fa5e2dd4 docs/wiki/AgentPrograms --- a/docs/wiki/AgentPrograms Tue Nov 03 18:30:31 2015 +0100 +++ b/docs/wiki/AgentPrograms Tue Nov 03 18:32:20 2015 +0100 @@ -39,3 +39,25 @@ One exception is the `imip_person.py` program that needs to be told whether it will deliver messages using [[../MailIntegration/LMTP|LMTP]] with the `-l` option or using [[../MailIntegration/LocalSMTP|SMTP]] with the `-L` option. + +== Program Responsibilities == + +The person agent programs or "handlers", `imip_person.py` and +`imip_person_outgoing.py` are responsible for keeping the schedule of each +participating calendar user up to date with the requests that are sent and +received by that user. Their roles are limited to recording data along with +a small amount of automation: they can be [[../Preferences|configured]] to +reply to free/busy requests without requesting any intervention on the part +of the user receiving such requests. + +Such handlers may be enhanced to perform more tasks autonomously, so that +certain requests might be dealt with automatically, according to policies +defined by each user. See the [[../UseCases|use-cases guide]] for some +potentially-implementable ideas. + +Meanwhile, the resource handler, `imip_resource.py`, is responsible not only +for maintaining a schedule for a resource, but it must also make scheduling +decisions itself without human involvement. How it may behave is determined +by a number of policies set in the [[../Preferences|preferences]] so that, +for example, it may suggest alternative event periods when those requested +in an invitation are unavailable. diff -r d72c57e949d8 -r 1bb2fa5e2dd4 docs/wiki/FrontPage --- a/docs/wiki/FrontPage Tue Nov 03 18:30:31 2015 +0100 +++ b/docs/wiki/FrontPage Tue Nov 03 18:32:20 2015 +0100 @@ -2,7 +2,8 @@ {{{#!table [[/Downloads|Downloads]] || [[/GettingStarted|Getting started]] || -[[#Deployment|Deployment]] || [[#Notes|Design/Implementation Notes]] +[[#Deployment|Deployment]] || [[#Notes|Design/Implementation Notes]] || +[[/CalendaringSupport|Support for Standards]] }}} imip-agent is an extension for existing mail systems (such as @@ -131,12 +132,17 @@ <> == Deploying the Software == +Initial activities: + * [[/Downloads|Downloads]] * [[/GettingStarted|Getting Started]] + +References: + + * [[/Administration|Administering imip-agent]] * [[/Configuration|Configuration]] and [[/Preferences|Preferences]] * [[/CalendarManager|Calendar Management Interface]] * [[/FreeBusyPublishing|Free/Busy Publishing]] - * [[/Usage|Usage]] <> == Design and Implementation Notes == @@ -144,6 +150,7 @@ Details of the mechanisms employed by imip-agent are described in the following documents: + * [[/AgentPrograms|Agent Programs]] * [[/CalendaringSupport|Calendaring Support]] * [[/CounterProposals|Counter-Proposals and Offers]] * [[/CronIntegration|Cron Task Scheduler Integration]] diff -r d72c57e949d8 -r 1bb2fa5e2dd4 docs/wiki/Usage --- a/docs/wiki/Usage Tue Nov 03 18:30:31 2015 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,78 +0,0 @@ -= Using imip-agent = - -With imip-agent deployed, usage of the software should occur automatically. -However, evidence of its operation will only emerge when calendar-related -messages are exchanged between e-mail users. This will cause a few different -things to happen: - - * Summary messages may be sent by the calendar system to mail recipients - - * Replies to calendar-related messages may be received by the senders of - those messages - - * Free/busy information will become available, either in responses to - requests sent over e-mail, or [[../FreeBusyPublishing|over the Web]] - -In the background, imip-agent uses and updates information as described in the -[[../FilesystemUsage|filesystem usage guide]]. - -== Creating User Data Stores == - -The [[../MailIntegration|mail system]] mechanisms are responsible for -determining whether a valid recipient has been specified in any given message, -and imip-agent does not attempt to validate such information again. Therefore, -when a message is received for a calendar user for whom no data store has been -initialised in the [[../FilesystemUsage|filesystem]], the software will -automatically create one. - -Consequently, users for whom such data stores have been created will experience -the software using the default configuration, described in the -[[../Preferences|preferences guide]]. It is for this reason that the default -values in the [[../Configuration|configuration]] should be adjusted according -to the policies decided for the deployment of this software. - -However, it is possible to create data stores for users in advance using the -`tools/init_user.sh` script as in the following example: - -{{{ -tools/init_user.sh mailto:vincent.vole@example.com -}}} - -Here, the user identity is given as a URI since this is how iCalendar references -participants in scheduling operations. The result of the above command should be -some new directories in the [[../FilesystemUsage|filesystem area]] dedicated to -calendar information storage. - -=== Adjusting Preferences === - -Once initialised, the user preferences can be adjusted by adding files to the -`preferences` directory created by the above command. For example, if a user has -elected to not participate in the calendar system, a file called `participating` -can be added as follows: - -{{{ -echo 'no' > '/var/lib/imip-agent/preferences/mailto:vincent.vole@example.com/participating' -}}} - -Here, the default storage location has been given in the filename. - -Normally, users should visit the [[../CalendarManager|management interface]] to -change their preferences, but modifications done by administrators are more -efficiently performed by directly interacting with the filesystem. For example, -an administrator might initialise the common names of users by scripting changes -to the `CN` file for each user, obtaining such names from some kind of database. - -== Excluding Users Entirely == - -Since the [[../AgentPrograms|agent programs]] are installed as part of the mail -handling workflow, even the configuration of non-participation in the calendar -system for users will still result in those users' messages being passed along -the workflow by imip-agent, which may result in a decrease in general mail -delivery performance. - -To exclude users entirely, the routing configuration of the -[[../MailIntegration|MTA]] needs to be changed so that such users identities are -not recognised as calendar system participants, thus preventing their messages -from being routed via imip-agent. This is as simple as either not listing the -identity in [[../MailIntegration/Simple|lists of addresses]] or by adjusting -[[../MailIntegration/LDAP|queries yielding calendar users]].