Synchronizing with MS Exchange

Guide
Advanced

Integration with various entities of MS Exchange via EWS protocol (Exchange Web Services) is supported by the Sync Engine synchronization mechanism.

Synchronizing tasks with MS Exchange 

The process runs in three stages:

  1. Retrieving changes from MS Exchange and applying them;
  2. Retrieving changes from Creatio and applying them
  3. Creating new tasks from Creatio in MS Exchange.

Integration classes 

As described in the "Sync Engine synchronization mechanism basics " article, in order to implement an integration using this mechanism, you need a class that implements the logic of the external storage (an heir of the RemoteProvider class). The hierarchy of provider classes is shown in figure. You also need a class that implements the IRemoteItem interface, which represents a single instance of a synchronization item (in this case — the MS Exchange task). The RemoteItem hierarchy is shown in figure.

scr_syncengine_msexchangetask_hierarchy_sheme_remoteprovider_1.png

The ExchangeTaskSyncProvider class is the service provider for the MS Exchange external storage. This class implements the logic of selecting data and saving changes in Creatio and MS Exchange. The ExchangeTask class implements the IRemoteItem interface. The logic of filling in data in the corresponding systems is implemented in it.

scr_syncengine_msexchangetask_hierarchy_sheme_remoteitem_1.png

Synchronized data 

The correspondence of Creatio objects to the ExchangeTask class fileds is shown on table.

The correspondence of Creatio objects to the ExchangeTask class fileds

Creatio object Object field The ExchangeTask class field
Activity Title <Subject
  StartDate StartDate
  DueDate <CompleteDate or DueDate depending on whether a task is finished or not.
  Priority Importance
  Status Status
  RemindToOwner IsRemindSet
  RemindToOwnerDate ReminderDueBy
  Notes Body.Text

Logic of selecting data for synchronization 

To select changes to the list of tasks selected for MS Exchange folder synchronization, use the following terms: select tasks for MS Exchange, which were modified after the last task synchronization or an MS Exchange task, which was not marked as synced. The MS Exchange task which were modified have corresponding activities in Creatio. The updated changes are applied in the corresponding system.

When you select modified Creatio activities, select the following:

  • activities that are recorded in the metadata synchronization as MS Exchange tasks.
  • activities that have the current user as an author.
  • activities with a date of the last modification that does not correspond to the date of the last synchronization.

When selecting new Creatio activities, configure a set of common and custom filters. The main filter conditions are:

  1. Activity type is not "email".
  2. Activity does not have the Display in calendar checkbox selected.

A user can specify activity groups that will be exported from Creatio.

Filling in the Start Date and Due Date fields 

The ExchangeTask object has several features for working with start date and due date:

  • These fields are stored without time values. If you change a task in MS Exchange after synchronization, Creatio will apply the date from the MS Exchange task, and the time from the Creatio activity.
  • The due date in ExchangeTask has two fields: due date and complete date.
  • The start date and due date are optional in MS Exchange. If either of them is not filled in, the current date is set. Due to this, conflicts may arise, as both the start date and due date are required in Creatio, and the start date should be earlier than the due date.

Synchronizing contacts with MS Exchange 

The process runs in three stages:

  1. Retrieving changes from MS Exchange and applying them.
  2. Retrieving changes from Creatio and applying them.
  3. Creating new contacts from Creatio in MS Exchange.

Integration implementation 

As described in the "Sync Engine synchronization mechanism basics " article, to implement integration using this mechanism, a class is required that implements the logic of working with external storage (RemoteProvider heir) and a class that implements the IRemoteItem interface, which is an instance of the synchronization element (in our case — MS Exchange contact).

RemoteProvider hierarchy schema

scr_syncengine_msexchangecontact_hierarchy_sheme_remoteprovider.png

RemoteItem hierarchy schema

scr_syncengine_msexchangecontact_hierarchy_sheme_remoteitem.png

The following classes are used for contact synchronization:

  • The ExchangeContactSyncProvider class is the service provider for the MS Exchange external storage. This class implements the logic of selecting data and saving changes in Creatio and MS Exchange.
  • The ExchangeContact class implements the IRemoteItem interface. The logic of filling in data in the corresponding systems is implemented in it.
  • The ExchangeAddressDetailsSynchronizer class contains methods for converting contact addresses.
  • The ExchangeEmailAddressDetailsSynchronizer class contains methods for converting contact email addresses.
  • The ExchangePhoneNumbersDetailsSynchronizer class contains methods for convertingcontacts phones.

The logic of filling in details is located in separate classes, as there are significant differences in the formats of data storage in Creatio and MS Exchange. Additional conversion is required.

Synchronized data 

The correspondence of Creatio objects to the Contact MS Exchange class fields is shown on table.

The correspondence of Creatio objects to the Contact MS Exchange class fields

Creatio object Object field The Contact MS Exchange class field
Contact Name DisplayName
  Surname Surname
  GivenName GivenName
  MiddleName MiddleName
  Account CompanyName
  JobTitle JobTitle
  Department Department
  BirthDate Birthday
  SalutationType TitleTag
  Gender GenderTag
ContactCommunication Number The PhoneNumbers collection values
  CommunitactionType The PhoneNumbers collection value key
ContactAddresses City The PhysicalAddresses collection element City field
  Country The PhysicalAddresses collection element CountryOrRegion field
  Region The PhysicalAddresses collection element State field
  Address The PhysicalAddresses collection element Street field
  Zip The PhysicalAddresses collection element PostalCode field
  AddressType The PhysicalAddresses collection value key<

The correspondence of communication types is shown in table.

The correspondence of communication types of Creatio to MS Exchange

Creatio communication type MS Exchange communication type
Email EmailAddress1, EmailAddress2, EmailAddress3
WorkPhone BusinessPhone, BusinessPhone2
HomePhone HomePhone
MobilePhone MobilePhone

The correspondence of addresses is shown in table.

The correspondence of addresses of Creatio to MS Exchange

Creatio address type MS Exchange address type
HomeAddress Home
BusinessAddress Business

Logic of selecting data for synchronization 

To select changes to the list of contacts selected for MS Exchange folder synchronization, use the following terms: select contacts for MS Exchange, which were modified after the last contact synchronization or an MS Exchange contact, which was not marked as synced. The contacts which were modified have corresponding contacts in Creatio. The updated changes are applied in the corresponding system.

When you select Creatio contacts for synchronization, select the following:

  • contacts that have the current user as an author
  • contacts with a date of last modification that does not correspond to the date of the last synchronization.
  • contacts that were not used on the first step of synchronization

User settings also affect the rules for selecting new contacts in Creatio. Three settings are available:

  1. Synchronize employees contacts. When you select this setting, the "Contact type" filter will be added to the request, and only the "Employee" type contacts will be synchronized.
  2. Synchronize customers contacts. When you select this setting, the "Contact type" filter will be added to the request, and only the "Customer" type contacts will be synchronized.
  3. Sync contacts from certain groups. When you select this setting, the selected contact group filters will be added to the request.

Additional features 

Using the advanced contact keys in external storage 

A situation may occur when there is a large number of MS Exchange contacts and of them will receive the same ID. As a result, synchronization may not correctly identify the appropriate contact in Creatio. To work around this situation, there are advanced external keys, which can be enabled by the Use composite IDs for MS Exchange synchronized contacts setting. Setting code - UseComplexExchangeContactId. After enabling it, you may need to resynchronize.

Synchronizing appointments with MS Exchange 

Creatio appointment synchronization is performed only for new activities or when the Title, Location, StartDate, DueDate, Priority, Notes fields are modified. The hash stored in the additional metadata parameters (in the ExtraParameters field) is formed according to these fields. If an appointment has been changed in Creatio, and the hash for ExtraParameters does not match the new hash, this appointment should be synchronized.

The process runs in three stages:

  1. Retrieving changes from MS Exchange and applying them.
  2. Retrieving changes from Creatio and applying them.
  3. Creating new appointments from Creatio in MS Exchange.

Integration implementation 

As described in the "Sync Engine synchronization mechanism basics " article, to implement integration using this mechanism, a class is required that implements the logic of working with external storage (RemoteProvider heir) and a class that implements the IRemoteItem interface, which is an instance of the synchronization element (in our case — MS Exchange appointment).

scr_syncengine_msexchangeappointment_hierarchy_sheme_remoteprovider.png

The ExchangeAppointmentSyncProvider is the provider used to work with the Exchange external storage. It contains the logic of selecting data and saving changes in Creatio and Exchange.

The ExchangeAppointment class implements the IRemoteItem interface, in which the logic of filling in data in Creatio objects is implemented.

scr_syncengine_msexchangeappointment_hierarchy_sheme_remoteitem.png

Synchronized data 

The correspondence of Creatio objects to the ExchangeAppointment class fileds is shown on table.

The correspondence of Creatio objects to the ExchangeAppointment class fileds

Creatio object Object field MS Exchange Appointment corresponding field
Activity Title Subject
  Location Location
  StartDate StartDate
  DueDate CompleteDate or DueDate depending on whether an appointment is finished or not.
  Priority Importance
  Status

Filled in as follows:

If the status is not specified and the due date is later than the current date — Creatio sets the "New Appointment" status.

If the due date is earlier than the current date, the status is set as a closed appointment with the "Information received" status.
  RemindToOwner IsReminderSet
  RemindToOwnerDate ReminderDueBy
  Notes Body.Text
ActivityParticipant InviteResponse If the checkbox in MS Exchange is selected that identifies that an appointment was received and the user is its owner, and the "Appointment confirmed" checkbox is selected. Otherwise, it the checkbox is selected that identifies that the appointment was canceled.

Logic of selecting data for synchronization 

To select changes to the list of appointments selected for MS Exchange folder synchronization, use the following terms: select appointments for MS Exchange, which were modified after the last contact synchronization or an MS Exchange appointment, which was not marked as synced. The appointments which were modified have corresponding contacts in Creatio. The updated changes are applied in the corresponding system.

When you select modified Creatio activities, select the following:

  • activities which are recorded in the synchronization metadata as MS Exchange appointments via RemoteId (determined by a unique appointment ID in the ICalId calendar);
  • activities with a date of the last modification that does not correspond to the date of the last synchronization.
  • one appointment in Creatio corresponds to several appointments in MS Exchange for each participant.

When selecting new Creatio activities, configure a set of common and custom filters. The main filter conditions are:

  1. Activity type is not "Email".
  2. Activity has the Display in calendar checkbox selected.

A user can specify activity groups that will be exported from Creatio.

Logic of selecting appointment participants 

When you synchronize an activity from MS Exchange to Creatio, only contacts that have email addresses from the list of appointment participants in MS Exchange are added to the Participants detail.

When you synchronize activities from Creatio to MS Exchange, the appointment participants for MS Exchange are filled in with primary contact email addresses.