From be3dc6787956d27b4fdfe988f7b4f0176f9ce70a Mon Sep 17 00:00:00 2001 From: cindylay Date: Fri, 29 May 2026 16:34:46 -0700 Subject: [PATCH 01/10] 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 02/10] 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 03/10] 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 04/10] 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) From f319323cf13ce326dbcdfe30b00019ae41bdf4e7 Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Mon, 8 Jun 2026 13:02:04 -0700 Subject: [PATCH 05/10] Cover both search and driveItem.webUrl in redirect behavior article Reframes urlTemplate as governing redirect behavior on two surfaces (Microsoft 365 search results and driveItem.webUrl), replaces PDF-specific copy with embed-viewer language, clarifies token resolution, adds a forward-looking webUrl callout with webDavUrl workaround, adds PowerShell redirect-URI naming clarification and a recrawl limitation, and inserts TODO comments for undocumented tokens. --- .../configure-redirect-behavior.md | 74 ++++++++++++------- 1 file changed, 49 insertions(+), 25 deletions(-) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index f1633b0c7..8764ca88b 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -1,13 +1,18 @@ --- 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. +description: Configure the urlTemplate property on a SharePoint Embedded container type to control how Microsoft 365 routes users to container content from Microsoft 365 search results and from the driveItem.webUrl property returned by Microsoft Graph. 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](../../getting-started/containertypes.md). This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate` to route users to your application. +The `urlTemplate` property on a SharePoint Embedded [container type](../../getting-started/containertypes.md) governs where Microsoft 365 sends users when they open files in your containers. It controls the destination on two surfaces: + +- Microsoft 365 search results. +- The `driveItem.webUrl` property returned by Microsoft Graph, which is the canonical URL apps consume to open an item. + +For files without a supported viewer (the Office web viewer or the embed viewer), both surfaces use `urlTemplate` to route users to your application. This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate`. ## Prerequisites @@ -15,30 +20,43 @@ Before you configure `urlTemplate`, ensure you have: - 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. +- `isDiscoverabilityEnabled` set to `true` on your container type's settings — required only for the search-results scenario, so files in your containers appear in Microsoft 365 search results. The `driveItem.webUrl` redirect behavior doesn't depend on `isDiscoverabilityEnabled`. -## How Microsoft 365 chooses a destination for a search result +## How Microsoft 365 chooses a destination -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. +Microsoft 365 chooses a destination based on the file type. `urlTemplate` applies only to files without a supported viewer (the Office web viewer or the embed viewer). This file-type scope is the same today and after the `webUrl` rollout described in [driveItem.webUrl behavior](#driveitemweburl-behavior). -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. +If `urlTemplate` isn't configured, Microsoft 365 sends users who open files without a supported viewer to a generic [Microsoft help page](https://aka.ms/spe-openfilelocation). 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: +The destination for a file depends on the file type and whether `urlTemplate` is set: -| File type | `urlTemplate` set? | Behavior when selected from search | +| File type | `urlTemplate` set? | Behavior when opened | | --- | --- | --- | -| 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 | +| Files with a supported Office web viewer (Word, Excel, PowerPoint, Visio, OneNote, and others) | Either | Opens in the corresponding Office web viewer | +| Files supported by the embed viewer | Either | Opens in the embed viewer | | 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) | + + +### `driveItem.webUrl` behavior + +For SharePoint Embedded items, the `driveItem.webUrl` property returned by Microsoft Graph reflects the same redirect behavior described above: + +- For files without a supported viewer, when `urlTemplate` is set: `webUrl` returns the resolved `urlTemplate` redirect URL. +- For files without a supported viewer, when `urlTemplate` isn't set: `webUrl` returns the `aka.ms` help link. +- For files with a supported viewer: `webUrl` returns the viewer URL. + +> [!IMPORTANT] +> `driveItem.webUrl` will soon reflect the redirect behavior described above. If your application currently relies on `webUrl` returning the file's canonical URL, switch to the [`webDavUrl`](/graph/api/resources/driveitem) property, which returns the canonical URL today and continues to do so after the rollout. + ## 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. +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 opens an item. + +The SharePoint Embedded PowerShell cmdlet exposes the same setting as a "redirect URI" parameter. The PowerShell "redirect URI" is the `urlTemplate` value and is unrelated to the app-registration redirect URI used for authentication. ### Requirements @@ -56,7 +74,9 @@ 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 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. +Each placeholder token uses curly braces. When a user opens an item, 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 drops the entire query parameter that contains that token from the resolved URL (for example, `&folder={folder-id}` is dropped entirely rather than emitted as `&folder=`). The exceptions are `{tenant-id}` and `{drive-id}`: when Microsoft 365 can't resolve them, their query parameters remain in the URL with the token left as literal text (for example, `&tenant={tenant-id}`). ### Supported tokens @@ -64,11 +84,11 @@ Each placeholder token uses curly braces. When a user selects a search result, M | --- | --- | | `{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. | +| `{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, Microsoft 365 drops the entire query parameter that contains `{folder-id}` from the redirect URL rather than passing it with 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._ | +| `{site-domain}` | | +| `{list-id}` | | +| `{site-url}` | | 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). @@ -78,9 +98,9 @@ The following tokens cover specialized scenarios. Most applications can rely on | Token | Value your application receives | | --- | --- | -| `{ownershipType}` | _To be documented._ | -| `{itemname-guid}` | _To be documented._ | -| `{folderpath-guids}` | _To be documented._ | +| `{ownershipType}` | | +| `{itemname-guid}` | | +| `{folderpath-guids}` | | ### Example @@ -90,13 +110,13 @@ If your container type has `urlTemplate` set to: 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: +When a user opens a `.txt` file, 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 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. +Your application receives the tenant ID, drive ID, and item ID as the values of whatever query-parameter names you defined in the template. The parameter names — `t`, `d`, and `i` in this example — are arbitrary and developer-defined; Microsoft 365 doesn't require any specific names. Use the parsed values to retrieve and open the file through the Microsoft Graph API. ### Update `urlTemplate` with Microsoft Graph @@ -131,7 +151,7 @@ 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. +1. Call Microsoft Graph with the drive ID and item ID values from the query string 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). @@ -140,7 +160,7 @@ For information about calling Microsoft Graph against a consuming tenant's conta | 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. | +| 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 supported viewer (the Office web viewer or the embed 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). | @@ -150,6 +170,10 @@ For information about calling Microsoft Graph against a consuming tenant's conta 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. +### Search results for already-indexed content require a recrawl + +Setting or updating `urlTemplate` takes effect immediately for Microsoft Graph API responses. However, search results for content that's already indexed continue to use the previously indexed destination until Microsoft 365 recrawls and reindexes that content. Today, there's no self-serve mechanism to trigger a recrawl. + ### `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. From be4ade11e60eb14412290c76ac6a6bb79a3b0c25 Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Mon, 8 Jun 2026 13:10:17 -0700 Subject: [PATCH 06/10] token definitions --- .../configure-redirect-behavior.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index 8764ca88b..23b4a0ab7 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -86,9 +86,9 @@ If Microsoft 365 can't resolve a token, it drops the entire query parameter that | `{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, Microsoft 365 drops the entire query parameter that contains `{folder-id}` from the redirect URL rather than passing it with an empty value. | | `{item-id}` | Item ID of the driveItem. Item IDs aren't GUIDs. | -| `{site-domain}` | | -| `{list-id}` | | -| `{site-url}` | | +| `{site-domain}` | | +| `{list-id}` | | +| `{site-url}` | | 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). @@ -98,9 +98,9 @@ The following tokens cover specialized scenarios. Most applications can rely on | Token | Value your application receives | | --- | --- | -| `{ownershipType}` | | -| `{itemname-guid}` | | -| `{folderpath-guids}` | | +| `{ownershipType}` | The container's ownership type: TenantOwned, UserOwned, GroupOwned, or ApplicationOwned | +| `{itemname-guid}` | The GUID parsed from the item's filename, if the file is named .extension. Empty if the filename is not a GUID. | +| `{folderpath-guids}` | Comma-separated GUIDs found in the folder path segments leading to the item. Path segments split on / or _ are each checked for a valid GUID | ### Example From 4a3ab7f6e0261121c13cb319e24e8c73ada29634 Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Mon, 8 Jun 2026 15:43:26 -0700 Subject: [PATCH 07/10] fix wrong use of canonical url --- .../content-experiences/configure-redirect-behavior.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index 23b4a0ab7..1b9570569 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -10,7 +10,7 @@ ms.localizationpriority: high The `urlTemplate` property on a SharePoint Embedded [container type](../../getting-started/containertypes.md) governs where Microsoft 365 sends users when they open files in your containers. It controls the destination on two surfaces: - Microsoft 365 search results. -- The `driveItem.webUrl` property returned by Microsoft Graph, which is the canonical URL apps consume to open an item. +- The `driveItem.webUrl` property is used to open an item in a browser. For files without a supported viewer (the Office web viewer or the embed viewer), both surfaces use `urlTemplate` to route users to your application. This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate`. From 9dfa02225ec0c7da5264c67c08314f9789e765cc Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Tue, 9 Jun 2026 16:59:19 -0700 Subject: [PATCH 08/10] Enhance token descriptions in redirect behavior documentation Updated descriptions for tokens related to redirect behavior and clarified the usage of custom properties in urlTemplate. --- .../content-experiences/configure-redirect-behavior.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index 1b9570569..55bf242df 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -86,11 +86,9 @@ If Microsoft 365 can't resolve a token, it drops the entire query parameter that | `{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, Microsoft 365 drops the entire query parameter that contains `{folder-id}` from the redirect URL rather than passing it with an empty value. | | `{item-id}` | Item ID of the driveItem. Item IDs aren't GUIDs. | -| `{site-domain}` | | -| `{list-id}` | | -| `{site-url}` | | - -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). +| `{site-domain}` | The hostname of the container's site (e.g., contoso.sharepoint.com). Sourced from SPSite.HostName. | +| `{list-id}` | The GUID identifier of the document library (SPList) that backs the container. | +| `{site-url}` | The container site's full web URL without the scheme (authority + path + query + fragment). For example: `contoso.sharepoint.com/contentstorage/CSP_6fa4ae51-5276-4437-b4f5-9b42388a9e1c` | #### Advanced tokens @@ -161,7 +159,7 @@ For information about calling Microsoft Graph against a consuming tenant's conta | --- | --- | | 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 supported viewer (the Office web viewer or the embed 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`. | +| 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](/graph/api/filestoragecontainer-post-customproperty). | | Updates to `urlTemplate` don't appear in search results. | Search index updates aren't instantaneous. See [Limitations](#limitations). | ## Limitations From 859ffb91318855fa3e8e0cab40e6458fe11457f7 Mon Sep 17 00:00:00 2001 From: Cindy Lay Date: Tue, 9 Jun 2026 17:32:11 -0700 Subject: [PATCH 09/10] Clarify urlTemplate permissions and discoverability; fix typos - Document both APIs that set urlTemplate (container type vs. registration) with their correct Graph permissions (FileStorageContainerType.Manage.All vs. FileStorageContainerTypeReg.Selected/.Manage.All) - Rewrite the discoverability note: clarify it's separate from redirect behavior, disabled by default, and that search still works via includeHiddenContent - Fix rendering bug (code-wrap .extension), add missing periods, align 'supported tokens' wording, remove internal type names and a stale TODO Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../configure-redirect-behavior.md | 31 ++++++++++++------- 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index 55bf242df..97f271917 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -18,9 +18,13 @@ For files without a supported viewer (the Office web viewer or the embed viewer) Before you configure `urlTemplate`, ensure you have: -- 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 — required only for the search-results scenario, so files in your containers appear in Microsoft 365 search results. The `driveItem.webUrl` redirect behavior doesn't depend on `isDiscoverabilityEnabled`. +- A SharePoint Embedded [container type](../../getting-started/containertypes.md) that you own, if you want to set `urlTemplate` for every tenant that registers the container type. To override `urlTemplate` for a single consuming tenant instead, you need a registration of that container type in the consuming tenant. +- The Microsoft Graph permission required by the API you call (see [Configure `urlTemplate`](#configure-urltemplate)): + - To set `urlTemplate` on the container type with [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update): `FileStorageContainerType.Manage.All` (delegated, work or school account). Application permissions aren't supported. + - To override `urlTemplate` on a registration with [Update fileStorageContainerTypeRegistration](/graph/api/filestoragecontainertyperegistration-update): `FileStorageContainerTypeReg.Selected` (least privileged; delegated or application) or `FileStorageContainerTypeReg.Manage.All` (delegated only). Delegated calls also require the SharePoint Embedded Administrator or Global Administrator role. + +> [!NOTE] +> Discoverability is separate from redirect behavior: you don't need to enable it to configure or use `urlTemplate`. The [`isDiscoverabilityEnabled`](/graph/api/resources/filestoragecontainertypesettings) setting is **disabled by default** and controls only whether your content is surfaced in the broader Microsoft 365 experience — such as **My Activity**, office.com, OneDrive.com, other intelligent file discovery features, and Copilot grounding. Leaving it disabled doesn't prevent search: applications can still query content in non-discoverable containers with the [Microsoft Search API](search-content) by setting `sharePointOneDriveOptions.includeHiddenContent` to `true`. To learn how discoverability affects Microsoft 365 surfaces, see [Content discovery in Microsoft 365](user-experiences-overview.md#content-discovery-in-microsoft-365). ## How Microsoft 365 chooses a destination @@ -39,8 +43,6 @@ The destination for a file depends on the file type and whether `urlTemplate` is | 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) | - - ### `driveItem.webUrl` behavior For SharePoint Embedded items, the `driveItem.webUrl` property returned by Microsoft Graph reflects the same redirect behavior described above: @@ -54,7 +56,12 @@ For SharePoint Embedded items, the `driveItem.webUrl` property returned by Micro ## 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 opens an item. +You can set `urlTemplate` in two places: + +- **On the container type**, which applies to every tenant that registers it. Call the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API (`PATCH /storage/fileStorage/containerTypes/{id}`) and set `settings.urlTemplate`. This requires the `FileStorageContainerType.Manage.All` delegated permission; application permissions aren't supported. +- **On a container type registration**, which overrides the value for a single consuming tenant. Call the [Update fileStorageContainerTypeRegistration](/graph/api/filestoragecontainertyperegistration-update) API (`PATCH /storage/fileStorage/containerTypeRegistrations/{id}`) and set `settings.urlTemplate`. This requires the `FileStorageContainerTypeReg.Selected` permission (least privileged; delegated or application) or `FileStorageContainerTypeReg.Manage.All` (delegated only). A registration can override `urlTemplate` only if the owning container type lists `urlTemplate` in its `consumingTenantOverridables` setting. + +The value is a URL with placeholder tokens that Microsoft 365 resolves to actual item identifiers when a user opens an item. The SharePoint Embedded PowerShell cmdlet exposes the same setting as a "redirect URI" parameter. The PowerShell "redirect URI" is the `urlTemplate` value and is unrelated to the app-registration redirect URI used for authentication. @@ -86,19 +93,19 @@ If Microsoft 365 can't resolve a token, it drops the entire query parameter that | `{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, Microsoft 365 drops the entire query parameter that contains `{folder-id}` from the redirect URL rather than passing it with an empty value. | | `{item-id}` | Item ID of the driveItem. Item IDs aren't GUIDs. | -| `{site-domain}` | The hostname of the container's site (e.g., contoso.sharepoint.com). Sourced from SPSite.HostName. | -| `{list-id}` | The GUID identifier of the document library (SPList) that backs the container. | +| `{site-domain}` | The hostname of the container's site (for example, contoso.sharepoint.com). | +| `{list-id}` | The GUID identifier of the document library that backs the container. | | `{site-url}` | The container site's full web URL without the scheme (authority + path + query + fragment). For example: `contoso.sharepoint.com/contentstorage/CSP_6fa4ae51-5276-4437-b4f5-9b42388a9e1c` | #### Advanced tokens -The following tokens cover specialized scenarios. Most applications can rely on the [common tokens](#supported-tokens) above. +The following tokens cover specialized scenarios. Most applications can rely on the [supported tokens](#supported-tokens) above. | Token | Value your application receives | | --- | --- | -| `{ownershipType}` | The container's ownership type: TenantOwned, UserOwned, GroupOwned, or ApplicationOwned | -| `{itemname-guid}` | The GUID parsed from the item's filename, if the file is named .extension. Empty if the filename is not a GUID. | -| `{folderpath-guids}` | Comma-separated GUIDs found in the folder path segments leading to the item. Path segments split on / or _ are each checked for a valid GUID | +| `{ownershipType}` | The container's ownership type: TenantOwned, UserOwned, GroupOwned, or ApplicationOwned. | +| `{itemname-guid}` | The GUID parsed from the item's filename, if the file is named `.extension`. Empty if the filename isn't a GUID. | +| `{folderpath-guids}` | Comma-separated GUIDs found in the folder path segments leading to the item. Path segments split on / or _ are each checked for a valid GUID. | ### Example From c92dc7e548d69fcc0c7184d3fdd9e511a3aa30d0 Mon Sep 17 00:00:00 2001 From: Andrew Connell Date: Wed, 10 Jun 2026 05:04:23 -0400 Subject: [PATCH 10/10] docs: fix Acrolinx findings - correct "embed viewer" to "embedded viewer" - replace em dashes with commas or parentheses --- .../configure-redirect-behavior.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/embedded/development/content-experiences/configure-redirect-behavior.md b/docs/embedded/development/content-experiences/configure-redirect-behavior.md index 97f271917..f7dbf01ad 100644 --- a/docs/embedded/development/content-experiences/configure-redirect-behavior.md +++ b/docs/embedded/development/content-experiences/configure-redirect-behavior.md @@ -12,7 +12,7 @@ The `urlTemplate` property on a SharePoint Embedded [container type](../../getti - Microsoft 365 search results. - The `driveItem.webUrl` property is used to open an item in a browser. -For files without a supported viewer (the Office web viewer or the embed viewer), both surfaces use `urlTemplate` to route users to your application. This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate`. +For files without a supported viewer (the Office web viewer or the embedded viewer), both surfaces use `urlTemplate` to route users to your application. This article explains how Microsoft 365 chooses a destination and how to configure `urlTemplate`. ## Prerequisites @@ -24,11 +24,11 @@ Before you configure `urlTemplate`, ensure you have: - To override `urlTemplate` on a registration with [Update fileStorageContainerTypeRegistration](/graph/api/filestoragecontainertyperegistration-update): `FileStorageContainerTypeReg.Selected` (least privileged; delegated or application) or `FileStorageContainerTypeReg.Manage.All` (delegated only). Delegated calls also require the SharePoint Embedded Administrator or Global Administrator role. > [!NOTE] -> Discoverability is separate from redirect behavior: you don't need to enable it to configure or use `urlTemplate`. The [`isDiscoverabilityEnabled`](/graph/api/resources/filestoragecontainertypesettings) setting is **disabled by default** and controls only whether your content is surfaced in the broader Microsoft 365 experience — such as **My Activity**, office.com, OneDrive.com, other intelligent file discovery features, and Copilot grounding. Leaving it disabled doesn't prevent search: applications can still query content in non-discoverable containers with the [Microsoft Search API](search-content) by setting `sharePointOneDriveOptions.includeHiddenContent` to `true`. To learn how discoverability affects Microsoft 365 surfaces, see [Content discovery in Microsoft 365](user-experiences-overview.md#content-discovery-in-microsoft-365). +> Discoverability is separate from redirect behavior: you don't need to enable it to configure or use `urlTemplate`. The [`isDiscoverabilityEnabled`](/graph/api/resources/filestoragecontainertypesettings) setting is **disabled by default** and controls only whether your content is surfaced in the broader Microsoft 365 experience, such as **My Activity**, office.com, OneDrive.com, other intelligent file discovery features, and Copilot grounding. Leaving it disabled doesn't prevent search: applications can still query content in non-discoverable containers with the [Microsoft Search API](search-content) by setting `sharePointOneDriveOptions.includeHiddenContent` to `true`. To learn how discoverability affects Microsoft 365 surfaces, see [Content discovery in Microsoft 365](user-experiences-overview.md#content-discovery-in-microsoft-365). ## How Microsoft 365 chooses a destination -Microsoft 365 chooses a destination based on the file type. `urlTemplate` applies only to files without a supported viewer (the Office web viewer or the embed viewer). This file-type scope is the same today and after the `webUrl` rollout described in [driveItem.webUrl behavior](#driveitemweburl-behavior). +Microsoft 365 chooses a destination based on the file type. `urlTemplate` applies only to files without a supported viewer (the Office web viewer or the embedded viewer). This file-type scope is the same today and after the `webUrl` rollout described in [driveItem.webUrl behavior](#driveitemweburl-behavior). If `urlTemplate` isn't configured, Microsoft 365 sends users who open files without a supported viewer to a generic [Microsoft help page](https://aka.ms/spe-openfilelocation). The help page explains that the file is stored in a third-party application and directs the user to open it there. @@ -39,7 +39,7 @@ The destination for a file depends on the file type and whether `urlTemplate` is | File type | `urlTemplate` set? | Behavior when opened | | --- | --- | --- | | Files with a supported Office web viewer (Word, Excel, PowerPoint, Visio, OneNote, and others) | Either | Opens in the corresponding Office web viewer | -| Files supported by the embed viewer | Either | Opens in the embed viewer | +| Files supported by the embedded viewer | Either | Opens in the embedded viewer | | 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) | @@ -121,7 +121,7 @@ When a user opens a `.txt` file, Microsoft 365 redirects the user to a URL like https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123def456ghi789jkl0&i=01ABC23DEF45GHI67JKL890 ``` -Your application receives the tenant ID, drive ID, and item ID as the values of whatever query-parameter names you defined in the template. The parameter names — `t`, `d`, and `i` in this example — are arbitrary and developer-defined; Microsoft 365 doesn't require any specific names. Use the parsed values to retrieve and open the file through the Microsoft Graph API. +Your application receives the tenant ID, drive ID, and item ID as the values of whatever query-parameter names you defined in the template. The parameter names (`t`, `d`, and `i` in this example) are arbitrary and developer-defined; Microsoft 365 doesn't require any specific names. Use the parsed values to retrieve and open the file through the Microsoft Graph API. ### Update `urlTemplate` with Microsoft Graph @@ -165,7 +165,7 @@ For information about calling Microsoft Graph against a consuming tenant's conta | 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 supported viewer (the Office web viewer or the embed viewer) instead of redirecting. | +| 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 supported viewer (the Office web viewer or the embedded 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](/graph/api/filestoragecontainer-post-customproperty). | | Updates to `urlTemplate` don't appear in search results. | Search index updates aren't instantaneous. See [Limitations](#limitations). |