From 53cc83717449107b38bff8ac4d50f90dd09913d0 Mon Sep 17 00:00:00 2001 From: cindylay Date: Wed, 22 Apr 2026 09:16:58 -0700 Subject: [PATCH 1/6] Add PDF viewer documentation --- .../tutorials/using-file-preview.md | 33 ++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/embedded/development/tutorials/using-file-preview.md b/docs/embedded/development/tutorials/using-file-preview.md index 08c9602a2a..82aa506549 100644 --- a/docs/embedded/development/tutorials/using-file-preview.md +++ b/docs/embedded/development/tutorials/using-file-preview.md @@ -1,7 +1,7 @@ --- title: File Previews description: Preview SharePoint Embedded content -ms.date: 05/21/2024 +ms.date: 04/22/2026 ms.localizationpriority: high --- @@ -101,3 +101,34 @@ async function preview(driveId, itemId) { document.getElementById('preview').src = response + "&nb=true"; //Use nb=true to suppress banner } ``` + +## PDF Preview + +SharePoint Embedded includes a PDF previewer that you can enhance with query parameters appended to the driveItem's `webUrl` property. To get `webUrl`, call the [driveItem Graph endpoint](/graph/api/resources/driveitem) and retrieve the `webUrl` field. + +The parameters are passed as a JSON-encoded `embed` query string: + +```text +&embed={"":,"":} +``` + +You can include one or more parameters in the same object. + +> [!NOTE] +> Additional query parameters will be added to this section as the PDF previewer expands. + +### Print (`mpp`) + +Enables the print icon and Ctrl+P functionality. + +```text +&embed={"mpp":true} +``` + +### Sticky Notes (`mpsn`) + +Shows sticky note content if sticky notes are present in the PDF. + +```text +&embed={"mpsn":true} +``` From 8b0a7bd0cb3247645dfa5ea9cad54ebc27ef5915 Mon Sep 17 00:00:00 2001 From: cindylay Date: Fri, 24 Apr 2026 17:37:36 -0700 Subject: [PATCH 2/6] Add article on url template --- .../content-experiences/office-experience.md | 110 +++++++++++++++++- 1 file changed, 105 insertions(+), 5 deletions(-) diff --git a/docs/embedded/development/content-experiences/office-experience.md b/docs/embedded/development/content-experiences/office-experience.md index 03f75af649..49a757a0e3 100644 --- a/docs/embedded/development/content-experiences/office-experience.md +++ b/docs/embedded/development/content-experiences/office-experience.md @@ -7,11 +7,11 @@ ms.localizationpriority: high # Office file experiences for SharePoint Embedded -Office file experiences for SharePoint Embedded platform will work in a similar manner to Microsoft 365 platform. +Office file experiences for the SharePoint Embedded platform work similarly to the Microsoft 365 platform. ## Opening Office documents from SharePoint Embedded -Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. AutoSave feature saves your files automatically as your user's work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. +Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. The AutoSave feature saves files automatically as your users work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. Documents stored in an archived container can’t be viewed or accessed. Applications must handle the archived state of the container by displaying an appropriate error message and guiding end users on the next steps to regain access, such as reactivating the container. @@ -21,10 +21,10 @@ Versioning is automatically enabled on each Word, Excel, and PowerPoint file sto ## Collaborating on Office documents from SharePoint Embedded -It's simple for your users to collaborate on your SharePoint Embedded Application's Office documents – they can **Share documents** with specific peers or with people outside your organization by Creating a shareable link to use wherever needed, Send an email invitation or @mention in comments to tag someone for feedback and, **Collaborate in real time** by co-authoring in Office with SharePoint Embedded Applications. +It's simple for your users to collaborate on your SharePoint Embedded Application's Office documents – they can **Share documents** with specific peers or with people outside your organization by creating a shareable link to use wherever needed, sending an email invitation or @mention in comments to tag someone for feedback and, **Collaborate in real time** by co-authoring in Office with SharePoint Embedded Applications. > [!NOTE] -> Mentions require target users to [have an Microsoft 365 license assigned to them](../auth.md#mention-users-in-office-documents). +> Mentions require target users to [have a Microsoft 365 license assigned to them](../auth.md#mention-users-in-office-documents). > > Mentions are restricted to people inside the consuming tenant's organization. Mentions exclude guests and users from other tenants in a multitenant setting. @@ -74,6 +74,106 @@ Breadcrumb patterns for SharePoint Embedded Application Apps are constructed fro ![Screenshot of breadcrumb pattern in SharePoint Embedded Applications](../../images/office2.png) -Here are few examples of SharePoint Embedded Application breadcrumb display within Office client experiences. +Here are a few examples of SharePoint Embedded Application breadcrumb display within Office client experiences. ![Screenshot of breadcrumb options in SharePoint Embedded Applications.](../../images/office1.png) + +## Controlling where users land when opening SPE files from Microsoft 365 search + +When users search for content on Microsoft 365 (for example, on Office.com or OneDrive), search results include files stored in SharePoint Embedded containers. Clicking a search result opens the file in an appropriate viewer. For file types without a built-in Microsoft viewer, the destination depends on whether your container type has a URL template configured. + +The `urlTemplate` property on your container type lets you specify a URL pattern in your application that Microsoft 365 uses as the destination when a user clicks on one of your files stored in your containers in search results. Without it, users clicking non-Office, non-PDF files in search results are directed to a generic Microsoft help page rather than your application. + +### How file types are handled + +The destination URL for a file in search results depends on the file type, regardless of whether `urlTemplate` is set: + +| File type | `urlTemplate` set? | Destination when clicked in search | +|---|---|---| +| Word, Excel, PowerPoint | Yes or No | Opens in Office Web Apps | +| PDF and other files supported by the embedded viewer | Yes or No | Opens in the embedded file viewer | +| All other types (.txt, custom extensions, etc.) | Yes | Redirected to your application via the resolved `urlTemplate` | +| All other types (.txt, custom extensions, etc.) | No | Redirected to `https://aka.ms/spe-openfilelocation` | + +### Configuring `urlTemplate` + +Set `urlTemplate` on your container type using the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API. The value is a URL with placeholder tokens that Microsoft 365 resolves to actual item identifiers at the time a user clicks a search result. + +#### URL template syntax + +``` +https://app.contoso.com/open?tenant={tenant-id}&drive={drive-id}&item={item-id} +``` + +Tokens are enclosed in curly braces and replaced with values for the specific item the user clicked. Any token that cannot be resolved is removed from the URL before the redirect occurs. + +#### Supported tokens + +| Token | Value your app receives | +|---|---| +| `{tenant-id}` | ID of the consuming tenant; use to make tenant-scoped Graph API calls | +| `{drive-id}` | Drive ID of the container; use with the Graph Files API to reference the container | +| `{folder-id}` | ID of the item's immediate parent folder; may be absent for root-level files | +| `{item-id}` | ID of the file; combine with `{drive-id}` and the Graph Files API to open or retrieve the file | + +You can also use container custom properties as tokens, as long as the custom property was created with `isPatternToken: true`. The token format is `{propertyName}` where `propertyName` is the key of the custom property. + +For more information on custom property tokens, see [Custom properties on fileStorageContainers](/graph/api/filestoragecontainer-post-customproperty). + +#### Example + +If your container type has `urlTemplate` set to: + +``` +https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id} +``` + +Then when a user clicks a `.txt` file in a search result, they are redirected to something like: + +``` +https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123...&i=01ABC... +``` + +Your application receives the tenant ID, drive ID, and item ID as query parameters and can use them to open the correct file using the Microsoft Graph Files API. + +#### Setting `urlTemplate` via the Graph API + +Use a PATCH request to update the container type: + +```http +PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId} +Content-Type: application/json + +{ + "settings": { + "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}" + }, + "etag": "" +} +``` + +For the full reference, see [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update). + +### Fallback behavior when `urlTemplate` is not set + +If `urlTemplate` is not configured on your container type, users who click on non-Office, non-PDF files in Microsoft 365 search results are redirected to `https://aka.ms/spe-openfilelocation`. This page explains that the file is stored in a third-party application and that the user should open it there directly. + +If your application stores only Word, Excel, PowerPoint, and PDF files, you may not need to set `urlTemplate` at all. For applications that store any other file types, setting `urlTemplate` is strongly recommended to avoid users encountering this help page from search. + +### Limitations + +#### Search index updates require a re-crawl + +The destination URL for each file is stored in the Microsoft 365 search index when the file is crawled. If you configure or update `urlTemplate` after files have already been indexed, existing search results continue to route to the previous destination until those files are re-crawled. Microsoft 365 performs incremental crawls automatically, but there may be a delay before all files reflect the updated URL. + +#### `urlTemplate` is scoped to the container type, not individual containers + +The template applies to all containers of that type across all consuming tenants. Use the `{tenant-id}` token to route users to the correct tenant context within your application. + +#### Custom property tokens require `isPatternToken: true` + +Container custom properties are only eligible for use as URL tokens if they were created with `isPatternToken: true`. Properties without this flag cannot be used in the template. + +#### `{folder-id}` reflects the item's immediate parent + +For files at the root of the container, this token may not resolve and is removed from the final URL. Design your application to handle URLs where `{folder-id}` is absent. From 0e0c06dcd49ad559c9e13a08a4f04c86f18b1557 Mon Sep 17 00:00:00 2001 From: cindylay Date: Mon, 27 Apr 2026 09:09:50 -0700 Subject: [PATCH 3/6] remove PDF viewer changes --- .../tutorials/using-file-preview.md | 33 +------------------ 1 file changed, 1 insertion(+), 32 deletions(-) diff --git a/docs/embedded/development/tutorials/using-file-preview.md b/docs/embedded/development/tutorials/using-file-preview.md index 82aa506549..08c9602a2a 100644 --- a/docs/embedded/development/tutorials/using-file-preview.md +++ b/docs/embedded/development/tutorials/using-file-preview.md @@ -1,7 +1,7 @@ --- title: File Previews description: Preview SharePoint Embedded content -ms.date: 04/22/2026 +ms.date: 05/21/2024 ms.localizationpriority: high --- @@ -101,34 +101,3 @@ async function preview(driveId, itemId) { document.getElementById('preview').src = response + "&nb=true"; //Use nb=true to suppress banner } ``` - -## PDF Preview - -SharePoint Embedded includes a PDF previewer that you can enhance with query parameters appended to the driveItem's `webUrl` property. To get `webUrl`, call the [driveItem Graph endpoint](/graph/api/resources/driveitem) and retrieve the `webUrl` field. - -The parameters are passed as a JSON-encoded `embed` query string: - -```text -&embed={"":,"":} -``` - -You can include one or more parameters in the same object. - -> [!NOTE] -> Additional query parameters will be added to this section as the PDF previewer expands. - -### Print (`mpp`) - -Enables the print icon and Ctrl+P functionality. - -```text -&embed={"mpp":true} -``` - -### Sticky Notes (`mpsn`) - -Shows sticky note content if sticky notes are present in the PDF. - -```text -&embed={"mpsn":true} -``` From 10387ff6890f8630e3ed227180d0d2814dc4f7f7 Mon Sep 17 00:00:00 2001 From: cindylay Date: Mon, 27 Apr 2026 09:58:53 -0700 Subject: [PATCH 4/6] remove 1P parameter and update File Types table --- .../content-experiences/office-experience.md | 35 +++++++++---------- 1 file changed, 16 insertions(+), 19 deletions(-) diff --git a/docs/embedded/development/content-experiences/office-experience.md b/docs/embedded/development/content-experiences/office-experience.md index 49a757a0e3..7b2dc1fe17 100644 --- a/docs/embedded/development/content-experiences/office-experience.md +++ b/docs/embedded/development/content-experiences/office-experience.md @@ -1,7 +1,7 @@ --- title: Office Experiences description: Overview of Office experiences with SharePoint Embedded content -ms.date: 06/18/2025 +ms.date: 04/27/2026 ms.localizationpriority: high --- @@ -11,7 +11,7 @@ Office file experiences for the SharePoint Embedded platform work similarly to t ## Opening Office documents from SharePoint Embedded -Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. The AutoSave feature saves files automatically as your users work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. +Office documents in SharePoint Embedded apps can be opened and edited in Office for the web or in desktop Office applications for a richer experience. AutoSave is enabled by default, automatically saving changes to Word, Excel, and PowerPoint files. Documents stored in an archived container can’t be viewed or accessed. Applications must handle the archived state of the container by displaying an appropriate error message and guiding end users on the next steps to regain access, such as reactivating the container. @@ -88,13 +88,13 @@ The `urlTemplate` property on your container type lets you specify a URL pattern The destination URL for a file in search results depends on the file type, regardless of whether `urlTemplate` is set: -| File type | `urlTemplate` set? | Destination when clicked in search | -|---|---|---| -| Word, Excel, PowerPoint | Yes or No | Opens in Office Web Apps | -| PDF and other files supported by the embedded viewer | Yes or No | Opens in the embedded file viewer | -| All other types (.txt, custom extensions, etc.) | Yes | Redirected to your application via the resolved `urlTemplate` | -| All other types (.txt, custom extensions, etc.) | No | Redirected to `https://aka.ms/spe-openfilelocation` | - +| File type | `urlTemplate` set? | Destination when clicked in search | +|------------------------------------------------------|--------------------|----------------------------------------------------| +| Word, Excel, PowerPoint | Yes | Opens in Office Web Apps | +| PDF | Yes | Opens in the SharePoint Embedded PDF Previewer | +| All other types | Yes | Redirected to your application via `urlTemplate` | +| All other types | No | Redirected to `https://aka.ms/spe-openfilelocation`| + ### Configuring `urlTemplate` Set `urlTemplate` on your container type using the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API. The value is a URL with placeholder tokens that Microsoft 365 resolves to actual item identifiers at the time a user clicks a search result. @@ -109,14 +109,14 @@ Tokens are enclosed in curly braces and replaced with values for the specific it #### Supported tokens -| Token | Value your app receives | -|---|---| -| `{tenant-id}` | ID of the consuming tenant; use to make tenant-scoped Graph API calls | -| `{drive-id}` | Drive ID of the container; use with the Graph Files API to reference the container | -| `{folder-id}` | ID of the item's immediate parent folder; may be absent for root-level files | -| `{item-id}` | ID of the file; combine with `{drive-id}` and the Graph Files API to open or retrieve the file | +| Token | Value your app receives | +|--------------|-----------------------------------------------------------------------------------------------| +| `{tenant-id}`| ID of the consuming tenant; use to make tenant-scoped Graph API calls | +| `{drive-id}` | Drive ID of the container; use with the Graph Files API to reference the container | +| `{folder-id}`| ID of the item's immediate parent folder; may be absent for root-level files | +| `{item-id}` | ID of the file; combine with `{drive-id}` and the Graph Files API to open or retrieve the file| + -You can also use container custom properties as tokens, as long as the custom property was created with `isPatternToken: true`. The token format is `{propertyName}` where `propertyName` is the key of the custom property. For more information on custom property tokens, see [Custom properties on fileStorageContainers](/graph/api/filestoragecontainer-post-customproperty). @@ -170,9 +170,6 @@ The destination URL for each file is stored in the Microsoft 365 search index wh The template applies to all containers of that type across all consuming tenants. Use the `{tenant-id}` token to route users to the correct tenant context within your application. -#### Custom property tokens require `isPatternToken: true` - -Container custom properties are only eligible for use as URL tokens if they were created with `isPatternToken: true`. Properties without this flag cannot be used in the template. #### `{folder-id}` reflects the item's immediate parent From 6544184100d46210c6abf5a1ca006ad3c223da69 Mon Sep 17 00:00:00 2001 From: cindylay Date: Mon, 27 Apr 2026 14:52:16 -0700 Subject: [PATCH 5/6] run MS Learn linter for style and prose --- .../content-experiences/office-experience.md | 136 ++++++++---------- 1 file changed, 63 insertions(+), 73 deletions(-) diff --git a/docs/embedded/development/content-experiences/office-experience.md b/docs/embedded/development/content-experiences/office-experience.md index 7b2dc1fe17..b3fd6c3410 100644 --- a/docs/embedded/development/content-experiences/office-experience.md +++ b/docs/embedded/development/content-experiences/office-experience.md @@ -1,144 +1,143 @@ --- -title: Office Experiences -description: Overview of Office experiences with SharePoint Embedded content +title: Office file experiences for SharePoint Embedded +description: Learn how Office file experiences work with SharePoint Embedded, including versioning, collaboration, co-authoring, breadcrumb navigation, and Microsoft 365 search integration. ms.date: 04/27/2026 ms.localizationpriority: high --- # Office file experiences for SharePoint Embedded -Office file experiences for the SharePoint Embedded platform work similarly to the Microsoft 365 platform. +SharePoint Embedded supports the same Office file experiences available in Microsoft 365, including opening and editing documents, co-authoring, versioning, sharing, and breadcrumb navigation. This article describes how these experiences work in SharePoint Embedded applications. ## Opening Office documents from SharePoint Embedded -Office documents in SharePoint Embedded apps can be opened and edited in Office for the web or in desktop Office applications for a richer experience. AutoSave is enabled by default, automatically saving changes to Word, Excel, and PowerPoint files. +Office documents in SharePoint Embedded apps can be opened and edited in Office for the web or in desktop Office applications for full desktop functionality. AutoSave is enabled by default and automatically saves changes to Word, Excel, and PowerPoint files. -Documents stored in an archived container can’t be viewed or accessed. Applications must handle the archived state of the container by displaying an appropriate error message and guiding end users on the next steps to regain access, such as reactivating the container. +Documents stored in an archived container can’t be viewed or accessed. Your application must handle the archived state of the container by displaying an appropriate error message and guiding users through the steps to regain access, such as reactivating the container. ## View or restore a previous version of an Office document from SharePoint Embedded -Versioning is automatically enabled on each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Apps, that helps your users to see what changes have been made in a file, compare different versions, or restore the version you want. This is incredibly important to your users if a mistake was made, a previous version is preferred, or in multi-user coauthoring scenarios when your users are collaborating with others and someone makes changes your users didn't want in a file. +Office document versioning is controlled by the `isVersioningEnabled` setting in your container type configuration. Users can track changes, compare versions, and restore earlier versions when needed—whether to recover from mistakes, revert to a preferred version, or manage changes in collaborative scenarios. ## Collaborating on Office documents from SharePoint Embedded -It's simple for your users to collaborate on your SharePoint Embedded Application's Office documents – they can **Share documents** with specific peers or with people outside your organization by creating a shareable link to use wherever needed, sending an email invitation or @mention in comments to tag someone for feedback and, **Collaborate in real time** by co-authoring in Office with SharePoint Embedded Applications. +Users can share files with specific individuals or external users via links, email invitations, or @mentions in comments. Office also supports real-time collaboration through co-authoring. > [!NOTE] -> Mentions require target users to [have a Microsoft 365 license assigned to them](../auth.md#mention-users-in-office-documents). +> Users you @mention must [have a Microsoft 365 license assigned to them](../auth.md#mention-users-in-office-documents). > -> Mentions are restricted to people inside the consuming tenant's organization. Mentions exclude guests and users from other tenants in a multitenant setting. +> The @mentions feature is restricted to people inside the consuming tenant's organization and excludes guests and users from other tenants in a multitenant setting. ### Share your documents -#### Send an email invite +#### Send an email invitation Share your SharePoint Embedded documents by sending an email invitation to specific people: -- Select Share, start typing the email addresses or contact names of people you want to share with. When you begin to enter info in the box, you can also choose a contact from the list that appears. -- Include a message if you want and hit Send. +- Select **Share** and start typing the email addresses or contact names of people you want to share with. You can choose contacts from the list that appears. #### Create a shareable link -Creating a shareable link makes it simple to share your SharePoint Embedded document in an email, document, or IM. +Creating a shareable link makes it simple to share your SharePoint Embedded document in an email, document, or instant message. -- Select Share, Copy Link, and Paste the link wherever you want -- Change any permissions of the link if needed +- Select **Share**, select **Copy Link**, and paste the link wherever you want. +- Change any link permissions if needed. -#### Co-Author +### Co-author -If you want others to edit with you, you can easily share files and collaborate with trusted peers for a fresh perspective. When you need help with a presentation, you can invite trusted peers to help you get it into shape. This means that when you work on a file, they can as well. You’ll see their changes and they’ll see yours—as you make them! Use @mentions in comments to get someone's attention. +Users can collaborate on Office files by sharing them with colleagues. Multiple users can edit shared files simultaneously, with changes visible as they happen. @mentions in comments help bring others into the conversation for feedback. - See who else is in the document and where they're working. -- A presence indicator shows where someone is making changes. See any changes right as they're being made. -- See changes made by others and see what's happened while you were away. +- See a presence indicator where someone is making changes, and view those changes in real time. +- See changes made by others and review what happened while you were away. -#### Levels of sharing access +### Levels of sharing access -There are different options for sharing SharePoint Embedded Application Office Documents from: +The following table describes the sharing options available for SharePoint Embedded application files: -| If you want to … | Sharing Setting to Set | -| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Allow Anyone who receives the link access to SharePoint Embedded Application File | **Anyone**  gives access to anyone who receives this link, whether they receive it directly from you or are forwarded from someone else. This might include people outside of your organization. | -| Allow anyone in your organization to access to your SharePoint Embedded Application File | **People in \** gives anyone in your organization who has the link access to the file, whether they receive it directly from you or forwarded from someone else. | -| Secure your SharePoint Embedded Application docs only to specific people. | When you need to prevent recipients from forwarding a shared link, use the **Specific People**  permission. **Specific people**  gives access only to the people you specify, although other people might already have access. If people forward the sharing invitation, only people who already have access to the item will be able to use the link. | -| Reshare the link with specific people | **People with existing access**  can be used by people who already have access to the document or folder. It doesn't change the permissions on the item. Use this if you just want to send a link to somebody who already has access. | +| If you want to … | Setting | +| --- | --- | +| Allow anyone who receives the link access to a SharePoint Embedded application file | **Anyone** gives access to anyone who receives this link, whether they receive it directly from you or it's forwarded from someone else. This might include people outside of your organization. | +| Allow anyone in your organization to access your SharePoint Embedded application file | **People in \** gives anyone in your organization with the link access to the file, whether they receive it directly from you or it's forwarded from someone else. | +| Restrict your SharePoint Embedded application files to specific people | When you need to prevent recipients from forwarding a shared link, use the **Specific People** permission scope. **Specific People** grants access only to the recipients you designate explicitly. If a recipient forwards the sharing invitation, only people who already have access to the item can use the link. | +| Reshare the link with specific people | Use **People with existing access** to share a link with someone who already has access to the document or folder. This option doesn't change any existing permissions. | ## Breadcrumb properties on Office documents from SharePoint Embedded -Breadcrumb properties are used by Office clients to display breadcrumb-style elements within Office client UI that aid your users in associating Office files with your Application. +Breadcrumb properties enable Office clients to display navigation elements that help users associate Office files with your application. > [!NOTE] -> We recommend specifying 'Current Channel' to take advantage of Breadcrumb patterns and future enhancements to Office Apps. Learn more about [specifying update channels for Office Apps](/deployoffice/updates/overview-update-channels). +> We recommend specifying **Current Channel** to take advantage of breadcrumb patterns and future enhancements to Office apps. Learn more about [specifying update channels for Office apps](/deployoffice/updates/overview-update-channels). -Breadcrumb patterns for SharePoint Embedded Application Apps are constructed from container properties configured for your Apps. The following diagram maps the container properties to breadcrumb presentation in Office clients: +Container properties configured for your app define the breadcrumb patterns. The following diagram shows how container properties map to the breadcrumb display in Office clients: -![Screenshot of breadcrumb pattern in SharePoint Embedded Applications](../../images/office2.png) +![Screenshot of breadcrumb pattern in SharePoint Embedded applications](../../images/office2.png) -Here are a few examples of SharePoint Embedded Application breadcrumb display within Office client experiences. +Here are a few examples of SharePoint Embedded application breadcrumb navigation in Office clients. -![Screenshot of breadcrumb options in SharePoint Embedded Applications.](../../images/office1.png) +![Screenshot of breadcrumb options in SharePoint Embedded applications.](../../images/office1.png) -## Controlling where users land when opening SPE files from Microsoft 365 search +## Opening files from Microsoft 365 search -When users search for content on Microsoft 365 (for example, on Office.com or OneDrive), search results include files stored in SharePoint Embedded containers. Clicking a search result opens the file in an appropriate viewer. For file types without a built-in Microsoft viewer, the destination depends on whether your container type has a URL template configured. +When users search for content on Microsoft 365 (for example, on Office.com), search results include files stored in SharePoint Embedded containers. Selecting a search result opens the file in an appropriate viewer. For file types without a built-in Microsoft viewer, the destination depends on the container type's [URL template](/graph/api/resources/filestoragecontainertypesettings#properties). -The `urlTemplate` property on your container type lets you specify a URL pattern in your application that Microsoft 365 uses as the destination when a user clicks on one of your files stored in your containers in search results. Without it, users clicking non-Office, non-PDF files in search results are directed to a generic Microsoft help page rather than your application. +You can control whether files appear in Microsoft 365 search results using the [`isDiscoverabilityEnabled`](/graph/api/resources/filestoragecontainertypesettings#properties) container type configuration. + +The `urlTemplate` property specifies the URL pattern Microsoft 365 uses when users open files from search results. If no URL template is configured, Microsoft 365 directs file types with no default viewer to a generic Microsoft help page instead of your application. ### How file types are handled -The destination URL for a file in search results depends on the file type, regardless of whether `urlTemplate` is set: +The destination URL for a file in search results depends on the file type and whether `urlTemplate` is set: + +| File type | `urlTemplate` set? | Behavior when selected from search | +|---|---|---| +| Word, Excel, PowerPoint | Either | Opens in Office for the web | +| PDF | Either | Opens in the SharePoint Embedded PDF Previewer | +| All other types | Yes | Redirected to your application via `urlTemplate` | +| All other types | No | Redirected to a [Microsoft help page](https://aka.ms/spe-openfilelocation) | -| File type | `urlTemplate` set? | Destination when clicked in search | -|------------------------------------------------------|--------------------|----------------------------------------------------| -| Word, Excel, PowerPoint | Yes | Opens in Office Web Apps | -| PDF | Yes | Opens in the SharePoint Embedded PDF Previewer | -| All other types | Yes | Redirected to your application via `urlTemplate` | -| All other types | No | Redirected to `https://aka.ms/spe-openfilelocation`| - ### Configuring `urlTemplate` -Set `urlTemplate` on your container type using the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API. The value is a URL with placeholder tokens that Microsoft 365 resolves to actual item identifiers at the time a user clicks a search result. +Set the `urlTemplate` property on your container type using the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API. The value is a URL with placeholder tokens that Microsoft 365 resolves to actual item identifiers at the time a user selects a search result. #### URL template syntax -``` +```text https://app.contoso.com/open?tenant={tenant-id}&drive={drive-id}&item={item-id} ``` -Tokens are enclosed in curly braces and replaced with values for the specific item the user clicked. Any token that cannot be resolved is removed from the URL before the redirect occurs. +Tokens are enclosed in curly braces and replaced with values for the specific item the user selects. Any token that cannot be resolved is removed from the URL before the redirect occurs. #### Supported tokens -| Token | Value your app receives | -|--------------|-----------------------------------------------------------------------------------------------| -| `{tenant-id}`| ID of the consuming tenant; use to make tenant-scoped Graph API calls | -| `{drive-id}` | Drive ID of the container; use with the Graph Files API to reference the container | -| `{folder-id}`| ID of the item's immediate parent folder; may be absent for root-level files | -| `{item-id}` | ID of the file; combine with `{drive-id}` and the Graph Files API to open or retrieve the file| +| Token | Value your app receives | +|---|---| +| `{tenant-id}` | ID of the consuming tenant; used to make tenant-scoped Graph API calls | +| `{drive-id}` | Drive ID of the container; use with the Graph APIs to reference the container | +| `{folder-id}` | ID of the item's immediate parent folder; omitted entirely from the URL for root-level files | +| `{item-id}` | ID of the driveItem | - - -For more information on custom property tokens, see [Custom properties on fileStorageContainers](/graph/api/filestoragecontainer-post-customproperty). +For more information on custom properties, see [Custom properties on fileStorageContainers](/graph/api/filestoragecontainer-post-customproperty). #### Example If your container type has `urlTemplate` set to: -``` +```text https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id} ``` -Then when a user clicks a `.txt` file in a search result, they are redirected to something like: +Then when a user opens a `.txt` file from a search result, Microsoft 365 redirects them to a URL like: -``` +```text https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123...&i=01ABC... ``` -Your application receives the tenant ID, drive ID, and item ID as query parameters and can use them to open the correct file using the Microsoft Graph Files API. +Your application receives the tenant ID, drive ID, and item ID as query parameters and can use them to retrieve and open the file via the Microsoft Graph API. -#### Setting `urlTemplate` via the Graph API +#### Setting `urlTemplate` via Graph API -Use a PATCH request to update the container type: +Use the PATCH endpoint [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) to update `urlTemplate`: ```http PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId} @@ -152,25 +151,16 @@ Content-Type: application/json } ``` -For the full reference, see [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update). - -### Fallback behavior when `urlTemplate` is not set - -If `urlTemplate` is not configured on your container type, users who click on non-Office, non-PDF files in Microsoft 365 search results are redirected to `https://aka.ms/spe-openfilelocation`. This page explains that the file is stored in a third-party application and that the user should open it there directly. - -If your application stores only Word, Excel, PowerPoint, and PDF files, you may not need to set `urlTemplate` at all. For applications that store any other file types, setting `urlTemplate` is strongly recommended to avoid users encountering this help page from search. - ### Limitations #### Search index updates require a re-crawl The destination URL for each file is stored in the Microsoft 365 search index when the file is crawled. If you configure or update `urlTemplate` after files have already been indexed, existing search results continue to route to the previous destination until those files are re-crawled. Microsoft 365 performs incremental crawls automatically, but there may be a delay before all files reflect the updated URL. -#### `urlTemplate` is scoped to the container type, not individual containers +#### `urlTemplate` is scoped to the container type The template applies to all containers of that type across all consuming tenants. Use the `{tenant-id}` token to route users to the correct tenant context within your application. - #### `{folder-id}` reflects the item's immediate parent -For files at the root of the container, this token may not resolve and is removed from the final URL. Design your application to handle URLs where `{folder-id}` is absent. +If a file is stored at the root of the container, `{folder-id}` is omitted from the redirect URL rather than passed as an empty value. Make sure your application handles URLs where this parameter is not present. \ No newline at end of file From ab6b0897ab6bcf1b50e3d98bdedcdd8be6166e15 Mon Sep 17 00:00:00 2001 From: cindylay Date: Mon, 27 Apr 2026 15:11:02 -0700 Subject: [PATCH 6/6] fix typos and wording suggestions --- .../content-experiences/office-experience.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/embedded/development/content-experiences/office-experience.md b/docs/embedded/development/content-experiences/office-experience.md index b3fd6c3410..41e0a1abb3 100644 --- a/docs/embedded/development/content-experiences/office-experience.md +++ b/docs/embedded/development/content-experiences/office-experience.md @@ -36,9 +36,9 @@ Share your SharePoint Embedded documents by sending an email invitation to speci - Select **Share** and start typing the email addresses or contact names of people you want to share with. You can choose contacts from the list that appears. -#### Create a shareable link +#### Create a sharing link -Creating a shareable link makes it simple to share your SharePoint Embedded document in an email, document, or instant message. +Creating a sharing link makes it simple to share your SharePoint Embedded document in an email, document, or instant message. - Select **Share**, select **Copy Link**, and paste the link wherever you want. - Change any link permissions if needed. @@ -153,13 +153,13 @@ Content-Type: application/json ### Limitations -#### Search index updates require a re-crawl +#### Search index updates may be delayed -The destination URL for each file is stored in the Microsoft 365 search index when the file is crawled. If you configure or update `urlTemplate` after files have already been indexed, existing search results continue to route to the previous destination until those files are re-crawled. Microsoft 365 performs incremental crawls automatically, but there may be a delay before all files reflect the updated URL. +The destination URL for each file is stored in the Microsoft 365 search index when the file is indexed. If you configure or update `urlTemplate` after files have already been indexed, existing search results continue to route to the previous destination until those files are re-indexed. Microsoft 365 performs incremental indexing automatically, but there may be a delay before all files reflect the updated URL. #### `urlTemplate` is scoped to the container type -The template applies to all containers of that type across all consuming tenants. Use the `{tenant-id}` token to route users to the correct tenant context within your application. +The template applies to all container instances of the corresponding container type across all consuming tenants. Use the `{tenant-id}` token to route users to the correct tenant within your application. #### `{folder-id}` reflects the item's immediate parent