Enabling Microsoft 365 Calendar Sync

Learning Team

Please note: This content is intended for Practifi System Administrators and is technical. The steps described in this article may require System Administrator permissions to complete. Please discuss your integration installation plans with your Practifi Customer Support Team for their assistance.

Einstein Activity Capture and other third-party calendar sync tools must be turned off before enabling Microsoft Calendar Sync. If not turned off, it will trigger event notification emails to clients. For instructions on how to disable, please consult our Disabling Calendar Sync Tools article. If you have any questions, please get in touch with your CSM or our Practifi Support Team.

Overview

Microsoft 365 Calendar Sync allows users to view their calendars in both Microsoft 365 and Practifi. When this sync is enabled in your firm's Practifi organization, you can view events in either system and be confident you are seeing your entire schedule, keeping your team's availability accurate wherever they choose to work. Practifi Administrators can choose a one-way event sync (Microsoft to Practifi, or Practifi to Microsoft) or a two-way event sync between Microsoft 365 and Practifi.

This article outlines the steps to enable Microsoft 365 Calendar Sync in your organization. For more information about the Microsoft 365 calendar sync, please consult our Using Microsoft 365 Calendar Sync article.

Before You Begin
Enablement Process
Default Scopes
Enabling Event Sync
Sync Settings
Microsoft Integration Settings
Syncing Event Locations
Sync Considerations
Practifi Protect Compatibility
Object & Field Mapping
Data Model Extensions
Customization Considerations
Troubleshooting

Before You Begin

This calendar sync is part of our Microsoft 365 Sync, a paid add-on feature. Contact your Client Success Manager to discuss pricing in more detail and sign up for the service. You cannot enable this functionality in your organization without purchasing this add-on.

Please note: The number of users granted access must match the number of licenses in your Practifi contract.

Please note: This integration works only with Microsoft Cloud. It is not compatible with on-premises Exchange servers or self-hosted Exchange servers.

Enablement Process

The majority of the enablement steps for Microsoft 365 Calendar Sync are identical to those for Microsoft 365 Email Sync, with additional steps to enable event sync and configure sync settings. These are described in the sections below. To begin the enablement process, System Administrators should complete the steps described in our Enabling Microsoft 365 Email Sync article before proceeding to the next section of this article.

Default Scopes

Enter the following in the Default Scopes field for the Auth. Provider when enabling Event Sync:

OpenID offline_access https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Calendars.ReadWrite https://graph.microsoft.com/Calendars.ReadWrite.Shared

Please note: There is a character limit on the Default Scopes field in the Auth. Provider. If you are enabling both Email and Event Sync, you will need to authenticate twice: first with the email scope, then with the calendar scope.

Follow this process:

Set the Auth. Provider with the email scope:
- OpenID offline_access https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/Mail.ReadWrite.Shared
Authenticate the Microsoft365SyncService named credential.
Authenticate the MicrosoftGraphAPI named credential.
Set the Auth. Provider with the calendar scope:
- OpenID offline_access https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Calendars.ReadWrite https://graph.microsoft.com/Calendars.ReadWrite.Shared
Authenticate the MicrosoftGraphAPI named credential.

The Microsoft365SyncService named credential does not need to be re-authenticated once the calendar scope is set.

Enabling Event Sync

Important: Microsoft 365 Calendar Sync uses the Microsoft Graph API to access your firm's Microsoft Cloud services. Due to the nature of the Microsoft Graph API, any update made to a past or future calendar event from Practifi to Microsoft Outlook will automatically trigger Microsoft Outlook to send an updated event invitation to all attendees' inboxes.

For this reason, we recommend Administrators examine all potential risks before enabling the two-way calendar sync feature. Enabling the two-way event sync without careful consideration may result in unwanted event invitations, updates, or cancellations being sent to end clients.

To enable event sync for users, navigate to the Users & Mailboxes tab of the Microsoft 365 Sync page within the Settings app. The Sync Events option appears as a column in the User table alongside Sync Emails. Check the box for each user you would like to enable. To save time, you can check the box next to Sync Events in the header row to select all listed users.

If a user is linked to more than one mailbox (for example, if they're the nominated user for a shared mailbox), you'll need to select which mailbox is their Primary Mailbox. This is the mailbox whose Microsoft 365 calendar will be used for any of that user's Events created in Practifi, and also the email address from which Event invitations will be sent.

Once you've checked the box next to each user you want to enable Microsoft 365 calendar sync for, click Save to finalize your changes.

Sync Settings

Once the users have been enabled, you can modify sync settings to suit your firm's needs, aligning the sync with how your team works day-to-day in Practifi. On the Sync Settings tab, scroll down to locate the Event Settings section. Within this section, you can modify settings by toggling the different event settings on and off. The options available are as follows:

Sync Internal Events: An internal event is one that's only attended by team members who are also Practifi users. Enable this setting if your firm uses Practifi as an internal business management solution.
Delete Synced Events: When an event is deleted from one system, choose how that affects the other (either delete it as well or keep it). If Practifi is the system of record for your business, you should use a stricter policy than for Microsoft 365.
- Set the from Microsoft 365 option to Yes if you want to delete an event in Practifi whenever a synced event is deleted from Microsoft.
- Set the from Practifi option to Yes if you want to delete an event in Microsoft whenever a synced event is deleted from Practifi.
Sync Private Events: Certain events are marked as private by their organizers in Practifi or Microsoft 365. Choose whether to include these in your firm's sync.
Sync Direction: Choose whether to implement a comprehensive two-way solution or keep things simple with a one-way approach. There are two one-way options: Microsoft to Practifi or Practifi to Microsoft. If you select Microsoft to Practifi, events created in Microsoft will flow into Practifi, but events created in Practifi will not appear in Microsoft.
If you enable the two-way option, and a synced Event is updated in both systems between syncs, the changes made in Microsoft 365 will take precedence.
Sync Unmatched Events: All events in synced calendars will appear in Practifi, even if they aren't related to any records. Enable this setting if your firm uses Practifi as its primary calendaring solution.

Once you have modified the settings to suit your firm's needs, click Save to finalize your changes.

Microsoft Integration Settings

Other event sync settings control how historical and future events are handled. To access these, do the following:

Click the Setup cog in the upper right-hand corner of Practifi and select Salesforce Setup.
In the Quick Find box, search for Custom Settings and select Custom Settings from the suggestions.
On the Custom Settings page, next to Microsoft Integration Settings, click the Manage link.
On the Microsoft Integration Settings page, you can click the Edit button to configure the following settings:

Commencement Date: This is the date on which the syncing of past events from Microsoft into Practifi begins. This field is automatically populated with the date six months before the sync was enabled.

Please note: Historical events will not sync from Practifi to Microsoft.

Future Inbound Event Sync Range in Years: This field sets the number of years into the future that Microsoft events will sync into Practifi. This means that any change to events within that range will be synced. The default value is 10.
Future Outbound Event Sync in Months: This field sets the number of months into the future that Practifi events will sync into Microsoft 365. This means that any change to events within that range will be synced. The default value is 24.

Important: The Practifi event sync to Microsoft is trigger-based, so any future-dated events will only sync to Microsoft after an insert, update, or delete action is made on the Practifi Event record. If you are enabling two-way event sync for the first time, existing future-dated Practifi event records that fit within the Future Outbound Event Sync in Months (automatically set to 24 months) setting will not automatically sync to Microsoft unless those Practifi events are edited and re-saved. Note that updates to the attendees list in Practifi will not trigger a sync update to Microsoft.

Syncing Event Locations

Syncing Event locations between systems is supported in Practifi as Resource Calendars, which surface the location as a resource with its own calendar, allowing it to be managed as a typical meeting room and giving your team visibility into room availability without leaving Practifi.

Please note: For this sync to occur, administrators must first recreate your Microsoft 365 locations as Resource Calendars with names identical to those found in Microsoft 365. To avoid sync conflicts, Microsoft 365 locations must have unique names.

Sync Considerations

When syncing Events, the following should be considered:

Attachments - Event attachments are currently unsupported.
Data imports - Importing events into Practifi is unsupported; only events created in the Practifi UI will be synchronized with Microsoft 365. This is by design, as any calendar event synchronized with Microsoft 365 causes invitations to be sent. In a typical import scenario, this isn't desired.
Draft events - Draft events in Microsoft 365 won't appear in Practifi. To sync them, they must first be saved as confirmed calendar entries.
Maximum attendees - Only 50 attendees are synced per Event. If more than 50 exist, then the first 50 are selected alphabetically.
Private events - Supported in both directions but without attendees.
Secondary user calendars - This is not currently supported functionality; only the user's default calendar will be synced.
Shared calendars - Only personal calendars are currently supported.
Acceptance status - An invited client member does not need to accept a meeting invite for it to sync correctly to their client record, nor will the acceptance status of an event impact whether the event syncs.

Practifi Protect Compatibility

Practifi Protect and Microsoft 365 Calendar Sync can be enabled simultaneously. However, the encryption introduced by Practifi Protect prevents Microsoft 365 Sync's record-matching logic from operating. This means that firms cannot encrypt the following fields if they want to make use of them in the matching process:

Email (Contact)
Alternative Email (Contact)
Other custom email fields on Contact
Email (User)

This guidance is taken from Salesforce Help and is one of the trade-offs inherent in enabling Salesforce Shield, the technology behind Practifi Protect.

Object & Field Mapping

The tables below outline the object and field mapping for the integration. Where picklist values are mapped, the value mappings are based on which bullet items appear on the same line in each column.

Objects

Practifi (object)	Microsoft 365 (collection)	Notes
Calendar	location	Resource Calendars provide a great home for 365's locations information, allowing room availability to appear in Practifi alongside Events. These should be prioritized in sync operations and should always come ahead of Events and Emails to ensure they don't wait in the queue when sync volumes exceed daily limits.
Event	event	The calendar items themselves.
EventRelation	attendee (for Attendees) location (for Resources)	The internal and external attendees of the event, as well as the location/s where the event is held.

Calendar

Practifi (Field Label)	Microsoft 365 (property)	Notes
IsActive	N/A	Predefined as True.
Name	displayName
Type Resource	locationType default	Value combination is predefined and cannot be changed in Practifi. If the Type is modified in Microsoft 365, it does not change in Practifi.

Event

Practifi (Field Label)	Microsoft 365 (property)	Notes
All-Day Event	isAllDay
Assigned To	organizer	Exceptions apply in certain situations, such as when handling internal attendees.
Attendees (EventRelation)	attendees collection
Description	body	Stored as HTML in Microsoft 365, but plain text in Practifi.
Duration (DurationInMinutes)	N/A	Calculated automatically using the Start and End values.
End	end	Synced using UTC, with the user's local time settings applied in Practifi.
External ID	id
Location	location
Resources	location collection	Using Resource Calendars via EventRelation.
Microsoft 365 Sync Status	N/A	Set to Never if the record hasn't been synced with Microsoft 365. Set to Active if the record is part of the ongoing scheduled sync job. Set to Inactive if the record was once synced, but has now been deactivated as per Deactivate Sync for Past Events.
Private Unchecked Checked	sensitivity Normal Private	Other sensitivity settings in Microsoft 365 aren't supported.
Recurring in Microsoft 365	recurrence
Reminder Date/Time	reminderMinutesBeforeStart	This is captured differently between systems. Practifi sets the calendar date/time for the reminder, and Microsoft sets the number of minutes before the Event's Start. Calculation logic is used to translate these values.
Reminder Set	N/A	Populated based on the presence of a reminderMinutesBeforeStart value.
Show Time As Busy Out of Office Free	showAs busy ooo, workingElsewhere free, tentative, unknown
Start	start	Synced using UTC, with the user's local time zone settings applied in Practifi.
Subject	subject
Teams Meeting	isOnlineMeeting = true onlineMeetingProvider = teamsForBusiness
Teams Meeting URL	onlineMeetingURL

EventRelation

Practifi (Field Label)	Microsoft 365 (property)	Notes
EventId	parent Event resource
RelationId	emailAddress (if Attendee) displayName (if Location)	Matching logic is used to derive User and Contact IDs from email addresses.
Status New Accepted Declined	responseStatus none, notResponded organizer, tentativelyAccepted, accepted declined

Data Model Extensions

The table below outlines the fields added to the Event object in Practifi to support this integration. Select the tab to expand this table and view these fields.

Event Fields

Name	Field Type	Notes
Recurring in Microsoft 365	Text (255)	Read-only field
Microsoft 365 Sync Status	Picklist	Available values: Never Active Inactive Read-only field
Send Invitations to Attendees	Checkbox	The Send Invitations determines the default value for the Attendees setting.
Show Time As	Picklist
Teams Meeting	Checkbox
Teams Meeting URL	URL (255)	Read-only field

Customization Considerations

This feature has modified the following items. If your firm has customized them, then you'll need to either copy the changes into your customized version or switch to the default version and redo your changes.

Lightning pages
- Event Record Page
Page layouts
- Event Layout

Troubleshooting

Practifi Administrators can view error logs on the Logs & Errors tab within the Microsoft 365 Sync page. To view only error logs, click the Errors Only button to filter the page.

Errors that display 0 values in the Records Processed, Synced Successfully, and Errors columns are usually due to Graph API errors, such as an expired access token or internal errors. This type of error is often resolved when the sync re-runs.

Log entries with a Retry link often result from processing errors in Azure. We recommend clicking the Retry link next to the error to see if it resolves the issue.

To retry all email and event sync errors from the past 30 days at once, click the Retry Errors from Last 30 Days button.

To view in-depth error logs, open the Salesforce Developer Console and use this query for more detailed information:

SELECT Id, practifi__Error_Message__c, practifi__External_System__c, practifi__Date_Time__c, practifi__Is_Error__c FROM practifi__Integration_Log__c WHERE practifi__external_system__c = 'Microsoft Email Sync' AND practifi__is_error__c = true ORDER BY practifi__Date_Time__c DESC