IcalSrv FAQ - some questions and answers

Author:
JVL
Mostly updated to:
Version:
0.9.37-a4 (icalsrv)
Date:
20060501

FAQ Intro

Hi, this is the first, very rudimentary version of a Frequently Asked Questions list about IcalSrv, the Egroupware's Icalendar over http service.

I will record here some basic questions seen in the egw forum or elsewhere. As both IcalSRV and its features are still in a growing phase, I will try to record with each question the versions of IcalSrv for which the situation applies. This is in the SINCE: version .... : ... lines below a question and answer.

As some questions are most often posed by basic users, while others are rather dedicated towared more technical users and developers, I try to put an UB (for User Basic) or UT (for User Technical) or DEV (for Developer) as label to the questions.

UB: How do I access a calendar via Icalsrv?

As soon as you have Icalsrv running and setup properly, there maybe many icalendars available to be accessed from a client like Sunbird. As explained in the overview in About IcalSrv NG you can see what virtual calendars are provided by IcalSrv in your Egroupware server using a special url. You should note that he virtual calendars come in two variants:

After you have found in these listings a certain calendar that you want to use in your client. Copy its url (e.g. using the copy links actions of you browser when right mouse clicking on the hyperlink in the listing. And put this url in de appropiate subscribe field in your client. If you also want to publish this calendar later again to Egw you may need, dependant on your client, to put this url also in a publish field of the client setup (see the IcalSrv clients status and supported features for more specific client details on this).

Now you should be able to use the client to download and publish the (virtual) calendar.

UB: I cannot see MrX his personal calendar?

To see somebodies personal calendar you have to access it using the correct url (see UB: How do I access a calendar via Icalsrv?). Next thing is that need to have sufficient rights to read it. This means that the calendar owner, lets say MrX, must have granted you (i.e. the user that accesses Egw icalsrv via e.g. Sunbird using http basic authentication), access to his calendar (if the requested virtual calendar refers to his Egw calendar events) or his infolog (if the requested virtual calendar refers to MrX his infolog tasks). This granting of access is something MrX has to do using the "grants" menu in his calendar and/or infolog pages. It can be played by either setting these ACL grants for you individually of by setting them for a specific group that you are member of. (see also UB: Can I have the secretaries manage the bosses calendar?).

UB: Can I have the secretaries manage the bosses calendar?

An often found situation is where the personal calendar/infolog of a boss (MrBoss) should be managed (read and/or updated) by a secretary (MrSecretary) that should though not be in the possession of MrBoss his Egw password. Can this be done via IcalSrv? Yes, it can, just as with browser based usage of Egw, using the correct ACL rights settings by the MrBoss.

The steps are as follows. Lets assume we have a group of secretaries MrSec1 and MissSec2.

Since:
v0.9.36-ng working

UB: Help, I cannot delete events or todos via IcalSrv

Yes, you found a disappointing feature..

Deletion of a complete remote calendar (on Egw) via IcalSrv is not supported. For a discussion on why this is not , and should not be, implemented see the webcal protocol discussion in Discussion on iCalendar based protocols for Egroupware

Individual calendar events or todos cannot be deleted either by just deleting them on the client and then hoping that this propagates to Egroupware at the moment of publishing. Though this is something that you certainly would like to have as a feature, there are various reasons for why this is not implemented. Most of them have to do with the fact that Egroupware is a real multi-user groupware server and not just a storage for icalendars. When we will support the CalDAV or GroupDAV protocol, at some moment in time, you will have this functionality though.

But nevertheless, for the time being, there is a smart hack. That is: you can though delete items by simply renaming them (via the summary/title field) to X-DELETE. I you do so, they will get deleted in Egw on publishing. When you later download ("reload"/"refresh") the remote calendar in your client you should notice that the event is gone..

UB: Will my virtual calendar period settings prevent publishing events outside that period?

Short answer: at the moment: NO! Currently the filtering used in virtual calendars works only on export from Egw to the client. On upload (publishing) from the client to Egw, all events (and todos) are imported into Egw, wether or not they fall in the virtual calendar period. The ACL checking, to see if the event is allowed to be updated is done though.
SINCE: version 0.9.33-ng-b1 : ...

UB: Help, published event participants get lost and strange text appears in the event desciption.

Icalsrv can, on import from a client, only recognize valid eGroupware participants if they have an email address associated with them (at the time of export and now). For other detected participants of an event, on import a short note is written in the event its description, telling that there are some Non EGW participants and then listing them.

UB: Help, I put a comma in my field text and now its half missing!

Using a COMMA or COLON or SEMICOLON in icalfields like SUMMARY, DESCRIPTION or LOCATION may easily lead to wrong results when importing and exporting. Although the RFC says that in this case the program should double-quote the values of the fields, it appears that various clients react differently when confronted with these.

In versions before v0.9.37 of egwical, use of commas would lead to loss of a part of the field. Since v0.9.37 there is modest escaping built in for commas appearing in one of the fields mentioned above. This is done by prepending backslashes (as rfc 2426 sec2.4.2 suggests). At least in recent versions of Sunbird and Korganizer this appears to work reasonable.

UT: How do I install IcalSrv?

This mostly comprises two things: getting the stuff and actually installing it.

UT: How to get IcalSrv

You have a couple of possibilities, especially if you want the latest version. For up-todate info see the icalsrc wiki page on http://www.egroupware.org/egroupware/wiki/index.php?page=IcalSrv

Since egw1.2Rc8 you find icalsrv in the standard (base or contrib) egroupware package and via the egroupware CVS. Occasionally I produce a tarball that I provide via my homepage (see the wiki page above for more info)

A bit on the current situation:

SINCE version 0.9.36/egw-1.2.1

The IcalSrv is an application that is in the 1.2.1 contrib package, in a separate rpm file and in CVS (HEAD and branch_1_2_0). So if you install Egw and the contrib package You have it!

If you use rpm packages you need to install the basic egw rpm and further icalsrv.rpm and the --backend piece-- egwical.rpm package,

Note:
IcalSrv needs a "backend" piece called "egwical" that is not yet standard in the phpgwapi, so you have to have this installed too, in an appropiate version. This is either from the contrib or via an rpm package.
SINCE version 0.9.33/egw-1.2

I dont know yet where we will have the IcalSrv and Egwical packages in the final 1.2 release....

UT: How to Install IcalSrv from the sources?

There should be some info in the SHORT experimental Install How-To: in the Icalsrv mainpage.

Help: UT: I installed IcalSrv and it doesnot work? Some Tips.

Yes, many things can go wrong ;-) Here some general tips to check:

UT,DEV: Help: I installed IcalSrv it doesnot work? How to debug?.

IcalSrv is a sevice that does not generate webpages, so to see any error or debug information, there are just three other places to look at:

  1. The HTTP error message.
    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..
  2. The httpd errorlog file/stream.
    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 egw administrators are likely the only ones for who this can be of help.
  3. The ical.log files and ical.exportxxxx plus ical.importxxxx
    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.

UT: What features are implemented and what is missing in IcalSrv?

We used to have a list of implemented features, bugs and todos. Sorry but at the moment this list is missing.. Via the mainpage of this documentation you should be able to find (via related pages) a page with the currently open todos and bugs. The most important ones are also listed on the page IcalSrv Release Log

For the current status of iCalendar fields that are imported/exported from and to Egroupware via IcalSRV you should consult the package EgwIcal documentation, as this is the working engine that does all the conversions.

Notably missing features at moment are though;

UT: Does IcalSrv work with https?

Yes, since version 0.9.36-ng-a4 it is checked to work with both http and https (checked on apache2 under linux). In earlier versions it worked to but the content of .../list.html didnot adopt the links in the file to the appropiate connection. After this version there is a fix for this, but this is known to fail on some http servers. The system virtual calendars list.html uses since v0.9.37-ng-a2 another fix that should work on all platforms.

UT: Is the icalsrv output/input the same as the ical file import/export via the sidebar menu in the calendar app?

At the moment (egw1.2.1) not, unless you replaced the files calendar/class.boical.inc.php and infolog/class.vcalinfolog.inc.php by the compat classes files egwical/class.boical.inc.compat.php and resp. egwical/class.vcalinfolog.inc.compat.php See the egwical documentation for more on this.

Currently these classes provide more or less the same functionality, and in future they might merge, but as the syncml package that is currently being actively developed, is using the first two too, there we may have, at the moment, a slight difference in icalendar handling between IcalSrv and the manual import or export of a icalendar file via the calendar menu.

UT: Is IcalSRV still working with php4? What problems to expect?

Unfortunately I did no thorough checking anymore, to test the icalsrv and egwical compliancy to php4 for the NG versions (say >v0.9.30). We had reports from people that it still works mostly with php4, after a few offending constructs are removed to get rid of a lot of warnings. These constructs are mainly:

As some important features of Egw in the current release require php5 anyway, I wont spend much time on making it fully php4 compliant. That is, unless specifically requested ;-)


Generated on Thu Jun 8 22:17:12 2006 for IcalSrv by  doxygen 1.4.6