forked from extern/egroupware
204 lines
8.3 KiB
Plaintext
204 lines
8.3 KiB
Plaintext
/*! @mainpage Ical Service 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.01R2
|
|
@author jvl
|
|
@date 20060314
|
|
|
|
@section secabout About IcalSrv
|
|
|
|
At the moment IcalSrv is a small package that allows a socalled
|
|
<i>ical client</i> 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 @ref secicalsrvclients)
|
|
|
|
This means that in the client you can download (aka <i> reload </i>)
|
|
the data from an a socalled <i> subscribed </i> 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.
|
|
|
|
At the moment, the IcalSrv service is just a simple --experimental-- variant
|
|
that is not based on webdav (as most of these services), but that may
|
|
nevertheless can be quite practical. It allows only upload and
|
|
download of complete calendars (with events and todos) and no direct
|
|
deletions of events. (Read more on this below at @ref secdeletions )
|
|
|
|
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>
|
|
|
|
|
|
|
|
|
|
@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 small release notes document that tells of about the changes in
|
|
the releases.
|
|
|
|
- Install the icalsrv package by either checking out the icalsrv stuff from cvs
|
|
or untarring some tarball icalsrv-vx.y.x.tgz of the package (if available).
|
|
At the moment (200602xx) the icalsrv is partly in cvs module <i>egroupware</i> and
|
|
partly (the documentation only) in module <i>phpgwapi</i>. So be sure to update at least the first one!
|
|
- @note The IcalSrv package depends on the availability of an
|
|
EgwIcal (>= 0.9.x) 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 (HEAD).
|
|
|
|
- Take care that icalsrv.php is <code>.../egroupware/icalsrv.php</code>
|
|
(and the other files from the icalsrv package also in their appropiate places)
|
|
|
|
- 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
|
|
Order allow,deny
|
|
Allow from all
|
|
</Location>
|
|
</PRE>
|
|
|
|
- Restart apache (or other webserver) ( /etc/init.d/httpd restart )
|
|
|
|
- Connect your ical client (e.g: Sunbird)
|
|
with http://your.host.com/egroupware/icalsrv.php
|
|
|
|
- now you should 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.
|
|
|
|
- using the "publish" calendar action you can write the (modified) calendar
|
|
from the sunbird client back to EGW
|
|
|
|
|
|
|
|
@section secicalsrvclients Clients for IcalSrv
|
|
|
|
This is tested with egw1.2rc6 and clients:
|
|
|
|
- Korganizer (3.3.2,(read) 3.4.2, 3.5.0 (READ+WRITE))
|
|
- Mozilla calendar (2004040813-cal) (READ+WRITE)
|
|
- Evolution 2.2 (READ)
|
|
- Apple Ical, is reported to be working too. (READ+WRITE)
|
|
|
|
See @ref pageicalsrvclients for further use and experience with these
|
|
clients and supported features <i>Now with screenshots too!!</i>
|
|
|
|
|
|
@section secdeletions Deleting Calendars, events or todos
|
|
|
|
deletion of the whole remote calendar is not supported see the webcal
|
|
protocol discussion in @ref pagewebcaldiscussion
|
|
|
|
Individual calendar events or todos cannot be deleted either by just
|
|
deleting them on the client and then hoping that this propagates to
|
|
Egroupware on publish. There are various reasons for why this is not
|
|
implemented.
|
|
|
|
But, you can though delete items by simply renaming them to
|
|
<code>X-DELETE</code>. I you do so, they will get deleted in Egw on
|
|
publishing. When you later dowload ("reload"/"refresh") the remote
|
|
calendar in your client you should notice that the event is gone..
|
|
|
|
|
|
@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 ...
|
|
|
|
|
|
@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 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.
|
|
|
|
|
|
|
|
|
|
@subsection subsecdebugtools Debugging of IcalSrv.
|
|
|
|
IcalSrv does not generate webpages, so to see any error or debug
|
|
information, there a just three other places to look at:
|
|
|
|
-# The HTTP error message. <br>
|
|
If you have a really problematic error, IcalSrv will answer your http
|
|
request with a 403 error and --hopefully-- a short message. In some
|
|
clients (like Korganize) this is reported back via a popup with a
|
|
silly message that "exporting went wrong or access denied" or so, instead of displaying
|
|
this message it got together with the 403 error. Note: Sunbird does
|
|
display the message. Unfortunately at the moment this will be mostly
|
|
"VEVENTS import ERROR" or so..
|
|
-# The httpd errorlog file/stream. <br>
|
|
Most problematic errors are reported
|
|
to this file of the egw server. So this is indeed the best source for
|
|
debug info. But to read it, you need access to the
|
|
server and to this log file. So only egw administrators are likely
|
|
the only ones for who this can be of help.
|
|
-# The ical.log files and ical.exportxxxx plus ical.importxxxx <br>
|
|
files.
|
|
If you did install the icalsrv.php file with the variable
|
|
$logdir set to folder where the httpd is allowed to write, you will
|
|
get a detailed log in file ical.log of all uploads and downloads via
|
|
IcalSrv furhtermore for each of these the associated iCalendar data
|
|
will be logged in ical.exportXXXXXX files with XXXX the utime of the
|
|
action. These files reside on the egw server, mostly in /tmp. So again
|
|
to read them you will need access to this server directory.
|
|
Of course this feature needs to be disabled in a production setting:
|
|
the file growth and the security issues of it demand it.
|
|
|
|
|
|
@section secbugandtodo BuG and todo list
|
|
|
|
-see BUGs and TODOs in @ref pageicalsrvbugandtodo
|
|
-see Todo page in ..
|
|
|
|
|
|
|
|
have fun
|
|
|
|
|
|
JVL
|
|
|
|
|
|
*/ |