Dynamics 365 Virtual Entities: Cross-System Federation, CRUD Capabilities & Limitations

TL;DR

• Bottom line: Virtual entities (virtual tables) let Dataverse surface external data as native tables without replication — full CRUD supported via OData v4 provider, Azure Cosmos DB provider, or custom plug-in providers. [src1]
• Key limit: External data sources must expose GUID primary keys (Edm.Guid) — integer or string IDs cannot map to Dataverse unique identifiers. [src1, src4]
• Watch out for: No auditing, no search, no calculated/rollup columns, no field-level security, and only organization-owned security mode — these are non-negotiable platform constraints. [src1]
• Best for: Real-time federated read/write access to external data (F&O, SQL, OData endpoints, Cosmos DB) from Power Apps, Power Automate, and Dataverse APIs without maintaining duplicate data. [src2]
• Authentication: F&O virtual entities use service-to-service (S2S) calls via Microsoft Entra application; OData v4 provider supports custom header/query string auth parameters. [src2, src4]

System Profile

Dataverse virtual entities are a platform-level feature of Microsoft Dataverse that project external data as if it were native Dataverse tables. The external data is never copied — every Create, Retrieve, RetrieveMultiple, Update, and Delete operation is translated into a call to the external data source in real time. [src1]

For Finance & Operations (F&O) apps specifically, Microsoft provides a dedicated virtual entity provider that maps all OData-enabled F&O entities into Dataverse. This is the primary mechanism for cross-system federation between customer engagement apps (Sales, Service, Marketing) and F&O apps (Finance, Supply Chain Management, Human Resources). [src2]

API Surfaces & Capabilities

Virtual entities operate through data providers that translate Dataverse operations into external system calls. Three provider types are available plus a dedicated F&O provider. [src1, src4, src8]

Rate Limits & Quotas

Per-Request Limits

Rolling / Daily Limits (F&O Backend)

Important: F&O virtual entity calls are exempt from F&O service protection API limits when Power Platform integration is enabled. However, Dataverse service protection API limits still apply. [src5]

Authentication

Authentication Gotchas

• F&O S2S application should have access only to CDSVirtualEntityAdapterService and catalog entity — broader access is a security anti-pattern. [src2]
• Dataverse passes invoking user's identity to F&O during S2S calls — F&O query runs in that user's security context. Ensure the mapped F&O user has correct entity/row-level permissions. [src2]
• Portal users accessing F&O virtual entities must have CDSVirtualEntityAuthorizedPortalUser role but must NOT have sysadmin or security admin roles. [src2]
• OData v4 Data Provider cannot connect to another Dataverse environment — only non-Dataverse OData endpoints. [src4]

Constraints

• Organization-owned only: No user-owned security filtering or field-level security. [src1]
• GUID primary key required: Edm.Int32 and Edm.String cannot map to Dataverse unique identifiers. [src1, src4]
• No auditing: Changes to virtual entity records not captured in Dataverse audit logs. [src1]
• No search: Excluded from Dataverse search (no persisted data). [src1]
• No calculated/rollup columns: Must implement on external side. [src1]
• No charts/dashboards: Virtual table data cannot power Dataverse visualizations. [src1]
• Immutable table type: Cannot convert between virtual and standard after creation. [src1]
• No offline caching: Values never cached locally — always fetched live. [src1]
• Cannot represent activities or support BPFs. [src1]
• F&O tenant restriction: Dataverse and F&O must share same Microsoft Entra tenant. [src2]

Integration Pattern Decision Tree

START — User needs to access external data from Dataverse/Power Platform
├── Does the user need data replicated INTO Dataverse?
│   ├── YES — need auditing, search, calculated fields, or offline
│   │   ├── Real-time bidirectional? → Dual Write
│   │   └── Batch ETL? → DMF or Azure Synapse Link
│   └── NO — federated read/write acceptable
│       ├── External source is Finance & Operations?
│       │   ├── YES → F&O Virtual Entities (built-in provider)
│       │   └── NO ↓
│       ├── External source exposes OData v4?
│       │   ├── YES → OData v4 Data Provider (built-in)
│       │   └── NO ↓
│       ├── Azure Cosmos DB?
│       │   ├── YES → Cosmos DB provider (Marketplace)
│       │   └── NO → Custom Data Provider (.NET plug-ins)
├── Data volume
│   ├── < 1K records/day → Virtual entities fine
│   ├── 1K-10K records/day → Optimize with $select, pagination
│   └── > 10K records/day → Consider Dual Write or DMF instead
└── Need charts, dashboards, search, or auditing?
    ├── YES → Cannot use virtual entities; replicate to native tables
    └── NO → Virtual entities are the right choice

Quick Reference

F&O Virtual Entity Setup Checklist

OData v4 Provider Data Type Mappings

Step-by-Step Integration Guide

1. Configure OData v4 Virtual Table Data Source

Create a data source pointing to your external OData endpoint. [src4]

1. Navigate to Settings > Administration > Virtual Entity Data Sources
2. Click New and select OData v4 Data Provider
3. Set the URI to your OData service root
4. Set Timeout (default 30 seconds)
5. Choose Pagination mode: client-side (default) or server-side ($skiptoken)
6. Add authentication headers/query strings (up to 10 parameters)
7. Save

Verify: Navigate to Virtual Entity Data Sources list → new source appears with status Active.

2. Create the Virtual Table Definition

Map your external entity to a Dataverse virtual table. [src1]

1. Go to Power Apps → Tables → New table → Virtual table
2. Select the data source created in Step 1
3. Map the entity name and primary key (must be Edm.Guid)
4. Map columns: external field names to Dataverse column definitions
5. Define relationships (lookups) to other tables if needed

Verify: Open the new table in Advanced Find → records from external source appear.

3. Query Virtual Table via Web API

Read records from the virtual table through the Dataverse Web API. [src6]

GET [Organization URI]/api/data/v9.2/new_externalproducts?$select=new_name,new_price,new_category&$filter=new_category eq 'Electronics'&$top=50
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

Verify: HTTP 200 response with value array containing external records.

4. Perform CRUD Operations

Write operations work identically to native Dataverse tables. [src1, src7]

POST [Organization URI]/api/data/v9.2/new_externalproducts
Content-Type: application/json

{
  "new_name": "Widget Pro",
  "new_price": 29.99,
  "new_category": "Electronics"
}

Verify: HTTP 204 response with OData-EntityId header. Confirm record exists in external source.

Code Examples

Python: Query F&O Virtual Entity via Dataverse Web API

# Input:  Microsoft Entra app credentials, Dataverse environment URL
# Output: List of F&O customer records surfaced as virtual entities

import requests
from msal import ConfidentialClientApplication

app = ConfidentialClientApplication(
    client_id="YOUR_APP_ID",
    client_credential="YOUR_CLIENT_SECRET",
    authority="https://login.microsoftonline.com/YOUR_TENANT_ID"
)
token = app.acquire_token_for_client(
    scopes=["https://YOUR_ORG.crm.dynamics.com/.default"]
)

headers = {
    "Authorization": f"Bearer {token['access_token']}",
    "OData-MaxVersion": "4.0",
    "OData-Version": "4.0",
    "Accept": "application/json",
    "Prefer": "odata.maxpagesize=100"
}

# Use $select to avoid FK overhead
url = "https://YOUR_ORG.crm.dynamics.com/api/data/v9.2/mserp_custcustomerv3entities"
params = {
    "$select": "mserp_customeraccount,mserp_organizationname,mserp_customergroupid",
    "$filter": "mserp_customergroupid eq '10'",
    "$top": "50"
}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
customers = response.json().get("value", [])

C#/.NET: CRUD on Virtual Table via SDK

// Input:  IOrganizationService from Dataverse SDK
// Output: Created/updated/deleted record in external system

var record = new Entity("new_externalproduct");
record["new_name"] = "Widget Pro Max";
record["new_price"] = new Money(49.99m);

// Create passes through to external data source
Guid newId = service.Create(record);

// Update
record.Id = newId;
record["new_price"] = new Money(44.99m);
service.Update(record);

// Delete
service.Delete("new_externalproduct", newId);

PowerShell: Enable F&O Virtual Entity

# Input:  Dataverse environment URL, F&O entity logical name
# Output: Virtual entity becomes visible in Dataverse

Install-Module -Name Microsoft.Xrm.Data.PowerShell -Scope CurrentUser
$conn = Connect-CrmOnline -ServerUrl "https://YOUR_ORG.crm.dynamics.com"

$catalog = Get-CrmRecords -conn $conn `
  -EntityLogicalName "mserp_finabortenvironmententity" `
  -FilterAttribute "mserp_physicalname" `
  -FilterOperator "eq" `
  -FilterValue "CustCustomerV3Entity"

$entityId = $catalog.CrmRecords[0].Id
Set-CrmRecord -conn $conn `
  -EntityLogicalName "mserp_finabortenvironmententity" `
  -Id $entityId `
  -Fields @{ "mserp_hasbeengenerated" = $true }

Data Mapping

OData EDM to Dataverse Type Gotchas

Data Type Gotchas

• OData v4 provider returns ALL columns regardless of $select in Retrieve/RetrieveMultiple — server-side projection is not applied. [src1]
• F&O virtual entities use the Dataverse company concept (cdm_companyid) — cross-company queries require explicit company filtering. [src2]
• Foreign key columns (prefixed with _mshr_fk_) trigger additional round-trips. Excluding them can reduce response time by 50-80%. [src6]

Error Handling & Failure Points

Common Error Codes

Failure Points in Production

• FK column expansion causes 429 throttling: Large grids with FK columns trigger cascading retrievals. Fix: Always use $select to exclude _mshr_fk_ prefixed columns. [src6]
• Cross-region latency spikes: Dataverse and F&O in different Azure regions adds 100-500ms per call. Fix: Co-locate in same Azure region. [src2]
• Stale metadata after F&O schema changes: Queries return wrong columns or fail until refreshed. Fix: Set Refresh checkbox on entity in catalog after schema changes. [src3]
• Portal user permissions misconfigured: Sysadmin role on portal users causes security errors. Fix: Assign CDSVirtualEntityAuthorizedPortalUser; remove sysadmin. [src2]
• Non-GUID primary key: Integration fails silently with integer IDs. Fix: Generate stable GUIDs (e.g., deterministic UUID v5) from external IDs in the data provider. [src1, src4]

Anti-Patterns

Wrong: Including all columns in virtual table grid views

// BAD — fetches all columns including FK navigation properties
GET /api/data/v9.2/mshr_hcmworkerbaseentities
// Triggers cascading round-trips to F&O for each FK column
// Causes throttling on datasets > 100 records

Correct: Use $select to exclude FK columns

// GOOD — explicitly select only needed columns
GET /api/data/v9.2/mshr_hcmworkerbaseentities?$select=mshr_name,mshr_firstname,mshr_lastname,mshr_personnelnumber
// 50-80% faster; avoids FK round-trips [src6]

Wrong: Using virtual entities for bulk data migration

// BAD — 50,000 sequential S2S calls via virtual entities
for (int i = 0; i < 50000; i++)
{
    var record = new Entity("mserp_vendvendortablev2entity");
    record["mserp_vendoraccountnumber"] = vendors[i].AccountNumber;
    service.Create(record);  // Each = round-trip to F&O
}
// Hours of runtime + throttled at 6,000/5min

Correct: Use DMF for bulk operations

// GOOD — use Data Management Framework for bulk operations
// Virtual entities are for real-time federated access, not ETL
// DMF supports parallel processing with configurable batch sizes
// Use DMF REST API: POST /data/DataManagementDefinitionGroups/
//   Microsoft.Dynamics.DataEntities.ImportFromPackage

Wrong: Assuming auditing captures virtual entity changes

// BAD — relying on Dataverse audit for virtual entity records
// Auditing is NOT supported for virtual tables [src1]

Correct: Implement change tracking on external system

// GOOD — use F&O entity change tracking or external audit logs
// For F&O: enable change tracking on data entity in AOT
// For custom providers: log changes in plug-in handlers

Common Pitfalls

• Not co-locating Dataverse and F&O: Cross-region adds 100-500ms latency per call. Fix: Always provision in same Azure region. [src2]
• Forgetting to refresh metadata after F&O updates: Cached schema causes query failures. Fix: Check Refresh checkbox after F&O schema changes; automate via CI/CD. [src3]
• Enabling all F&O entities as virtual: Adds unnecessary overhead. Fix: Only enable actively needed entities; disable unused ones. [src3]
• Expecting calculated columns to work: They silently return null. Fix: Implement calculations on external side or OData computed view. [src1]
• Power BI without column optimization: Defaults to fetching all columns with FK overhead. Fix: Use Advanced Editor in Power Query; exclude _mshr_fk_ columns. [src6]
• Portal security over-provisioning: Sysadmin role triggers "Unable to determine the user" errors. Fix: CDSVirtualEntityAuthorizedPortalUser role only. [src2]

Diagnostic Commands

# Check if F&O virtual entities solution is installed (PowerShell)
Get-CrmRecords -conn $conn -EntityLogicalName "solution" \
  -FilterAttribute "uniquename" -FilterOperator "like" \
  -FilterValue "MicrosoftOperations%"

# List all visible F&O virtual entities
GET [Org URI]/api/data/v9.2/mserp_finabortenvironmententities?\
  $filter=mserp_hasbeengenerated eq true\
  &$select=mserp_physicalname,mserp_hasbeengenerated

# Test virtual entity access (simple retrieve)
GET [Org URI]/api/data/v9.2/mserp_custcustomerv3entities?$top=1\
  &$select=mserp_customeraccount

# Check API limits via response headers
# Look for: x-ms-ratelimit-burst-remaining-xrm-requests
# And: Retry-After header on 429 responses

# Enable plug-in tracing for virtual entity errors
# Settings > Administration > System Settings > Customization tab
# Then check: Settings > Plug-In Trace Log

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Virtual entities return all columns on Retrieve/RetrieveMultiple regardless of $select — this is a known platform behavior, not a bug. Performance optimization must happen at the external endpoint or via narrow client-side projections. [src1]
• F&O virtual entity exemption from service protection API limits applies ONLY when Power Platform integration is enabled. Without integration, F&O endpoints enforce full throttling. [src5]
• Dataverse service protection limits (6,000 requests/5 min, 52 concurrent) still apply to the Dataverse side — the exemption only covers the F&O endpoint. [src5]
• Security is binary (org-wide on/off) — no way to restrict virtual entity access to specific records or fields within Dataverse. Row-level security depends on the external system's own authorization. [src1]
• Virtual table lookup columns in grid views cannot be filtered or sorted — permanent platform limitation. [src1]