1. Practifi Success
  2. System Administrator
  3. Integration Setup

Enabling Microsoft 365 Email Sync

Follow
Avatar
Learning Team
Please note: This content is intended for Practifi System Administrators and is technical in nature. The steps described in this article may not be able to be completed without System Administrator permissions. Please discuss your integration installation plans with your Practifi Customer Support Team for their assistance.

Overview

The Microsoft 365 Email Sync is a proprietary integration that syncs emails and attachments between a firm’s Outlook 365 instance and Practifi. Unlike the standard Salesforce/Outlook integration, emails are logged automatically without the need for users to opt-in, manually log emails or manually match emails to contacts within Practifi. Another major advantage is that the integration is enabled on the firm’s Outlook 365 email server rather than on a user’s own email client, meaning no additional installation or administration is needed on users’ various devices. The Microsoft 365 Email Sync is built on Microsoft’s Azure cloud services, and either be hosted in a firm’s own Azure organization or as a tenant in Practifi’s.

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

Before You Begin

Microsoft 365 Sync is a paid add-on feature. Please note that the number of users granted access must be the same as the number of licenses in your Practifi contract. Contact your Client Success Manager to discuss pricing in more detail and sign up for the service.

The Microsoft Outlook integration remains an excellent option for firms looking for a low-cost option. However, Microsoft 365 Sync improves on it in two crucial ways:

  • Emails are captured automatically, rather than relying on the user to opt-in to sending them. This ensures your email history in Practifi is comprehensive and accurate and reduces the workload for your team.

  • Microsoft 365 Sync is enabled for your email server rather than on devices themselves, meaning you only have to set it up once for everyone to be included, instead of installing it for each employee individually.

The Microsoft 365 Sync page appears in the Settings app for all firms regardless of whether they’ve enabled the feature. If your firm hasn’t enabled the feature, the page explains the disabled state of the feature and presents a call-to-action for the administrator to contact their Client Success Manager.

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


Sync Information 

How the Sync Works

Within Practifi, an Administrator matches each Practifi user with an Office 365 mailbox and determines a cadence for the sync to run, ranging from every 15 minutes to weekly. Whenever a matched mailbox sends or receives an email, that email is included in the next scheduled sync. When the sync runs, the sync engine processes all emails sent and received since the last run and sends them and their attachments to Practifi, where they are matched with the corresponding user.

After the sync completes, a job is automatically scheduled that matches emails with Entities and Contacts based on their email addresses. Email addresses used by the matching engine can be stored either on the Email and Alternate Email fields on the Entity/Contact record or use Contact Point Email records related to a Contact or Individual. Matched emails appear in the Activity Timeline of the matched Contact/Individual. Unmatched emails can be accessed from the Emails page in the user’s Practifi app, where they can be reviewed and mapped to contacts as a mass action.

When performing the initial sync with a firm’s Microsoft 365 instance, we retrieve the last six months of message history. If a new user is added after the initial sync, the sync engine will retrieve that user’s or mailbox’s emails from the initial sync date, to be in line with the rest of the organization.

Exclusions

A firm may not want to sync all emails. For this reason, an admin can configure global exclusions, personal exclusions, and internal email domains to control what content is included in the sync. These exclusions are only in effect on sync jobs after they have been established, so it is best practice to set them up before the initial sync.

We will touch on establishing these exclusions later, but in brief:

Global Exclusion - An exclusion that affects the entire organization, defined by an admin. These are useful for system emails from other tools a firm may use, such as a scheduling tool like Calendly, an HR platform like ADP, receipts from commonly-used vendors, or any other email notifications that may be irrelevant to have within Practifi.

Personal Exclusion - An exclusion that only affects a specific user, defined by that user. These are useful for user-specific email notifications, such as newsletter subscriptions, LinkedIn notifications, or general spam.

Internal Email Domains - An exclusion that affects the entire organization and will prevent emails that exclusively contain email addresses from internal domains from being synced. This is useful when a firm doesn’t wish to sync internal communications.

Enabling Microsoft 365 Sync

General Concepts

The following sections contain information to help you through the enablement process of the Microsoft 365 Sync in your Practifi instance and details concepts that are core to successful enablement.

To complete the steps in detailed in this article, you must have the following:

  • Global Administrator access for your firm's Office 365 account.
  • System Administrator access to your firm's Practifi organization.

Permissions

Once purchased, an administrator should have access to two new permissions sets: Practifi - Add-Ons - Microsoft 365 Sync Administrator and Practifi - Add-Ons - Microsoft 365 Sync User. During the setup process, assign the Practifi - Add-Ons - Microsoft 365 Sync Administrator permission to your own user and any other user who will require admin-level access.

Once the setup is complete, all other users can be assigned the Practifi - Add-Ons - Microsoft 365 Sync User permission, which will grant access to the Emails page and the ability to define personal exclusions.

The Microsoft 365 Sync Page

Enabling the integration requires multiple steps in multiple areas of Salesforce Setup. For this purpose, the integration includes a dedicated setup page where all aspects of enablement and configuration are centralized. This page can be accessed by users with the Practifi - Add-Ons - Microsoft 365 Sync Administrator permission set by searching Microsoft 365 Sync in the App Menu.

Microsoft_365_page.png


We recommend familiarizing yourself with the tabs and sections on this page before beginning the enablement process, as you will return to this page several times while enabling and configuring the integration. 

Microsoft 365 Permissions Setup

To perform the required permission setup, you must have the following:

  • Global Administrator access for your firm's Office 365 account.
  • System Administrator access to your firm's Practifi organization.

As the administrator user, you will need to enable some Read/Manage inbox permissions for the admin account in the Microsoft 365 organization. Please be aware that you must add these permissions for each individual that requires the email sync function.

To add these permissions:

  1. Log into your Office 365 Admin account and navigate to the Admin App.

    admin_app.png

  2. Navigate to Users > Active Users. Select the user. In the flyout menu, click the Mail tab and then Read and manage permissions.

    ms365admin1.jpg

  3. From here, select Add Permissions.

    ms365admin2.jpg

  4. Then, search for your Admin user (the same user whose credentials were used to authenticate the Named Credentials). Select the Admin user and click Add.

    ms365admin3.jpg
  5. Repeat this process for each user to be included in the sync.

Connecting Microsoft 365 and Practifi

Obtaining Authentication Credentials 

The next steps are for firms using the email sync service hosted on Practifi’s Azure instance. If you would like to deploy the sync service to your own Azure tenancy, your setup will be different. Reach out to your Client Success Manager if you are unsure, but in general, it is assumed that most firms are using the Practifi Azure instance. 

If your firm is using the Practifi Azure instance, send a request to Practifi Support to obtain the Consumer Key and Consumer Secret that you will need for the next steps. 

Create an Authentication Provider

First, create a new custom setting in Salesforce Setup:

  1. Open Salesforce Setup by selecting the Settings cog in the upper right-hand corner and selecting Setup from the drop-down menu.
  2. In the Quick Find Box, search for Custom Settings.
  3. On the Custom Settings page, click MS Integration Settings.
  4. On the MS Integration Settings page, click the Manage button at the top of the screen.
  5. On the Custom Setting screen, click the New button.
  6. Enter the following details:
  7. Other fields can be left blank or as default values. Click Save.

Next, create an Auth. Provider in the Microsoft 365 Sync app:

  1. Click the App Launcher and search for Microsoft 365 Sync.
  2. On the Microsoft 365 Sync page, under the Setup Assistant tab and in the Set up Microsoft 365 as an Authentication Provider section, click Go to Setup.
  3. From the Providers page, click New. Enter the following information:

Register URL as Remote Site

For Salesforce to communicate with an external site, its URL must be registered as a Remote Site. This step is only required for organizations that existed prior to Albariño. If your Practifi instance was created with this release already installed, then this step can be skipped.

  1. Open Salesforce Setup by selecting the Settings cog in the upper right-hand corner and selecting Setup from the drop-down menu.
  2. Use the Quick Find search bar in the top-left to search for and select “Remote Site Settings”.
  3. Click the New Remote Site button and add an entry with the following properties:
    • Name - Microsoft365Login
    • URL -  https://login.microsoftonline.com/

Create Named Credential

You will need to use the login credentials of the firm’s Microsoft 365 administrator to authenticate two sets of Named Credentials. The first set will be used to connect to the Practifi email sync service, and the second connects to the firm’s Microsoft 365 instance via the Microsoft Graph API. It may be necessary to schedule a call with the firm’s IT provider for this step.

  1. From Microsoft 365 Sync Page, under the Setup Assistant tab and in the Store Login Details as a Named Credential section, click Go to Setup.
  2. On the Named Credentials page, click New Named Credential. Enter the following information:
    • Label - Microsoft365SyncService
    • Name - Microsoft365SyncService
    • URL - https://mssyncus01.onpractifi.com
    • Identify Type - Named Principal
    • Authentication Protocol - OAuth 2.0
    • Authentication Provider - Microsoft365Sync
    • Scope - OpenID offline_access https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Mail.ReadWrite.Shared
    • Start Authentication Flow on Save - Checked
    • Generate Authorization Header - Checked
  3. Once you click Save you’ll need to log in with the firm’s Microsoft 365 administrator’s credentials.
  4. Create another Named Credential with the following information:
    • Label - MicrosoftGraphAPI
    • Name - MicrosoftGraphAPI
    • URL - https://graph.microsoft.com
    • Identify Type - Named Principal
    • Authentication Protocol - OAuth 2.0
    • Authentication Provider - Microsoft365Sync
    • Scope - OpenID offline_access https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Mail.ReadWrite.Shared
    • Start Authentication Flow on Save: Checked
    • Generate Authorization Header: Checked
  5. Again, once you click Save you’ll need to log in with the firm’s Microsoft 365 administrator’s credentials.

Test Connectivity

From Microsoft 365 Sync Page, under the Setup Assistant tab and in the Test Connectivity section, select Check. If the previous steps were performed correctly, you should see a green success notification appear. If you see an error message, confirm the configuration has been done per the instructions.

Enable Users and Mailboxes

Assign the Practifi - Add-Ons - Microsoft 365 Sync User permission set to your users. The Microsoft Sync administrator user should also have the permission set of Practifi - Set Audit Fields & Update with Inactive Owner assigned to their user profile.

Then link them to mailboxes on the Users & Mailboxes tab in the Microsoft 365 Sync Page. Users will only appear to be linked if they have the Practifi - Add-Ons - Microsoft 365 Sync User permission assigned to their profile.

mapping.png

Please note: While shared mailboxes are supported in this integration, groups and aliases are currently not supported.

Adding multiple mailboxes: If your firm has a lot of mailboxes to sync - so much so that adding them one by one would be very time-consuming - then you can use a data import tool to speed up the creation process. Here’s how you do it:

  1. Export the mailbox list: From Azure Portal, go to the Users section in Active Directory, then select Bulk Operations > Download users. Follow the prompts to complete the download process.

  2. Import the mailbox list: Use a tool such as Salesforce Data Loader to facilitate the import process. Add the records to the MS Graph User object, with field mappings as below:

    1. displayName: Name

    2. mail: Email Address

    3. userPrincipalName: User Principal Name

 

Confirm Settings and Activate 

Go to the Microsoft 365 Sync Page and review the configurable settings. Most of these configurable settings are straightforward. We are currently recommending the Sync Frequency be set to 15 minutes.

sync_settings.png

Exclusion Lists

Exclusion lists are very important. Without them, a needlessly large volume of emails could be imported into your organization and cause clutter with emails that aren’t useful in a CRM context. To avoid this, make sure to consult with your firm’s IT administrator and determine all domains that should be added to the Global Exclusions list. You may need to ask some questions to uncover the proper domains to add. For instance, ask about automated emails that your users may receive from tools or subscriptions your firm uses.

For instance, Practifi users may be receiving email notifications from Salesforce, such as chatter updates, task assignments and other system emails of that nature. In this case, *@salesforce.com could be added to the exclusion list.

Internal Domains 

Similar to exclusion lists, defining internal domains will help prevent internal communications from cluttering up the email sync. 

Activating the Sync

Once you’re content with your settings, it’s time to activate. Head back to the Microsoft 365 Sync Page and toggle the Confirm Settings and Activate switch. This will begin the initial sync process and schedule a series of rolling sync jobs that can be seen in Setup > Scheduled Jobs. The jobs will be named and will be labeled MS Sync Job.

Please note: We include the previous six months’ worth of email history in the initial sync, so it may take up to multiple days to complete depending on the volume of emails involved, and the number of users. If there are a large number of mailboxes to sync, it may make sense to add users every few days rather than all at once.

Email Match Engine

After each sync job, a job for the email match engine is automatically scheduled. This job will be labeled MS Sync Email Matching Job and will execute after each sync run. Because of this delay, users should allow additional time after each sync interval before seeing matched and unmatched emails populate on the Emails list views.

Please note: It is recommended that sync users do not have their work email addresses linked to contacts in the system. This will cause their emails to get matched to this contact.

Troubleshooting

Practifi Administrators can view error logs on 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 like access token expired or internal errors. This type of error is often resolved when the sync re-runs.

Entries that have a Retry link are often a result of errors during processing in Azure. We recommend clicking Retry to see if that resolves the error. 

image.png


To view in-depth error logs in detail, 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

0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.

Articles in this section

See more