With Debian 8 "Jessie", the Kontact Personal Information Management system receives a major upgrade. The new version makes much greater use of the indexing technologies that have been developed by the KDE community in recent years. For example,
akonadi coordinates actions such as logging into an IMAP server to obtain new mail, addressbooks and calendars.
baloo indexes the contents and metadata of emails enabling fast searching
Log out before upgrading
It is highly recommended that the user not be logged into a Plasma desktop session while the upgrade and dist-upgrade is run. At the very least, ensure that akonadi, nepomuk, kmail and kontact are not running.
Contents
Email (kmail)
Once the upgrade of the packages installed on the system is completed (that is, after the apt-get dist-upgrade step is finished and the system is booted into the updated kernel as per the release notes, each user needs to migrate their settings from the old kmail into the new.
- Log in through the display manager as normal
- Start kontact or kmail, if akonadi is not already running, it will be started (akonadi will automatically upgrade its database schema as required, this is quite fast)
- The KMail Migration Wizard will start and create new akonadi resources for the email accounts as needed
- The email accounts will be checked but there is lots of data to sync and this will take a while (reports of up to 30 min)
- The sidebar where accounts and folders will show the local folders and each migrated account as well as an entry for the old accounts from before the migration (this can be deleted from Settings → Configure KMail → Accounts once the migration is verified to have been completed successfully; cache data from disconnected IMAP accounts in ~/.kde/share/apps/kmail/dimap can be similarly deleted)
- It may be necessary to either restart kmail/kontact or even log out and log back in for the entire migration to complete. Given how central akonadi is to the desktop, that's probably a sensible step to take.
Troubleshooting:
If akonadi doesn't start up fast enough when the migration tool is run, the migration tool will assume that something is wrong with akonadi and drop back to an error dialogue. After closing the error dialogue, KMail will still start but will offer to create accounts etc because it currently has no data in it. Do not create new accounts; instead, exit KMail straight away and then run kmail-migrator --interactive (On a relatively slow test machine, akonadi took ~60s to start, perform its database migration and become responsive but the migration tool only waited ~10s.)
If, immediately following the migration completing, akonadiserver, akonadi_maildispatcher and mysqld seem to be stuck at 100% CPU without much happening, restart akonadi with akonadictl restart (or from the K-menu entry for the akonadi server) or alternatively, log out and log back in again.
Email Indexing
If the Message Search facility does not return results, it may be that indexing is not set up properly. Right clicking on an email folder in the KMail folder hierarchy, select Folder Properties → Maintenance and double check that Indexing is enabled for the folder. If all folders show that indexing is enabled but that the folder is not yet indexed, then baloo is not installed and running.
Install the necessary packages: as root, apt-get install baloo4 kde-config-baloo-advanced
In the System Settings dialogue, select Desktop Search (Advanced) and add ~/.kde to the excluded folders list if it is not already
- Logging out and then logging back in again is the simplest way to ensure that each of baloo, akonadi and kmail are working together
In akonadiconsole or System Settings → Personal Information, a resource called Akonadi Baloo Indexing Agent should be active
Email Filters
Email filters are not automatically migrated to the new KMail; however, they are not lost. The filters are still all stored in the old kmailrc configuration file and that can be directly imported into the new KMail. (It is also possible to export the filters from Wheezy's KMail prior to the upgrade and the import this backup into the new KMail which is perhaps a little more elegant.)
- In KMail, Settings → Configure Filters → Import
Either navigate to or directly type in ~/.kde/share/config/kmailrc
- Open the file to start importing the filters
- It is necessary to repair all the filters because the names of the folders have changed with the migration; however, the importer will make a very good guess at the folder names so it's only a matter of selecting the correct folder from the list. If there are multiple folders with the same name in the hierarchy then it is necessary to just guess which one is intended and then check and fix the filter later as there is no context given in the folder selection box. Select the folders that are in the new accounts hierarchy and not in the "Previous KMail's folders" hierarchy if they have not yet been deleted.
- At the end of the process of repairing the filters, a list of filters is presented and a selection (probably all of them) can be imported.
Custom Email Templates
Custom templates for replying to mails are not imported into the new KMail; however, they are not lost. The templates are still in the kmailrc configuration file.
Back up ~/.kde/share/config/kmail2rc and ~/.kde/share/config/customtemplatesrc
Copy either the entire ~/.kde/share/config/kmailrc file or (much better) its sections that have CTemplates headings (like the following) into ~/.kde/share/config/customtemplatesrc
[CTemplates #Generic thanks] Content=Dear %OFROMNAME,\n\nThank you for your enquiry. We're sure you'll love the new KMail\nregards\nDebian Qt/KDE Team\n%SIGNATURE Type=1
Add comma-separated references for these custom templates into the kmail2rc file. It should be sufficient to run the following to do this:
echo -en '[TemplateParser]\nCustomTemplates=' >> .kde/share/config/kmail2rc sed -nr 's/.CTemplates #(.*)]/\1/p' .kde/share/config/kmailrc | tr '\n' , >> .kde/share/config/kmail2rc
This would generate a section in the configuration file looking like
[TemplateParser] CustomTemplates=Generic thanks,Some template name,
Unresolved KMail Problems
Sent or received?: KMail can get confused about whether a folder is for incoming mail or sent mail (772612) and it is not evident why this is the case. In some circumstances, changing the folders listed in the Identities to not point to subfolders of the Inbox has been reported to help but this is not a universal fix. When KMail gets this wrong, it wrongly shows the Sender or Receiver column in the list of messages and, if it thinks the folder is a sent-mail folder, it may incorrectly show "Edit message" and "Send again" actions in the Message menu and context menu.
Calendars (korganizer)
Calendar data is migrated automatically including local file and directory resources.
Some Google Calendar hosted calenders are not correctly parsed by akonadi and this can result in flashing entries in the calendar, repeated attempts to download the resource and high CPU usage. If authenticated access to the calendar is available, then the new Google Calendars and Tasks akonadi resource is much more flexible. The Google Calendars and Tasks agent can be added from System Settings → Personal Information. Multiple accounts can be configured within this resource.
Addressbooks (kaddressbook)
File based addressbooks are migrated automatically.
For GMail users, the old akondai_googledata_resources (from the akonadi-kde-resource-googledata package) can be replaced with the new Google Contacts resources. These share authentication information with the similarly named Google Calendars and Tasks resources, can configure multiple accounts, understand the tag/categorisation structure of the Google contacts and are much more robust.
Further resources
Userbase:Akonadi Userbase:Akonadi and AddressBook Userbase:Kmail FAQs a little bit outdated