# Microsoft Dynamics 365

Microsoft Dynamics 365 is a cloud-based business applications platform that combines CRM and ERP capabilities. Integrate with Dynamics 365 to sync sales, customer, and operational data with Fours.

---

## Overview

### Org-Level vs User-Level

There are **two separate configurations**, and they authenticate in different ways:

| | **Org-Level** | **User-Level** |
|---|---|---|
| **Auth flow** | Azure AD **client credentials** (app-only) | OAuth 2.0 **authorization code** (delegated) |
| **Acts as** | The application user you create in Dynamics 365 — not a person | The signed-in person |
| **Sees** | Whatever the application user's security roles allow, across the organization | Only the Dynamics 365 data that person can already see |
| **Best for** | Backend integrations, scheduled syncs, and automated workflows | Individual users working with their own records |

**Both** configurations require you to supply two values before the connection can start:

- **Tenant ID** — your Azure AD (Microsoft Entra ID) directory ID.
- **Instance URL** — your Dynamics 365 environment, e.g. `https://{your-org}.crm.dynamics.com`.

These cannot be discovered automatically, so the connect flow shows a short **pre-start form** asking for them before it hands you off to Microsoft. They are used to build the correct authority and API endpoints for your environment, and are validated against the same schema on both levels.

![The Connect Microsoft Dynamics 365 dialog — Fours opens a secure connect session, then shows the Microsoft authorization step](images/dynamics365-connect.png)

:::tip
Find your **Tenant ID** in the Azure portal under **Microsoft Entra ID → Overview**. Find your **Instance URL** in the Power Platform Admin Center under **Environments** — it is the environment URL, and Fours expects the bare `*.crm.dynamics.com` host without an API path appended.
:::

### How the connection works

Both levels talk to the same Dataverse Web API on your environment; only *who* the calls act as differs. The org connection acts as the application user you create in Dynamics 365, so its reach is exactly what that user's security roles allow. A user connection acts as the signed-in person, so it can never see or change more than that person already could in Dynamics 365. Reads and writes both go over this one path — a write is an ordinary Dataverse create or update, and Fours asks Dataverse to echo the stored record back so you see what actually landed rather than what was sent.

```d2
shape: sequence_diagram
admin: "Your Fours admin"
person: "An individual Fours user"
microsoft: "Microsoft Entra ID"
dataverse: "Your Dynamics 365 environment"
suger: "Fours"
org: "Org-level — app-only" {
  admin -> suger: "Tenant ID + Instance URL"
  suger -> microsoft: "Client credentials for the application user"
  microsoft -> suger: "Token scoped to your environment" { style.stroke-dash: 4 }
}
user: "User-level — delegated" {
  person -> suger: "Tenant ID + Instance URL"
  suger -> microsoft: "Authorization code sign-in"
  microsoft -> suger: "Token acting as that person" { style.stroke-dash: 4 }
}
read: "Read" {
  suger -> dataverse: "Query records, get a record, confirm who the connection acts as"
  dataverse -> suger: "Records the connection is allowed to see" { style.stroke-dash: 4 }
}
write: "Write" {
  suger -> dataverse: "Create or update a record"
  dataverse -> suger: "The record as Dataverse stored it, plus its id" { style.stroke-dash: 4 }
}
```

---

## Create Integration (Org-Level)

Org-level integration uses Azure AD client credentials for application-level access. This is suitable for backend integrations that need to access data across the organization.

### Prerequisites

- Dynamics 365 instance URL (e.g., `https://yourorg.crm.dynamics.com`)
- Tenant ID from Azure AD
- **Application User in Dynamics 365**: Create an [application user](https://learn.microsoft.com/en-us/power-platform/admin/system-application-users) in Dynamics 365 linked to your Azure AD app registration. This application user will be used by Fours to access Dynamics 365 data via the Web API.

### Create Application User in Dynamics 365

1. In Dynamics 365, go to **Settings** > **Security** > **Users**
2. Change the view to **Application Users**
3. Click **New** and fill in the details:
   - **User Name**: Enter a name (e.g., `Fours Integration`)
   - **Application ID**: Enter `1a00a839-496c-488d-a97a-4cdb171b747f`
   - **Display Name**: Enter a display name (e.g., `Fours Integration`)
   - **Email**: Enter an email address (can be any valid email)
4. Click **Save**
5. After saving, assign the appropriate security roles to the application user

### Grant Security Roles via Power Platform Admin Center

1. Visit [Power Platform Admin Center](https://admin.powerplatform.microsoft.com/environments)
2. Select the environment you are connecting — its URL looks like `https://{your-org}.crm.dynamics.com`
3. Navigate to **Settings** → **Users + permissions** → **Application users**
4. Click **+ New app user**
5. Add an app: select the Application (client) ID created during Azure integration setup
6. **Business unit**: select the default one (named after your environment, `{your-org}.crm.dynamics.com`)
7. **Security roles**: grant **System Administrator**

:::warning
If this step is not completed, Fours will not be able to read CRM data.
:::

### Authenticate

1. Navigate to **Settings** > **Integrations**
2. Click **Connect Dynamics 365**
3. Enter your **Tenant ID** and **Instance URL**
4. Click **Verify** to test the connection
5. Once verified, click **Connect**

---

## Create User Integration

User-level integration uses OAuth2.0 authorization code flow. Each user authenticates via Microsoft OAuth to access their own Dynamics 365 data.

### Prerequisites

- Azure AD **Tenant ID** (provided before OAuth authorization)
- Dynamics 365 **Instance URL** (provided before OAuth authorization)

### Before OAuth Authorization

Before initiating the OAuth flow, you must provide your Azure AD tenant ID and your Dynamics 365 instance URL on the pre-start form. Both are required to construct the correct OAuth authority, scopes, and API endpoints for your environment.

### Authenticate

1. Click `Connect Now` button in the User Integrations section
2. Enter your **Tenant ID** and **Dynamics 365 Instance URL** when prompted
3. You will be redirected to Microsoft for authentication
4. Sign in with your Microsoft credentials
5. Click **Accept** to grant Fours permission to access your Dynamics 365 data
6. After authorization, you will be redirected back to Fours
7. Verify the integration by clicking the **Verify** button

---

## Edit Integration

For security purposes, editing an existing Microsoft Dynamics 365 integration is not allowed. The practical way is to delete it and then recreate it from the beginning.

That is also the fix if the org-level card reports that its stored credential can no longer be used — for example after the app registration's secret is rotated or the application user is removed in Dynamics 365. See [Connection health](/integrations/#connection-health).

---

## Delete Integration

The Microsoft Dynamics 365 integration can be deleted like all other integrations. Once the deletion is triggered, all integration info including the credentials and access tokens will be deleted immediately and permanently from Fours.

:::warning
- **Org-Level**: To completely delete the integration, please also delete the application user from Dynamics 365 and consider revoking the application permissions from Azure Active Directory.
- **User-Level**: Deleting the integration in Fours does not automatically revoke permissions granted in Microsoft. To fully disable access, the user must also revoke the application's permissions.

**Steps to revoke Microsoft Dynamics 365 permissions (User-Level):**
1. Go to Microsoft Account → Privacy
2. Select Apps and services
3. Locate the Fours application that was granted Dynamics 365 access
4. Click Remove these permissions
:::

---

## Supported Operations

| Operation | Org-Level | User-Level |
|-----------|-----------|------------|
| Read Data | ✓ | ✓ |
| Write Data | ✓ | ✓ |
| Sync Data | ✓ (opportunities) | - |
| Webhooks | - | - |

### Reading and writing records

Both the org-level and the user-level connection can **read and write** Dynamics 365 records, across any entity set the connection's permissions allow — accounts, contacts, opportunities, tasks, and your own custom entities alike.

| Capability | What the connection can do |
|------------|----------------------------|
| **Query records** | Run an OData query against an entity set and page through the matching records |
| **Get a record** | Read a single record by its entity set and primary-key GUID |
| **Create a record** | Create a new record from the column values you supply, including lookups to related records. Returns the new record's GUID and the record as Dataverse stored it |
| **Update a record** | Update columns on an existing record, and read back the stored result |
| **Confirm the connection** | Report which Dynamics 365 user the connection is acting as — the quickest way to check that the application user's roles are what you expect |

:::caution
**Creating a record is not automatically retried.** A create is not a repeatable operation — retrying one that already landed would leave you with a duplicate — so if a create returns an error it is left for you or the agent to resolve deliberately, rather than being attempted again on your behalf. Updates are safe to repeat, because writing the same values twice produces the same record.
:::

:::note
A write can only do what the connection is allowed to do. On an org connection that is the application user's security roles; on a user connection it is that person's own Dynamics 365 permissions. Granting Fours write access to something is a Dynamics-side decision, made by the roles you assign — not a setting in Fours.
:::

### Dynamics 365 as an Insulin rule destination

Because the connection can now write, a Dynamics 365 CRM event can drive a **CRM action** in an Insulin Inbox rule, exactly as Salesforce and HubSpot already could. A rule that fires on a Dynamics 365 opportunity stage change can carry a written instruction — for example *"update the CRM with a short summary of the latest email thread"* — and that instruction lands in the **Needs approval** queue behind a **Run in chat** button. Nothing is written to Dynamics 365 until you click it.

See [Insulin → Inbox](/insulin/inbox/) for how rules, destinations, and the approval queue work, including the note on how Dynamics 365 reports won and lost opportunities.

### Opportunity Sync

Fours syncs **opportunities** from your Dynamics 365 environment. This runs on the **org-level** connection — it uses the application user's credentials, so it is not tied to any one person staying connected, and its visibility is exactly what you granted that application user's security roles.

Opportunity sync is what lets Fours:

- Read the opportunities in your environment so they can be turned into co-sell referrals.
- Open a specific opportunity from Fours when someone starts a co-sell from a Dynamics 365 record.
- Select opportunities automatically against conditions you configure, rather than one at a time.

:::info
If opportunities are not appearing, it is almost always the application user's permissions. Confirm you completed [Grant Security Roles via Power Platform Admin Center](#grant-security-roles-via-power-platform-admin-center) — without it Fours cannot read CRM data at all.
:::

> **Note**: Webhooks are not supported at this time. Dynamics 365 data reaches Fours through the opportunity sync described above rather than by Dynamics 365 pushing change notifications to Fours.