Add new article Configure redirect behavior by cindylay · Pull Request #10868 · SharePoint/sp-dev-docs

cindylay · 2026-05-29T23:38:47Z

Related issues

Supersedes the urlTemplate content originally proposed in #10798. If this PR merges first, the URL template section in office-experience.md should be removed (or that PR retargeted).

What's in this Pull Request?

Adds a new standalone article documenting how to configure the urlTemplate setting on a
SharePoint Embedded container type. urlTemplate controls where Microsoft 365 redirects
users 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
urlTemplate is its own feature with its own permission model, validation rules, and
troubleshooting surface, so it's better served as a dedicated article.

Changes

New article: docs/embedded/development/content-experiences/configure-redirect-behavior.md
TOC: Added a "Configuring redirect behavior" entry under Development → Content Experiences, between Office Experiences and User Experiences.

What the article covers

Prerequisites — owning tenant access, the FileStorageContainerType.Manage.All delegated permission (application permissions aren't supported), and isDiscoverabilityEnabled = true.
How Microsoft 365 chooses a destination — the decision flow for click-throughs from search, including a file-type handling table (Office vs. PDF vs. other).
Configure urlTemplate — requirements, syntax, the full list of supported tokens with descriptions, an end-to-end example, a PATCH sample against Update fileStorageContainerType, and a GET to verify the value persisted.
What your application does when called — three-step runtime contract: authenticate the user, parse the token values, then call Microsoft Graph with driveId and itemId.
Troubleshooting — common symptoms (still routes to Office, value reverts to null, tokens appear literally) mapped to their causes.
Limitations — up-to-24-hour propagation window for setting changes; container-type scope.
Related content — links to the container types concept, the Update fileStorageContainerType API, the fileStorageContainerTypeSettings resource, custom container properties, and the SharePoint Embedded auth doc.

Style and editorial

Follows the Microsoft Learn style guide: sentence-case headings, active voice, present tense, contractions, Oxford commas, no "please / click / log in / just / simple".
One [!IMPORTANT] alert (within the 1–2 per article guidance).
All code identifiers in backticks; UI strings would be bold (none used).
Article description ~145 chars; H1 matches the title front-matter field.

learn-build-service-prod · 2026-05-29T23:39:49Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-05-29T23:40:50Z

Learn Build status updates of commit f2f0ebc:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/embedded/development/content-experiences/configure-redirect-behavior.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

For more details, please refer to the build report.

learn-build-service-prod · 2026-05-29T23:42:26Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-05-29T23:43:23Z

Learn Build status updates of commit be3dc67:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/embedded/development/content-experiences/configure-redirect-behavior.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

For more details, please refer to the build report.

Copilot

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.yml to 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-service-prod · 2026-05-29T23:49:50Z

Learn Build status updates of commit c3a5bb2:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/embedded/development/content-experiences/configure-redirect-behavior.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

For more details, please refer to the build report.

learn-build-service-prod · 2026-05-29T23:49:53Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

…oken-table updates Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

learn-build-service-prod · 2026-05-30T00:09:51Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-05-30T00:11:42Z

Learn Build status updates of commit 112fe95:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/embedded/development/content-experiences/configure-redirect-behavior.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

For more details, please refer to the build report.

learn-build-service-prod · 2026-05-30T00:12:05Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-05-30T00:14:19Z

Learn Build status updates of commit 181cc82:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/embedded/development/content-experiences/configure-redirect-behavior.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

For more details, please refer to the build report.

cindylay · 2026-06-01T17:14:32Z

awaiting review from internal folks

dluces · 2026-06-01T19:59:43Z

+
+# 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

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

learn-build-service-prod · 2026-06-02T11:00:58Z

Learn Build status updates of commit 7b44caf:

✅ Validation status: passed

File	Status	Preview URL	Details
docs/embedded/development/content-experiences/configure-redirect-behavior.md	✅Succeeded	View
docs/toc.yml	✅Succeeded	View

For more details, please refer to the build report.

learn-build-service-prod · 2026-06-02T11:01:00Z

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

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

This is good to go pending some token definitions

vhontovyy-MS · 2026-06-08T21:35:43Z

+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.


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).

andrewconnell · 2026-06-08T21:58:24Z

@cindylay said:

This is good to go pending some token definitions

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

ready to merge

cindylay requested a review from Copilot May 29, 2026 23:38

Copilot started reviewing on behalf of cindylay May 29, 2026 23:39 View session

Add new article Configure redirect behavior

be3dc67

cindylay force-pushed the cindylay/urltemplate branch from f2f0ebc to be3dc67 Compare May 29, 2026 23:41

Copilot AI reviewed May 29, 2026

View reviewed changes

Apply suggestions from code review

c3a5bb2

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

cindylay assigned cindylay and dluces May 29, 2026

cindylay and others added 2 commits May 29, 2026 17:06

fix tokens table

1092d09

Merge remote 'Apply suggestions from code review' commit with local t…

181cc82

…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 May 30, 2026 00:09

andrewconnell added the pr:in-review Actively reviewing pull request label Jun 1, 2026

andrewconnell self-assigned this Jun 1, 2026

andrewconnell self-requested a review June 1, 2026 09:43

dluces reviewed Jun 1, 2026

View reviewed changes

andrewconnell requested changes Jun 1, 2026

View reviewed changes

Comment thread docs/embedded/development/content-experiences/configure-redirect-behavior.md Outdated

andrewconnell added Needs: Author Feedback Awaiting response from the original poster of the issue. Marked as stale if no activity for 7 days. pr:do-not-merge Pull request not ready to be merged and removed pr:in-review Actively reviewing pull request labels Jun 1, 2026

docs: fix invalid relative link

7b44caf

andrewconnell self-requested a review June 2, 2026 11:00

andrewconnell approved these changes Jun 2, 2026

View reviewed changes

Cindy Lay and others added 2 commits June 8, 2026 13:02

token definitions

be4ade1

cindylay commented Jun 8, 2026

View reviewed changes

vhontovyy-MS reviewed Jun 8, 2026

View reviewed changes

andrewconnell self-requested a review June 8, 2026 21:57

cindylay marked this pull request as draft June 8, 2026 21:59

cindylay and others added 3 commits June 8, 2026 15:43

fix wrong use of canonical url

4a3ab7f

Enhance token descriptions in redirect behavior documentation

9dfa022

Updated descriptions for tokens related to redirect behavior and clarified the usage of custom properties in urlTemplate.

cindylay marked this pull request as ready for review June 10, 2026 00:33

cindylay removed pr:do-not-merge Pull request not ready to be merged pr:awaiting-peer-reviews Awaiting the requested reviewers to complete their review. labels Jun 10, 2026

cindylay commented Jun 10, 2026

View reviewed changes


		# 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.

Conversation

cindylay commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Category

Related issues

What's in this Pull Request?

Changes

What the article covers

Style and editorial

Uh oh!

learn-build-service-prod Bot commented May 29, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented May 29, 2026

✅ Validation status: passed

Uh oh!

learn-build-service-prod Bot commented May 29, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented May 29, 2026

✅ Validation status: passed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

learn-build-service-prod Bot commented May 29, 2026

✅ Validation status: passed

Uh oh!

learn-build-service-prod Bot commented May 29, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented May 30, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented May 30, 2026

✅ Validation status: passed

Uh oh!

learn-build-service-prod Bot commented May 30, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented May 30, 2026

✅ Validation status: passed

Uh oh!

cindylay commented Jun 1, 2026

Uh oh!

dluces Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

learn-build-service-prod Bot commented Jun 2, 2026

✅ Validation status: passed

Uh oh!

learn-build-service-prod Bot commented Jun 2, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

cindylay left a comment

Choose a reason for hiding this comment

Uh oh!

vhontovyy-MS Jun 8, 2026

Choose a reason for hiding this comment

Uh oh!

andrewconnell commented Jun 8, 2026

cindylay commented May 29, 2026 •

edited

Loading

dluces Jun 1, 2026 •

edited

Loading