Sophie: egroupware-icalsrv-1.6.002-7mdv2009.0 noarch

egroupware-icalsrv-1.6.002-7mdv2009.0.noarch.rpm

/*! \page pageicalsrvfaq IcalSrv FAQ - some questions and answers

@author JVL

Mostly updated to:
@version 0.9.37-a1 (icalsrv)
@date 20060427

\section secicalsrvfaqintro 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
<code>SINCE: version .... : ...</code>
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.

\section secicalsrvqa_access 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 @ref icalsrvsecabout 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:
- system virtual calendars that are independent of a user for their definition.
You get a listing of these 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 these for a certain userX via the url:
@url http://myserver.com/egroupware/icalsrv.php/userX/list.html

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 @ref pageicalsrvclients for more specific
client details on this).

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

\section icalsrvqa_personalvc UB: I cannot see MrX his personal calendar?

To see somebodies personal calendar you have to access it using the
correct url (see @ref secicalsrvqa_access). 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 @ref icalsrvqa_bossandsecretary).

\section icalsrvqa_bossandsecretary 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
<code>MrSec1</code> and <code>MissSec2</code>.
- first create (as Admin) a secretaries group, lets say:
<code>topsecretaries</code>
- As Admin add <code>MrSec1</code> and <code>MissSec2</code> to the group
<code>topsecretaries</code>
- Now, as MrBoss go to the Egw Calendar and set read (and if desired
write, etc...) grants allowed to the group <code>topsecretaries</code>
- If you want the secretaries also to maintain the infolog, as MrBoss
go to the Egw Infolog and set read (and if desired
write, etc...) grants allowed to the group
<code>topsecretaries</code> for this application too.
- Now a secretary like MrSec1 that accesses (using his own credentials)
via Sunbird the virtual calendar http://.....icalsrv.php/MrBoss/events.ics
should be able to see (and possible change) MrBoss events
To view or manipulate the tasks of MrBoss he might use the virtual calendar .../tasks.ics or
the combined calendar ..../defaults.ics

@since v0.9.36-ng working

\section icalsrvqa_deletions 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 @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 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 <code>X-DELETE</code>. 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..

\section icalsrvqa_publishfilter 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.
<PRE>
SINCE: version 0.9.33-ng-b1 : ...
</PRE>

\section icalsrvqa_nonegwparticipants 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.

\section icalsrvqa_commaesc 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.

\section icalsrvqa_install UT: How do I install IcalSrv?
This mostly comprises two things: getting the stuff and actually
installing it.

\subsection icalsrv_getting 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
@url 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:

<code>SINCE version 0.9.22/egw-1.2rc8 </code>

The IcalSrv is an application that is in the 1.2rc8 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.

<code>SINCE version 0.9.33/egw-1.2 </code>

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

\subsection icalsrv_installing UT: How to Install IcalSrv from the sources?

There should be some info in the @ref secinstall in the Icalsrv mainpage.

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

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

- Did you install both IcalSrv and Egwical in their correct versions?
Icalsrv is there when you have a folder .../icalsrv And egwical is
there when you have a folder .../egwical . The version can be found
in some version strings in the source code or via the api docs or (for
icalsrv via the manage applications menu in the administrator
configuration page.
.
<code>SINCE version 0.9.22/egw-1.2rc8 </code>

- Did you enable icalsrv application via the manage applications page in
egw setup?

- Did you enable IcalSrv for a specific user?
.
(Not yet possible/needed <code>SINCE version 0.9.22/egw-1.2rc8 </code>)

\section icalsrvqa_notworkdebug 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:

-# 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..
-# 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.
-# 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.

\section icalsrvqa_features 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.

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;
- no import or export of URL fields in events or todos (will come at
some time)
- no import or export of ATTACHMENTS in events or todos (funding might help
to implement it)
- recurring tasks for todos (egw does not support this yet)
- VTIMEZONE components are not supported (neither references to them) so
any timesettings defined with them are interpreted as local time (see
further the timezone handling page in the egwical documentation).
(here too: funding might help to implement it)

\section icalsrvqa_https 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 it
was fixed.

\section icalsrvqa_iocompat 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.

\section icalsrvqa_php4compat 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:
- the <code> &$arg = null </code> function argument declarations. Mostly the ampersand
can be removed, as this only means a slight decrease in efficiency. Be warned: there are
a couple of places in the code where this should not be done.
- and <code> foreach </code> loops that are confronted with empty arrays. Php4 doesnot like this
and will produce warnings.

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 ;-)