microsoft/Salesforce-Custom-Copilot-Connector

microsoft/Salesforce-Custom-Copilot-Connector

Description: Production-tested template for building Microsoft 365 Copilot custom connectors for Salesforce CRM - covers standard + custom objects and fields with all permission models enabled

Language: Python

Stars: 0

Forks: 0

Open issues: 12

Created: 2026-06-11T06:55:24Z

Pushed: 2026-06-18T03:21:59Z

Default branch: main

Fork: no

Archived: no

README:

Salesforce CRM Custom Connector for Microsoft Graph

A Python-based connector that syncs Salesforce CRM data into Microsoft Search via the Microsoft Graph External Connectors API. It fetches Salesforce objects (Accounts, Contacts, Leads, Opportunities, Cases, and custom objects), resolves record-level ACLs from Salesforce's sharing model, and ingests them as searchable items with proper access control.

---

Table of Contents

• [Features](#features)
• [Project Structure](#project-structure)
• [Prerequisites](#prerequisites)
• [Installation](#installation)
• [Configuration](#configuration)
• [Usage](#usage)
• [Logging](#logging)
• [ACL Resolution](#acl-resolution)
• [Tuning Parameters](#tuning-parameters)
• [Running Tests](#running-tests)
• [Validated Search Queries](#validated-search-queries)
• [Known Limitations](#known-limitations)
• [Extending for Production Use](#extending-for-production-use)
• [Security Considerations](#security-considerations)
• [FAQ](#faq)
• [Contributing](#contributing)
• [License](#license)

---

Features

• Multi-object sync — Accounts, Contacts, Leads, Opportunities, Cases, and custom objects (e.g. Customer_Project__c)
• Fine-grained ACL resolution — Respects Salesforce Org-Wide Defaults, role hierarchies, sharing rules, territories, queues, and public groups
• Adaptive Card search results — Configurable result templates for Microsoft Search
• CLI with multiple commands — Full deployment, re-ingestion, single-item/object debugging
• Live dashboard — Real-time per-object progress, throughput, ETA, and error display (powered by rich)
• Delta (incremental) sync — Only fetches records changed since the last successful run
• Checkpointing & resume — Crash-safe; restarts pick up where the previous run left off
• Failed records log — Per-item error details (HTTP status, error code, message) in a JSONL file for inspection and retry
• Parallel Graph API calls — Adaptive concurrency for $batch pushes (auto-dials down on 429 throttling)
• Bulk identity resolution — Batches Salesforce-to-AAD user lookups via Graph $batch (20x fewer HTTP calls)
• Self-healing queries — Automatically retries Salesforce queries when fields aren't available in the target org

---

Project Structure

├── run.py # CLI entry point
├── commands/ # CLI subcommand implementations
├── config/ # JSON schema, Graph properties, result templates, and sync state
├── dashboard.py # Live console dashboard (rich-powered)
├── env/ # Environment variable config files (.env.local)
├── graph/ # Microsoft Graph API client and ingestion pipeline
├── item/ # Salesforce → Graph external item conversion
├── salesforce/ # Salesforce REST API client and configuration
├── acl_engine/ # ACL resolution engine (OWD, shares, roles, territories)
├── logs/ # Runtime-generated log and summary files
├── docs/ # Architecture documentation (ACL data flow diagrams)
└── tests/ # Automated tests and mock data fixtures

Each folder contains its own README.md with detailed documentation.

---

Prerequisites

1. Python 3.10+

Download and install from python.org.

Verify your installation:

python --version # Should be 3.10 or higher
pip --version

2. Salesforce Connected App

You need a Salesforce Connected App with OAuth 2.0 credentials to allow API access.

Steps:

1. Log in to your Salesforce org as an admin. 2. Navigate to Setup → App Manager → New Connected App. 3. Fill in:

• Connected App Name: e.g. Graph Connector
• API (Enable OAuth Settings): ✅ Check
• Callback URL: https://login.salesforce.com/services/oauth2/callback
• Selected OAuth Scopes:
• Full access (full)
• Perform requests at any time (refresh_token, offline_access)
• Access and manage your data (api)

4. Save and wait 2–10 minutes for activation. 5. Note down the Consumer Key (Client ID) and Consumer Secret.

Salesforce documentation:

• Create a Connected App
• OAuth 2.0 Client Credentials Flow
• Connected App Configuration

3. Microsoft Entra ID (Azure AD) App Registration

You need an app registration in Microsoft Entra ID with permissions for the Graph External Connectors API.

Steps:

1. Go to Microsoft Entra admin center → App registrations. 2. Click New registration.

• Name: e.g. Salesforce Graph Connector
• Supported account types: Single tenant
• Redirect URI: Leave blank (not needed for daemon app)

3. After creation, note the Application (client) ID and Directory (tenant) ID. 4. Go to Certificates & secrets → New client secret — note the secret value. 5. Go to API permissions → Add a permission → Microsoft Graph → Application permissions and add:

• ExternalConnection.ReadWrite.All
• ExternalItem.ReadWrite.All

6. Click Grant admin consent for your tenant.

Microsoft documentation:

• Register an application in Entra ID
• Graph Connector permissions
• Microsoft Graph External Connectors overview
• Admin consent for Graph permissions

4. Azure CLI (optional, for authentication)

If using DefaultAzureCredential (recommended for local dev):

# Install Azure CLI: https://learn.microsoft.com/en-us/cli/azure/install-azure-cli
az...