FAQ for Thunderbird contact sync

Also see:

Getting Started

  1. Download and install the addon.
  2. Check your Thunderbird proxy settings.

If your browser uses a proxy server to connect to the internet, use the same settings in Thunderbird. See Thunderbird/Tools/Options/Network/Connection.

  1. Visit Thunderbird/Tools/Zindus, then click “Add” and enter your login details.
  2. Click “Test Connection”, then OK.
  3. Click ‘Sync Now’

Before getting started, backup your contacts.  The addon’s record of stability speaks for itself.   But it has happened more than once that someone is in sync, deletes all their contacts, and then syncs again, causing the contacts on the other side to be deleted too.   So backup - its better to be safe than sorry.

What is slow sync?

When your contacts aren’t in sync (eg. after installation or the ‘Reset’ button), the addon uses a ’slow sync’ to get the local and remote sides in sync.

In a ’slow sync’, all contacts are retrieved and merged with those in Thunderbird.   Here is an example:

Thunderbird Remote
Before slow sync
a a
b c
After slow sync
a a
b b
c c

Contacts match if they are identical in every field that’s synced between Thunderbird and the remote server(s).

Slow sync doesn’t generate duplicates, but it doesn’t “intelligently merge” contacts either.  If two contacts are even a little bit different then the result is one of each - as with b and c in the example above.

The purpose of slow sync is to get the two sides into sync.  Fast sync keeps the two sides in sync.

What is fast sync?

In a fast sync, changes made to either to one side are propagated to the other side.

When a contact on one side changes, fast sync modifies the contact on the other side by overwriting all the fields that are common to both (and leaving the fields that aren’t common untouched).

Usually, the first sync is a slow sync and subsequent sync are “fast” syncs.

Merging contacts

Slow sync doesn’t attempt an intelligent merge, so if you start with John Smith on one side having an email address and on the other side a mobile phone number, slow sync leaves you with two John Smiths - one with a phone number and the other with an email address.

To merge contacts (making a single John Smith with an email address and phone number):

How to propagate contacts

To propagate the contacts from one side to the other:

  • backup the contacts on the ‘losing’ side then delete them
  • visit Tools/Zindus then select Reset then Sync Now.

Reset is the key here.  It forces a slow sync, which brings the two sides into sync using the contacts on the ‘winning’ side.

Without Reset, Sync Now might be a fast sync - risking deletion of all your contacts on the other side too!

What are Conflicts?

When a contact is modified in two places, or modified in one place and deleted in another, there’s a conflict.

Some conflicts are resolved automatically and other conflicts cause the sync to fail and must be resolved manually before a sync can succeed. Here are some examples:

Example Conflict #1 If a contact changed on both Thunderbird and the remote server, the conflict is resolved in favour of Thunderbird. The remote server is updated with Thunderbird’s version.

Example Conflict #2 If you are syncing with Zimbra and Thunderbird has an addressbook named “zindus/Trash”, the sync will fail and report:

Sync failed: Addressbook with reserved name: zindus/Trash

This type of conflict can’t be resolved automatically. In order to sync, the “zindus/Trash” addressbook must be removed or renamed to a name that is valid within Zimbra.

What is auto-sync?

To keep you in sync, the addon initiates sync on a periodic basis.  Two preferences affect the frequency:

  • extensions.zindus.system.as_timer_delay_on_start
    the number of seconds after startup
  • extensions.zindus.system.as_timer_delay_on_repeat
    the number of seconds after the first auto-sync

These preferences are only a mean - runtime values are randomized to minimize server congestion. To see or change their values, use the Thunderbird about:config editor.

If you want to know when the next auto-sync is scheduled, one of the last few lines in the logfile should look like this:

info: sync next: Friday, 11 January 2008 5:16:41 PM

Auto sync can be disabled via the Zindus Preferences dialog.

One of my contacts wont sync

If one of your Thunderbird contacts won’t sync the most likely reason is that it is in a mailing list.  Mailing lists and the contacts in them aren’t synced.  Instead, the addon syncs google groups.

Contacts in Thunderbird mailing lists are effectively removed from the view of the addon.  If you want to experiment with this, move a Thunderbird contact into a mailing list.  The next sync will delete the corresponding contact on the server.  To get the contact back, move the Thunderbird contact out of the mailing list and the next sync adds it back to the server.

If you aren’t sure whether the addon is working correctly, try this:

  1. from Thunderbird: add, modify or delete a contact, then visit Tools/Zindus then click ‘Sync Now’.
  2. from the browser: click ‘reload’ to force the browser refresh it’s cache from the server.
  3. Hey presto, the browser shows the change that you made in Thunderbird.

If you add, modify or delete a contact in Gmail, the change will eventually appear in Thunderbird, but it’s not immediate.  The delay can be minutes or hours before the change you made in Gmail is available via Google’s Contacts API.

The statusbar

The indicators in the statusbar are:

Y ==> in sync, next sync will be a fast sync
X ==> sync failed
!  ==> not synced (ie after installation or Reset), next sync will be a slow sync

Statusbar screenshot

Release streams

The addon has three release streams:

  1. addons.mozilla.org
    The most stable and least frequently updated.
  2. zindus.com production release
    Balances stablity and new features.
  3. zindus.com testing release
    The leading (but not bleeding) edge.

If you want a feature that is not yet available in your release stream, your options are:

  • be patient - the feature will eventually become available in your release stream, or
  • install the addon from a release stream that is updated more frequently

Security

Passwords

The addon stores passwords using the same mechanism that Thunderbird uses to store your IMAP/POP passwords.  The mechanism allows you to use a master password to encrypt stored passwords.  For technical details, do a web search for “nsIPasswordManager”.

Network traffic

The sync network traffic (usernames/passwords/contacts) goes between Thunderbird and your server (Google or Zimbra).  No third party web sites are involved.

For Google, the addon defaults to using https.

For Zimbra, the addon uses the url supplied by the user. When a Zimbra server gives the addon a choice of soapURLs, the addon defaults to selecting https.

Like most other addons, this addon checks the server that you downloaded it from for version updates.

Open-source software

The Zindus addon is open-source software.  The source code is written in Javascript and licensed under the Mozilla Public License.

To see the source code, download the addon, unzip the .xpi then unzip the .jar.

Roadmap

Q1 2012: sync photos

Q2 2012: first + last name sync

Parsing and sync of postal addresses (into street/city/state etc) is blocked pending a Google Contacts API v3 feature that Google has announced but not yet implemented.

Mailing lists

The Zindus addon doesn’t currently sync Thunderbird mailing lists or Zimbra Distribution Lists, but it does sync google groups.

We chose to sync Google Groups with addressbooks in preference to mailing lists because:

  • Thunderbird UI has better support for addressbooks than it does mailing lists, eg import/export
  • Thunderbird mailing list bugs

Direct support for mailing lists isn’t ruled out, but it is unlikely to take shape until Thunderbird evolves it’s plans for contacts and mailing list sanity.

Meantime, Google groups offer similar functionality to Thunderbird mailing lists - simply login to Google, compose an email and address it to the name of a group.

Thunderbird Versions

The addon generally supports the latest official release Thunderbird.

The testing release of the addon occasionally supports pre-releases of Thunderbird - check the release notes for details.

If you want to tweak the addon to force it to work on a bleeding-edge version of thunderbird:

  1. unzip the addon
  2. edit install.rdf to suit the current pre-release version.
  3. zip it up again and install it
  4. set the preference extensions.zindus.system.as_allow_pre_release to true.

If the addon doesn’t work in a pre-release build, it’s almost certainly because of a change to the Thunderbird API.  Check the Tools/Error Console.

Feature requests

If you would like the Zindus addon to do something that it doesn’t currently do, please let us know. It there is enough interest, it may get on to the roadmap. Here are some candidates:

  • Windows Live Contacts (Hotmail), Yahoo Mail, …

Let us know if you would like the Zindus addon to sync with something other than Google or Zimbra.  Other services that people have previously asked for: CardDAV, eGroupWare, Funambol (via SyncML) and Kerio Groupware.

  • Zarafa

Zarafa is an open-source email and collaboration tool.  We’ve had many requests to extend the addon to sync with Zarafa.

Unfortunately, while we continue to track interest in Zarafa, it’s user-base remains small compared to Google/Zimbra/Hotmail/Yahoo/iPhone, so it’s not likely to jump to the top of our priority list in the near term.

  • iPhone

Let us know if you would like the addon to sync iPhone contacts with Thunderbird.

  • One-way sync …

Let us know if you would like the addon to sync one-way only, either server ==> Thunderbird or Thunderbird ==> server or both.

Finally, if you are a developer, remember that the addon is open source, so you are free to study the addon and extend it yourself.  Please drop us a line if you want help getting started.

Reporting bugs

To report a bug:

  1. locate the Zindus logfile (see below)
  2. zip it up
  3. email it as an attachment along with a description of the problem to support@zindus.com
  4. open Tools/Error Console and copy+paste into your email anything that looks relevant.

The logfile helps us understand what the problem is. Without it we often can’t be of much help.

Disclosure: along with debugging information, the logfile may also contain part or all of your addressbook. Of course, we treat your personal information as completely confidential - as per the Privacy Policy.

The logfile is located in the zindus/log/ subdirectory of the Thunderbird profile directory.

Thunderbird profile directory

Example locations of Thunderbird’s profile directory:

Windows 2000 and XP:
C:\Documents and Settings\John Smith\Application Data\Thunderbird\Profiles\yidda0ce.default\zindus\log\logfile.txt

Windows Vista:
C:\Users\John Smith\AppData\Roaming\Thunderbird\Profiles\yidda0ce.default\zindus\log\logfile.txt

Debian Linux:
~/.mozilla-thunderbird/hbswezv5.default/zindus/log/logfile.txt

Apple Mac OS X
~/Library/Thunderbird/Profiles/yidda0ce.default/zindus/log/logfile.txt

To empty the logfile and force a slow sync, visit Tools/Zindus then select Reset.

What is synchronized?

For sync with Google or Zimbra, see: