Dynamics 365 technical integration guide
For Dynamics and Entra administrators, security reviewers and IT — both authentication modes, required Dataverse privileges, API consumption, failure behaviour and auditing.
This guide describes what Revial does inside your Dynamics 365 environment, so you can approve, configure and later audit the integration. For connecting step by step see Connecting Revial to Microsoft Dynamics 365; for every column read and written see What Revial syncs with Microsoft Dynamics 365.
1. What you are approving
Revial connects to the Dataverse Web API v9.2 in one of two modes:
| Property | Microsoft sign-in (delegated) | Service account (app-only) |
|---|---|---|
| Identity | The Dynamics user who signs in | An Application User for your own app registration |
| Protocol | OAuth 2.0 authorisation code (Azure AD v1, resource = your instance) | OAuth 2.0 client credentials (v2, scope {instance}/.default) |
| App registration | Revial's | Yours, single-tenant, with a client secret |
| Entra consent | Depends on your tenant's user-consent policy | None — the app needs no API permissions |
| Dynamics admin rights | Not required | Not required |
Either way, the identity's Dataverse security roles are the only limit on what Revial can see and change. Conditional Access applies to the interactive sign-in.
2. What your admin has to do
| Situation | What to do |
|---|---|
| Users see "Need admin approval" | Grant admin consent for Revial in Entra (delegated mode) |
| You prefer no user account | Create an app registration, client secret and Application User (app-only mode) |
| You want least privilege | Create a custom security role covering section 4 |
| You want Revial to write columns | Grant Write on them, then map them in Revial |
| You want appointments or a custom meeting record | Agree the configuration with Revial (section 6) |
There is no solution to import and no plug-in to register.
3. Authentication and token model
Delegated mode
| Property | Value |
|---|---|
| Authorise endpoint | https://login.microsoftonline.com/{tenant}/oauth2/authorize with resource={instance} and prompt=select_account |
| Token endpoint | https://login.microsoftonline.com/{tenant}/oauth2/token |
| PKCE | Not used |
| Post-connect check | WhoAmI, then the user's systemuserid, internalemailaddress and fullname |
| Refresh | When less than 35 minutes remain; up to three attempts with backoff; a rotated refresh token is stored |
App-only mode
| Property | Value |
|---|---|
| Token endpoint | https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token, grant_type=client_credentials |
| Tenant | Your Directory (tenant) ID as a GUID — common is not accepted |
| Refresh token | None — a new access token is minted when needed |
| Post-connect check | A token is minted and WhoAmI succeeds before anything is stored |
Instance URL. Must be HTTPS and match yourorg.crmN.dynamics.com; paths,
query strings and trailing slashes are removed. Data calls go to the matching
yourorg.api.crmN.dynamics.com/api/data/v9.2 host.
Storage. Access and refresh tokens, and the app-only client secret, are encrypted at rest (AES-256-GCM). The client ID and tenant ID are stored in plain text.
Failures. In delegated mode a 401 or invalid_grant marks the connection as
needing re-authorisation and notifies an organisation admin ("CRM: Authentication
expired"). In app-only mode an invalid or expired secret notifies "CRM: App
credential invalid" — it has to be fixed in Entra, not by reconnecting.
Who may connect on the Revial side. An organisation owner or admin on a
plan with the CRM integration; rate-limited; single-use state valid for five
minutes. One Dynamics connection per organisation; other CRMs can be connected
alongside it.
4. Required Dataverse privileges
| Revial needs to… | Privilege |
|---|---|
| Sync accounts, contacts, leads, opportunities | Read |
| Read sales process stages | Read on process stage and opportunity sales process |
| Look up the connecting user and sellers by email | Read on system user (organisation level) |
| Write meeting notes | Create on annotation; Append / Append To on the regarding tables |
| Create appointments (if enabled) | Create on appointment; Assign (owner is set to the seller) |
| Write mapped columns | Write on those columns' tables |
| Custom meeting records (if configured) | Create and Write on that table |
| Delete anything, administer | Not needed |
Missing privileges are not skipped. A missing Read on accounts, contacts, leads or opportunities stops the sync at that table; the next run tries again. A failure reading stages marks the sync partial and continues.
5. What Revial reads and writes
Reads: accounts (active only), contacts, leads, opportunities and one sales
process's stages, with explicit $select lists. Activities and notes are not
synced. Outside the sync: WhoAmI and system users, appointments near a meeting's
start time (appointment features only), current column values before a write, and
column metadata for the mapping screen.
Writes:
| Operation | Details |
|---|---|
| Meeting summary | Create an annotation (subject, notetext) regarding the matched opportunity, account or contact |
| Appointment (optional) | Create an appointment with owner = seller and attendees; never marked completed |
| Existing appointment / custom record (optional) | Update configured columns, replacing their content; optionally create the linked record |
| Mapped columns | Update the matched contact, account or opportunity |
Revial never deletes anything, never creates accounts, contacts or opportunities, and never closes opportunities.
6. Field mappings and configuration
Write mappings are self-serve for organisation admins under Organization →
CRM Settings → Property Mapping: batch PATCH, then per-column retry; existing
values are kept unless the mapping overwrites.
Pull mappings (additional columns added to the sync) and appointment or custom meeting-record configuration are set up by Revial for your organisation. For a custom meeting record, Revial matches an appointment within ±30 minutes of the meeting start by default. An invalid configuration is treated as not configured.
7. Sync cadence and API consumption
- Cadence: roughly every hour, starting immediately after connecting (except service accounts provisioned by Revial staff, which wait for the next hourly run).
- Change tracking: Revial uses Dataverse change tracking
(
Prefer: odata.track-changes) from the first sync, stores a delta link per table and receives deletions as deleted rows. Change tracking must be enabled on the synced tables; if it is not, the sync stops at that table. - Order: accounts → contacts → leads → stages → opportunities.
- Volume: Dataverse's default page size, 5 pages per job run with automatic continuation, and at most 50,000 records per fetch.
- Timeouts: 50 seconds per request.
- Service protection limits: Revial does not back off on HTTP 429; a failed request fails the job, which the queue retries.
8. Meeting-to-CRM matching
First match wins: direct IDs on the meeting; the open opportunity it is already linked to; attendee emails → contacts → their opportunities (scored); account by website or email domain; account by name. Scoring favours open opportunities, the attendee being the primary contact, title similarity, later stages and recency. Closed opportunities are excluded; free-email domains are ignored for account matching.
9. Security, limits and failure behaviour
- Least privilege: no Dynamics admin rights; a custom role is supported.
- Secrets: tokens and client secret encrypted at rest; never sent to the browser.
- Query safety: string values in OData filters are escaped.
- Error hygiene: stored errors keep only the HTTP status and Dataverse error code, not record contents.
- Data storage: synced rows and the raw API responses are stored in Revial and deleted when you disconnect.
10. Auditing and disconnecting
To see what Revial has done: Entra sign-in logs for the connecting user or service principal; Dataverse auditing (if enabled) attributes changes to the connecting identity; notes and appointments created by Revial show that identity as creator.
To disconnect:
- In Revial — Disconnect on the card. Revial deletes its synced copy, the field mappings and the stored tokens or secret. It revokes nothing at Microsoft.
- Delegated — remove or disable Revial's enterprise application in Entra, or revoke the user's sessions.
- App-only — delete the client secret, disable the Application User or remove its security role.
Records Revial already wrote stay in Dynamics.
11. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| "Need admin approval" | Tenant blocks user consent | Grant admin consent in Entra |
| "Failed to validate Dynamics 365 access" | No Dataverse role or licence | Assign a security role to the user |
| "Could not authenticate with these credentials…" | Wrong client ID, secret or tenant, or no Application User | Check the app registration and Application User |
| Sync stops at one table | Missing Read, or change tracking disabled | Grant Read / enable change tracking |
| "CRM: App credential invalid" | Client secret expired | Create a new secret; disconnect and reconnect |
| Settings lost after reconnecting | Reconnecting resets connection settings | Ask Revial to reapply appointment or pull configuration |
| Deleted account still shown | Account was deactivated, not deleted | Expected — deactivated accounts keep their last values |
What Revial syncs with Microsoft Dynamics 365
For your Dynamics administrator and whoever reviews the integration's data access — every Dataverse column Revial reads, everything it writes back, and the known gaps.
Connecting Revial to Odoo
Creating an Odoo API key, connecting your Odoo instance to Revial, and what to do when the connection fails.