evolution-kolab is a project to provide connectivity to Kolab groupware servers for Evolution.

evolution-kolab main page

1. evolution-kolab - Known issues with Kolab XML format conversion

1.1. Common

Please note that when this page was created, Evolution was used with german labels, which will therefore appear sometimes in this document.

1.1.1. Product ID

Every program writes it's own product-id. Also the libekolabconv library writes an own identifier (Evolution/libekolabconv), which is set automatically when new XML data is created from an internal structure. When Evolution structures are read, the identifier is set to NULL. Hence there are 3 states (1. Any identifier from Kolab-Clients: Client specific, 2. From Evolution to internal: NULL 3. From internal to XML: "Evolution/libekolabconv").

1.1.2. Sensitivity mapping

• Kolab: (private, confidential, public)
  

• iCal: In Evolution only available für iCal/(Task, Event, Note). not available for VCard/Contacts, so in this case, the sensitivity is saved in kolab store.
  

 typedef enum icalproperty_class {
    ICAL_CLASS_X = 10011,
    ICAL_CLASS_PUBLIC = 10012,
    ICAL_CLASS_PRIVATE = 10013,
    ICAL_CLASS_CONFIDENTIAL = 10014,
    ICAL_CLASS_NONE = 10015
 } icalproperty_class;

• eCal:
  

 typedef enum {
        E_CAL_COMPONENT_CLASS_NONE,
        E_CAL_COMPONENT_CLASS_PUBLIC,
        E_CAL_COMPONENT_CLASS_PRIVATE,
        E_CAL_COMPONENT_CLASS_CONFIDENTIAL,
        E_CAL_COMPONENT_CLASS_UNKNOWN
 } ECalComponentClassification;

Mapping table:

Default is "public".

1.1.3. Link Attachments

Link Attachments (only an url to the attachment is stored) are available in Kolab and the Evolution types: Event, task and notes. Link attachments are not offered in Evolution contacts. Evolution does not show manually created link attachments if they are not below a special user specific path. If a link attachment is added in Evolution, the file is copied below this folder and a link to this file is added to the iCalendar. It is therfore not possible to map link attachments between kolab and evolution. Kolab link attachments will be preserved by the kolab store.

1.1.4. Kolab Store

Unknown Kolab XML elements must be preserved by kolab clients according to the kolab specification (Kontact does not keep them). Due to technical restrictions of the Evolution API for the types EContact and ECalComponent, not all unknown Kolab XML elements could be preserved:

• Top Level elements are preserved in all types (contact, event, task, note)T
• Contact
  • Elements below "phone" and "email" elements are preserved.

  • Elements below "name" and "address" elements are not preserved.

• Event/Task
  • Elements below "organizer" and "recurrence" elements are preserved.

  • Elements below "attendee" are not preserved.

1.1.5. body

In one test case, there is a loss of some "\r" and "\n" after converting a base64 encoded Toltec contact. The appearance is not concerned. Carriage return between two words is lost, but has no effect on the appearance like the complete lost of carriage return and newline at the end of the text-field. Example: "Notizen\r\n123\r\n" to Notizen\n123"

Also if there is only one whitespace with carriage return and/or newline in the body field, the whitespace is getting lost, possibly due to Evolution, deleting this if nothing else is filled in the field.

1.2. Incidence

1.2.1. Alarm

• Evolution provides only event-alarms, no task alarms. kolab task alarms are preserved in the evolution store.

• Kolab Alarm to AdvancedAlarm mapping:
  

 <alarm>111</alarm> (in minutes)
 =
 <advanced-alarms><alarm type="display">
  <display-text>NULL</display-text>
  <start-offset>111</start-offset>
  <end-offset>NULL</end-offset>
  <repeat-count>NULL</repeat-count>
  <repeat-interval>NULL</repeat-interval>
 </advanced-alarms></alarm>

If start-offset is set and any other attributes are not set, except of type, which has to be display, then the advanced alarm is converted back (only the first) to simple alarm when writing xml. The <alarm> attribute has to be in a row before <advanced-alarms>.

1.2.1.1. Advanced Alarm

• Kontact: Kontact sets additional <enabled> attribute.

• Kontact: <repeat-interval> always set on 1 by Kontact, it ignores the value saved in the program.

1.2.1.1.1. AlarmType

• Kolab:

additional Kolab advanced-alarms specification: http://www.kolab.org/pipermail/kolab-format/2008-September/000873.html

• iCal:

 typedef enum icalproperty_action {
    ICAL_ACTION_X = 10000,
    ICAL_ACTION_AUDIO = 10001,
    ICAL_ACTION_DISPLAY = 10002,
    ICAL_ACTION_EMAIL = 10003,
    ICAL_ACTION_PROCEDURE = 10004,
    ICAL_ACTION_NONE = 10005
 } icalproperty_action;

• Evolution:
  

 typedef enum {
        E_CAL_COMPONENT_ALARM_NONE,
        E_CAL_COMPONENT_ALARM_AUDIO,
        E_CAL_COMPONENT_ALARM_DISPLAY,
        E_CAL_COMPONENT_ALARM_EMAIL,
        E_CAL_COMPONENT_ALARM_PROCEDURE,
        E_CAL_COMPONENT_ALARM_UNKNOWN
 } ECalComponentAlarmAction;

1.2.1.1.2. Alarm Trigger

The iCal specification defines an absolute alarm trigger, which starts the alarm on a specified time, independent to start or end date of the event.

1.2.1.2. Trigger

• Kolab:
  • Only duration possible (no possibility for absolute trigger date-time!)
  • Two seperate fields for start- or end-related. You can choose one of (Minuten, Stunden, Tage) and save one value.
• iCal:
  • VALUE = DURATION or DATE-TIME
  • RELATED = START or END

DURATION in iCal written in icaldurationtype

 struct icaldurationtype
 {
        int is_neg;
        unsigned int days;
        unsigned int weeks;
        unsigned int hours;
        unsigned int minutes;
        unsigned int seconds;
 };

=> conversion needed. conversion from evolution to kolab with icaldurationtype_as_int(trigger->u.rel_duration)/60 because function returns seconds, and kolab need minutes. Seconds from evolution get lost!

DATE-TIME written in iCal date-time - DATE-TIME:19980101T050000Z

1.2.2. Recurrence

1. Additionally to the recurrence examples in the kolab specification it is possible in outlook to define a daily recurring event which only happens on work days:

 <recurrence cycle="daily">
    <interval>1</interval>
    <day>monday</day>
    <day>tuesday</day>
    <day>wednesday</day>
    <day>thursday</day>
    <day>friday</day>
    <range type="none"/>
 </recurrence>

• Effect: Some clients may have problems with this data type because it is not specified
• Implementation: Can be mapped in the evolution data type

1.2.2.1. Recurrence-Cycle mapping

• Kolab: (daily, weekly, monthly, yearly)
• iCal:

/*
 * Recurrance enumerations
 */

typedef enum icalrecurrencetype_frequency

    /* These enums are used to index an array, so don't change the
       order or the integers */

    ICAL_SECONDLY_RECURRENCE=0,
    ICAL_MINUTELY_RECURRENCE=1,
    ICAL_HOURLY_RECURRENCE=2,
    ICAL_DAILY_RECURRENCE=3,
    ICAL_WEEKLY_RECURRENCE=4,
    ICAL_MONTHLY_RECURRENCE=5,
    ICAL_YEARLY_RECURRENCE=6,
    ICAL_NO_RECURRENCE=7

} icalrecurrencetype_frequency;

Mapping table:

1.2.2.1.1. Conversion problems:

Evolution can't handle events that recur yearly on the n-th day of the year. Recurrence settings will not be displayed and can't be edited. (cf. specification 6.4.3, Annotation 2)

Evolution can't handle events that recur yearly on the n-th weekday of a Month (recurrenceCycle == Yearly_Weekday, e.g. every 3rd Wednesday of March). Recurrence is converted to monthly every 12 months. (cf. specification 6.4.3, Annotation 2)

Recurrence on tasks is being ignored by Evolution. Yearly_Weekday recurrences are converted as described above. If no startDate is set for task, it is impossible to convert Recurrence back to Kolab, therefore the recurrence element is put in the kolab-store.

1.2.3. Attendee

Unknown kolab xml elements below the attendee element could not be preserved when mapping to evolution (attendee is a list field and ECalComponent does not offer the possibility to get the internal iCalendar property which belongs to a given object attribute).

1.3. Contact

1. Contact picture

• Toltec Connector does not write the tag „picture“ which specifies the name of the picture attachment. The attachment is always named „ContactPicture.jpg“. If the tag „picture“ is set by an other application, it is preserved by toltec connector. Also the picture attachment is preserved.

• Kontact writes the tag „picture“ but resizes the image and renames the attachment to „kolab-picture.png“.
• Effect: Contact pictures from other applications are not visible in outlook. Outlook preserves the picture which is set by other applications but also sets its own picture. There can be two different pictures in one contact. One is shown in outlook and the other one in other applications like kontact.

• Implementation: See kolab format specification. => Pictures from outlook are preserved. Picture changes in Evolution will only affect the Kontact picture and only the Kontact picture will be visible in Evolution.

2. Carriage return Characters

• CR characters are converted to a LF character in evolution when reading from vcard. The sequence CRLF is also converted to one LF character.
• Effect: Strings can change when converting to Evolution so Unittests have to differentiate between strings coming from Kolab or Evolution
• Implementation: Use stage parameter to differentiate between Strings which are read from Kolab or form evolution and use different comparing operations.

3. Trailing Newlines

• Trailing newlines are removed when converting to evolution and back (e.g. common.body)

4. Email Address

• Toltec Connector saves email address in "display-name" field instead of "smtp-address" field

5. Address

• Evolution can only handle 3 addresses: HOME, WORK, OTHER
• Evolution VCARD only stores one OTHER address, even if there is more than one
• If there is more than one address of type OTHER, they are stored in kolab store
• As the sort order of addresses is not preserverd in EContact, the choice of the single OTHER address is arbitrary
• Unknown tags below the address xml node cannot be preserved (contact kolbab store is not possible for multivalued vCard fields due to limitations of the EDS API)

6. Phone Numbers

• Evolution has a phone-type 'Other Fax' which is not present in the Kolab Specification

7. Free Busy URL

• The free-busy-url can be specified in Kontact, but it is not saved to the kolab xml on the mail server. So the GUI free-busy-url field is empty after reopening the contact.

8. GEO

• The Kolab format defines geographic coordinates and Kontact provides the ability to write them.
• The iCal format defines geographic coordinates but Evolution does not provide the ability to write them.

1.3.1. Date

• Month: Kolab 0->11 vs. iCal 1->12

• Year: Kolab year-1900 vs. iCal year

1.3.2. Phone list

• Kolab: Specification defines following values: business1, business2, businessfax, callback, car, company, home1, home2, homefax, isdn, mobile, pager, primary, radio, telex, ttytdd, assistant and other. Every type can be choosen once.
• Evolution: max 8 numbers

• Kontact can save n→∞ phone elements where each type can be on more than one number.

legend (phone list):

1.3.3. Addresses

All GString fields in Address (pobox, locality, region, postal_code, street, country) struct of contact have due to libecal functions empty String as value instead of NULL if they are not set. It has no effect on the appearance in Kontact or Evolution.

1.3.4. Instant Messenger Fields

Kolab: Provides or defines one text field for instant messenger.

• Kontact: Provides additionally as much instant messenger fields as you want with a new tag (x-custom) and attributes value, app and name. You can add new Fields with address and type. If one type is added more than one time, Kontact saves only one xml tag with all values of same type, separated alphabetically by  (&#57344;). A special case is IRC. For each entry two values (address and network are saved in value attribute separated by  (&#57632;). First value is the address. [Example with both cases: "IRC2-AddressIRC2-NetworkIRC-AddressIRC-Network"]

Standard im field is set by first added messenger field value if contains no text. Text is not updated when changing im value. VCard: Provides 3 im fields for each of the three address types (home, private, other).

• Evolution: 4 different input fields for im addresses where you can choose type and write in the address. It is possible to save 4 times the same type. Every field is saved separate in VCard with the additional slot id from Evolution. In Evolution there is no connection to the address type. You have maximum 4 for one contact. Evolution cannot handle im fields with type work, only home has to be set. If work is set, contact information is shown in preview but all form fields in editing are empty!

Mapping:

 <x-custom value="AIM-Address" app="messaging/aim" name="All" />
 <x-custom value="Gadu Gadu-Address" app="messaging/gadu" name="All" />
 <x-custom value="GroupWise-Address" app="messaging/groupwise" name="All" />
 <x-custom value="ICQ-Address" app="messaging/icq" name="All" />
 <x-custom value="IRC2-Address&#57632;IRC2-NetworkIRC-Address&#57632;IRC-Network" app="messaging/irc" name="All" />
 <x-custom value="Jabber-Address" app="messaging/xmpp" name="All" />
 <x-custom value="MSN-Address" app="messaging/msn" name="All" />
 <x-custom value="Meanwhile-Address" app="messaging/meanwhile" name="All" />
 <x-custom value="SMS-Address" app="messaging/sms" name="All" />
 <x-custom value="Skype-Address" app="messaging/skype" name="All" />

• Maximum 4 IM's are saved in Evolution. Rest schould be saved in kolab store.
• If more than one XML element with the same IM type is stored in the Kolab XML, Kontact will only show one entry of them.

1.4. Event

1.4.1. Event Attendee-Status mapping

• Kolab format specifies 4 states. (none, tentative, accepted, declined)
• iCal format specifies following 9 states:

 typedef enum icalparameter_partstat {
    ICAL_PARTSTAT_X = 20029,
    ICAL_PARTSTAT_NEEDSACTION = 20030,
    ICAL_PARTSTAT_ACCEPTED = 20031,
    ICAL_PARTSTAT_DECLINED = 20032,
    ICAL_PARTSTAT_TENTATIVE = 20033,
    ICAL_PARTSTAT_DELEGATED = 20034,
    ICAL_PARTSTAT_COMPLETED = 20035,
    ICAL_PARTSTAT_INPROCESS = 20036,
    ICAL_PARTSTAT_NONE = 20037
 } icalparameter_partstat;

• Kontact saves the value "none" if you choose that you need an action. For that reason you have to choose a status and cannot leave it empty. So Kontact saves the 4 Kolab states and additionally the state "delegated". In fact you can also save two further states with Kontact (completed & inprocess), but whyever they are saved both as accepted in Kolab-XML file. (You have to close Kontact and reopen it to see that these two states are saved wrong in the server) So there is a result of 5 states for Kontact to map.

• Toltec saves Event Attendees maybe in the Microsoft bin-attachment, saved with the kolab xml-file. In fact it does not save the attendees in kolab xml. This can be shown, when copying a toltec event element to kontact, where all attendees get lost. Just as they miss in the xml-file.
• Evolution provides 5 states (ICAL_PARTSTAT_NEEDSACTION, ICAL_PARTSTAT_ACCEPTED, ICAL_PARTSTAT_DECLINED, ICAL_PARTSTAT_TENTATIVE and ICAL_PARTSTAT_DELEGATED), the rest of the iCal-Format is not used and cannot be chosen. You are also forced to choose one state and cannot leave it empty, but in Evolution "ICAL_PARTSTAT_NEEDSECTION" is saved right, and "NONE" is not used.

Result is the following mapping:

[1] Value is saved wrong by Kontact.

Default will be none/ICAL_PARTSTAT_NEEDSACTION! It is set on any other case.

1.4.2. Event Attendee-Role mapping

• Kolab specifies 3 possibilities of a role (required, optional and resource).
• iCal Format has following 6 available parameters:

 typedef enum icalparameter_role {
    ICAL_ROLE_X = 20051,
    ICAL_ROLE_CHAIR = 20052,
    ICAL_ROLE_REQPARTICIPANT = 20053,
    ICAL_ROLE_OPTPARTICIPANT = 20054,
    ICAL_ROLE_NONPARTICIPANT = 20055,
    ICAL_ROLE_NONE = 20056
 } icalparameter_role;

• Kontact uses the 3 Kolab specified roles and additionally the role "Leiter". But this option is saved in Kolab as required, so the information gets lost and every "Leiter" is shown after saving on server as normal required participant.
• Toltec saves Event Attendees maybe in the Microsoft TNEF-attachment, saved with the kolab xml-file. In fact it does not save the attendees in kolab xml. This can be shown, when copying a toltec event element to kontact, where all attendees get lost. Just as they miss in the xml-file.
• Evolution has 5 options for role attribute. Three of them are exactly the same as in Kontact. Additionally "Vorsitzender"/"Chair" and "Unbekannt"/"Unknown". If there is chosen "Unbekannt"/"Unknown", role attribute is just left out when saving iCal.

Result is the following mapping table: (If there is no role attribute in iCal or it is ICAL_ROLE_CHAIR it will be mapped as a generalization to normal participant "required".)

[1] Value is saved wrong by Kontact.

[2] No role tag is saved by Evolution in iCal.

Default will be required/ICAL_ROLE_REQPARTICIPANT! It is set on any other case.

1.4.3. Event ShowTimeAs mapping

• Kolab: busy, free, tentative, outofoffice
• iCal: FBTYPE is used for own objects in free time analysis, not for single events. TRANSPARENCY provides the same options.

 typedef enum icalparameter_fbtype {
    ICAL_FBTYPE_X = 20019,
    ICAL_FBTYPE_FREE = 20020,
    ICAL_FBTYPE_BUSY = 20021,
    ICAL_FBTYPE_BUSYUNAVAILABLE = 20022,
    ICAL_FBTYPE_BUSYTENTATIVE = 20023,
    ICAL_FBTYPE_NONE = 20024
 } icalparameter_fbtype;

 typedef enum icalproperty_transp {
    ICAL_TRANSP_X = 10061,
    ICAL_TRANSP_OPAQUE = 10062,
    ICAL_TRANSP_OPAQUENOCONFLICT = 10063,
    ICAL_TRANSP_TRANSPARENT = 10064,
    ICAL_TRANSP_TRANSPARENTNOCONFLICT = 10065,
    ICAL_TRANSP_NONE = 10066
 } icalproperty_transp;

Mapping table:

1.5. Task

1.5.1. Task Attendee-Status mapping

• see Event Attendee-Status mapping

Additional information: Toltec Tasks have no possibility to save Attendees to them. Different to Events where they are saved, but not in Kolab-XML, here they are not saved at all.

1.5.2. Task Attendee-Role mapping

• see Event Attendee-Role mapping

Additional information: Toltec Tasks have no possibility to save Attendees to them. Different to Events where they are saved, but not in Kolab-XML, here they are not saved at all.

1.5.3. Task Status mapping

• Kolab specifies following states: not-started, in-progress, completed, waiting-on-someone-else, deferred
• iCal defines following states:

 typedef enum icalproperty_status {
    ICAL_STATUS_X = 10051,
    ICAL_STATUS_TENTATIVE = 10052,
    ICAL_STATUS_CONFIRMED = 10053,
    ICAL_STATUS_COMPLETED = 10054,
    ICAL_STATUS_NEEDSACTION = 10055,
    ICAL_STATUS_CANCELLED = 10056,
    ICAL_STATUS_INPROCESS = 10057,
    ICAL_STATUS_DRAFT = 10058,
    ICAL_STATUS_FINAL = 10059,
    ICAL_STATUS_NONE = 10060
 } icalproperty_status;

• Kontact has no possibility to choose any task status. It is by default set on "not-started". It has to be tested if Kontact just does not read this element-node, that you can save any other value for Toltec or other programs.

• Toltec provides all Kolab task-states.The states "waiting-on-someone-else" and "deferred" are not possible in iCal, so they are mapped to "not-started" to prevent program errors.
• Evolution gives the possibility to choose 4 states for a task (Nicht begonnen, In Bearbeitung, Abgeschlossen, Abgebrochen). The first three are also available in Kolab Format. When saving not started the Status tag is completely left away. Cancelled is not available in Kolab format an will be mapped to "not-started".

Result is the following mapping table:

[1] No possibility to choose status in Kontact, always set to default on new tasks.

[2] No status tag is saved by Evolution in iCal.

Default will be not-started/<not saved>! It is set on any other case.

1.5.4. Task Priority mapping

• Evolution, Kolab, Kontact and Toltec use different conventions for indicating priority:

• While the Kolab standard (Section 10) specifies the priority element name as "priority", Kontact uses its own element "x-kcal-priority". In Kontact, the Kolab-XML "priority" field is mapped to the values of 1 to 5 like in the mapping table underneath.

Priority mapping done by Evolution:

Handling and mapping in libekolabconv:

• only detailed priority (0-9) is written in intern structure
• normal priority is calculated from it when writing xml
• other way round, detailed priority is calculated from normal if detailed is not available
• detailed is fully mappable with evolution
• no redundant data management

1.5.5. Parent Task

In Kolab you can create subtasks, which become a parent tag with the id of his parent. Evolution does not provide those subtasks, hence the parent id is written into kolab store. Notice, that some connection between tasks can get lost if for example parent is deleted in Evolution.

1.6. Note

1.6.1. body / HTML

In body text of notes, Kontact writes text as HTML as soon as some formatting is done. It's the <body> tag of common, but only in notes you have the possibility to format your text in Kontact. Evolution does not provide formatting text in any field. To prevent unexpected conditions, HTML, if exists, will be parsed out of the body text before saving to Evolution. Faormatting will get lost, but newslines will be still there.

1.7. Appendix

1.7.1. mapping table legend

1.7.2. used program versions