EspoCRM Outlook Connector for Outlook 365 and Exchange Online

The EspoCRM Connector for Outlook 365 and Exchange Online allows bidirectional synchronization of calendar events such as: tasks, meetings, and calls between EspoCRM and Outlook 365 (or Exchange Online). The synchronization is performed at the scheduled time (time interval) by running the scheduled cron jobs in EspoCRM.

Admin Functions

In Outlook 365 or Exchange Online

Creating application

To install the synchronization module, you must first create an application in Outlook. To do this switch to and log in with your user credentials and create an application in Outlook 365 that you can use to create tokens for authorization.

To add a new application, click on the “Add an App” button, enter the name of the application you are creating in the open window, and click on the “create” button.

addanapp

Generating password (public key)

After going to the settings page of the new application, you must generate a password (public key) that will be used to synchronize the EspoCRM and Outlook 365 entities. For this click on the button “Generate New Password”.

appsecret

Important! The password in its full form is only displayed immediately after its generation - this password is to be saved. You will not be able to see the password later. In the future, this password must be entered in the EspoCRM event synchronization settings.

Adding platform

After creating the password, you must add a platform for which the application is created and assign appropriate redirects that relate to EspoCRM. To do this, click on the “Add platform” button and select the platform type “WEB” in the open window.

addplatform

After adding the platform, register two redirect URLs (to add another URL, click the “Add URL” button).

Important! Redirects must be https:

https://.../api/v1/OutlookCalendar/Authorization/Graph
https://.../api/v1/OutlookCalendar/Authorization/Outlook

The following image shows the permissions that are required for proper EspoCRM Outlook synchronization: To add permissions, click the “Delegated Permissions - Add” and “Application Permissions - Add” button. In the following window, select all required elements and click “Confirm” and “Save”.

permissions

In EspoCRM

Install and set up composer

professional support may be required.

"league/oauth2-client": "^2.0",
"microsoft/microsoft-graph": "1.0.*"
  • Change of the doctrine version may be necessary:
"doctrine/dbal": "2.4.2"

Module Installation

To install the module, go to the admin panel EspoCRM ../#Admin/extensions. Choose the module archive and click on the button “Upload”.

extention-install

After installing module, please rebuild the system (../#Admin/rebuild), empty the server cache (../#admin/clearCache) and local cache (../#clearCache)

rebuild

Enable Synchronization in EspoCRM

After installing the module, go to ../#Admin/integrations/name=OutlookCalendar and set the value to “Enabled” to enable synchronization. After activation, you must enter the following application data from Outlook 365: “Application ID”, “Application Secrets”, the password generated in Outlook, and “Number of events or tasks for synchronization” (Default 10) - the number of events being synchronized in one iteration of synchronization.

integrations

Setting Up the Default Synchronization Rules

Admin can set up the default (standard) synchronization rules in ../#Admin/integrations/name=OutlookCalendar for all users.

For further description see "Setting Up the Synchronization Rules".

Important! The settings specified in the admin area are the default settings for all users. If you need to change some specific setting for a particular user, you can do this in the user preferences ../#Preferences .

By default users have access to their own preferences and can override the default synchronization settings, but in this module admin can change user's access to his preferences, see "Update User Access Rights to their Preferences" for further information.

Configure the synchronization schedule

After the module installation, the data entry for automatic synchronization of each event type is created in the admin area ../#ScheduledJob. Here you can specify the frequency for each synchronization.

cronjobs

Manual synchronization start

Normally, ScheduledJobs are set up for synchronization (see above), but sometimes it is necessary to manually start synchronization for a specific entity. To do this, you can select a synchronization direction (“To Espo”/“To Outlook”) and the event type to be synchronized (“Meeting”/“Call”/“Task”) on the ../#Admin/integrations/name= OutlookCalendar page and click on the “Synchronize” button.

manualsynchro

Update User Access Rights to their Preferences

By default all (non-admin) EspoCRM users always can see and edit their own Preferences at the page ../#Preferences and admin cannot change this.

Our module allows the EspoCRM admin to set up for any role the access rights to his/her own preferences or separate preference fields using the standard ACL tool ../#Role.

acl-preferences

This was done because the following synchronization settings can be done by either admin or the account owner (usual user) himself at their preferences page:

  • Binding EspoCRM and Outlook accounts by the e-mail address (see "Binding EspoCRM and Outlook accounts").
  • Set up Synchronization Rules (see "Set up Synchronization Rules")

User Functions

Binding EspoCRM and Outlook accounts

*Admin can forbid the users to access this setting, see "Update User Access Rights to their Preferences" for more information.

In order to be able to synchronize, after completing the settings in the admin panel, each individual EspoCRM user should be associated to his Outlook account.

To do this, Admin or the user himself should go to his user settings ../#Preferences and activate the checkbox “Enable synchronization”. To grant access to the Outlook account, click on the “Generate Token” link and authorize your Outlook login and password in the open window.

enable-synchro

If the generated tokens are displayed in the settings, it means the access is properly provided and the synchronization is working.

In these settings, you should also specify, starting date from when the events should be synchronized.

Setting Up the Synchronization Rules

Admin can forbid the users to access this setting, see "Update User Access Rights to their Preferences" for more information.

Users can set up the synchronization rules at their preferences page ../#Preferences

espo-conflictresolutionsetup

Options for the direction of synchronization of each event type:

  • Disable - the synchronization is deactivated;
  • Espo to Outlook - the synchronization of events runs in one direction, from EspoCRM into Outlook;
  • Outlook to Espo - the synchronization of events runs in one direction, from Outlook into EspoCRM;
  • In both directions - the synchronization of events is bidirectional. If you select the synchronization direction “In both directions” option, you can specify the priority of the synchronized values (for situations when between two synchronizations the same event field in both EspoCRM AND in Outlook has been changed).

Options of synchronization priority are:

  • From Espo - prioritized is the data transferred from EspoCRM;
  • From Outlook - prioritized is the data transferred from Outlook;
  • By a newest date - prioritized is the data that was modified later;

Events are synchronized between EspoCRM and Outlook along with their participants. For Outlook fields Name+Email are sufficient, and these are not mandatory fields. In EspoCRM, every event participant must have a data entry: either as contact, or as lead, or as user. So when an event participant comes with email address from Outlook, EspoCRM checks if this address already exists in the user list. If not - the contacts list and then the leads list will be checked. If user comes without e-mail address or his e-mail address was not found in the above 3 lists, a new contact OR a new lead will be created in EspoCRM (configurable).

Options of participant types automatically created in EspoCRM:

  • Contact - the missing participant of the event is created as a new contact in EspoCRM;
  • Lead - the missing participant of the event is created as a new lead in EspoCRM (recommended). He can later be manually converted to Contact.

Viewing Synchronization History and Reverting Event Updates

After connecting and configuring the synchronization, the synchronization of the events between the two platforms takes place depending on the set synchronization direction and priority for each event type (“Meeting”/“Call”/“Task”).

After the event is created, events are synchronized based on the configured schedule. When using unidirectional synchronization from one system to another, the events must always be managed (created, modified, and deleted) in the platform from which the events are synchronized.

In Espo, you can see the history of synchronization and, if necessary, restore the changed values.

To see the complete synchronization history for all events, open the link ../#OutlookHistory

To see the exact changes of a specific event during synchronization, open a “System updated ..” time entry in the stream of this event.

stream

After opening a specific change during synchronization, you can see the field that was updated during synchronization, the direction of synchronization, the type of change (create / update) and its old and new value.

history

Note: Changes to attachments are not presented here.

With “Revert” you can undo the changes made by the specific synchronization and restore the previous values.

Individual (de) activation of synchronization for specific events

The synchronization of the supported events is active by default. But it can be individually deactivated for each specific event (as well as activated again later). To do this, you can switch the “Synchronize with Outlook” checkbox at the event page.

event-setting

When syncing tasks, the attachments added to these tasks are also synced. Sync history does not specify changes made to attachments.

Event reminders

Event reminders are also synchronized. Depending on the nature of the event, a reminder will be sent either as a notification of the event start date (for Calls, Meetings) or as a notification of event due date (for Tasks). Since in EspoCRM any number of reminders is possible, and in Outlook - only 1, only the first reminder is sent from EspoCRM to Outlook during the synchronization.