Our Integration with Microsoft 365 keeps your Microsoft and OpenCRM Contacts, Calendar, and Task lists in sync. This FAQ is going to walk you through setting up a sync between your Microsoft account and your OpenCRM User account.
There are several considerations you should make BEFORE setting up a sync of this nature between OpenCRM and any third party software.
We've written a short article discussing these and some best practices on managing your Contact folders.
Please please read through those BEFORE you start setting up the sync between your Microsoft account and OpenCRM.
How does the integration work?
The actual how to's of each of these will be covered below, but in short.
1. You authorise OpenCRM to connect to your Business Microsoft 365 (MS365) account. Note this needs to be a business account, not a personal one.
2. Each user's OpenCRM account is then connected to their individual MS365 account.
a. You can decide at the organisation level whether your users can edit the settings themselves or whether you'd like to keep this restricted to admins only.
3. Depending on their settings, each user's Contacts, Calendar items, and Tasks can be synced between the two systems. You can choose either:
a. A one-way sync (i.e. new records and changes in one system are sent to the other, but not back) or
b. A two-way sync (new records and changes to existing ones are sent back and forth between the two systems).
How does the sync work?
The rest of the FAQ will cover how to set these things up, but before you get started there are a few things you should know about the way the sync works:
There is a time restriction on when Calendar and Tasks are synced:
- Any Activity from 2 months before the current date or after 1 year will not be synced (based on the Activity Start Date & Time).
- Tasks follow the same restriction but are based on Start Date & Time in OpenCRM and Due Date in Microsoft.
The sync runs every 10 minutes:
- The time it takes to sync will be affected the number of Activities and Users being synced
You can restrict Contact syncing based on
- OpenCRM Assigned To (choose to sync only records assigned to your User, or ignore this limitation)
- Individual records setting (a tickbox)
- Contact folders (in both Microsoft and OpenCRM)
At the bottom of this FAQ are a series of additional questions on how the sync works, including:
Questions about Meetings
Questions about Tasks
Questions about Contacts
How do Calendar Events with Attendees sync between OpenCRM and Microsoft
Step 1: Setup/ Enable at Organisation level
The first thing you need to do to start your team being able to sync their OpenCRM Contacts, Calendar items, and Tasks (via Planner) with their Microsoft account is to enable this at the company level.
This means you will need to be an administrator both on your Business Microsoft Account and OpenCRM.
1. You will need an activation key from us. To get this, please start a chat with our support team (or email firstname.lastname@example.org).
2. Once you have the key, login to OpenCRM and navigate to Settings (menu in the top right)
3. Scroll down to the Integration section in Settings, click Microsoft Synchronisation.
Authorise in Microsoft
1. The first thing you will need to do is click the Authorise link next to the Microsoft 365 Authorisation. You MUST be an administrator on your MS account in order to do this.
2. Clicking this will pop open a window for you to sign into your Microsoft account.
3. Once signed in, you will need to click to agree to OpenCRM having access to your Microsoft account.
Activate in OpenCRM
1. Once you have authorised the Microsoft side of the integration, you'll need to authorise the OpenCRM side.
2. Take that Activation Key you got from the support team here at OpenCRM and copy it into the relevant box:
3. Click the Enabled tick box to turn on the sync (don't worry, nothing will start syncing until you set up the individual users)
4. Switch on whether you want to sync your Contacts and/or Calendars and tasks
5. And then choose which direction the sync should go:
a. Both: records created and edited in OpenCRM will be sent to Microsoft and vice versa.
b. OpenCRM->Microsoft: this will send records created and edited in OpenCRM to Microsoft, but any changes made in Microsoft will not appear in OpenCRM.
c. Microsoft->OpenCRM: this will send records created and edited in Microsoft to OpenCRM, but any changes made in OpenCRM will not appear in Microsoft.
6. The next three sections explain how your users can interact with the sync and matching rules and what happens if/ when there is a conflict in the sync (i.e. if a record in OpenCRM and Microsoft). The best thing to do here is read the guidance in place on the Settings page itself.
7. And now you can Save ... which brings us to the second step of the MS integration set up.
Step 2: Connect to Microsoft 365 User Account
Once set up at Organisation level and enabled at User level, the sync for for individual Users can be configured by clicking the Microsoft Sync button on the User record.
Firstly, you will need to connect your OpenCRM account to your Microsoft 365 account. Click the Sign In with Microsoft button and sign in to your Microsoft account.
A screen will popup with a (rather long) Access Key. Copy this key and paste the Access key into the field on the main screen.
Once you have connected your account, click on the button to Continue to Settings.
Additional Microsoft 365 Sync Functionality and Questions
This section seeks to answer some of the most commonly asked questions about our Microsoft Integration. If you think we have missed one, please get in touch.
Limitations on Recurring Meetings?
If you edit or add attendees to an individual instance of a recurring meeting (i.e. not the original meeting that the instance was generated from), these changes may not sync to OpenCRM. This is a limitation of the Microsoft API which only presents changes from the master event in the series. Therefore if you have an event which runs on multiple dates and that is likely to change (e.g. attendees need changing / adding), it is recommended to set these up as individual meetings, with a reminder to schedule the next batch set up in OpenCRM. Another option would be to set up as a recurring meeting in MS and then whenever a change is needed, delete all the events in the series (see How can I delete recurring Meetings below), and set up a new event series. This could leave entries in users calendars in MS however if individual users to not remove the copies of the event from their calendar.
What happens if I delete a record?
Due to a limitation of the Microsoft API, deletion of anything in MS (Contact, Calendar Task) will not sync back to OpenCRM.
If you need to delete an item (Contact, Calendar entry or Task) - do so in OpenCRM. When then next sync runs, that will also remove that entry from Microsoft 365.
How can I delete recurring Meetings?
If you create a Recurring Meeting in either your Microsoft 365 Calendar or OpenCRM, you will need to delete these in OpenCRM.
As above, Microsoft simply cannot tell OpenCRM when an item has been deleted. So if you delete in M365, nothing will be sent to OpenCRM and so the Activities will remain there...and will re-sync to Microsoft.
But, if you delete ALL the Activities from OpenCRM, this will be sent to Microsoft and the Meetings will be removed there. The easiest way to do this is to create a Custom View filtering on the exact name of the Meeting created and delete the Activities in bulk.
Meeting Notes Aren't Syncing?
The notes on a meeting are only synced to Microsoft from OpenCRM (or vice versa) the first time the record syncs. This is to allow you to add notes to your meeting in OpenCRM once it has been completed, without any danger of these notes being sent or visible to your attendees.
If a meeting is marked as private in OpenCRM, it will be set to private in Microsoft (and vice versa). Note that a private meeting in Microsoft will remain set as private even if it is changed to not private in OpenCRM (and vice versa for meetings in OpenCRM changed in Microsoft).
Private Activities and the Calendar
If you mark an Activity as Private, either using the "Private" tickbox or in Microsoft, you have two options when it comes to how this appears in your Calendar for other users.
Option 1: Private Activities are not visible in the Calendar. (This is the default)
Option 2: Private Activities appear in the Calendar, but are not editable or clickable by other users and only show up with the subject "Private" for all unlinked/unassigned users.
To enable Option 2, you will need to go to Settings > Configuration > Additional Settings and click the Calendar option. Then you will need to enable the following setting:
Can I see my MS Planner Task lists in OpenCRM? Can I send Tasks from OpenCRM to a particular MS Planner list?
You will find the Task List field on Activities in OpenCRM - this is under the Activity Details heading. This is a standard picklist, but once your sync is configured , it will also be populated with the Microsoft 365 Planner Task lists that you have access to in Planner/ Teams.
By selecting one of these task lists in the list when creating an Activity in OpenCRM, when the Activity has synced, it will be placed in the matching task list in Planner/ Teams. Additionally, this field is populated when an Activity is created from Planner and synced into OpenCRM. You can use this field to move a planner task between planner lists by changing the task list in OpenCRM - when the Activity syncs back to Planner, it will be placed in the new task list.
Can I assign Tasks to other users?
Because Microsoft Planner allows you to assign tasks to other users in your Microsoft 365 organisation, if you assign a task to another user, and they also have Microsoft 365 sync setup on their OpenCRM user, that task will be synced to their OpenCRM task list.
If they do not have an OpenCRM account or have their sync set up, the task will not be brought into OpenCRM.
If you add another user to a task in Microsoft Planner, that user will be added to the users sub tab in OpenCRM if that user is setup with the sync.
If you remove a users assignment from a task in Microsoft Planner, that user will be removed from the users sub tab, but, if that user is the Assigned To user on the task, the Assigned to will remain the same in OpenCRM. It is not possible to change the assigned user of a task in OpenCRM from Microsoft.
I've updated a task Description in Planner and OpenCRM has not updated, why?
Due to rate limiting on Microsoft's API, OpenCRM is limited to only retrieving the Description of tasks where the due date is 1 month either side of the current date and time. This means if you edit a task description in Microsoft which is outside of this window, it will not be updated in OpenCRM. However it will also NOT be overwritten with the value from OpenCRM unless / until the record is edited in OpenCRM at which point the OpenCRM record will be seen as having the most up to date information.
Where do the different times (and statuses) come from on Tasks?
Microsoft Planner handles tasks very different than we do in OpenCRM:
How OpenCRM decides which Tasks to sync
Microsoft Planner does not have a "modified date/time" that we can use to decide which records to sync. This means we have to use other options to determine if a Task has been changed and needs to re-sync with OpenCRM.
We therefore sync records using the following two rules:
If the answer to the first point above is YES and to the second is NO, the OpenCRM task will be updated from the Microsoft task.
If the answer to the second question is YES, however, the Microsoft task will be updated from the OpenCRM task. Changes in OpenCRM will always override changes made in Microsoft.
Microsoft to OpenCRM
Due to rate limiting on Microsoft's API (and to shorten sync times), OpenCRM will not sync any changes to tasks marked as complete in Microsoft that are more than two weeks old.
Can I move a Contact from one folder to another? Can I have a single Contact in multiple folders?
In Microsoft 365, a Contact can only be in one Contact folder. If a contact is listed in multiple folders in OpenCRM, the first folder will be the one used to decide what folder the Contact will go in in Microsoft 365.
Caution should be used when moving Contacts between folders, if the same Contact in OpenCRM is synced to multiple Microsoft 365 accounts. Doing so would move that Contact to different folders for all Users and a User may have not selected the folder it moves to when it syncs back to OpenCRM.
How is the assigned to set in OpenCRM if a Contact is in multiple M365 Contact groups?
To try and prevent duplicates from being created in the event that two of your users have the same Contact in their Microsoft list, the following rules are applied:
What happens if a Contact is re-assigned in OpenCRM?
When a Contact is reassigned in OpenCRM the sync with M365 should not be affected...unless that reassigning changes the permission of the Contact or the the sync itself:
Calendar Events with Attendees (Users in OpenCRM)
OpenCRM -> Microsoft
Two settings in the Microsoft sync settings control what happens when a meeting with attendees is synced from Microsoft to OpenCRM
If these settings are ticked, activities created in OpenCRM with users on the sub tab will be created in Microsoft with each user on the sub tab added as an attendee, if they are synced by the activities primary user (the assigned to user) and so long as the attendees primary OpenCRM email address matches their Microsoft user account. The meeting Organiser in Microsoft will be the Microsoft account linked to the assigned to user of the activity.
WARNING: When a meeting is added to Microsoft by the sync from OpenCRM, it will send an invite to all attendees on the meeting (from the meeting organiser). It is worth considering this when setting up users on the sync for the first time as it will send invites for all new meetings it adds to the Microsoft calendar - including meetings that have already taken place if the first of the above two settings is enabled.
If the assigned to user of the activity is not configured for the sync, regardless of the above settings, the activity will be synced to the calendars of users on the sub tab who are configured with the sync, but they will be individual meetings in each persons calendar and no attendees will be added. This is to prevent meeting invites being sent from the wrong people.
Additionally, you cannot add attendees to a meeting in Outlook, by adding them to the activity in OpenCRM unless the meeting organiser in Outlook is setup on the Microsoft sync (and is also therefore the assigned to user on the activity in OpenCRM). This is because only the organiser user has permission to modify the event and/or add attendees.
Microsoft -> OpenCRM
If a user who is setup on to sync with Microsoft creates a Meeting in Microsoft and links users from their organisation, all the attendees will be added to the sub tab on the Activity in OpenCRM as long as the email address of the attendee in Microsoft matches one on their OpenCRM User account. The attendees to not need to have the sync setup for this.
If someone who is NOT setup on the Microsoft sync creates a meeting in Microsoft with attendees from their organisation and any of the other attendees are setup on the sync, the meeting will be added to the OpenCRM calendar of the users with the sync enabled. (a single Meeting with any syncing Users added to it). The Assigned User in OpenCRM will be set to be the first User that synced. It will not include attendees for users that are not set up with the sync.
For shared calendar events, only changes made by the meeting organiser will be synced from Microsoft to OpenCRM. Any OpenCRM user could make changes to the event in OpenCRM providing they had sufficient permissions to do so. This would update the organiser's event in Microsoft as well as the event in all attendee calendars.
If an attendee makes a change to a shared calendar event in the Microsoft calendar, this would be overwritten by any changes made to the event in OpenCRM.
A few things to be aware of
- You can click Disconnect if you wish to unlink your OpenCRM account from your Microsoft 365 account. This will also disable your sync.
- User Sync Settings: Read through the guidance on the Settings page itself to understand what each one does, complete the User configuration and click to Save.
- Start Date: If you have set a Due Date on a Task in Microsoft, this will be used as the Start Date. If you have NOT set a Due Date on a Task, the sync date will be used.
- The start time is controlled within the User settings
- Modified Time: Tasks in Microsoft have no modified time (and filters can't be applied to the API) which means the following:
- OpenCRM retrieves all Tasks from the specified lists and then filters what is pushed to OpenCRM itself.
- OpenCRM uses the last sync date as the modified time for the Task in Microsoft. It will only show a change in the modified time if the Task has been modified.
- OpenCRM Task changes will always override Microsoft Task changes if the record is changed in both systems.
- Status: Microsoft Planner Tasks have no status, just a percent complete. So we have used some logic to determine how to handle this in OpenCRM:
- Not Started = 0%
- Done/Cancelled = 100%
- All other statuses = 50%
- If Microsoft Task is set to anything other than 0% or 100% complete, it will have a Status of In Progress in OpenCRM
- If a Task has the Status of On Hold in OpenCRM, this will only change via the sync if the Microsoft Task is set to 0% or 100%
- If a Task has the Status of Cancelled in OpenCRM, this will only change status via the sync if the Microsoft Task is set to anything other than 100%
- If any fields on the Microsoft task differ to any fields on the OpenCRM task
- If the record has changed in OpenCRM since the last sync.
- New Contact: If no match with any existing Contact is found in OpenCRM, a new Contact is created. This Contact will initially be assigned to the first person that syncs it.
- When a Contact is synced from M365 which matches an existing Contact in OpenCRM (either by another user or just because the contact was in OpenCRM already), it's details are updated, but assigned to is not changed.
- No subsequent syncs will update the assigned to.
- Permissions Change: If a user no longer has access to a Contact record by normal OpenCRM team permissions, the contact would be removed from their MS/Google account on the next sync.
- Sync Settings: If the user has "only my items" ticked on the Contact sync settings and the sync direction is either OpenCRM->MS/Google or Both, the contact would be removed from their MS/Google account on the next sync.
- Calendar - Add attendees to historic meetings
- Calendar - Add attendees to future meetings