Synchronization with Microsoft Outlook
- 5 minutes to read
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)
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 - SchedulerDataStorage.CreateOutlookImportSynchronizer and SchedulerDataStorage.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.
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.
Note
A complete sample project is available at https://github.com/DevExpress-Examples/synchronization-with-ms-outlook-a-demonstration-example-t158895
AppointmentImportSynchronizer synchronizer = schedulerControl1.Storage.CreateOutlookImportSynchronizer();
// Specify the field that contains appointment identifier used by a third-party application.
synchronizer.ForeignIdFieldName = OutlookEntryIDFieldName;
// The AppointmentSynchronizing event allows you to control the operation for an individual appointment.
synchronizer.AppointmentSynchronizing += new AppointmentSynchronizingEventHandler(importSynchronizer_AppointmentSynchronizing);
// The AppointmentSynchronized event indicates that the operation for a particular appointment is complete.
synchronizer.AppointmentSynchronized += new AppointmentSynchronizedEventHandler(importSynchronizer_AppointmentSynchronized);
// Specify MS Outlook calendar path.
((ISupportCalendarFolders)synchronizer).CalendarFolderName = comboBoxEdit1.EditValue.ToString();
// Perform the operation.
synchronizer.Synchronize();
The import and export operations are schematically represented in the following images.
Export to Microsoft Outlook
Import from Microsoft Outlook
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.
Import from Outlook
| Outlook item (source) | XtraScheduler item (destination) | Operation |
|---|---|---|
| + | - | Create |
| + | + | Replace |
| - | + | Delete |
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.
Tip
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.
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.