Calendars and contacts synchronization / Outlook plugin

Developer's documentation (not related to Easy Project)

Calendars and contacts synchronization is a plugin for Microsoft Outlook, which synchronizes events, tasks, CRM data, contacts and other resources between Easy Project and Outlook. Easy Project server uses CalDAV/CardDAV standard, which means that also other compatible apps and devices can be used instead of Outlook such as Mozilla Thunderbird, Apple iOS or Android OS with a sync app installed.

Overview
Features
How to get the plugin
How to install the plugin
Types of CalDAV entities to synchronize
How to configure the plugin
General options and SSL settings
Profile import/export
Synchronization status and system tray icon with notifications
Troubleshooting
Common network problems
Category filter and color
Corner situations

Overview

Calendars and contacts synchronization plugin brings a better experience to all Easy Project users, not only to users of Outlook e-mail client. Now users of all CalDAV compliant calendar apps can experience the same visualization like in Meeting calendar of Easy Project. This was achieved by:

Improving CalDAV functionality on Easy Project server – standard user without the plugin can synchronize meetings to any device supporting CalDAV. A user with purchased plugin can synchronize more entities so is able to see calendar visualization similar to the internal calendar in Easy Project (tasks, milestones, CRM cases, etc). This applies basically to all devices/programs.
This extension to MS Outlook enables CalDAV synchronization for Outlook e-mail and calendar client, which is not supported by default. The integration is between Easy Project server and local Outlook application, not with Exchange server.

It means that if you are not Outlook e-mail client user but, for instance, Mozilla user with Lightning Calendar extension, you can just go and configure your local calendar client and benefit from this new plugin without any installation.

As for Apple iOS, CalDAV protocol is natively supported so you don't need to install any additional application to synchronize data between Easy Project and your mobile device.

As for Android operating system, CalDAV protocol is not natively supported so you need to install an additional application to synchronize data between Easy Project and your mobile device. You can select from a broad variety of such apps at Google Play online store after entering keyword "CalDAV" into the search box (see below).

For Microsoft Exchange users

If your organization is using Microsoft Exchange server, you may consider synchronizing especially meetings from Easy Project to your local calendar folder, which is under synchronization with Exchange server. This way your Outlook will propagate data from Exchange to Easy Project and vice versa and so your colleagues also see your availability and meetings based in both systems. The limitation is that such data exchange is done only through your local Outlook application and hence the data are not exchanging once you PC with Outlook is turned off.

Features

Two-way-sync
SSL/TLS support, support for self-signed certificates and client certificate authentication
Manual proxy configuration support for NTLM or basic auth proxies
Autodiscovery of calendars and address books
Configurable sync range
Sync multiple calendars per profile
Sync reminders, categories, recurrences with exceptions, importance, transparency
Sync organizer and attendees and own response status
Task support
CardDAV support to sync contacts
Time-triggered-sync
Change-triggered-sync
Manual-triggered-sync
Category Filtering (sync CalDAV calendar/tasks to Outlook categories)
Map CalDAV server colors to Outlook category colors
Show reports of last sync runs and status
System tray icon with notifications
Bulk creation of multiple profiles
Use server settings from Outlook IMAP/POP3 account profile
Map Windows to standard IANA/Olson timezones
Configurable mapping of Outlook custom properties
Create DAV server calendars/addressbooks with MKCOL
Map Outlook formatted RTFBody to HTML description via X-ALT-DESC attribute

How to get the plugin

The plugin is available to purchase via the Client zone or free download from here. Please note that support for meetings synchronization is provided free of charge, while support for synchronization of other entities is paid only according to the current price of the plugin.

How to install the plugin

If you used any previous version of CalDAV synchronizer, please delete all profiles and uninstall CalDAV synchronizer before you start installing a new one. Download and extract the installation ZIP file into any directory and start setup.exe. You can change the default install path, but you need to use a directory on the C:\ drive. If the installer is complaining about the missing Visual Studio 2010 Tools for Office Runtime, install it manually from here. You should also update manually to the latest Visual Studio 2010 Tools for Office Runtime (Version 10.0.60825) if you have an older version installed, since some COMExceptions have been fixed.

The default install location is ProgramFilesDir\CalDAVSynchronizer\ and the installer remembers the chosen directory for the next updates. Also the install option to install for Everyone instead of the current user is working now for Outlook 2010 and higher, if you want to install the addin for all users on the current machine. For Outlook 2007 you can only install the addin for the current user. We recommend updating to the latest .NET Framework but the minimal required version is .NET 4.5, which is not supported on Windows XP. If you need Outlook CalDAV Synchronizer for Windows XP you can download a backport to .NET 4.0 from a forked project here.

Types of CalDAV entities to synchronize

The following entities are possible to sync with any CalDAV client. In Outlook CalDAV Synchronizer, enter the URL https://yourdomain.easyproject.com/caldav/ without any appendix and the tool will automatically provide you with the full selection of entities available for synchronization just after clicking on "Test or discover settings" button in Synchronization Profiles.

In the Essentials Plan:

Meetings
Tasks
Milestones

In the Business Plan:

Attendance
Resource allocations

In the Platform plan (or with the B2B CRM plugin):

Opportunities
Contracts
Sales activities

How to configure the plugin

After installing the plugin, a new ribbon called "CalDAV Synchronizer" is added in Outlook with 6 menu items:

Synchronize now
Synchronization Profiles
General Options
About
Reports
Status

Use the Synchronization Profiles dialog to configure different synchronization profiles. Each profile is responsible for synchronizing one Outlook calendar/task or contact folder with a remote folder of a CalDAV/CardDAV server.

When clicking on "Test or discover settings", it will open the list of entities available for synchronization, which correspond with the selected Outlook folder (such as inbox, calendar, tasks etc.). The below image shows an example of entities of calendar type. For each entity, a unique color can be selected.

And this is an example of address books (basically contacts, users, groups of users, and related filtered lists).

Advanced configuration settings are hidden by default and you can enable them by clicking on "Show advanced settings" and disable them again by clicking on "Hide advanced settings". The default behavior can also be configured as a general option, see below.

The toolbar on the left upper part provides the following options:

Add new profile adds a new empty profile
Add multiple profiles bulk profile creation to add multiple profiles at once and choose the folder for each discovered server resource (calendar, addressbook and task)
Delete selected profile deletes the current profile
Copy selected profile copies the current profile to a new one
Move selected profile up change ordering in the tree view (only in advanced settings)
Move selected profile down change ordering in the tree view (only in advanced settings)
Open data directory of selected profile Show directory with cached relations file in explorer for debugging (only in advanced settings)
Clear cache delete the sync cache and start a new initial sync with the next sync run.
Expand all nodes expand all nodes in the tree view, enabled by default but can be changed in general options (only in advanced settings)
Collapse all nodes collapse all nodes in the tree view (only in advanced settings)
Export Profiles to File and
Import Profiles from File See Profile Import/Export

When adding a new profile you can choose between a generic CalDAV/CardDAV, a google profile to simplify the google profile creation and predefined CalDAV/CardDAV profiles for SOGo, Fruux, Posteo, Yandex, GMX, Sarenet and Landmarks, Cozy Cloud, and Nextcloud where the DAV Url for autodiscovery is already entered.

The following list includes all properties that can be configured for a new generic profile in advanced view (button "Show advanced settings"). However, most of them can be left unchanged as their predefined values are already optimized for a typical use.

Profile name: An arbitrary name for the profile, which will be displayed in the tree view.
- Outlook settings:
- Outlook Folder: Outlook folder that should be used for synchronization. You can choose a calendar, contact or task folder. Depending on the folder type, the matching server resource type in the server settings must be used.
- Synchronize items immediately after change Trigger a partial synchronization run immediately after an item is created, changed or deleted in Outlook (with a 10 seconds delay).
Server settings:
- DAV Url: URL of the remote CalDAV or CardDAV server. You should use an HTTPS connection here for security reason! The Url must end with a / e.g. https://myserver.com/
- If you only have a self-signed certificate, add the self-signed cert to the Local Computer Trusted Root Certification Authorities. You can import the cert by running the MMC as Administrator. If that fails, see section ‘Advanced options’
- Username: Username to connect to the CalDAV server
- Password: Password used for the connection. The password will be saved encrypted in the option config file.
- ** Use IMAP/POP3 Account Password** Instead of entering the password you can use the IMAP/Pop3 Password from the Outlook Account associated with the folder, the password is fetched from the Windows registry entry of the Outlook profile. (only in advanced settings)
- Email address: email address used as remote identity for the CalDAV server, necessary to synchronize the organizer. The email address can also be used for autodiscovery via DNS lookups, see section Autodiscovery.
- Create DAV resource You can add server DAV resources (calendars or addressbooks). You can configure the resource displayname and if the URL should be created with a random string or the displayname. For calendars, you can also change the server calendar color. (only in advanced settings)
Sync settings:
- Synchronization settings
  - Outlook -> Server (Replicate): synchronizes everything from Outlook to the server (one way)
  - Outlook <- Server (Replicate): synchronizes everything from the server to Outlook (one way)
  - Outlook -> Server (Merge): synchronizes everything from Outlook to the server but don’t change events created in on the server
  - Outlook <- Server (Merge): synchronizes everything from the server to Outlook but don’t change events created in Outlook
  - Outlook <-> Server (Two-Way): Two-Way synchronization between Outlook and the server with one of the following conflict resolution
- Conflict resolution (only used in Two-Way synchronization mode and only available in advanced settings)
  - Outlook Wins: If an event is modified in Outlook and in the server since last sync, use the Outlook version. If an event is modified in Outlook and deleted in the server since last sync, also use the Outlook version. If an event is deleted in Outlook and modified in the server, also delete it in the server.
  - Server Wins: If an event is modified in Outlook and in the server since last sync, use the server version. If an event is modified in Outlook and deleted in the server since last sync, also delete it in Outlook. If an event is deleted in Outlook and modified in the server, recreate it in Outlook.
  - Automatic: If event is modified in Outlook and in the server since last sync, use the last recent modified version. If an event is modified in Outlook and deleted in the server since last sync, delete it also in Outlook. If an event is deleted in Outlook and modified in the server, also delete it in the server
- Synchronization interval (minutes): Choose the interval for synchronization in minutes, if ‘Manual only’ is choosen, there is no automatic sync but you can use the ‘Synchronize now’ menu item.
- Perform synchronization in chunks and
- Chunk size perform CalDAV/CardDAV sync in chunks with configurable chunk size to avoid OutOfMemoryEceptions, disabled by default and should only be enabled for huge resources and low memory. (only in advanced settings)
- Use time range filter and
- Synchronization timespan past (days) and
- Synchronization timespan future (days) (only in advanced settings) For performance reasons it is useful to sync only a given timespan of a big calendar, especially past events are normally not necessary to sync after a given timespan. But be aware that Outlook and Google and some other CalDAV servers calculate the intersection with the time-range differently for recurring events which can cause doubled or deleted events, so it is recommended to select a time-range which is larger than the largest interval of your recurring events (e.g. 1 year for birthdays).

When everything is configured correctly, let's start the sync process by clicking on "Synchronize now" button and wait for the synchronization process to complete.

Don't forget you can assign different sources (like tasks, meetings, CRM cases, milestones, contacts, sales activities, attendance, etc.) to different folders and distinguish them by colors like on the below screen.

In order to make all the selected sources (folders) visible within a single calendar view, the overlay feature in Outlook must be enabled.

By drag and drop in Outlook or other calendars with CalDAV support, you can now change due date of tasks or milestones, replan your forecast (CRM contract date) or replan your sales activities. See details of tasks, milestones, and sales activities and get to Easy Project with one click.

The same data can be synchronized in Mozilla Thunderbird.

General options and SSL settings

In the General Options dialog, you can change settings which are used for all synchronization profiles:

Automatically check for newer versions set to false to disable checking for updates.
Check Internet connection before sync run checks if an interface is up and try DNS query to dns.msftncsi.com first and if that fails try to download http://www.msftncsi.com/ncsi.txt with the configured proxy before each sync run to avoid error reports if network is unavailable after hibernate for example. Disable this option if you are in a local network where DNS and that URL is blocked.
Store data in roaming folder set to true if you need to store state and profile data in the AppData\Roaming\ directory for roaming profiles in a AD domain for example. When changing this option, a restart of Outlook is required.
Include custom message classes in Outlook filter Disabled by default, enable only if you have custom forms with message_classes other than the default IPM.Appointment/Contact/Task. For better performance, Windows Search Service shouldn’t be deactivated if this option is enabled.
Use fast queries for Outlook folders Enabled by default, uses fast GetTable queries when accessing Outlook folders. Disable only if you get errors in GetVersions, when disabled every item needs to be requested which causes a performance penalty!
Trigger sync after Outlook Send/Receive and on Startup If checked a manual sync is triggered after the Outlook Send/Receive finishes and on Outlook startup.
Show advanced settings as default Show the advanced settings in synchronization profiles as default if enabled.
Expand all nodes in Synchronization profiles Enabled by default, expands all nodes in the synchronization profiles to see the suboptions for network settings and mapping configuration.
Enable Tray Icon Enabled by default, you can disable the tray icon in the Windows Taskbar if you don’t need it.
Fix invalid settings Fixes invalid settings automatically, when synchronization profiles are edited.
Accept invalid chars in server response If checked invalid characters in XML server responses are allowed. A typical invalid char, sent by some servers is Form feed (0x0C).
** Enable useUnsafeHeaderParsing** Enable, if the server sends invalid http headers, see common network errors. Needed for Yahoo and cPanel Horde servers for example. The general option overrides the setting in the app.config file.
CalDAV Connection Timeout (secs) For slow server connections you can increaste the timeout value (default 90 secs).

If you have problems with SSL/TLS and self-signed certificates, you can change the following settings at your own risk. The recommended way would be to add the self signed cert to the Local Computer Trusted Root Certification Authorities You can import the cert by running the MMC as Administrator.

Disable Certificate Validation set to true to disable SSL/TLS certificate validation, major security risk, use with caution!
Enable Client Certificates If enabled, the available client certificates from the Windows user certificate store will automatically be provided.
Enable Tls12 set to false to disable TLS12, not recommended
Enable Ssl3 set to true to enable deprecated SSLv3, major security risk, use with caution!

In the General Logging section, you can show or clear the log file and define the log level. Possible log levels are INFO and DEBUG.

Profile import/export

In the toolbar of the synchronization profiles, you can export all profiles to a file and import profiles from an earlier exported file. When exporting, you can choose a filename, the extension is *.cdsp and all options are saved in an xml format into this file. When importing the file, existing profiles are merged with the imported ones. If the selected Outlook folder for the profile doesn’t exist during import, you need to manually select a folder before you can save the options, they are not automatically created. You need also be aware of the fact, that saved profile passwords won’t work on other accounts or machines, since the encryption is dependant on the current user. But you can use the account password from the IMAP/POP3 account if available. General options are not saved in that file, but in the registry inHKEY_CURRENT_USER\Software\CalDAVSynchronizer.

Synchronization status and system tray icon with notifications

With the Status button in the CalDAV Synchronizer Ribbon or via double-click from the tray icon you can access the status of the active sync profiles with their last sync run shown in minutes ago and the status OK, error, or warning. When clicking on the profile name you get to the according to sync profile settings, when clicking the status icon, you can open the according to sync report. When a sync run has any errors or warnings you will get a notification from the CalDAV Synchronizer tray icon.

Troubleshooting

Options and state information is normally stored in the following folder:

C:\Users\<Your Username>\AppData\Local\CalDAVSychronizer

If you activated Store data in roaming folder the location is changed to the following folder:

C:\Users\<Your Username>\AppData\Roaming\CalDAVSychronizer

There is one options_<your outlook profile>.xml file which stores the options for each outlook profile. For each sync profile there is a subfolder with state information stored in a relations.xml file after the inital sync. If you delete that folder, a fresh inital sync is performed. In the Synchronization profiles dialog a context menu is available in each profile (right click), which allows to open the cache directory and read the relations.xml file.

Each synchronization attempt is logged in the log.txt file. There you can find information about sync duration and the amount of added, deleted or modified events. Errors and Exceptions are logged aswell. You can view and clear the log file in General Options. There you can also change the log level from INFO to DEBUG.

Common network problems

System.Net.Http.HttpRequestException: Response status code does not indicate success: ‘401’ (‘Unauthorized’).
- Wrong Username and/or Password provided.
System.Net.Http.HttpRequestException: An error occurred while sending the request. —> System.Net.WebException: The underlying connection was closed: A connection that was expected to be kept alive was closed by the server.
- The server has KeepAlive disabled. Use “Close connection after each request” in Network and proxy options.
System.Net.Http.HttpRequestException: An error occurred while sending the request. —> System.Net.WebException: The server committed a protocol violation. Section=ResponseStatusLine
- The server sends invalid headers. Enable the general option Enable useUnsafeHeaderParsing or the commented out option useUnsafeHeaderparsing in the app config file, see Debugging and more config options above.

Category filter and color

Don't change the default settings unless you are an expert or it's necessary. This can be configured only when advanced options in Synchronization profiles are displayed. If you want to sync multiple CalDAV calendars or task lists into one Outlook folder you can configure an Outlook category for filtering in the Mapping Configuration. You can choose a category from the drop-down list of all available Outlook categories or enter a new category name. For all events/tasks from the server the defined category is added in Outlook when syncing back from Outlook to the server only appointments/tasks with that category are considered but the filter category is removed. The category name must not contain any commas or semicolons! With the checkbox Sync also Appointments without any category also all appointments/tasks without a category are synced to the server. With the checkbox below you can alternatively negate the filter and sync all appointments/tasks except this category. For calendars, it is also possible to choose the color of the category or to fetch the calendar color from the server and map it to the nearest supported Outlook category color with the button Fetch Color. With Set DAV Color it is also possible to sync the chosen category color back to set the server calendar color accordingly. With Category Shortcut Key you can define the shortcut key of the selected category for easier access when creating appointments.

Corner situations

Tested on Thunderbird and Outlook 2016
We do not support exceptions.
We support only the rules that are in our classic repeating.
When you configure two synchronization profiles with the same settings (such as syncing meetings from the same source into the same folder), the items are getting multiplied with each sync repetition launched. This may harm your calendar because of a need to delete redundant items then.
A repeating event in Google Calendar does not sync with Easy Project through iCal (not implemented).
Meetings synchronized from the Meeting Calendar into Outlook Calendar has the plain text format only, with no option for HTML format yet.