Important

You are browsing the documentation for version 1.6 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Available in OroCRM Available in OroCommerce

MS Outlook Integration

The Enterprise edition of your Oro application (OroCRM or OroCommerce) supports an out-of-the-box integration with MS Outlook (2010, 2013, 2016). All contacts, tasks and calendar events can be synchronized between Oro and a specific MS Outlook account with the help of an MS Outlook add-in. In addition, with the help of the add-in, leads, opportunities and cases can be created on the Outlook side and synchronized back to Oro.

The following guide outlines the prerequisites for integration, describes the step-by-step setup process on both sides, and gives an overview of the synchronization workflow between the applications.

Note

Please be aware that emails are not synced in the course of Outlook integration. To learn about email synchronization, please refer to Email Configuration topic.

Hint

Learn how to configure Outlook Integration in Oro system settings globally and per organization.

Before You Begin

To configure the integration between your Oro Enterprise application and MS Outlook, you need to perform 6 simple steps:

  1. Ensure that you meet the hardware and software requirements.
  2. Download MS Outlook Add-in.
  3. Set up the add-in on the Outlook side.
  4. Connect the add-in to your Oro instance.
  5. Configure Outlook settings on the Oro side.
  6. Synchronize applications.
The ms outlook integration prerequisites displayed in 6 steps

Check Hardware and System Requirements

Hardware Requirements

Hardware Minimum Recommended
RAM MS Outlook x86, x64 – 4GB

MS Outlook x86 – 4GB,

MS Outlook x64 – 8GB
CPU

MS Outlook x86 - 1 GHz IA-32 processor,

MS Outlook x64 - 1 GHz x86-64 processor

 MS Outlook x86 – 2-3 GHz IA-32 processor (Dual Core), MS Outlook x64 – 2-3 GHz x86-64 processor (Dual Core)
HDD Requirements for available disk space depend on the size of PST file you operate, and other programs installed on your computer. At least 40GB of available disk space.
Disk average rotational latency 20 milliseconds 5 milliseconds

Software Requirements

  • OroCRM Enterprise version 1.6+
  • Outlook 2010+

Note

Please be aware that the following factors may influence your Outlook add-in performance:

  • Email archiving
  • Antivirus
  • Mobile devices connected to the computer
  • Voice mail
  • Other programs or Outlook add-ins that create additional views or search folders

Download MS Outlook Add-in

The link to the MS Outlook add-in is located in your Oro application instance.

To download the add-in:

  1. Click My User below your username on the top right of the application.

    My user menu displayed on the top right of the application

  2. Next to the MS Outlook Add-in option, click the link to download the file.

    The link for downloading the file displayed next to the ms outlook add-in option

    Note

    At this point it is also recommended to generate an API key by clicking Generate Key next to the API Key option. Once generated, copy the key as it will later be required during add-in installation.

  3. Open the downloaded file and start the installation process.

    Note

    You may be asked to install Visual Studio 2010 for office Runtime before proceeding with the add-in installation.

Connect MS Outlook Add-in to Oro Instance

During add-in installation you are required to provide integration settings to ensure correct work between applications:

General outlook add-in settings available when configuring the integration between applications

  1. OroCRM URL — Provide the URL of your instance:

    • If you are running a CRM application, copy the URL from the address bar. Alternatively, copy it from the Application URL field by navigating to System > Configuration > System Configuration > General Setup > Application Settings (e.g. demo.orocrm.com).
    • If you are running an OroCommerce application, add /admin at the end of the URL. Otherwise, connection between the add-in and your Oro instance may fail (e.g. demo.orocommerce.com/admin).

  2. Ignore self-signed certificate — Check this box to allow connection to secure servers that use self-signed certificates. We recommend to keep this box checked at all times.

  3. User — Provide the username defined on the My User page of your Oro instance.

    Demonstrating a path to the username defined on my user page

  4. API Key — Paste the API key generated in your Oro instance.

    Note

    You can generate the key by opening My User page and clicking Generate Key next to the API Key option. Copy the key once generated.

  5. Disable Sync — this check box defines synchronization conditions.

    • When Disable Sync is not selected, synchronization runs automatically within the intervals defined in your Oro instance.

    • When Disable Sync is selected, synchronization has to be triggered manually. One way of doing this is by right-clicking on the Outlook add-in icon on the bottom right of your screen and clicking Sync Now.

      The sync now button displayed on the bottom right of your screen when right-clicking the outlook add-in icon

    Alternatively, start sync within your Outlook application by clicking the ADD-INS tab, and clicking Sync Now in the OroCRM for Outlook settings menu.

    The sync now button displayed in the orocrm for outlook settings menu

  6. Sync Type — Select whether you wish to sync all or selected records.

  7. Show Alerts — This check box controls whether alerts are displayed in the bottom panel next to the add-in icon:

    • If the Show Alerts check box is checked, sync-related alerts pop up in the bottom panel.
    • If the Show Alerts check box is not checked, alerts are not displayed.

  8. Sync Birthdays — Select the check box if you wish to sync contacts’ birthdays.

  9. Check Connection — Click Check Connection once you filled in all the settings fields. A corresponding message pops up when the connection fails/is successful.

  10. Automatic Updating — Define the schedule and conditions for updates.

  11. Click Save to save these settings.

    When the add-in is installed, you see its icon displayed on the bottom right corner of your computer screen.

    The outlook add-in icon displayed in the bottom right corner of your computer screen

Note

You can access the same settings after installation by clicking Settings in the OroCRM for Outlook menu under the ADD-INS tab in your Outlook application.

The settings button displayed in the orocrm for outlook menu under the add-ins tab

Create Leads, Opportunities, and Cases from Outlook

With the help of the OroCRM for Outlook add-in side panel, you can create leads, opportunities and cases from Outlook based on email data, or manually, and sync the data back to your Oro application.

A path to the lead, opportunity, and case create button in the outlook application

Create a Lead from Outlook

To create a lead, open the add-in side panel in Outlook:

  1. Navigate to ADD-INS in the main menu.

  2. Click OroCRM for Outlook on the top left.

  3. Click Show/Hide Side Panel to open the panel on your right.

    Note

    You can move the panel to a different location on the screen, if necessary.

  4. In the panel, click Create.

  5. Click Lead.

  6. A pop-up window opens with a form to fill in. The create lead form has the same fields as the one in the Oro application.

    A popup window that opens when clicking lead

  7. Fill in the required details, and click Create Lead on the bottom right of the pop-up window.

  8. Start sync between the Oro and Outlook applications to sync the new lead back to Oro.

    Illustration of a lead created in outlook and synced back to the oro application

Create an Opportunity from Outlook

To create an opportunity, open the add-in side panel in Outlook:

  1. Navigate to ADD-INS in the main menu.

  2. Click OroCRM for Outlook on the top left.

  3. Click Show/Hide Side Panel to open the panel on your right.

    Note

    You can move the panel to a different location on the screen, if necessary.

  4. In the panel, click Create.

  5. Click Opportunity.

  6. A pop-up window opens with a form to fill in. The create opportunity form has the same fields as the one in the Oro application.

    A popup window that opens when clicking opportunity

  7. Fill in the required details, and click Create Opportunity on the bottom right of the pop-up window.

  8. Start sync between the Oro and Outlook applications to sync the new opportunity back to Oro.

    Illustration of an opportunity created in outlook and synced back to the oro application

Create a Case from Outlook

To create a case, open the add-in side panel in Outlook.

  1. Navigate to ADD-INS in the main menu.

  2. Click OroCRM for Outlook on the top left.

  3. Click Show/Hide Side Panel to open the panel on your right.

    Note

    You can move the panel to a different location on the screen, if necessary.

  4. In the panel, click Create.

  5. Click Case.

  6. A pop-up window opens with a form to fill in. The create case form has the same fields as the one in the Oro application.

    A popup window that opens when clicking case

  7. Fill in the required details, and click Create Case on the bottom right of the pop-up window.

  8. Start sync between the Oro and Outlook applications to sync the new case back to Oro.

    Illustration of a case created in outlook and synced back to the oro application

Review Mapping Rules Between Oro and Outlook

Specific values of the fields of OroCRM and Outlook records are mapped during synchronization of contacts, tasks, and events.

Contact Mapping Rules

The following rules represent the mapping strategy of the OroCRM contact record fields into the Outlook contact record fields.

OroCRM Field Outlook Field Note
First Name First Name If no First Name is defined in the Outlook record, the Last Name value is used for the both first name and last name in OroCRM.
Middle Name Middle Name —
Last Name Last Name If no Last Name is defined in the Outlook record, the First Name value is used for both the first name and the last name in OroCRM.
Name Suffix Name Suffix —
Description Notes —
Email Email All the existing email addresses are mapped.
Phone Primary Phone Only the first OroCRM phone number is mapped.
Job Title Job Title —
Birthday Birthday —
Gender Gender —
Fax Fax —
Address of a Billing Type Business Address —
Address of a Shipping Type Home Address —
Address with no type defined Other Address —

Task Mapping Rules

The following fields of an OroCRM task record are mapped into the following fields of an Outlook task record.

OroCRM Field Outlook Field
Subject Subject
Priority Priority
Due Date Due Date

OroCRM statuses are mapped into Outlook unchanged:

OroCRM Task Status Outlook Task Status
In progress In progress
Closed Closed
Open Open

The Outlook statuses that are not available in OroCRM are mapped as follows:

Outlook Task Status OroCRM Task Status
Not Started Open
Completed Closed
Waiting on someone else In progress
Deferred In Progress

Calendar Mapping Rules

The following fields of an OroCRM calendar event record are mapped to the following fields of an Outlook appointment.

OroCRM Field Outlook Field
Title Subject
Start Start time
End End time
All-Day Event All day event

Note

Only a calendar assigned to the specified user is mapped, regardless of access settings.

Invitations, received by the user are sent to Outlook as regular calendar events.

Important

Be aware that if you add a Google-based account to the existing MS Exchange account, your default calendar may change. This is important to remember when synchronizing events between Oro and Outlook.

Review Sync Rules Between Oro and Outlook

Select Sync Type: Automatic VS Manual

When connecting your MS Outlook application to the Oro instance, you can define the sync settings to be used. Synchronization can be triggered either automatically within defined time intervals, or manually. Manual synchronization can happen either via the Outlook add-in settings, or by right-clicking on the Outlook icon at the bottom of you screen. More information on synchronization settings and conditions is described in the Connect MS Outlook Add-in to Oro Instance topic.

Identify a Record

For every synchronized record, there is a defined key. The key is a set of field values used to identify a record. Fields of a key can be chosen subject to the specific company needs and defined in the back-office.

The following keys are used by default:

Entity Key Fields
Contact First Name, Last Name, Gender and Birthday
Calendar Event Title(Subject), Start Time, End Time and whether it is an All-day event
Task Subject and Task Priority

Every contact, task and calendar event available in OroCRM has a unique ID. When a record is saved in Outlook, the ID value is saved from OroCRM in the OroCRM_id field.

Sync Records from OroCRM to Outlook

Synchronization is run in the same way for records of activities, tasks and calendar events:

A diagram that explains how to sync records from orocrm to outlook

All the records processed in OroCRM since the latest synchronization date and available to the user are checked:

  • If the ID of an OroCRM record matches the OroCRM_id value of an Outlook record, the Outlook record is updated. (Values of all the mapped fields in Outlook are overwritten with the corresponding values from OroCRM).
  • If the ID of an OroCRM record does not match the OroCRM_id of any Outlook records, their keys are checked against the fields of Outlook records with an empty OroCRM_id field.
    • As soon as an Outlook record with empty OroCRM_id and a matching key is found, it is updated from OroCRM, and the ID value is saved from OroCRM into the OroCRM_id field of the Outlook record.
    • If no Outlook record with empty OroCRM_id and matching key is found, a new record is created in Outlook.

Note

During the first synchronization, or resynchronization, all Outlook records with a non-empty OroCRM_id field are deleted first, and then OroCRM record keys are checked for all of them.

If Then
Such record already exists in Outlook. Values of the mapped fields of the OroCRM record replace the corresponding values for the Outlook record.
A record does not yet exist in Outlook. OroCRM creates the record in Outlook.
Multiple matching records exist in Outlook. OroCRM updates one of them.
You updated a record in OroCRM. Values of the mapped fields of the OroCRM record replace corresponding values for the Outlook record.
You updated a record in Outlook. The updates remain in the Outlook record, but are not synced into OroCRM.
You deleted a record in Outlook. OroCRM creates the record again.
You deleted a record in OroCRM. The record stays in Outlook with no changes.

Important

Be aware that if you add a Google-based account to the existing MS Exchange account, your default calendar may change. This is important to remember when synchronizing events between Oro and Outlook.

Sync Records from Outlook to OroCRM

A diagram that explains how to sync records from outlook to orocrm

All the records processed in Outlook since the latest synchronization date and available to the user are loaded:

  1. If the OroCRM_id field of a record is empty, a new record is created in OroCRM.
  2. If the OroCRM_id field is defined, and this is the first synchronization or resynchronization, the record is deleted.
  3. Otherwise, the OroCRM_id is checked against ID values of the records in OroCRM:
    • if a record with the matching ID is found in OroCRM, it is updated with data from Outlook.
    • if a record with a matching ID is absent in OroCRM, it is deleted from Outlook.
If Then
Such record (record with such ID) already exists in OroCRM. Values of the mapped fields of the Outlook record replace the corresponding values for the OroCRM record.
A record does not yet exist in OroCRM. A new record is created in OroCRM.
You updated a record in OroCRM. Values of the mapped fields of the Outlook record replace the corresponding values of the OroCRM record.
You updated a record in Outlook. Values of the mapped fields of the Outlook record replace the corresponding values of the OroCRM record.
You deleted a record in Outlook. The record stays in OroCRM.
You deleted a record in OroCRM. The record is deleted from Outlook.

Sync Records with Bidirectional Synchronization

For bidirectional synchronization, synchronization from OroCRM to Outlook is performed first and followed by synchronization from Outlook to OroCRM.

If Then
A record exists in both OroCRM and Outlook. Values of the mapped fields of the OroCRM record replace the corresponding values for the Outlook record.
A record does not yet exist in OroCRM. A new record is created in OroCRM.
A record does not yet exist in Outlook. A new record is created in Outlook.
You updated a record in OroCRM. Values of the mapped fields of the OroCRM record replace the corresponding values of the Outlook record.
You updated a record in Outlook. Values of the mapped fields of the Outlook record replace the corresponding values of the OroCRM record.
You updated a record in the both OroCRM and Outlook. Subject to your conflict resolution settings.
You deleted a record in Outlook. The record stays in OroCRM and is added to Outlook.
You deleted a record in OroCRM. The record is deleted from Outlook.