[object Object]

A user uploads a contract to the Documents tab on an Account, the file appears, and everyone is happy. Six months later legal asks for every document linked to a closed account in the last quarter, and you discover that the Account folder was deleted in SharePoint but the Dynamics references still point to it. The integration is real but thin, and the cost of fixing the structure later is brutal.

What Server-Based Integration Actually Does

When you enable SharePoint integration, Dynamics stores a record in the SharePointDocumentLocation and SharePointSite tables for each folder it knows about. The Documents tab on a record renders an embedded list view that calls the SharePoint REST API in the user’s context, retrieves the matching folder contents, and shows them inline. The files themselves never enter Dataverse storage. The user’s SharePoint permissions, not their Dynamics permissions, decide what they can see.

This is the part teams forget. Granting a user read on Account in Dynamics does not grant them read on the SharePoint site. They will see the Documents tab and an empty list with a permission error tucked in the corner.

Pick a Folder Structure Before You Enable

The folder strategy choice is one-way and painful to reverse. Three patterns are common:

Flat by entity:
/AccountDocuments/Contoso (account_guid)/
/OpportunityDocuments/Renewal Q3 (opp_guid)/

Nested by parent:
/AccountDocuments/Contoso/Opportunities/Renewal Q3/

Hybrid with custom site per business unit:
/Sales-EMEA/Accounts/Contoso/
/Sales-AMER/Accounts/Acme/

Nested gets you breadcrumbs in SharePoint but creates orphan paths if a relationship changes. Flat is durable but loses the visual hierarchy. Hybrid scales for global teams but doubles the SharePointSite records you need to maintain.

Pick one, write it down, and reject feature requests that violate it.

Custom Site URLs and Permission Inheritance

A common ask is to point each business unit at a different SharePoint site. The integration supports this through SharePointSite records, but every folder created under that site inherits its permissions. If the EMEA site grants read to all of EMEA Sales, every account folder there is visible to anyone in EMEA Sales, even if Dynamics security restricts the account itself to one team.

This is by design. SharePoint is the authority for document permissions. If you need document-level security, either use unique permissions per folder, which scales poorly, or stop putting sensitive content in SharePoint and store it in Azure Blob with a custom retrieval flow.

Searching Across Both Stores

Dataverse Search indexes document metadata if you opt in to file and image indexing, but SharePoint full text search lives in Microsoft Search. Users who expect to find a phrase from inside a PDF need to search from SharePoint or M365 search, not from the Dynamics global bar. Set this expectation up front or you will keep getting tickets about missing documents that are sitting in the right folder.

Programmatic Folder Creation

When you need a folder before the user clicks the Documents tab, call the AddOrUpdateLocation action through the Web API.

async function ensureFolder(accountId) {
  const url = "/api/data/v9.2/AddOrUpdateLocation";
  const body = {
    AbsoluteUrl: `https://contoso.sharepoint.com/sites/sales/Account/${accountId}`,
    RegardingObject: { "@odata.type": "Microsoft.Dynamics.CRM.account", accountid: accountId },
    SiteEntityId: "00000000-0000-0000-0000-000000000000"
  };
  await fetch(url, { method: "POST", body: JSON.stringify(body), headers: { "Content-Type": "application/json" } });
}

This avoids the lazy-create surprise where the folder does not exist until a user clicks the tab.

Cleanup of Orphan Locations

Run a monthly job that lists SharePointDocumentLocation rows whose RelativeUrl returns 404 from SharePoint, and either recreate the folder or delete the location. Without this, the Documents tab shows broken folders forever and users start saving to email instead.

What to do this week

Document your folder strategy in one paragraph, audit the SharePointDocumentLocation table for any path that violates it, and schedule the orphan cleanup as a recurring flow. Add a one-line note on the Documents tab description that explains the SharePoint permission model.

[object Object]
Share