Microsoft Outlook Grid Integration

The Microsoft Outlook Grid integration brings live Outlook emails and calendar events directly into AppColab Grid via Microsoft Graph. Sales and service reps can view recent email communication threads and upcoming calendar meetings linked to their Salesforce Contacts without ever leaving the CRM.

What’s Deployed

One-Time Manual Setup

1. Register App in Microsoft Azure Portal

1. Sign in to the Microsoft Entra / Azure Portal and navigate to App registrations.
2. Click New registration:
   • Name: AppColab Grid Outlook Integration
   • Supported account types: Select “Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)”.

     [!IMPORTANT] Selecting Multitenant + Personal accounts ensures both corporate Microsoft 365 and personal @outlook.com / @hotmail.com accounts can sign in.

   • Redirect URI: Select Web (leave URL blank for now).
   • Click Register.
3. Under Overview, copy your Application (client) ID.
4. In the left navigation menu, go to Certificates & secrets:
   • Click New client secret → add description (e.g. Salesforce Grid Outlook).
   • Click Add and immediately copy the Value.
5. In the left navigation menu, go to API permissions:
   • Click Add a permission → select Microsoft Graph → Delegated permissions.
   • Add the following scopes:
     • Mail.Read (read emails in Outlook mailbox)
     • Calendars.Read (read calendar meetings)
     • offline_access (maintain permanent refresh token)
     • openid, profile, email
   • Click Add permissions.

2. Configure Salesforce Auth. Provider

1. In Salesforce Setup, enter Auth. Providers in the Quick Find box and click New:
   • Provider Type: OpenIdConnect
   • Name: Outlook_Microsoft_OAuth
   • URL Suffix: Outlook_Microsoft_OAuth
   • Consumer Key: Paste your Azure Application (client) ID from Step 1
   • Consumer Secret: Paste your Azure Client Secret Value from Step 1
   • Authorize Endpoint URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

     [!IMPORTANT] Ensure you use the /common/ endpoint in the URL, NOT /organizations/. The /organizations/ endpoint rejects personal Microsoft accounts with an error.

   • Token Endpoint URL: https://login.microsoftonline.com/common/oauth2/v2.0/token
   • Default Scopes: offline_access openid profile email https://graph.microsoft.com/Mail.Read https://graph.microsoft.com/Calendars.Read
2. Click Save.
3. Scroll down and copy the generated Callback URL (e.g. https://yourdomain.my.salesforce.com/services/authcallback/Outlook_Microsoft_OAuth).
4. In Azure Portal under your App Registration > Authentication > Web, click Add URI, paste the Salesforce Callback URL, and click Save.

3. Configure Credentials in Salesforce Setup

3.1 Create the External Credential

1. In Salesforce Setup, enter Named Credentials in Quick Find.
2. Click the External Credentials tab → click New:
   • Label: Outlook
   • Name: Outlook
   • Authentication Protocol: OAuth 2.0
   • Authentication Provider: Select Outlook_Microsoft_OAuth
   • Scope: offline_access openid profile email https://graph.microsoft.com/Mail.Read https://graph.microsoft.com/Calendars.Read
   • Click Save.
3. In the Principals section, click New:
   • Parameter Name: ApiKey
   • Sequence: 1
   • Identity Type: Named Principal
   • Scope: offline_access openid profile email https://graph.microsoft.com/Mail.Read https://graph.microsoft.com/Calendars.Read
   • Click Save.
4. On the ApiKey row, click the dropdown action arrow ▼ → click Authenticate:
   • Sign in with your Microsoft account in the popup.
   • Click Accept to authorize mailbox and calendar read permissions.
   • Confirm the Principal status turns to Configured with a green checkmark.

3.2 Create the Named Credential

1. Click the Named Credentials tab (next to External Credentials) → click New:
   • Label: Outlook
   • Name: Outlook
   • URL: https://graph.microsoft.com
   • External Credential: Select Outlook
   • Generate Authorization Header: Checked
   • Allow Formulas in HTTP Header: Checked
2. Click Save.

4. Assign Permission Set Access

1. In Salesforce Setup, enter Permission Sets in Quick Find.
2. Select Integration Admin (or Outlook_Integration / your custom admin permission set).
3. Click External Credential Principal Access → click Edit.
4. Add Outlook - ApiKey to Enabled External Credential Principals.
5. Click Save and verify the permission set is assigned to your Salesforce users.

Creating an Outlook Grid Definition

1. In Salesforce, open AppColab Grid app → Grid Definitions tab → click New Grid Definition.
2. Fill in:
   • Grid Settings Name: Contact_Outlook_Messages_Grid
   • Grid Label: Contact Outlook Messages
   • Is Active?: Checked
   • Data Provider Class: OutlookGridDataProvider
   • Data Provider Configuration:

     {
       "resource": "messages",
       "parentMatchField": "Email"
     }
     

     Tip: Set "resource" to "events" to create an Outlook Calendar Events grid.

3. Click Save & Next → proceed to Preview.
4. Live Outlook email messages or calendar events load with Subject, Sender, Received Date, and Snippet!

Supported Grid Features

Troubleshooting & Common Gotchas

• “You can’t sign in here with a personal account. Use your work or school account instead.”:
  • Cause: In Salesforce Setup > Auth. Providers, the Authorize or Token URL has /organizations/ instead of /common/.
  • Fix: Edit Outlook_Microsoft_OAuth and change URLs to https://login.microsoftonline.com/common/oauth2/v2.0/authorize and https://login.microsoftonline.com/common/oauth2/v2.0/token. In Azure Portal, ensure Supported account types is Multitenant + Personal.
• 0 records returned in Standalone Preview:
  • Cause: When "parentMatchField": "Email" is configured, the provider filters emails matching the parent record’s Email field. In a standalone preview or grid wizard, there is no parent record context (parentId == null), so 0 rows are returned by design.
  • Fix: Place the grid component on a Contact record page in Lightning App Builder to view matching emails.
• 403 Forbidden / Access Denied:
  • Cause: Missing delegated scopes (Mail.Read or Calendars.Read) in Azure Portal or missing external credential principal permission.
  • Fix: Confirm permissions are granted in Azure and verify your user is assigned the permission set with Outlook - ApiKey access.