Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Collapse]WinForms Controls
  Prerequisites
 [Expand]What's Installed
 [Expand]Build an Application
 [Collapse]Controls and Libraries
  [Expand]Forms and User Controls
  [Expand]Messages, Notifications and Dialogs
  [Expand]Editors and Simple Controls
  [Expand]Ribbon, Bars and Menu
  [Expand]Application UI Manager
  [Expand]Docking Library
  [Expand]Data Grid
  [Expand]Vertical Grid
  [Expand]Pivot Grid
  [Expand]Tree List
  [Expand]Chart Control
  [Expand]Diagrams
  [Expand]Gauges
  [Expand]Map Control
  [Collapse]Scheduler
   [Expand]Product Information
   [Expand]Getting Started
   [Collapse]Fundamentals
    [Expand]Scheduler Elements
    [Expand]Scheduler Structure
    [Expand]Appointments
     Resources for Appointments
    [Expand]Views
    [Expand]Data Binding
    [Expand]Mappings
    [Collapse]Supported Formats
      Synchronization with Microsoft Outlook
      iCalendar Support
      VCalendar 1.0 Support
    [Expand]Services
    [Expand]Time Zones
     Printing
    [Expand]Scheduler Reporting
   [Expand]Visual Elements
   [Expand]Design-Time Features
   [Expand]Examples
   [Expand]End-User Capabilities
   [Expand]Member Tables
  [Expand]Spreadsheet
  [Expand]Rich Text Editor
  [Expand]Spell Checker
  [Expand]Form Layout Managers
  [Expand]Navigation Controls
  [Expand]Printing-Exporting
  [Expand]PDF Viewer
   Reporting
  [Expand]Snap
  [Expand]TreeMap Control
 [Expand]Common Features
  Get More Help
 [Expand]API Reference
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Expand]eXpressApp Framework
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Synchronization with Microsoft Outlook

This document explains the recommended technique for synchronizing the Microsoft Outlook calendar with XtraScheduler. It provides a detailed overview on how to import/export Outlook calendar items, as well as a step-by-step guide for implementing your own synchronization procedures.

The technique described in this article is compatible with the following versions of Microsoft Outlook.

  • Outlook 2003
  • Outlook 2007
  • Outlook 2010 (32-bit and 64-bit)
  • Outlook 2013 (32-bit and 64-bit)

Expanded Synchronizer

The XtraScheduler Suite provides a base class designed specifically for import/export operations - the AppointmentSynchronizer. For export operations (Scheduler->Outlook), use its descendant - the AppointmentExportSynchronizer class. For import operations (Outlook->Scheduler), use another descendant - the AppointmentImportSynchronizer class. The synchronizer requires an additional data field for storing the identifier of the Outlook calendar item which corresponds to a Scheduler appointment. The name of the field is specified using the AppointmentSynchronizer.ForeignIdFieldName property, as illustrated in the image below.

The procedure starts with the creation of the required type of synchronizer. To accomplish this, use either simple constructors or specialized methods - SchedulerStorageBase.CreateOutlookImportSynchronizer and SchedulerStorageBase.CreateOutlookExportSynchronizer.

Next, it is necessary to specify initial parameters for the synchronizer to ensure its proper operation. Required options are the AppointmentSynchronizer.ForeignIdFieldName and the CalendarFolderName. The first property, as illustrated above, specifies a database field name to store the EntryID value of the Outlook AppointmentItem. The CalendarFolderName property specifies the name of the Microsoft Outlook Calendar. If it is left empty, the default path for the current Microsoft Outlook installation is used. The default path for the Microsoft Outlook 2013 Calendar is "\\Outlook Data File\Calendar". To modify the CalendarFolderName property, cast the synchronizer to the ISupportCalendarFolders type and use the ISupportCalendarFolders.CalendarFolderName property.

To determine the calendar paths, use the OutlookExchangeHelper.GetOutlookCalendarPaths method. This method returns an array of strings representing calendar locations.

Expanded Synchronization

To start the process, call the AppointmentSynchronizer.Synchronize method. Handle the AppointmentSynchronizer.AppointmentSynchronizing event to decide whether or not to copy a particular calendar item. This approach is flexible enough to implement any kind of synchronization mechanism, so you are not restricted by any predefined settings. You can leave the item intact, modify it or perform other actions that suit your synchronization model.

Also, the AppointmentExchanger.SourceObjectCount property of the synchronizer returns the number of items to process. It assists you in organizing your work, and preparing supplementary elements, such as the progress bar, to indicate process completion.

Setting the AppointmentCancelEventArgs.Cancel property to true within the AppointmentSynchronizing event handler cancels the operation. In this instance, the AppointmentSynchronizer.AppointmentSynchronized event will not occur.

The following code snippet illustrates import from MS Outlook.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=T158895.

The import and export operations are schematically represented in the following images.

Export to Microsoft Outlook

Import from Microsoft Outlook

Expanded Event Handling

Next, we will examine synchronizer events in more detail. The SynchronizeOperation enumeration defines the available operation types - SynchronizeOperation.Create, SynchronizeOperation.Replace and SynchronizeOperation.Delete. The operation type indicates whether the target calendar item should be created, modified or deleted.

The following tables presents default variants of synchronization behavior. The plus sign indicates the presence of an appointment, and the minus sign indicates its absence.

Expanded Import from Outlook

Outlook item (source)

XtraScheduler item (destination)

Operation

+

-

Create

+

+

Replace

-

+

Delete

Expanded Export to Outlook

Outlook item (destination)

XtraScheduler item (source)

Operation

+

-

Delete

+

+

Replace

-

+

Create

By analyzing the AppointmentSynchronizingEventArgs.Operation and AppointmentEventArgs.Appointment properties, you can implement virtually any appointment conflict resolution scenario while synchronizing XtraScheduler with Microsoft Outlook. If the target calendar application contains both previous and new appointments, and you wish to leave the existing appointments intact, you can set e.Cancel to true to stop the operation when e.Operation is equal to SynchronizeOperation.Replace.

Show Me

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=T158895.

Other scenarios may require you to modify the operation type within the AppointmentSynchronizer.AppointmentSynchronizing event handler. Instead of Replace you may choose to Delete the calendar item. This can easily be accomplished by changing the AppointmentSynchronizingEventArgs.Operation property value from SynchronizeOperation.Replace to SynchronizeOperation.Delete.

You can subscribe to the AppointmentExchanger.OnException event, which is triggered if an exception arises during the process. You can analyze the exception, and if necessary, roll back the operation using the AppointmentExchanger.Terminate method.

Expanded Appointment

You do not need to create a custom field and specify a custom mapping to enable the import/export appointment functionality. The appointment's foreign ID relationship is maintained internally. To get the Outlook ID value for an appointment, you can use the IPersistentObject.GetValue method, passing the name of the field as the parameter.

Note

The export operation updates the OutlookEntryID field of the appointment's data source. Ensure that all changes are committed to the data source when import or export operations are complete.

How would you rate this topic?​​​​​​​