Add new article Configure redirect behavior#10868
Conversation
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit f2f0ebc: ✅ Validation status: passed
For more details, please refer to the build report. |
cindylay
force-pushed
the
cindylay/urltemplate
branch
from
f2f0ebc to
be3dc67
Compare
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit be3dc67: ✅ Validation status: passed
For more details, please refer to the build report. |
There was a problem hiding this comment.
Pull request overview
Adds a new SharePoint Embedded documentation article describing how to configure fileStorageContainerType.settings.urlTemplate so Microsoft 365 search result click-throughs can redirect to an app-defined experience, and wires the article into the docs navigation.
Changes:
- Adds a new standalone article: Configuring redirect behavior (
configure-redirect-behavior.md). - Updates
docs/toc.ymlto include the new article under Development → Content Experiences.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/toc.yml | Adds a TOC entry pointing to the new redirect-behavior article. |
| docs/embedded/development/content-experiences/configure-redirect-behavior.md | New end-to-end guidance for configuring urlTemplate, including token reference, examples, troubleshooting, and limitations. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
Learn Build status updates of commit c3a5bb2: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
…oken-table updates Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
cindylay
force-pushed
the
cindylay/urltemplate
branch
from
112fe95 to
181cc82
Compare
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 112fe95: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 181cc82: ✅ Validation status: passed
For more details, please refer to the build report. |
|
awaiting review from internal folks |
|
|
||
| # 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. |
There was a problem hiding this comment.
When a user selects a SharePoint Embedded file in Microsoft 365 search results
Does this affect only search results or also the driveItem.webUrl property from API responses? I thought it was the latter.
For files without a built-in Microsoft 365 web viewer,
Weren't we going to close that gap so all files redirect to the redirectUrl and then the app would decide how to handle it? @cindylay
andrewconnell
added
Needs: Author Feedback
andrewconnell
added
pr:awaiting-peer-reviews
|
Learn Build status updates of commit 7b44caf: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
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.
cindylay
left a comment
cindylay
left a comment
There was a problem hiding this comment.
This is good to go pending some token definitions
| 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. |
There was a problem hiding this comment.
What does "which is the canonical URL" mean here?
A canonical URL in SPO terms would normally take the user to an AccessDenied page if the file is stored in an SPE container.
A "new" webUrl won't look like a canonical URL. Instead, it will either be WAC URL, an OneUp (Embed) Viewer URL, an app-specific urlTemplate-driven URL, or the aka.ms URL.
suggestion: ... to open an item in a browser.
webUrl is specifically designed to work in a web browser (for supported file types / container types / apps).
|
@cindylay said:
If so, can you remove the other human reviewers from the PR if you're ready for the final review + merge to prod? The presence of open requested reviews indicates to me that it's still in flight. Trying to avoid prematurely reviewing & publishing. |
Updated descriptions for tokens related to redirect behavior and clarified the usage of custom properties in urlTemplate.
- 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 <GUID>.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>
cindylay
removed
pr:do-not-merge
- correct "embed viewer" to "embedded viewer" - replace em dashes with commas or parentheses
andrewconnell
added
pr:ready-to-merge
Category
Related issues
urlTemplatecontent originally proposed in #10798. If this PR merges first, the URL template section inoffice-experience.mdshould be removed (or that PR retargeted).What's in this Pull Request?
Adds a new standalone article documenting how to configure the
urlTemplatesetting on aSharePoint Embedded container type.
urlTemplatecontrols where Microsoft 365 redirectsusers when they select a search result for content stored in a container — sending them to
the application's own UI instead of the default Office viewer.
This content previously lived in the Office Experiences article (PR #10798), but
urlTemplateis its own feature with its own permission model, validation rules, andtroubleshooting surface, so it's better served as a dedicated article.
Changes
docs/embedded/development/content-experiences/configure-redirect-behavior.mdWhat the article covers
FileStorageContainerType.Manage.Alldelegated permission (application permissions aren't supported), andisDiscoverabilityEnabled = true.urlTemplate— requirements, syntax, the full list of supported tokens with descriptions, an end-to-end example, aPATCHsample againstUpdate fileStorageContainerType, and aGETto verify the value persisted.driveIdanditemId.null, tokens appear literally) mapped to their causes.Update fileStorageContainerTypeAPI, thefileStorageContainerTypeSettingsresource, custom container properties, and the SharePoint Embedded auth doc.Style and editorial
[!IMPORTANT]alert (within the 1–2 per article guidance).titlefront-matter field.