HOME

5h-3LL 1.0
DIR: /srv/http/vyvoj.adent.cz/egroupware/pfi/icalsrv/doc
/srv/http/vyvoj.adent.cz/egroupware/pfi/icalsrv/doc/
Current File : /srv/http/vyvoj.adent.cz/egroupware/pfi/icalsrv/doc/IcalSrv-Overview.dox
/*!  @mainpage  Simple Ical Service NG for Egroupware

@note this is still <b>EXPERIMENTAL, USE AT YOUR OWN RISK! </b> and better not yet in a
production environment.
@version 0.9.37-ng-a1
@author jvl 
@date 20060427

@note <b>you need to have package EgwIcal in version >= 0.9.30-ng to be able to
 use this icalsrv-ng version!</b>

@section icalsrvsecabout About IcalSrv NG

IcalSrv NG is a rewrite of the old IcalSrv service that allows an
<i>ical client</i> (see @ref secicalsrvclients) like Mozilla Sunbird,
Apple iCal or Korganizer to access the events and tasks from a persons
egroupware calendar and infolog application, remotely via a "icalendar
over http" connection. See @url http://en.wikipedia.org/wiki/ICalendar for
more info on this format.

This means that in the client you can download (aka <i> reload </i>)
the data from an a socalled <i> subscribed </i> virtual calendar on the
egroupware server and then read and manipulate it offline.  On a
later moment you can upload (aka <i> publish </i>) this client
calendardata again to egroupware. The changes made in your client
should then propagate to your calendars and infolog maintained on the
egw server. All this, provided you have the appropiate access rights
for the egroupware server data.

Given this functionality you can use an ical client in combination with
Egroupware in two typical use cases:

- ical client used as a <b>connected (Rich) Web Client</b> for Egw
  <br/>
   In this case the client is just used to access the Egroupware server
  via an internet connection as an alternative for a web browser.
  The benefits of accessing Egw
  by a client like Sunbird instead of by a browser maybe related to an
  increase in speed, a better overview, availability of a single known gui for the user,
  the capability of comparing many (remote and local) calendars at once in
  the gui etc. etc.

- ical client used as a <b>semi connected mobile Client</b> for Egw
  <br/>
  In this case the client is not constantly connected to the Egw
  Server, but only at some times, when it synchronyzes its data with
  the Egw server.
  Using your client this way obviously puts an extra functionality to
  your Egw calendar: you can work with it while not connected to it!
 <br/>
  Though nice at it seems, this is certainly not without problems. Some of these
  problems are mentioned in @ref pagewebcaldiscussion . However by clever use
  of the features of a client (like e.g. multiple calendars, local calendars etc.)
  you probably overcome these problems and use you client benificially in this semi 
  connected mode. See for client specific details the info @ref pageicalsrvclients .

At the moment, the IcalSrv service is still a simple --experimental-- variant
that is not based on webdav (as most of these services), but that can
prove evertheless  to be quite practical. 

@section secoverviewvcs Virtual Calendars

In the current NG (new generation) version it is based on the idea that you access
a <em> Virtual Calendar </em> that defines a set of events and tasks found
in your Egroupware server. To  see what virtual calendars are provided
by IcalSrv in your Egroupware server you can acces the Egroupware
server via a special url. This gives you, possibly after some form of
authentication, an overview of the available virtual calendars. 
These virtual calendars come in two variants:
- system virtual calendars that do not dependent on a user for their definition.
  For these you can get a listing  via the url: 
  @url http://myserver.com/egroupware/icalsrv.php/list.html

- personal virtual calendars that hold a definition for calendars based on
  user settings.   You get a listing of the supported personal virtual
  calendars for lets say <em>userX</em> via the url: 
  @url http://myserver.com/egroupware/icalsrv.php/userX/list.html
  If you have enough rights granted by <em>userX</em> you can use
  the urls in this list to access his virtual calendars.
  <br/>
  Currently the set of virtual calendars is already predefined by the
  implementation, only the access rights can be set by a user. In some
  future version we want to extend the system to allow users to define
  their own personal calendars

\subsection secwarning Some important issues and warnings

For the latest state of bugs and problems please have a look at the
info in @ref pageicalsrvreleaselog

At the moment IcaSrv allows only upload and download of complete
(virtual) calendars (with events and todos) and no direct deletions of
events. (Read more on this in the FAQ  at @ref icalsrvqa_deletions )

We are working on extensions towards real groupdav and caldav behaviour.

@note We tried to prevent that accidental misuse of the service can ruin all
your egroupware data. But, <b> be warned: when you use the service for
<i>publishing</i> from the client, you can (and want to) change data
in the egroupware server, and thus you have a potential risk of damaging
or losing egroupware data!</b>

One well known danger is the loss of multiple egroupware categories
attributed to an event or task when you publish calendars from a
client that doesnot allow multiple categories. In this case the
single, client attributed, category will replace the original egw
attributed set.   Mozilla Sunbird is notably such a 'single category only" client.

For behaviour of the various clients see futher in @ref pageicalsrvclients

@note At the moment (v 0.9.3X) the development of the virtual calendars (see
@ref secoverviewvcs ) has just started, so be sure to check to current
state of these in the releaselog.

@note The latest versions (>v0.9.30) have been developed with php5 and
apache2. Al though we try to keep it all compatible with php4, it may
be the case that some problems come up if you use icalsrv with
php4. Please report via mailinglist or bug list if you found some. See
below for bug reporting.

@section secinstall SHORT experimental Install How-To:
		 
 - Best thing to do before installing, is to have a look at the
   egroupware wiki page about IcalSrv
   at @url http://www.egroupware.org/egroupware/wiki/index.php?page=IcalSrv
   .
   There you can find the current status of the project and see what
   the latest available versions are and where to find them. In @ref pageicalsrvreleaselog
   you find a release notes document that tells about bugs and changes in
   the releases.

 - Install the latest icalsrv package by either untarring some tarball icalsrv-vx.y.x.tgz of the
  package (if available) or by checking out the icalsrv stuff from
cvs. Or just use the version available in the standard Egroupware install
(either in the main or the contrib or from a rpm or debian package).
  At the moment (200603xx) the icalsrv is partly (the file icalsrv.php) in cvs module
  <i>egroupware</i> and for the rest in module <i>icalsrv</i>.
  So be sure to update both (file) icalsrv.php and (folder) icalsrv when using cvs.
 - @note The IcalSrv package depends on the availability of an
   EgwIcal (>= 0.9.30) package. So if you dont have this already, be sure
   to install that too. Likewise this can be installed by untarring an appropiate
   egwical-vx.y.z.tgz tarball or by checking out the <i> egwical</i> module from cvs.
   
 - Take care that icalsrv.php is <code>.../egroupware/icalsrv.php</code>
   (and that the other files from the icalsrv package are also in their appropiate places)

- If your install (shouldnot be needed anymore after egw1.2RC8) didnot provide a icalsrv
  catered version of the
  httpd.conf, you should manually add a small piece of extra lines. 
  That is, append something like the following onto your apache httpd.conf part	
  for egroupware (assuming that your standard egroupware root path is
  e.g in <code>/var/www/egroupware</code> and with a http alias
 <code>egroupware</code> pointing to it):
<PRE>
 <Location /egroupware/icalsrv.php>
    Script PUT /var/www/egroupware/icalsrv.php
    AddHandler ical/ics .ics
    Action ical/ics /var/www/egroupware/icalsrv.php
    AcceptPathInfo On
    Order allow,deny
    Allow from all
 </Location>
</PRE>

- In apache you need to make sure that you have a @em mod_actions moduler enabled,
  to get the Script directive to work.
  See e.g. the apache manual in @url http://www.apachefreaks.com/apache2/mod/mod_actions.html
  In Debian you can do this by <code>a2enmod actions</code>

- Restart apache (or other webserver) ( /etc/init.d/httpd restart )

- Now you can get an overview of the available virtual calendars by
  pointing your browser to
  http://your.host.com/egroupware/icalsrv.php/list.html .
  <br/>
  In there you will probably find that under
  <code>/default.ics</code> there is a standard virtual calendar available.		
		
- To use this virtual calendar, connect your ical client (e.g: Sunbird)
	   with http://your.host.com/egroupware/icalsrv.php/default.ics
        
- now you probably need to authenticate (with your normal EGW login and password)
  and when done you receive the calendar on doing a "reload remote calendars" or so.
  This should give you a default calendar of your personal events and tasks
  @note If have not set your egw domain to default (in header.inc.php), authentication
  probably wont succeed. In this case you can add your domain to the url by a domain parameter.
  The url for the list will then become something like:
   http://your.host.com/egroupware/icalsrv.php/list.html?domain=myegwdomain 

- if you use the same url in your clients settings for "calendar publishing",
  you should be able to write the (modified) calendar from the sunbird client back to
  EGW.


@section secicalsrvclients Clients for IcalSrv

In @ref pageicalsrvclients you can find some details on how to use the
various ical clients together with IcalSrv. Screenshots, User experiences, a bit on
supported features and hints on how to use a client for online and
offline usage may be found there.

A short list of known ical clients (some tested some not) is:

- Korganizer (3.3.2,(read)  3.4.2, 3.5.0 (READ+WRITE))<br/>
   (see @url http://korganizer.kde.org/ )
- Mozilla Sunbird (v2.2 linux, v2.3+ linux)(READ+WRITE)<br/>
  (see @url http://www.mozilla.org/projects/calendar/sunbird.html)
- Mozilla Calendar (2004040813-cal) (READ+WRITE)<br/>
  (see @url http://www.mozilla.org/projects/calendar)
- Apple Ical, (version ? reported to be working). (READ+WRITE)<br/>
  (see @url http://www.apple.com/macosx/features/ical/ )
- Evolution 2.2 (READ)<br/>
  (see @url http://www.novell.com/products/desktop/features/evolution.html )
- Outlook 2003 with RemoteCalendars-plugin (version 4.0 UNTESTED) <br/>
  (see @url http://sourceforge.net/projects/remotecalendars )
- Yagoon Time (version ?, UNTESTED)<br/>
  (see @url http://www.yagoon.com )
- Rainlendar (version ?, UNTESTED)<br/>
  (see http://www.rainlendar.net )
- ....

The testing was with egw1.2rc9. ;-)

For an overview of more icalendar clients see e.g.
@url http://microformats.org/wiki/icalendar-implementations 



@section secdocumentation Documentation

There is (somewhere) complete doxygen generated documentation for the
IcalSrv package. Otherwise you can generate it yourself by using
doxygen on the source filetree. Maybe you are just reading it now ...

Make sure that you also read the FAQ in @ref pageicalsrvfaq , the
Release Notes in @ref pageicalsrvreleaselog and the Clients Overview in 
@ref pageicalsrvclients


@section sectestandebug Testing and Debugging

As IcalSrv is still a young and experimental new service for
Egroupware, that must mediate between a multitude of clients, each
with their own peculiarities and the various internal applications of Egw,
it is very likely that a lot of problems, deficiencies and bugs will
appear. 

Thus to get error feedback for it is a healthy thing. You should best
do this --as with any egw application-- by following the guidelines
See the egroupware wiki at @url http://www.egroupware.org/bug-reports
for more instructions on this)

This will point you to the sourceforge.net Egroupware buglist at @url
https://sourceforge.net/tracker/?group_id=78745&atid=554338 and the
dedicated egroupware forums or mailinglist at @url
http://www.egroupware.org/forum/?page_name=forum

What to report? Well you should realize that IcalSrv is --currently--
on it self just a rather simple http interface script, that relies for
its connection to the egw backends heavily on the new (re) written
EgwIcal package. This means that problems with in and export of
iCalendar data will mostly have their source in that (i.e. EgwIcal)
package! So in case of errors allways report info on that package and
when debugging try the debug tools for that package.


@section icalsrvroadmap The IcalSrv future

At some time we hope to provide the ability to let users configure their own calendars
by setting search periods, access grants and possibly other criteria.

Later on we want to work towards GroupDav and CalDAV extended functionality.

...


have fun
 

JVL


*/