Skip to content

Commit f2f0ebc

Browse files
author
cindylay
committed
Add new article Configure redirect behavior
1 parent e84462c commit f2f0ebc

2 files changed

Lines changed: 152 additions & 0 deletions

File tree

‎docs/embedded/development/content-experiences/configure-redirect-behavior.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
title: Configuring redirect behavior
3+
description: Configure the urlTemplate property on a SharePoint Embedded container type to route users from Microsoft 365 search results to your application.
4+
ms.date: 05/29/2026
5+
ms.localizationpriority: high
6+
---
7+
8+
# Configuring redirect behavior
9+
10+
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.
11+
12+
## Prerequisites
13+
14+
Before you configure `urlTemplate`, ensure you have:
15+
16+
- A SharePoint Embedded [container type](/sharepoint/dev/embedded/concepts/app-concepts/containertypes) that you own.
17+
- The Microsoft Graph permission `FileStorageContainerType.Manage.All` (delegated, work or school account). Application permissions aren't supported for [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update).
18+
- `isDiscoverabilityEnabled` set to `true` on your container type's settings, so files in your containers appear in Microsoft 365 search results.
19+
20+
## How Microsoft 365 chooses a destination for a search result
21+
22+
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.
23+
24+
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.
25+
26+
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.
27+
28+
### How file types are handled
29+
30+
The destination URL for a file in search results depends on the file type and whether `urlTemplate` is set:
31+
32+
| File type | `urlTemplate` set? | Behavior when selected from search |
33+
|---|---|---|
34+
| Files with a supported Microsoft 365 web viewer (Word, Excel, PowerPoint, Visio, OneNote, and others) | Either | Opens in the corresponding Microsoft 365 web viewer |
35+
| PDF | Either | Opens in the SharePoint Embedded PDF Previewer |
36+
| All other types | Yes | Redirected to your application through `urlTemplate` |
37+
| All other types | No | Redirected to a [Microsoft help page](https://aka.ms/spe-openfilelocation) |
38+
39+
## Configure `urlTemplate`
40+
41+
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.
42+
43+
### Requirements
44+
45+
The `urlTemplate` value must:
46+
47+
- Be a valid absolute URL that uses the `https://` scheme. HTTP URLs aren't accepted.
48+
- Not resolve to a loopback address, such as `localhost` or `127.0.0.1`.
49+
50+
> [!IMPORTANT]
51+
> 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).
52+
53+
### URL template syntax
54+
55+
```text
56+
https://app.contoso.com/open?tenant={tenant-id}&drive={drive-id}&item={item-id}
57+
```
58+
59+
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.
60+
61+
### Supported tokens
62+
63+
| Token | Value your application receives |
64+
|---|---|
65+
| `{tenant-id}` | GUID of the consuming tenant. Used to make tenant-scoped Microsoft Graph API calls. |
66+
| `{drive-id}` | Drive ID of the container. Use it with Microsoft Graph APIs to reference the container. |
67+
| `{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. |
68+
| `{item-id}` | Item ID of the driveItem. Item IDs aren't GUIDs. |
69+
70+
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).
71+
72+
### Example
73+
74+
If your container type has `urlTemplate` set to:
75+
76+
```text
77+
https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}
78+
```
79+
80+
When a user opens a `.txt` file from a search result, Microsoft 365 redirects the user to a URL like the following:
81+
82+
```text
83+
https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123def456ghi789jkl0&i=01ABC23DEF45GHI67JKL890
84+
```
85+
86+
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.
87+
88+
### Update `urlTemplate` with Microsoft Graph
89+
90+
Use the PATCH endpoint [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) to update `urlTemplate`:
91+
92+
```http
93+
PATCH https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}
94+
Content-Type: application/json
95+
96+
{
97+
"settings": {
98+
"urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}"
99+
}
100+
}
101+
```
102+
103+
To clear `urlTemplate`, set the property to `null` in the PATCH request body.
104+
105+
### Verify your configuration
106+
107+
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:
108+
109+
```http
110+
GET https://graph.microsoft.com/v1.0/storage/fileStorage/containerTypes/{containerTypeId}?$select=settings
111+
```
112+
113+
If the response shows `urlTemplate` as `null`, the URL you submitted didn't meet the [requirements](#requirements). Update the value and try again.
114+
115+
## What your application does when called
116+
117+
When Microsoft 365 routes a user to your application, your application must:
118+
119+
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.
120+
1. Parse the token values from the redirect URL query string.
121+
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.
122+
123+
For information about calling Microsoft Graph against a consuming tenant's containers, see [Authentication and authorization](../auth.md).
124+
125+
## Troubleshooting
126+
127+
| Symptom | Possible cause |
128+
|---|---|
129+
| 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. |
130+
| 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. |
131+
| 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`. |
132+
| Updates to `urlTemplate` don't appear in search results. | Search index updates aren't instantaneous. See [Limitations](#limitations). |
133+
134+
## Limitations
135+
136+
### Updates to `urlTemplate` aren't instantaneous
137+
138+
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.
139+
140+
### `urlTemplate` is scoped to the container type
141+
142+
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.
143+
144+
## Related content
145+
146+
- [Container types](/sharepoint/dev/embedded/concepts/app-concepts/containertypes)
147+
- [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update)
148+
- [fileStorageContainerTypeSettings](/graph/api/resources/filestoragecontainertypesettings)
149+
- [Add custom properties to a fileStorageContainer](/graph/api/filestoragecontainer-post-customproperty)
150+
- [Authentication and authorization](../auth.md)

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -620,6 +620,8 @@
620620
href: embedded/development/support-archival-of-containers.md
621621
- name: Office Experiences
622622
href: embedded/development/content-experiences/office-experience.md
623+
- name: Configuring redirect behavior
624+
href: embedded/development/content-experiences/configure-redirect-behavior.md
623625
- name: User Experiences
624626
href: embedded/development/content-experiences/user-experiences-overview.md
625627
- name: Search Content

0 commit comments

Comments
 (0)