Content

1. What is Kolab?
2. So what about Thunderbird 2?
3. How do I get the Source
4. How does Sync Kolab sync entries?
5. How can you use the custom4 field?
6. Help, I am getting tons of duplicates!!11
7. How to write a bug? While syncing, the process suddenly stopps. How can I find out what's wrong?
8. SyncKolab just wont start at all..
9. How do I completely (and manually) uninstall synckolab?

It loads all your contacts (from a selected address book) as well as events and todos (from the selected calendar), and synchronizes them with a selected imap folder. Where every contact is stored as an vcard and every event,todo as iCalendar. For more information http://kolab.org/

The idea behind this is, that you can now have your contacts+calendar entries stored on the imap server. so you can actually have the same addresses on more than one computer. The kolab project has a groupware server that uses imap to exchange calendar entries and vcards. But you can also setup simple sharing in your office if you have f.e. cyrus by symlinking shared folders.

The source is included in the xpi. You can check it out in your profile directory under extensions/{571CFACF-0F7D-49b4-BD77-E6FC7B209ADC}/chrome/content/ or if you unzip the xpi (just rename it to .zip and use you favorite unzip util).

If you want to change some code make sure to unzip the synckolab.jar conatined in this xpi and modify the files in there. Otherwise the changes wont be visible!

For those interested here is a short explenation (pretty technical) on how Sync Kolab actually works.
When a sync is started (doesnt matter if its a calendar/task or adress book sync):

• get a list of all messages in the imap folder (only headers, which are cached locally. Thunderbird also makes sure that new messages are included)
• check each message header with a local database of the previous sync for a change. Message size, date and subject are used there (subject is the key value)
• if something changed or the message is new, download the message and strip everything except the message body (xml/ical/vcard). Save this part in the local sync database (=the file system)
• parse the message body into a adress book card/calendar event/task (lets call it CUR)
• get the id from CUR and check the local address book/calendar if there is an entry with the same id (lets call it ENTRY)
• if we did not find an ENTRY, save CUR in the adress book/calendar and continue
• if we found an ENTRY, make a comparison between CUR, ENTRY and LOCALDB (the entry stored in the local sync database (file system) from a previous sync)
  • if CUR=LOCALDB but ENTRY!=LOCALDB -> we know we changed something locally (ie. changed the name) so update ENTRY on the server (update=delete and readd), also update the LOCALDB on the filesystem
  • if CUR!=LOCALDB but ENTRY=LOCALDB -> we know the server entry changed, so we have to update ENTRY and LOCALDB
  • id CUR!=LOCALDB!=ENTRY -> we know we have a local change AND soemone changed the server entry -> ask what we should do
  • if CUR=LOCALDB but ENTRY is missing -> we know it has been deleted locally, so delete the entry on the server
• remember all entries already processed (so we dont check it twice)
• now go through all local entries (ENTRY) (except the one we already processed) and check:
  • if ENTRY is in LOCALDB: delete it (means it has been deleted from the server since the last sync)
  • if ENTRY is not in the LOCALDB: add it to the imap server
• finish up (liek make all new messages unread, and run compact to make sure its all on the server)
A few Remarks:
• if you uncheck "write to IMAP", nothing will be written on the imap server. So whatever you change locally (delete/modify entries) will result in messages "update on server" or "delete on server", but that wont happen. Next sync you will get "delete locally" "update locally" messages (since nothing changed on the server, but locally you had changed). This is because the sync DB needs two syncs to be in sync again
• the "ignore entries older than XXX" applies for the timestamp on the messages AND for the calendar entries (enddate is used there). -1 will just sync all entires
• the sync interval set to 0 will still produce debug messages (like "starting sync...") which is only an indicator that the check for an interval is working (should happen once a minute) - nothing is syncd if this is the only message
• If you delete the snyc db from the filesystem (synckolab folder). Synckolab will try to resolve all differences automatically or ask you (will probably result in lots of "locally updated" messages)
• If you have problem (especially entries which are not synced at all or wrong) make sure to check in the javascript Error-Console (Fehlerkonsole) for messages. Until 1.0 debug is FULLY enabled to help track problems. There is also a pause button available that helps you track problems.

Short answer: Not at all.

Long answer: Because of the way tbird saves contacts, it's not really possible to have any "invisible" field for the id. So I use the custom4 field. When using another program that writes vcards and use the custom4 field, it will stay valid (the information is saved and restored when the message is written on the server). Unfortunately, you can not modify/view the field in thunderbird right now (maybe this will change with 3.0).

• Make sure you got a working imap connection
• delete ALL configruation lines with synckolab out of your prefs.js (make sure that thunderbird is closed before doing so)
• Try setting up synkolab agian...
• If that did not work check your prefs.js if following lines are present (if not add them):
  user_pref("SyncKolab.<ContactConfigName>.ContactFolderPath", "imap://user@imapserver.com/<ContactFolder>");
  user_pref("SyncKolab.<CalendarConfigName>.CalendarFolderPath", "imap://user@imapserver.com/<CalendarFolder>");
• If it still did not work please check for any messages in your javascript console and report to the mailing list

• you sync your entries (even tough you then have most entries 4 times) and then use something like: Duplicate Contact Manager to clean out the dupes

• (if you know 100% that all entries on all machines are the same):
  You sync with ONE machine - so you have all the entries on the server, then you delete the adresses on the other machines and sync so synckolab will create the entries for you.

• Install a nightly build - often the problem is already fixed. (make a backup of your profile folder first.. just to be on the save side)
  
• if the problem persists:
• Check the javascript error console (found unter tools). Clear everything then start synckolab. In almost all cases you will find some kind of error message there. Rightclick it and copy it in the clipboard (ctrl-c)
• Open a new bug in bugzilla. Make sure you add:
  • Thunderbird Version
  • SyncKolab version (if a nightly, make sure to add the date/time as well)
  • a description what's going on
  • the copy/pasted error
  • the operating system
  • if you used xml or vcard/ical format
  • If the error is a parsing error save the message as eml (right click -> save As) and either attach the message to the bug or - if it contains sensetive information you don't want to see everyone - send directly to me via email (attach the eml)

• Check if it is configured correctly
• check if there are any errors in the error console (see above)
• try uninstalling some other extensions, maybe it's just a cross-extension problem

• CLOSE thunderbird!!!
• Find your thunderbird profile folder
• Remove all hdb files (*.hdb the sync databases)
• delete the synckolab folder
• Edit your prefs.js and remove all lines containing "SyncKolab"
• delete the extensions{571CFACF-0F7D-49b4-BD77-E6FC7B209ADC} folder (this is the extension itself)