From be3dc6787956d27b4fdfe988f7b4f0176f9ce70a Mon Sep 17 00:00:00 2001 From: cindylay Date: Fri, 29 May 2026 16:34:46 -0700 Subject: [PATCH 1/4] Add new article Configure redirect behavior --- .../configure-redirect-behavior.md | 150 ++++++++++++++++++ docs/toc.yml | 2 + 2 files changed, 152 insertions(+) create mode 100644 docs/embedded/development/content-experiences/configure-redirect-behavior.md diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md new file mode 100644 index 000000000..50caf62fb --- /dev/null +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -0,0 +1,150 @@ +--- +title: Configuring redirect behavior +description: Configure the urlTemplate property on a SharePoint Embedded container type to route users from Microsoft 365 search results to your application. +ms.date: 05/29/2026 +ms.localizationpriority: high +--- + +# Configuring redirect behavior + +When a user selects a SharePoint Embedded file in Microsoft 365 search results, Microsoft 365 chooses a destination based on the file type. For files without a built-in Microsoft 365 web viewer, the destination depends on the `urlTemplate` property on the [container type](/sharepoint/dev/embedded/concepts/app-concepts/containertypes). This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate` to route users to your application. + +## Prerequisites + +Before you configure `urlTemplate`, ensure you have: + +- A SharePoint Embedded [container type](/sharepoint/dev/embedded/concepts/app-concepts/containertypes) that you own. +- The Microsoft Graph permission `FileStorageContainerType.Manage.All` (delegated, work or school account). Application permissions aren't supported for [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update). +- `isDiscoverabilityEnabled` set to `true` on your container type's settings, so files in your containers appear in Microsoft 365 search results. + +## How Microsoft 365 chooses a destination for a search result + +The [`isDiscoverabilityEnabled`](/graph/api/resources/filestoragecontainertypesettings) setting on the container type controls whether a container's files appear in Microsoft 365 search results. Files appear in search only when `isDiscoverabilityEnabled` is `true` for their container type. + +When a user selects a SharePoint Embedded file from search results, the file opens in an appropriate viewer. For file types without a built-in Microsoft 365 viewer, the destination depends on the container type's [`urlTemplate`](/graph/api/resources/filestoragecontainertypesettings) property. + +If `urlTemplate` isn't configured, Microsoft 365 redirects users who select non-Office or non-PDF files to a generic Microsoft help page. The help page explains that the file is stored in a third-party application and directs the user to open it there. + +### How file types are handled + +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 | +|---|---|---| +| Files with a supported Microsoft 365 web viewer (Word, Excel, PowerPoint, Visio, OneNote, and others) | Either | Opens in the corresponding Microsoft 365 web viewer | +| PDF | Either | Opens in the SharePoint Embedded PDF Previewer | +| All other types | Yes | Redirected to your application through `urlTemplate` | +| All other types | No | Redirected to a [Microsoft help page](https://aka.ms/spe-openfilelocation) | + +## Configure `urlTemplate` + +Set the `urlTemplate` property on your container type by calling the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API. The value is a URL with placeholder tokens that Microsoft 365 resolves to actual item identifiers when a user selects a search result. + +### Requirements + +The `urlTemplate` value must: + +- Be a valid absolute URL that uses the `https://` scheme. HTTP URLs aren't accepted. +- Not resolve to a loopback address, such as `localhost` or `127.0.0.1`. + +> [!IMPORTANT] +> If the URL fails validation, `urlTemplate` is silently set to `null` without returning an error. To confirm your configuration, see [Verify your configuration](#verify-your-configuration). + +### URL template syntax + +```text +https://app.contoso.com/open?tenant={tenant-id}&drive={drive-id}&item={item-id} +``` + +Each placeholder token uses curly braces. When a user selects a search result, Microsoft 365 resolves each token to a value that corresponds to the item, URL-encodes the value, and substitutes it in the template. If Microsoft 365 can't resolve a token, it removes the token from the URL. The exceptions are `{tenant-id}` and `{drive-id}`—if Microsoft 365 can't resolve them, they remain as literal text in the URL. + +### Supported tokens + +| Token | Value your application receives | +|---|---| +| `{tenant-id}` | GUID of the consuming tenant. Used to make tenant-scoped Microsoft Graph API calls. | +| `{drive-id}` | Drive ID of the container. Use it with Microsoft Graph APIs to reference the container. | +| `{folder-id}` | Item ID of the file's immediate parent folder. Item IDs aren't GUIDs. If the file is at the root of the container, `{folder-id}` is omitted from the redirect URL rather than passed as an empty value. | +| `{item-id}` | Item ID of the driveItem. Item IDs aren't GUIDs. | + +To use a custom container property as a token in `urlTemplate`, set the property's `isPatternToken` value to `true` when you create or update the property. Then reference the property in your template by enclosing its name in curly braces (for example, `{myCustomProperty}`). For more information, see [Add custom properties to a fileStorageContainer](/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} +``` + +When a user opens a `.txt` file from a search result, Microsoft 365 redirects the user to a URL like the following: + +```text +https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123def456ghi789jkl0&i=01ABC23DEF45GHI67JKL890 +``` + +Your application receives the `tenantId`, `driveId`, and `itemId` as query parameters. Use these parameters to retrieve and open the file through the Microsoft Graph API. + +### Update `urlTemplate` with Microsoft Graph + +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} +Content-Type: application/json + +{ + "settings": { + "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}" + } +} +``` + +To clear `urlTemplate`, set the property to `null` in the PATCH request body. + +### Verify your configuration + +Because validation failures are silent, confirm your update by reading the value back. Call [Get fileStorageContainerType](/graph/api/filestoragecontainertype-get) with the `$select` query option to retrieve the current `urlTemplate` value: + +```http +GET https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}?$select=settings +``` + +If the response shows `urlTemplate` as `null`, the URL you submitted didn't meet the [requirements](#requirements). Update the value and try again. + +## What your application does when called + +When Microsoft 365 routes a user to your application, your application must: + +1. Authenticate the user. The user might not have an active session in your app. Microsoft 365 doesn't pass authentication context in the redirect URL. +1. Parse the token values from the redirect URL query string. +1. Call Microsoft Graph with the `driveId` and `itemId` to retrieve the [driveItem](/graph/api/resources/driveitem) and open the file in your application's UI. + +For information about calling Microsoft Graph against a consuming tenant's containers, see [Authentication and authorization](../auth.md). + +## Troubleshooting + +| Symptom | Possible cause | +|---|---| +| Your files don't appear in Microsoft 365 search results. | The container type's `isDiscoverabilityEnabled` setting is `false`, or the registration in the consuming tenant overrides the setting. Search indexing can also take time after enablement. | +| Users land on the Microsoft help page instead of your application. | `urlTemplate` is `null` (likely because the URL failed validation), or the file type opens in a Microsoft 365 viewer instead of redirecting. | +| A token appears as literal text (such as `{tenant-id}`) in the redirect URL. | Microsoft 365 couldn't resolve the token for the current item. Verify the token name matches a [supported token](#supported-tokens) or a custom property with `isPatternToken` set to `true`. | +| Updates to `urlTemplate` don't appear in search results. | Search index updates aren't instantaneous. See [Limitations](#limitations). | + +## Limitations + +### Updates to `urlTemplate` aren't instantaneous + +Microsoft 365 stores the destination URL for each file in the search index. If you configure or update `urlTemplate` after files are indexed, search results continue to use the previous destination until Microsoft 365 updates the index. Updates to a container type's settings can take up to 24 hours to reach existing container type registrations. + +### `urlTemplate` is scoped to the container type + +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. + +## Related content + +- [Container types](/sharepoint/dev/embedded/concepts/app-concepts/containertypes) +- [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) +- [fileStorageContainerTypeSettings](/graph/api/resources/filestoragecontainertypesettings) +- [Add custom properties to a fileStorageContainer](/graph/api/filestoragecontainer-post-customproperty) +- [Authentication and authorization](../auth.md) diff --git a/docs/toc.yml b/docs/toc.yml index c89393725..08ea00f6f 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -620,6 +620,8 @@ href: embedded/development/support-archival-of-containers.md - name: Office Experiences href: embedded/development/content-experiences/office-experience.md + - name: Configuring redirect behavior + href: embedded/development/content-experiences/configure-redirect-behavior.md - name: User Experiences href: embedded/development/content-experiences/user-experiences-overview.md - name: Search Content From c3a5bb29e8c2b7fcd94a4e9539aaca59371be8be Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Fri, 29 May 2026 16:47:51 -0700 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../content-experiences/configure-redirect-behavior.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index 50caf62fb..332aaef26 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -32,7 +32,7 @@ The destination URL for a file in search results depends on the file type and wh | File type | `urlTemplate` set? | Behavior when selected from search | |---|---|---| | Files with a supported Microsoft 365 web viewer (Word, Excel, PowerPoint, Visio, OneNote, and others) | Either | Opens in the corresponding Microsoft 365 web viewer | -| PDF | Either | Opens in the SharePoint Embedded PDF Previewer | +| PDF | Either | Opens in the SharePoint Embedded PDF previewer | | All other types | Yes | Redirected to your application through `urlTemplate` | | All other types | No | Redirected to a [Microsoft help page](https://aka.ms/spe-openfilelocation) | @@ -56,7 +56,7 @@ The `urlTemplate` value must: https://app.contoso.com/open?tenant={tenant-id}&drive={drive-id}&item={item-id} ``` -Each placeholder token uses curly braces. When a user selects a search result, Microsoft 365 resolves each token to a value that corresponds to the item, URL-encodes the value, and substitutes it in the template. If Microsoft 365 can't resolve a token, it removes the token from the URL. The exceptions are `{tenant-id}` and `{drive-id}`—if Microsoft 365 can't resolve them, they remain as literal text in the URL. +Each placeholder token uses curly braces. When a user selects a search result, Microsoft 365 resolves each token to a value that corresponds to the item, URL-encodes the value, and substitutes it in the template. If Microsoft 365 can't resolve a token, it omits that token from the resolved URL. The exceptions are `{tenant-id}` and `{drive-id}`—if Microsoft 365 can't resolve them, they remain as literal text in the URL. ### Supported tokens @@ -83,7 +83,7 @@ When a user opens a `.txt` file from a search result, Microsoft 365 redirects th https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123def456ghi789jkl0&i=01ABC23DEF45GHI67JKL890 ``` -Your application receives the `tenantId`, `driveId`, and `itemId` as query parameters. Use these parameters to retrieve and open the file through the Microsoft Graph API. +Your application receives the tenant ID, drive ID, and item ID as query parameter values (using the parameter names you defined in the template, such as `t`, `d`, and `i`). Use these values to retrieve and open the file through the Microsoft Graph API. ### Update `urlTemplate` with Microsoft Graph From 1092d096ff8fd76aed15e4204f98bd06aa7a4228 Mon Sep 17 00:00:00 2001 From: cindylay Date: Fri, 29 May 2026 17:06:59 -0700 Subject: [PATCH 3/4] fix tokens table --- .../configure-redirect-behavior.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index 50caf62fb..83d9b9fd0 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -66,9 +66,22 @@ Each placeholder token uses curly braces. When a user selects a search result, M | `{drive-id}` | Drive ID of the container. Use it with Microsoft Graph APIs to reference the container. | | `{folder-id}` | Item ID of the file's immediate parent folder. Item IDs aren't GUIDs. If the file is at the root of the container, `{folder-id}` is omitted from the redirect URL rather than passed as an empty value. | | `{item-id}` | Item ID of the driveItem. Item IDs aren't GUIDs. | +| `{site-domain}` | _To be documented._ | +| `{list-id}` | _To be documented._ | +| `{site-url}` | _To be documented._ | To use a custom container property as a token in `urlTemplate`, set the property's `isPatternToken` value to `true` when you create or update the property. Then reference the property in your template by enclosing its name in curly braces (for example, `{myCustomProperty}`). For more information, see [Add custom properties to a fileStorageContainer](/graph/api/filestoragecontainer-post-customproperty). +#### Advanced tokens + +The following tokens cover specialized scenarios. Most applications can rely on the [common tokens](#supported-tokens) above. + +| Token | Value your application receives | +|---|---| +| `{ownershipType}` | _To be documented._ | +| `{itemname-guid}` | _To be documented._ | +| `{folderpath-guids}` | _To be documented._ | + ### Example If your container type has `urlTemplate` set to: From 7b44caf2b1ad9fc23cde455e150887523db0220a Mon Sep 17 00:00:00 2001 From: Andrew Connell Date: Tue, 2 Jun 2026 06:57:51 -0400 Subject: [PATCH 4/4] docs: fix invalid relative link --- .../configure-redirect-behavior.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index b434b3c6e..f1633b0c7 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -7,13 +7,13 @@ ms.localizationpriority: high # Configuring redirect behavior -When a user selects a SharePoint Embedded file in Microsoft 365 search results, Microsoft 365 chooses a destination based on the file type. For files without a built-in Microsoft 365 web viewer, the destination depends on the `urlTemplate` property on the [container type](/sharepoint/dev/embedded/concepts/app-concepts/containertypes). This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate` to route users to your application. +When a user selects a SharePoint Embedded file in Microsoft 365 search results, Microsoft 365 chooses a destination based on the file type. For files without a built-in Microsoft 365 web viewer, the destination depends on the `urlTemplate` property on the [container type](../../getting-started/containertypes.md). This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate` to route users to your application. ## Prerequisites Before you configure `urlTemplate`, ensure you have: -- A SharePoint Embedded [container type](/sharepoint/dev/embedded/concepts/app-concepts/containertypes) that you own. +- A SharePoint Embedded [container type](../../getting-started/containertypes.md) that you own. - The Microsoft Graph permission `FileStorageContainerType.Manage.All` (delegated, work or school account). Application permissions aren't supported for [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update). - `isDiscoverabilityEnabled` set to `true` on your container type's settings, so files in your containers appear in Microsoft 365 search results. @@ -30,7 +30,7 @@ If `urlTemplate` isn't configured, Microsoft 365 redirects users who select non- 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 | -|---|---|---| +| --- | --- | --- | | Files with a supported Microsoft 365 web viewer (Word, Excel, PowerPoint, Visio, OneNote, and others) | Either | Opens in the corresponding Microsoft 365 web viewer | | PDF | Either | Opens in the SharePoint Embedded PDF previewer | | All other types | Yes | Redirected to your application through `urlTemplate` | @@ -61,7 +61,7 @@ Each placeholder token uses curly braces. When a user selects a search result, M ### Supported tokens | Token | Value your application receives | -|---|---| +| --- | --- | | `{tenant-id}` | GUID of the consuming tenant. Used to make tenant-scoped Microsoft Graph API calls. | | `{drive-id}` | Drive ID of the container. Use it with Microsoft Graph APIs to reference the container. | | `{folder-id}` | Item ID of the file's immediate parent folder. Item IDs aren't GUIDs. If the file is at the root of the container, `{folder-id}` is omitted from the redirect URL rather than passed as an empty value. | @@ -77,7 +77,7 @@ To use a custom container property as a token in `urlTemplate`, set the property The following tokens cover specialized scenarios. Most applications can rely on the [common tokens](#supported-tokens) above. | Token | Value your application receives | -|---|---| +| --- | --- | | `{ownershipType}` | _To be documented._ | | `{itemname-guid}` | _To be documented._ | | `{folderpath-guids}` | _To be documented._ | @@ -138,7 +138,7 @@ For information about calling Microsoft Graph against a consuming tenant's conta ## Troubleshooting | Symptom | Possible cause | -|---|---| +| --- | --- | | Your files don't appear in Microsoft 365 search results. | The container type's `isDiscoverabilityEnabled` setting is `false`, or the registration in the consuming tenant overrides the setting. Search indexing can also take time after enablement. | | Users land on the Microsoft help page instead of your application. | `urlTemplate` is `null` (likely because the URL failed validation), or the file type opens in a Microsoft 365 viewer instead of redirecting. | | A token appears as literal text (such as `{tenant-id}`) in the redirect URL. | Microsoft 365 couldn't resolve the token for the current item. Verify the token name matches a [supported token](#supported-tokens) or a custom property with `isPatternToken` set to `true`. | @@ -156,7 +156,7 @@ The template applies to all container instances of the corresponding container t ## Related content -- [Container types](/sharepoint/dev/embedded/concepts/app-concepts/containertypes) +- [Container types](../../getting-started/containertypes.md) - [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) - [fileStorageContainerTypeSettings](/graph/api/resources/filestoragecontainertypesettings) - [Add custom properties to a fileStorageContainer](/graph/api/filestoragecontainer-post-customproperty)