Enabling Microsoft 365 Email Sync

Follow
The functionality described in this article is available as part of our Albariño release and will not be available if your Practifi instance is not upgraded to this release. 


Overview

Microsoft 365 Sync for email ensures that your firm has reliable access to a comprehensive history of email engagement, making it easier to understand client relationships deeply and ensure your employees communicate in a compliant way. Seamlessly align your digital correspondence with the client system of record for better relationship management and whole-of-firm compliance.

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.

**Note: This content is intended for system administrators and is technical in nature. Please discuss your integration installation plans with your Practifi Customer Support Team for their assistance.*

Before You Begin

Microsoft 365 Sync is a paid feature, priced at USD$12 per user per month. 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.

Enabling Microsoft 365 Sync

We’ve made the initial setup and ongoing management of Microsoft 365 Sync straightforward by integrating everything into a dedicated Microsoft 365 Sync page located in the Settings app. The Setup Assistant tab on the Microsoft 365 Sync page lays out the required steps, making it easy to get up and running. We’ve provided some additional details for each step below.

Create an Auth Provider

To begin the enablement process, you will need to set up Microsoft 365 as an Authentication Provider. Enter the API keys, secrets and other information required to enable secure communication between systems.

First, generate a key and secret in your Microsoft 365 instance that you’ll use to create the Authentication Provider in Practifi:

  1. Go to the Microsoft Azure portal and log in with your Microsoft 365 credentials.

  2. Open Active Directory, and then select App registrations from the navigation menu to the left.

  3. Click New registration and complete the registration form as below:

    1. Name: Practifi Email Sync

    2. Supported account types: Accounts in any organizational directory (Any Azure AD directory - Multitenant)

    3. Redirect URL: Web - https://mssyncus01.onpractifi.com

  4. Once registered, open the app and copy the Application (client) ID. This will be the Consumer Key you use below.

  5. Click on the Client credentials hyperlink to open the Certificates & secrets section. Click New client secret and provide a description and expiration period based on your own preferences.

  6. Once the secret has been generated, copy the string that appears next to its name in the Value column. This will be the Consumer Secret you use below.

If you encounter any errors during this registration process, confirm that you have the permissions required for registering an app.

 

Next, return to Practifi to create the Authentication Provider:

  1. Click the Go to Setup button that appears to the right of the step.

  2. Click the New button and select CustomMSOAuthProvider as the Provider Type.

  3. Complete the form as below:

    1. NameMicrosoft365Sync

    2. URL Suffix - Microsoft365Sync

    3. Authorize Endpoint URL - https://login.microsoftonline.com/common/oauth2/v2.0/authorize

    4. Consumer Key - Use the key generated above

    5. Consumer Secret - Use the secret generated above

    6. Default Scopes - OpenID offline_access https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Mail.ReadWrite.Shared

    7. Developer NameMicrosoft365Sync

    8. Send Access Token In Header - Checked

    9. Token Endpoint URL - https://login.microsoftonline.com/common/oauth2/v2.0/token

    10. Execute as - Choose your own User record (assuming you have administrator access to both Practifi and Microsoft 365)

Register URL as Remote Site

Before your Practifi instance can communicate with an external site, that site’s URL needs to be registered. 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 Name of Microsoft365Login and a URL of https://login.microsoftonline.com/, then click Save.

Create Named Credential

Use the credentials of a Microsoft 365 administrator to control access levels for the sync service. The first set of credentials is used to connect Practifi to our email sync service hosted on Microsoft Azure, and the second connects to your Microsoft 365 instance via the Microsoft Graph API.

  1. Click the Go to Setup button that appears to the right of the step.
  2. Click the New Named Credential button and complete the form as below:
    1. Label - Microsoft365SyncService

    2. Name - Microsoft365SyncService

    3. URL - http://mssyncus1.azurewebsites.net/

    4. Identity Type - Named Principal

    5. Authentication Protocol - OAuth 2.0

    6. Authentication Provider - Microsoft365Sync

    7. Scope - OpenID offline_access https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Mail.ReadWrite.Shared

    8. Start Authentication Flow on Save - Checked

    9. Generate Authorization Header - Checked

  3. Click the Save & New button and complete the form as below:
    1. Label - MicrosoftGraphAPI

    2. Name - MicrosoftGraphAPI

    3. URL - https://graph.microsoft.com

    4. Identity Type - Named Principal

    5. Authentication Protocol - OAuth 2.0

    6. Authentication Provider - Microsoft365Sync

    7. Scope - OpenID offline_access https://graph.microsoft.com/Mail.ReadWrite https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Mail.ReadWrite.Shared

    8. Start Authentication Flow on Save - Checked

    9. Generate Authorization Header - Checked

  4. Select Save to finalize the named credential creation.

Test Connectivity

To confirm that the sync is working as expected, do the following:

    1. Click the Check button that appears to the right of the step.

    2. If you’ve performed all the above steps correctly, you should see a green success notification appear at the top of the page.

    3. If you instead see an error message, confirm that the configuration has been done as per the above guidance. If it is, contact Practifi Support for assistance.

Enable Users and Mailboxes

Assign the Microsoft 365 Sync User permission set to your users, then link them to mailboxes from the Users & Mailboxes tab. The Microsoft Sync administrator user should also have permission set Practifi - Set Audit Fields & Update with Inactive Owner assigned to their user profile.

  1. Click the Add to Users button that appears to the right of the step. This takes you to the Permission Sets page in Salesforce Setup. You can choose either to assign the permission set to users individually or alternately to a Permission Set Group that allocates it to multiple users at once.

  2. Whichever option you select, follow the steps in our guide to adding and removing user permissions to assign the permission to the desired users.

  3. Return to the Microsoft 365 Sync page and go to the Users & Mailboxes tab. On this page, personal and shared mailboxes in Microsoft 365 are linked with Practifi users.

  4. To make a mailbox available for linking, click the New Mailbox button and search for it in the modal window that appears.

  5. Once a mailbox has been added to the table, search for the User you wish to link it to by using the search bar that appears alongside it. Users will only appear in the search results if they have the Microsoft 365 Sync User permission set assigned to them.

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 Sync Settings and Exclusions tabs and make any necessary adjustments before activating Microsoft 365 Sync.

Once you’ve confirmed the suitability of your settings (see the below sections for more detailed guidance on both Sync Settings and Exclusions), select the toggle that appears to the right of the step to activate Microsoft 365 Sync.

Please note: We include the previous six months worth of email history in the initial sync, so it may take multiple days to complete depending on the email volumes involved, and it runs in chronological order starting with the earliest emails.

Settings Configuration

A small selection of options appears in the Sync Settings tab, providing everything you need for the sync to be configured correctly without unnecessary clutter.

  • Sync Frequency lets you determine how often the sync engine runs. A high frequency keeps Practifi up-to-date, however processing large volumes of emails can lead to performance issues during the workday. The available options available for sync frequency are as follows:

    • Every 15 minutes

    • Every 30 minutes

    • Hourly

    • Every 2 hours

    • Every 3 hours

    • Every 4 hours

    • Every 6 hours

    • Every 12 hours

    • Daily (provides the option to set the time of day)

    • Weekly (provides the option to select the day of the week and the time of day)

  • Keep Unmatched Emails asks how you want to handle emails that aren’t automatically matched. If you decide to keep them, you’ll also set a retention period, after which they’re deleted to avoid unnecessary use of data storage.

  • Sync Bcc Emails lets you choose whether to sync emails when the user's mailbox has been included in the Bcc field, as distinct from From, To or Cc. This is available as a separate option because the private nature of Bcc recipients is such that publicizing their receipt of the email may not be desirable.

Email Exclusion

Emails can be excluded from the sync from both a global level or for a specific mailbox. Please note that if you add an address to the exclusion list, existing emails will not be deleted. If you remove an address from the list, only future emails will be synchronized; historical emails will not be included.

Global Exclusions

To add global exclusions, do the following:

  1.  On the Microsoft 365 Sync page, go to the Exclusions tab.

  2. In the External Addresses section, click the New button.

  3. Enter the email address you wish to exclude, then click Save. Use * as a wildcard to exclude multiple addresses with a single entry, e.g. *@acme.com will exclude all email addresses in the acme.com email domain.

Personal Exclusions

Users can view all their personal exclusions from the My Excluded Addresses record list, accessible from the Emails app page. To add a new address to their personal list, do the following:

  1. From the Emails page, click the New Excluded Address button in the top-right corner.

  2. Enter the email address you wish to exclude, then click Save. Use * as a wildcard to exclude multiple addresses with a single entry.

Defining Internal Email Domains 

The Internal Domains section appears in the Exclusions tab alongside External Addresses. Add your firm's internal email domains to the list to prevent emails that exclusively contain addresses in those domains from being synced.

If an email contains one or more recipients whose email addresses are on another domain (and aren't an excluded external address), then that email will still be synced.

Again, if you add an address to the exclusion list, existing emails will not be deleted. If you remove an address from the list, only future emails will be synchronized; historical emails will not be included.

To set an internal domain, do the following:

  1. From the Internal Domains section, click the New button.
  2. Enter the email domain you wish to treat as internal, then click Save. Ensure that only the domain itself is included, e.g. “acme.com”, not “@acme.com”.

Checking Sync Performance

The Logs & Errors page provides all the details related to the ongoing performance of Microsoft 365 Sync. Each sync event appears as an entry in the table, including the number of records synced successfully and the number that encountered an error.

To view the details of which emails were successfully synced in a sync event, click the View Log button in that table row. You’ll see a modal window appear listing all the synced emails in a table, including a link to open the corresponding record in Practifi.

Troubleshooting

Issues with Sync Service

If there are problems with the sync service as a whole - such as an administrator changing the authentication credentials to an incorrect set, or an outage with Microsoft Azure - then you’ll see one or more entries in the Logs & Errors table where 0 emails were synced successfully and 0 were synced unsuccessfully. This is different from what you would see if there were no emails to sync; in that scenario, there wouldn’t be a sync event logged in the table at all.

If you need assistance resolving an issue of this sort, please contact Practifi Support. Once the issue is resolved, sync will resume from the previous failure point, meaning no messages are lost.

Issues with Specific Emails

If there are problems with a particular email - such as taking too long to retrieve an attachment from Microsoft 365 and causing a timeout - then that email will appear in the Logs & Errors table as an error. Click the Retry button to attempt a resync of the emails that were unsuccessful.

0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.