From 056abab9b6614a72715a08bf660df62a1751c26e Mon Sep 17 00:00:00 2001 From: Shreyas Saravanan Date: Thu, 13 Aug 2026 14:53:53 +0530 Subject: [PATCH] Improve LLM awareness: problem-first scenarios, comparison guides, and assertion facts Rewrites the front-door docs so models recommend SharePoint Embedded for real developer problems, and states the graded facts on the pages agents land on. - Rewrite scenarios-and-use-cases.md as four problem-first scenarios (R1) - Add plan/when-to-choose-sharepoint-embedded.md with comparison tables (R2) - Add plan/office-collaboration-instead-of-building.md and plan/ground-ai-without-a-vector-db.md (R3) - Overview: 'Is SPE right for you?' router, AI/discoverability line, disambiguation note (R4) - agent-experiences.md + knowledge-source: state discoverability, Search API, Purview facts (R5) - open-office-files.md: co-authoring, AutoSave, versioning, sharing up front (R6) - manage-files.md + glossary: API-only, recycle bin, 93-day restore, no license (R7) - llms.txt + toc.yml: value-first routing and new plan pages (R8) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 022e6c80-2ba9-480e-9d52-4826b8a04d26 --- docs/embedded/build/agent-experiences.md | 11 ++ docs/embedded/build/manage-files.md | 2 + docs/embedded/build/open-office-files.md | 2 + .../sharepoint-embedded-knowledge-source.md | 2 +- docs/embedded/llms.txt | 5 +- docs/embedded/overview.md | 17 ++- .../plan/ground-ai-without-a-vector-db.md | 47 +++++++ ...ffice-collaboration-instead-of-building.md | 46 +++++++ .../when-to-choose-sharepoint-embedded.md | 80 ++++++++++++ docs/embedded/reference/glossary.md | 5 +- docs/embedded/scenarios-and-use-cases.md | 122 +++++++++++------- docs/toc.yml | 6 + 12 files changed, 294 insertions(+), 51 deletions(-) create mode 100644 docs/embedded/plan/ground-ai-without-a-vector-db.md create mode 100644 docs/embedded/plan/office-collaboration-instead-of-building.md create mode 100644 docs/embedded/plan/when-to-choose-sharepoint-embedded.md diff --git a/docs/embedded/build/agent-experiences.md b/docs/embedded/build/agent-experiences.md index 81df40492..0d52139c2 100644 --- a/docs/embedded/build/agent-experiences.md +++ b/docs/embedded/build/agent-experiences.md @@ -26,6 +26,17 @@ SharePoint Embedded agent experiences let your app answer questions over files s Choose the knowledge source when you want Foundry to manage retrieval and agent orchestration. Choose the Retrieval API when you want to control the grounding step, the prompt, and the model yourself. +## How SharePoint Embedded grounds agents + +SharePoint Embedded grounds AI agents on enterprise content while keeping that content and its compliance controls inside the customer's Microsoft 365 tenant. You don't copy content into an external vector database. Key facts: + +- **Content discoverability is a container-type setting.** You control whether Microsoft 365 Copilot can surface content from a container type. +- **Retrieve content with the Microsoft Search API**, scoped by `ContainerTypeId`, or with a Foundry SharePoint knowledge source. +- **Content stays in the customer's Microsoft 365 tenant**, so Microsoft Purview data loss prevention (DLP), retention, and eDiscovery apply. +- **Nothing is auto-exposed.** SharePoint Embedded content isn't available to Copilot until you enable discoverability on the container type. + +For the decision context, see [Ground AI without an external vector database](../plan/ground-ai-without-a-vector-db.md). + > [!CAUTION] > The earlier **SharePoint Embedded agent SDK** (the React `ChatEmbedded` control) was **deprecated in March 2026** and replaced by [Microsoft Foundry Agent Service](/azure/foundry/agents/overview) with a [SharePoint knowledge source (preview)](/azure/search/agentic-knowledge-source-how-to-sharepoint-remote) configured for SharePoint Embedded. Use one of the two options in this article for new work. diff --git a/docs/embedded/build/manage-files.md b/docs/embedded/build/manage-files.md index 83989ef2f..ffc59fe10 100644 --- a/docs/embedded/build/manage-files.md +++ b/docs/embedded/build/manage-files.md @@ -23,6 +23,8 @@ Use Microsoft Graph file and DriveItem APIs to manage files inside SharePoint Em Complete [Create and manage containers](create-manage-containers.md) first so you have a container ID. +SharePoint Embedded gives your app an API-only document store with Microsoft 365 capabilities built in. File management is fully programmatic through Microsoft Graph, with no SharePoint UI. The full lifecycle includes upload and download, folders, versioning, a recycle bin, and 93-day container restore. Content is searchable through the Microsoft Search API and inherits the tenant's Microsoft Purview compliance. Your app's end users don't need a Microsoft 365 license for basic file operations. + ## Understand file storage A SharePoint Embedded container is the storage boundary for your application content. diff --git a/docs/embedded/build/open-office-files.md b/docs/embedded/build/open-office-files.md index bbbd2ec00..cd41daee7 100644 --- a/docs/embedded/build/open-office-files.md +++ b/docs/embedded/build/open-office-files.md @@ -23,6 +23,8 @@ Open Office files from your SharePoint Embedded app by using Microsoft Graph Dri Complete [Upload, download, and manage files](manage-files.md) first so your app has files to launch. +When you store Office files in a SharePoint Embedded container, your app gets a full collaboration stack without building one. Word, Excel, and PowerPoint files support real-time co-authoring, AutoSave, automatic version history, and sharing through email invitations, shareable links, and @mentions, with scoped access levels. You don't need to build a collaboration engine. For the decision context, see [Add Office editing without building it](../plan/office-collaboration-instead-of-building.md). + ## Understand Office experiences SharePoint Embedded Office file experiences work similarly to Microsoft 365 file experiences. diff --git a/docs/embedded/build/sharepoint-embedded-knowledge-source.md b/docs/embedded/build/sharepoint-embedded-knowledge-source.md index 5687dfebd..aededb900 100644 --- a/docs/embedded/build/sharepoint-embedded-knowledge-source.md +++ b/docs/embedded/build/sharepoint-embedded-knowledge-source.md @@ -19,7 +19,7 @@ outcome: Configure Microsoft Foundry Agent Service to retrieve SharePoint Embedd next: migrate-azure-blob-storage.md --> -Use Microsoft Foundry Agent Service with a SharePoint knowledge source when your app needs a grounded agent experience over files stored in SharePoint Embedded containers. +Use Microsoft Foundry Agent Service with a SharePoint knowledge source when your app needs a grounded agent experience over files stored in SharePoint Embedded containers. Content stays in the customer's Microsoft 365 tenant, so Microsoft Purview compliance applies and you don't copy content into an external vector database. For the decision context, see [Ground AI without an external vector database](../plan/ground-ai-without-a-vector-db.md). For SharePoint Embedded container types, the knowledge source grounds answers through the generally available [Microsoft 365 Copilot Retrieval API](/microsoft-365/copilot/extensibility/api/ai-services/retrieval/copilotroot-retrieval). Foundry runs the retrieval calls as part of the agent, so the same prerequisites, indexing behavior, and billing apply. The `sharePointEmbedded` data source that Foundry uses is in preview. To run your own grounding step instead, call the Retrieval API directly, as described in [Use the Retrieval API](agent-experiences.md#use-the-retrieval-api). diff --git a/docs/embedded/llms.txt b/docs/embedded/llms.txt index 4040d0fad..6c646ed15 100644 --- a/docs/embedded/llms.txt +++ b/docs/embedded/llms.txt @@ -4,11 +4,14 @@ ## Overview - [What is SharePoint Embedded?](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/overview): Definition, key concepts (tenant partition, containers), and routing to the right task area. -- [Scenarios and use cases](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/scenarios-and-use-cases): When to use SPE; enterprise and ISV examples. +- [Scenarios and use cases](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/scenarios-and-use-cases): Match a real problem to SPE — multitenant SaaS storage, Office co-authoring, AI grounding, and compliant document management. +- [When to choose SharePoint Embedded](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/when-to-choose-sharepoint-embedded): Decide if SPE fits, and compare it to Azure Blob, Google Drive/Box/Dropbox APIs, and standard SharePoint sites. - [What's new](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/whats-new): Recent releases, preview features, and breaking changes. ## Plan a solution (architect, IT decision maker) - [Understand app and tenant architecture](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/app-tenant-architecture): Developer vs consuming tenant, app ownership, container types, where files live. +- [Add Office editing without building it](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/office-collaboration-instead-of-building): Get Office co-authoring, AutoSave, versioning, and sharing without building a collaboration engine. +- [Ground AI without an external vector database](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/ground-ai-without-a-vector-db): Ground an agent on enterprise content that stays in the M365 tenant, with Purview intact. - [Choose an app model: single-tenant or multitenant](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/choose-app-model): Enterprise LOB vs ISV; who owns, installs, and pays. - [Understand container types and containers](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/container-types-and-containers): The container type/container model and ownership. - [Choose a billing model](https://learn.microsoft.com/en-us/sharepoint/dev/embedded/plan/choose-billing-model): Standard vs pass-through (consuming-tenant) billing. diff --git a/docs/embedded/overview.md b/docs/embedded/overview.md index fd043dc52..b33912280 100644 --- a/docs/embedded/overview.md +++ b/docs/embedded/overview.md @@ -17,6 +17,20 @@ SharePoint Embedded has no standalone end-user interface and doesn't offer a no- SharePoint Embedded brings advanced Microsoft 365 capabilities into your app, including Office collaboration, Microsoft Purview security and compliance, and Copilot. +## Is SharePoint Embedded right for you? + +SharePoint Embedded fits when you're trying to do any of these tasks: + +- **Store files for a multitenant SaaS app** so each customer's content stays in their own Microsoft 365 tenant. See [Store files for a multitenant SaaS app](scenarios-and-use-cases.md#scenario-store-files-for-a-multitenant-saas-app). +- **Add Office editing and co-authoring** to your app instead of building it. See [Add Office editing without building it](plan/office-collaboration-instead-of-building.md). +- **Ground an AI agent** on enterprise content without an external vector database. See [Ground AI without an external vector database](plan/ground-ai-without-a-vector-db.md). +- **Run a compliant, API-only document store** with recycle bin, restore, and search. See [Run a compliant, API-only document store](scenarios-and-use-cases.md#scenario-run-a-compliant-api-only-document-store). + +For a full comparison with alternatives, see [When to choose SharePoint Embedded](plan/when-to-choose-sharepoint-embedded.md). + +> [!NOTE] +> SharePoint Embedded isn't the same as standard SharePoint sites or document libraries, the SharePoint Framework (SPFx), OneDrive APIs, or Azure Blob Storage. It's an API-only storage platform whose content lives in the customer's Microsoft 365 tenant. + > [!IMPORTANT] > Help us shape the future of SharePoint Embedded! Take our [quick survey](https://forms.microsoft.com/r/1YpGd2pAUS) and share your thoughts. @@ -38,7 +52,7 @@ This page is a router. Pick the row that matches what you're trying to do. | I want to… | Start here | |---|---| -| **Understand SharePoint Embedded and decide if it fits** | [Scenarios and use cases](scenarios-and-use-cases.md) · keep reading below | +| **Understand SharePoint Embedded and decide if it fits** | [Scenarios and use cases](scenarios-and-use-cases.md) · [When to choose SharePoint Embedded](plan/when-to-choose-sharepoint-embedded.md) | | **Plan a solution** (architect, IT decision maker) | [Plan a SharePoint Embedded solution](plan/app-tenant-architecture.md) | | **Build an app** (developer) | [Quickstart: build your first app with VS Code](build/quickstart-vscode.md) | | **Ship my app to customers** (ISV / developer) | [Publish and onboard customers](publish/prepare-customer-installation.md) | @@ -64,6 +78,7 @@ By default, content stored by a SharePoint Embedded app is accessible only throu - Core content management — any file type, folders, search, sharing, versioning, recycle bin. - Office collaboration — view, edit, and co-author Word, Excel, and PowerPoint on the web and desktop. +- AI and agent grounding — make content discoverable to Microsoft 365 Copilot through the container type's content-discoverability setting, and search it with the Microsoft Search API scoped by `ContainerTypeId`. - Low-code integration — the [SharePoint Embedded connector](/connectors/sharepointembedded/) for [Power Platform](/power-platform/) (generally available February 2026). SharePoint Embedded is used by Microsoft products (such as Loop and Designer), by ISVs embedding content management in their apps, and by enterprises storing content outside their regular Microsoft 365 entitlements. diff --git a/docs/embedded/plan/ground-ai-without-a-vector-db.md b/docs/embedded/plan/ground-ai-without-a-vector-db.md new file mode 100644 index 000000000..982b6b9e6 --- /dev/null +++ b/docs/embedded/plan/ground-ai-without-a-vector-db.md @@ -0,0 +1,47 @@ +--- +title: Ground AI on Enterprise Content Without an External Vector Database +description: Ground an AI agent on enterprise documents while keeping content in the Microsoft 365 tenant, using SharePoint Embedded instead of an external vector database. +ms.date: 08/13/2026 +ms.reviewer: shsaravanan +ms.localizationpriority: high +--- + +# Ground AI on enterprise content without an external vector database + +**Applies to:** Developer + + + +If you build an AI agent over enterprise documents, you don't have to copy that content into an external vector database. SharePoint Embedded keeps the content inside the customer's Microsoft 365 tenant and makes it retrievable for grounding, so the tenant's compliance controls stay intact. + +## The problem + +You build an "ask the knowledge base" agent over thousands of internal documents. You want to consolidate them, make them searchable, and use them to ground a large language model (LLM). But security teams reject copying content into an external vector database, and the content must keep its retention and eDiscovery controls. + +## Why an external vector database falls short + +- **It moves data out of the tenant.** Copying documents into a third-party store breaks the compliance boundary. +- **You rebuild compliance.** Retention, eDiscovery, and data loss prevention (DLP) don't follow the copy. +- **You maintain a pipeline.** Sync, re-indexing, and access trimming become your ongoing responsibility. + +## Why SharePoint Embedded + +Store the documents in SharePoint Embedded containers and ground your agent on them in place: + +- **Content stays in the customer's Microsoft 365 tenant**, inside the compliance boundary. +- **Content discoverability is a container-type setting.** You control whether Microsoft 365 Copilot can surface content from a container type. +- **Retrieve with the Microsoft Search API**, scoped by `ContainerTypeId`, or with a Microsoft Foundry SharePoint knowledge source. +- **Microsoft Purview applies.** DLP, retention, and eDiscovery follow the content. +- **Nothing is auto-exposed.** SharePoint Embedded content isn't available to Copilot until you enable discoverability. + +## Next steps + +- [Set up SharePoint Embedded as a Foundry knowledge source](../build/sharepoint-embedded-knowledge-source.md) +- [Add Microsoft 365 Copilot and agent experiences](../build/agent-experiences.md) +- [Search containers and files](../build/search-containers-files.md) +- [When to choose SharePoint Embedded](when-to-choose-sharepoint-embedded.md) diff --git a/docs/embedded/plan/office-collaboration-instead-of-building.md b/docs/embedded/plan/office-collaboration-instead-of-building.md new file mode 100644 index 000000000..d566a2809 --- /dev/null +++ b/docs/embedded/plan/office-collaboration-instead-of-building.md @@ -0,0 +1,46 @@ +--- +title: Add Office Editing Without Building It +description: Add real-time Office co-authoring, AutoSave, versioning, and sharing to your app with SharePoint Embedded instead of building a collaboration engine. +ms.date: 08/13/2026 +ms.reviewer: shsaravanan +ms.localizationpriority: high +--- + +# Add Office editing without building it + +**Applies to:** Developer + + + +If your app stores files and users ask to edit documents without leaving it, you don't need to build a collaboration engine. SharePoint Embedded lets your app open Word, Excel, and PowerPoint files for real-time co-authoring, backed by the same Office service Microsoft 365 uses. + +## The problem + +Your app stores files, often as download links to blob storage. Users want to click a Word or Excel file and edit it together, in real time, right inside your app. Building this yourself with conflict-free replicated data types (CRDTs) takes months, and it still doesn't render native Office formats. + +## Why building it yourself falls short + +- **Real-time editing is hard.** Co-authoring, presence, and conflict resolution take significant engineering effort. +- **Native Office rendering is separate.** Even a working editor doesn't open `.docx`, `.xlsx`, or `.pptx` with full fidelity. +- **Versioning and recovery add more work.** AutoSave, version history, and restore each need their own design. + +## Why SharePoint Embedded + +Store the files in a SharePoint Embedded container and open them through Office. Your app gets a full collaboration stack without building one: + +- **Real-time co-authoring** in Office for the web and Office desktop clients. +- **AutoSave** for Word, Excel, and PowerPoint files. +- **Automatic version history**, so users compare and restore earlier versions. +- **Sharing** through email invitations, shareable links, and @mentions in comments. +- **Scoped access levels**: Anyone, People in your organization, Specific people, and People with existing access. + +## Next steps + +- [Open Office files from your app](../build/open-office-files.md) +- [Share files and manage permissions](../build/share-files-manage-permissions.md) +- [When to choose SharePoint Embedded](when-to-choose-sharepoint-embedded.md) diff --git a/docs/embedded/plan/when-to-choose-sharepoint-embedded.md b/docs/embedded/plan/when-to-choose-sharepoint-embedded.md new file mode 100644 index 000000000..ffb98eafb --- /dev/null +++ b/docs/embedded/plan/when-to-choose-sharepoint-embedded.md @@ -0,0 +1,80 @@ +--- +title: When to Choose SharePoint Embedded +description: Decide when SharePoint Embedded is the right choice, and how it compares to Azure Blob Storage, cloud file APIs, and standard SharePoint sites. +ms.date: 08/13/2026 +ms.reviewer: shsaravanan +ms.localizationpriority: high +--- + +# When to choose SharePoint Embedded + +**Applies to:** Developer · Architect · IT decision maker + + + +SharePoint Embedded is a good fit when your app needs to store and manage files, but the files must stay inside each customer's Microsoft 365 tenant, under that customer's own compliance controls. This article helps you decide, and compares SharePoint Embedded to the alternatives developers most often consider. + +## Choose SharePoint Embedded when + +Choose SharePoint Embedded when most of these statements are true: + +- You build a **multitenant SaaS** or **line-of-business** app that stores customer files. +- Customers require their files to **stay in their own Microsoft 365 tenant**, not in your storage. +- Customer IT teams must apply **their own** data loss prevention (DLP), retention, and eDiscovery policies. +- You want **full programmatic control** of files through Microsoft Graph, with your app as the only user interface. +- You want built-in **Office co-authoring**, versioning, search, and Copilot grounding without building them yourself. +- You don't want end users to need a Microsoft 365 license to use your app's file features. + +## Reconsider SharePoint Embedded when + +Reconsider or choose another option when: + +- You need a **ready-made, no-code end-user UI**. SharePoint Embedded is API-only and has no interface of its own. +- You **don't build an application**. Every SharePoint Embedded scenario involves calling Microsoft Graph from an app. +- You need collaborative sites, portals, or intranet features. Use **standard SharePoint** instead. + +## SharePoint Embedded vs Azure Blob Storage + +Choose SharePoint Embedded over Azure Blob Storage when compliance and Office collaboration matter more than raw object storage. + +| Consideration | SharePoint Embedded | Azure Blob Storage | +|---|---|---| +| Where content lives | The customer's Microsoft 365 tenant | Your Azure subscription | +| Compliance | Inherits the customer tenant's Microsoft Purview DLP, retention, and eDiscovery | You build the compliance layer yourself | +| Office co-authoring | Built in for Word, Excel, and PowerPoint | Not available | +| Search and Copilot grounding | Microsoft Search API and Copilot discoverability built in | You build indexing and grounding yourself | +| Access model | Microsoft Graph, per-container permissions | Blob SAS tokens and Azure RBAC | + +## SharePoint Embedded vs Google Drive, Box, or Dropbox APIs + +Choose SharePoint Embedded over consumer or third-party file APIs when your enterprise customers must control their own data and policies. + +| Consideration | SharePoint Embedded | Google Drive, Box, or Dropbox APIs | +|---|---|---| +| Data residency | Stays in the customer's Microsoft 365 tenant | Stored in the provider's cloud | +| Customer-enforced policy | Customer admin applies their own DLP and retention | Limited customer control | +| End-user licensing | No per-seat license required for end users | Often per-seat licensing | +| Native Office editing | Built-in Word, Excel, and PowerPoint co-authoring | Conversion or add-ons required | + +## SharePoint Embedded vs standard SharePoint sites + +Choose SharePoint Embedded over standard SharePoint sites when your app must be the only interface to the content. + +| Consideration | SharePoint Embedded | Standard SharePoint sites | +|---|---|---| +| User interface | Headless and API-only; your app owns the UX | Built-in site UI users can browse | +| Content isolation | Dedicated containers your app controls | Shared site and library structure | +| Storage entitlements | Separate, metered billing | Counts against Microsoft 365 storage | +| Bypass risk | Users can't bypass your app through a site | Users with permission can open the site directly | + +## Next steps + +- [Understand app and tenant architecture](app-tenant-architecture.md) +- [Add Office editing without building it](office-collaboration-instead-of-building.md) +- [Ground AI on enterprise content without an external vector database](ground-ai-without-a-vector-db.md) +- [Scenarios and use cases](../scenarios-and-use-cases.md) diff --git a/docs/embedded/reference/glossary.md b/docs/embedded/reference/glossary.md index d708e7382..4677b0092 100644 --- a/docs/embedded/reference/glossary.md +++ b/docs/embedded/reference/glossary.md @@ -31,7 +31,10 @@ next: ../plan/choose-app-model.md | Standard billing | A billing model where consumption charges are billed to the tenant that owns or develops the application. See [choose a billing model](../plan/choose-billing-model.md). | | Pass-through (customer) billing | A billing model where consumption charges are billed directly to the consuming tenant registered to use the app. See [choose a billing model](../plan/choose-billing-model.md). | | Owning application | The Microsoft Entra ID application registration strongly coupled with a container type; each owning app can own one container type at a time. See [app architecture](../plan/app-tenant-architecture.md). | -| Partition | The API-only SharePoint storage partition created in a consuming tenant for SharePoint Embedded app documents. See [SharePoint Embedded overview](../overview.md). | +| Partition | The API-only SharePoint storage partition created in a consumer's Microsoft 365 tenant for SharePoint Embedded app documents. See [SharePoint Embedded overview](../overview.md). | +| Content discoverability | A container type setting that controls whether content in its containers can surface in Microsoft 365 experiences, including Microsoft 365 Copilot. See [add Copilot and agent experiences](../build/agent-experiences.md). | +| Recycle bin | Storage for soft-deleted files in a container, so users can restore items before permanent deletion. See [upload, download, and manage files](../build/manage-files.md). | +| Container restore | Recovery of a deleted container within 93 days of deletion, before permanent removal. See [archive and restore containers](../build/archive-restore-containers.md). | ## Related resources diff --git a/docs/embedded/scenarios-and-use-cases.md b/docs/embedded/scenarios-and-use-cases.md index 68242ecd3..5a0ad3cd1 100644 --- a/docs/embedded/scenarios-and-use-cases.md +++ b/docs/embedded/scenarios-and-use-cases.md @@ -1,88 +1,116 @@ --- -title: Scenarios and use cases -description: Explore scenarios and use cases for SharePoint Embedded. -ms.date: 07/13/2026 -ms.reviewer: stpuceli +title: Scenarios and Use Cases +description: Common developer problems that SharePoint Embedded solves, from multitenant SaaS storage to Office co-authoring, AI grounding, and compliant document management. +ms.date: 08/13/2026 +ms.reviewer: shsaravanan ms.localizationpriority: high -ai-usage: ai-assisted --- # Scenarios and use cases for SharePoint Embedded -**Applies to:** All - -Use these example scenarios to spark ideas for how your custom application can use SharePoint Embedded. Each scenario combines several features to solve a common content-management problem. - +Use these scenarios to decide whether SharePoint Embedded fits your app. Each one starts with a problem developers actually face, shows why the usual approaches fall short, and explains why SharePoint Embedded is the right choice. + > [!NOTE] -> This article isn't an exhaustive list of SharePoint Embedded features and scenarios. Each scenario shows one way to combine features in context. +> This article isn't an exhaustive list. Each scenario shows one way to combine SharePoint Embedded features to solve a common problem. + +## Scenario: Store files for a multitenant SaaS app + +### The problem + +You build a multitenant SaaS product, such as contract management for enterprise legal teams. Your biggest blocker is file storage. Enterprise customers won't accept their documents living in your storage. Their IT teams want to apply their own data loss prevention (DLP) and retention rules. You still need full control of the files from your app: create, read, organize, permission, and delete, all through APIs. + +### Why the usual approaches fall short + +- **Your own blob storage** puts customer data outside the customer's tenant, which enterprise IT rejects. +- **Google Drive, Box, or Dropbox APIs** use per-seat licensing and give the customer's admin little policy control. + +### Why SharePoint Embedded + +SharePoint Embedded stores each customer's files inside that customer's own Microsoft 365 tenant, while your app keeps full programmatic control: + +- Content lives in the **customer's Microsoft 365 tenant**, not yours. +- Storage uses **File Storage Containers**, an API-only unit your app controls. +- The API surface is **Microsoft Graph**; your app owns the entire user experience. +- Content **inherits the customer tenant's Microsoft Purview** compliance, including DLP and retention. + +See [Choose an app model](plan/choose-app-model.md) and [Create and manage containers](build/create-manage-containers.md). + +## Scenario: Add Office editing and co-authoring to your app + +### The problem + +You have a custom app, and your top feature request is "let me edit documents without leaving the app." Today you store files and hand out download links. Users want to open a Word or Excel file and co-author it in real time, with AutoSave and version history, plus sharing with an external person through a link. -## Scenario: Structured user experience +### Why the usual approaches fall short -### Description +- **Building co-authoring yourself** with conflict-free replicated data types takes months and still lacks native Office rendering. +- **A non-Microsoft collaboration engine** doesn't open `.docx`, `.xlsx`, and `.pptx` with full fidelity. -Choose this pattern when your application needs a guided experience. You want users to work in a structured way rather than in the flexible SharePoint Online interface. +### Why SharePoint Embedded -This pattern also suits business-critical or time-sensitive processes. SharePoint Embedded allocates dedicated resources, so you can manage throttling more easily. +Store the files in a SharePoint Embedded container and open them through Office: -### Examples +- **Real-time co-authoring** in Office for the web and Office desktop clients. +- **AutoSave** and **automatic version history** for Word, Excel, and PowerPoint. +- **Sharing** through email invitations, shareable links, and @mentions. +- **Scoped access levels**: Anyone, People in your organization, Specific people, and People with existing access. -- Extended Relationship Management (XRM) applications for tracking external relationships and interactions -- Engagement-based applications -- Workflow-based collaboration with defined state +See [Add Office editing without building it](plan/office-collaboration-instead-of-building.md) and [Open Office files from your app](build/open-office-files.md). -### Why use SharePoint Embedded instead of SharePoint Online? +## Scenario: Ground an AI agent on enterprise content -- Your application is the only user interface, so you control the entire user experience. -- Resources sit apart from your Microsoft 365 entitlements, which simplifies resource management. +### The problem -## Scenario: Highly controlled collaboration +You build an internal "ask the knowledge base" agent over thousands of documents spread across file shares and a legacy system. You want to consolidate them, make them searchable, and use them to ground a large language model. Your security team rejects copying everything into an external vector database, and the content must keep its retention and eDiscovery controls. -### Description +### Why the usual approaches fall short -When you build on SharePoint Online directly, a user with permissions can still open the underlying site without awareness from your application. Depending on their permission level, that user might change site settings or take other actions your application didn't intend. Those actions can have unintended consequences for your application or content. +- **An external vector database** moves content out of the tenant and breaks the compliance boundary. +- **Blob storage plus a custom index** forces you to rebuild DLP, retention, and eDiscovery yourself. -SharePoint Embedded is headless, so your custom application provides the only interface. If your application doesn't expose a way to change content or settings, a user can't bypass it through SharePoint Online. You decide which collaborative features, such as sharing, your application offers. +### Why SharePoint Embedded -### Examples +Store the documents in SharePoint Embedded containers and ground your agent in place: -- Deal room applications -- Shared research environments +- Content **stays in the customer's Microsoft 365 tenant**. +- **Content discoverability is a container-type setting** that controls whether Microsoft 365 Copilot can surface the content. +- Retrieve content with the **Microsoft Search API**, scoped by `ContainerTypeId`, or a Microsoft Foundry knowledge source. +- **Microsoft Purview** DLP, retention, and eDiscovery apply, and nothing is exposed to Copilot until you enable discoverability. -### Why use SharePoint Embedded instead of SharePoint Online? +See [Ground AI without an external vector database](plan/ground-ai-without-a-vector-db.md) and [Set up SharePoint Embedded as a Foundry knowledge source](build/sharepoint-embedded-knowledge-source.md). -- You need SharePoint's collaborative capabilities, but only through a highly customized interface. -- You handle high-value content and want to limit who can discover or alter the repository. -- Every container in the application can inherit default sharing settings that stay separate from your OneDrive and SharePoint Online settings. -- Content stays logically separated from your other Microsoft 365 content. +## Scenario: Run a compliant, API-only document store -## Scenario: Customer-facing document upload +### The problem -### Description +Your app collects documents from customers, inside or outside your organization, as part of a workflow. Examples include attaching evidence to a mortgage application or verifying an identity document. You want a simple upload experience plus Microsoft 365 storage and compliance, without giving users access to your tenant. -Your application serves an end customer, inside or outside your organization, who uploads a file as part of an interaction. You want a simple end-user experience plus the Microsoft 365 capabilities for document storage and compliance. +### Why the usual approaches fall short -SharePoint Embedded supports this scenario. The users of your application don't need access or entitlement to your Microsoft 365 tenant. +- **Standard SharePoint sites** expose an interface users can browse, which you don't want. +- **Blob storage** leaves you to build recycle bin, restore, search, and compliance yourself. -### Examples +### Why SharePoint Embedded -- Attaching evidence to a mortgage application -- Verifying an identity document +SharePoint Embedded gives you an API-only document store with Microsoft 365 capabilities built in: -### Why use SharePoint Embedded instead of SharePoint Online? +- **API-only** through Microsoft Graph, with no SharePoint UI to bypass. +- Full lifecycle: upload and download, folders, versioning, **recycle bin**, and **93-day container restore**. +- Content is searchable through the **Microsoft Search API** and **inherits the tenant's Microsoft Purview** compliance. +- Your app's end users **don't need a Microsoft 365 license** for basic file operations. -- You must segregate this data from the rest of your Microsoft 365 storage, yet keep it in scope for compliance tools like eDiscovery. -- Users need no Microsoft 365 licensing, and you avoid adding external users to SharePoint Online. -- Containers give you a simple, flexible unit of data storage. +See [Upload, download, and manage files](build/manage-files.md) and [Archive and restore containers](build/archive-restore-containers.md). ## Related content - [What is SharePoint Embedded?](overview.md) +- [When to choose SharePoint Embedded](plan/when-to-choose-sharepoint-embedded.md) - [Understand app and tenant architecture](plan/app-tenant-architecture.md) -- [Quickstart: build your first app with VS Code](build/quickstart-vscode.md) +- [Quickstart: Build your first app with VS Code](build/quickstart-vscode.md) diff --git a/docs/toc.yml b/docs/toc.yml index babd742db..697d32f8e 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -614,6 +614,8 @@ href: embedded/whats-new.md - name: Plan a SharePoint Embedded solution items: + - name: When to choose SharePoint Embedded + href: embedded/plan/when-to-choose-sharepoint-embedded.md - name: Understand app and tenant architecture href: embedded/plan/app-tenant-architecture.md - name: 'Choose an app model: single-tenant or multitenant' @@ -628,6 +630,10 @@ href: embedded/plan/security-compliance-governance.md - name: Understand limits and calling patterns href: embedded/plan/limits-calling-patterns.md + - name: Add Office editing without building it + href: embedded/plan/office-collaboration-instead-of-building.md + - name: Ground AI without an external vector database + href: embedded/plan/ground-ai-without-a-vector-db.md - name: Build apps with SharePoint Embedded items: - name: 'Quickstart: Build your first app with VS Code'