Conversation
|
Learn Build status updates of commit 8b0a7bd: ❌ Validation status: errorsPlease follow instructions here which may help to resolve issue.
For more details, please refer to the build report. Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them. |
| # Office file experiences for SharePoint Embedded | ||
|
|
||
| Office file experiences for SharePoint Embedded platform will work in a similar manner to Microsoft 365 platform. | ||
| Office file experiences for the SharePoint Embedded platform work similarly to the Microsoft 365 platform. |
There was a problem hiding this comment.
I would recommend rephasing this to "Office files in SharePoint Embedded containers behave similarly to Office files stored in OneDrive and SharePoint sites."
| ## Opening Office documents from SharePoint Embedded | ||
|
|
||
| Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. AutoSave feature saves your files automatically as your user's work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. | ||
| Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. The AutoSave feature saves files automatically as your users work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. |
There was a problem hiding this comment.
I would recommend rephasing this to "Office documents in SharePoint Embedded apps can be opened and edited in Office for the web or in desktop Office applications for a richer experience. AutoSave is enabled by default, automatically saving changes to Word, Excel, and PowerPoint files as users work."
| Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. AutoSave feature saves your files automatically as your user's work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. | ||
| Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. The AutoSave feature saves files automatically as your users work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. | ||
|
|
||
| Documents stored in an archived container can’t be viewed or accessed. Applications must handle the archived state of the container by displaying an appropriate error message and guiding end users on the next steps to regain access, such as reactivating the container. |
There was a problem hiding this comment.
We should not use the word "activate" in this context. Activate carries a specific meaning in SPE land. An archived container is already activated.
I would recommend rephasing this to "Documents in archived containers can’t be accessed or viewed. Applications should handle this state by displaying an appropriate message and guiding users on how to unarchive the container before access attempts."
|
|
||
| ## View or restore a previous version of an Office document from SharePoint Embedded | ||
|
|
||
| Versioning is automatically enabled on each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Apps, that helps your users to see what changes have been made in a file, compare different versions, or restore the version you want. This is incredibly important to your users if a mistake was made, a previous version is preferred, or in multi-user coauthoring scenarios when your users are collaborating with others and someone makes changes your users didn't want in a file. |
There was a problem hiding this comment.
"Versioning is automatically enabled on each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Apps" is not true for CTs set versioningEnable to false.
There was a problem hiding this comment.
I would recommend rephasing this to "Versioning of Office documents are enabled via the isVersioningEnable container type configuration of your SharePoint Embedded application. This allows users to track changes, compare versions, and restore earlier versions when needed—whether to recover from mistakes, revert to a preferred version, or manage changes in collaborative scenarios."
| ## Collaborating on Office documents from SharePoint Embedded | ||
|
|
||
| It's simple for your users to collaborate on your SharePoint Embedded Application's Office documents – they can **Share documents** with specific peers or with people outside your organization by Creating a shareable link to use wherever needed, Send an email invitation or @mention in comments to tag someone for feedback and, **Collaborate in real time** by co-authoring in Office with SharePoint Embedded Applications. | ||
| It's simple for your users to collaborate on your SharePoint Embedded Application's Office documents – they can **Share documents** with specific peers or with people outside your organization by creating a shareable link to use wherever needed, sending an email invitation or @mention in comments to tag someone for feedback and, **Collaborate in real time** by co-authoring in Office with SharePoint Embedded Applications. |
There was a problem hiding this comment.
I would recommend rephasing this to "Users can share files with specific individuals or external users via links, email invitations, or @mentions in comments, and collaborate in real time through co-authoring in Office."
There was a problem hiding this comment.
It is a public facing doc. Do not describe a process or interaction as easy, simple, hard or challenging. Just explain the steps 1, 2, 3 to achieve outcome X.
|
|
||
| Share your SharePoint Embedded documents by sending an email invitation to specific people: | ||
|
|
||
| - Select Share, start typing the email addresses or contact names of people you want to share with. When you begin to enter info in the box, you can also choose a contact from the list that appears. |
There was a problem hiding this comment.
I would recommend rephasing this to "Select Share and start typing the email addresses or contact names of people you want to share with. You can choose contacts from the list that appears."
| - Select Share, start typing the email addresses or contact names of people you want to share with. When you begin to enter info in the box, you can also choose a contact from the list that appears. | ||
| - Include a message if you want and hit Send. | ||
|
|
||
| #### Create a shareable link |
There was a problem hiding this comment.
Rephase this to "Create a sharing link"
Sharing link is the name for the feature. Not shareable link
|
|
||
| #### Create a shareable link | ||
|
|
||
| Creating a shareable link makes it simple to share your SharePoint Embedded document in an email, document, or IM. |
There was a problem hiding this comment.
I recommend rephasing this to "SharePoint Embedded app users can share their files by sending a link." How they send the link is irrelevant.
|
|
||
| #### Co-Author | ||
|
|
||
| If you want others to edit with you, you can easily share files and collaborate with trusted peers for a fresh perspective. When you need help with a presentation, you can invite trusted peers to help you get it into shape. This means that when you work on a file, they can as well. You’ll see their changes and they’ll see yours—as you make them! Use @mentions in comments to get someone's attention. |
There was a problem hiding this comment.
I would recommend rephasing this to "Users can collaborate on Office files by sharing them with trusted peers. Shared files can be edited together in real time, with changes visible as they happen. @mentions in comments help bring others into the conversation for feedback."
|
|
||
| | If you want to … | Sharing Setting to Set | | ||
| | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Allow Anyone who receives the link access to SharePoint Embedded Application File | **Anyone** gives access to anyone who receives this link, whether they receive it directly from you or are forwarded from someone else. This might include people outside of your organization. | |
There was a problem hiding this comment.
We should standardize how we call the files here - we have in this article "Office documents from SharePoint Embedded", "SharePoint Embedded Application File", "SharePoint Embedded Application docs" to name a few.
"This might include people outside of your organization." contradicts an earlier line "Mentions exclude guests and users from other tenants in a multitenant setting."
| | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | Allow Anyone who receives the link access to SharePoint Embedded Application File | **Anyone** gives access to anyone who receives this link, whether they receive it directly from you or are forwarded from someone else. This might include people outside of your organization. | | ||
| | Allow anyone in your organization to access to your SharePoint Embedded Application File | **People in \<Your Organization\>** gives anyone in your organization who has the link access to the file, whether they receive it directly from you or forwarded from someone else. | | ||
| | Secure your SharePoint Embedded Application docs only to specific people. | When you need to prevent recipients from forwarding a shared link, use the **Specific People** permission. **Specific people** gives access only to the people you specify, although other people might already have access. If people forward the sharing invitation, only people who already have access to the item will be able to use the link. | |
There was a problem hiding this comment.
recommend rephasing "use the link" to "redeem the link"
|
|
||
| ## Breadcrumb properties on Office documents from SharePoint Embedded | ||
|
|
||
| Breadcrumb properties are used by Office clients to display breadcrumb-style elements within Office client UI that aid your users in associating Office files with your Application. |
There was a problem hiding this comment.
Does "Office clients" here mean Office Webapp or Desktop or both? Best clarify what "Office clients" mean up front.
| > [!NOTE] | ||
| > We recommend specifying 'Current Channel' to take advantage of Breadcrumb patterns and future enhancements to Office Apps. Learn more about [specifying update channels for Office Apps](/deployoffice/updates/overview-update-channels). | ||
|
|
||
| Breadcrumb patterns for SharePoint Embedded Application Apps are constructed from container properties configured for your Apps. The following diagram maps the container properties to breadcrumb presentation in Office clients: |
There was a problem hiding this comment.
I recommend rephasing this to "Breadcrumbs in SharePoint Embedded apps are derived from the corresponding container type configuration. The following diagram shows how these properties map to breadcrumb display in Office clients."
|
|
||
| ## Controlling where users land when opening SPE files from Microsoft 365 search | ||
|
|
||
| When users search for content on Microsoft 365 (for example, on Office.com or OneDrive), search results include files stored in SharePoint Embedded containers. Clicking a search result opens the file in an appropriate viewer. For file types without a built-in Microsoft viewer, the destination depends on whether your container type has a URL template configured. |
There was a problem hiding this comment.
I recommend rephasing this to "When users search across Microsoft 365 (such as on Office.com), results include files stored in SharePoint Embedded containers. Selecting a result opens the file in the appropriate viewer. For file types without a built-in Microsoft viewer, the destination depends on the container’s configured URL template."
You should also add a note that searchability across M365 is controlled by the container type configuration isDiscoverabilityDisabled.
|
|
||
| When users search for content on Microsoft 365 (for example, on Office.com or OneDrive), search results include files stored in SharePoint Embedded containers. Clicking a search result opens the file in an appropriate viewer. For file types without a built-in Microsoft viewer, the destination depends on whether your container type has a URL template configured. | ||
|
|
||
| The `urlTemplate` property on your container type lets you specify a URL pattern in your application that Microsoft 365 uses as the destination when a user clicks on one of your files stored in your containers in search results. Without it, users clicking non-Office, non-PDF files in search results are directed to a generic Microsoft help page rather than your application. |
There was a problem hiding this comment.
I recommend rephasing this to "The urlTemplate property on a container type specifies the URL pattern used by Microsoft 365 when users open files from search results. If no URL template is configured, users clicking non-Office and non-PDF files are directed to a generic Microsoft help page rather than your application."
|
|
||
| | File type | `urlTemplate` set? | Destination when clicked in search | | ||
| |---|---|---| | ||
| | Word, Excel, PowerPoint | Yes or No | Opens in Office Web Apps | |
There was a problem hiding this comment.
Rephase "Yes or No" to Either
| | File type | `urlTemplate` set? | Destination when clicked in search | | ||
| |---|---|---| | ||
| | Word, Excel, PowerPoint | Yes or No | Opens in Office Web Apps | | ||
| | PDF and other files supported by the embedded viewer | Yes or No | Opens in the embedded file viewer | |
There was a problem hiding this comment.
Rephase "Yes or No" to Either
What are "the other files supported by the embedded viewer"? I think we should provide a list of supported file formats supported by the embedded viewer. It currently reads as "PDF and something else" and we are not telling you what that something else is.
Should it be "other files" or "other file types"?
| |---|---|---| | ||
| | Word, Excel, PowerPoint | Yes or No | Opens in Office Web Apps | | ||
| | PDF and other files supported by the embedded viewer | Yes or No | Opens in the embedded file viewer | | ||
| | All other types (.txt, custom extensions, etc.) | Yes | Redirected to your application via the resolved `urlTemplate` | |
There was a problem hiding this comment.
"All other types (.txt, custom extensions, etc.)" I would recommend rephase this to "Txt files and all other file types, including custom extensions"
|
|
||
| ### Configuring `urlTemplate` | ||
|
|
||
| Set `urlTemplate` on your container type using the [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update) API. The value is a URL with placeholder tokens that Microsoft 365 resolves to actual item identifiers at the time a user clicks a search result. |
There was a problem hiding this comment.
I recommend rephasing this to "Set the urlTemplate property on your container type using the Update fileStorageContainerType API. This value defines a URL pattern with placeholder tokens that Microsoft 365 resolves to the appropriate item identifiers when a user selects a file from search results."
|
|
||
| You can also use container custom properties as tokens, as long as the custom property was created with `isPatternToken: true`. The token format is `{propertyName}` where `propertyName` is the key of the custom property. | ||
|
|
||
| For more information on custom property tokens, see [Custom properties on fileStorageContainers](/graph/api/filestoragecontainer-post-customproperty). |
There was a problem hiding this comment.
"For more information on custom property token" rephased to "For more information on custom properties".
"custom property tokens" is not a SPE supported entity.
| https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123...&i=01ABC... | ||
| ``` | ||
|
|
||
| Your application receives the tenant ID, drive ID, and item ID as query parameters and can use them to open the correct file using the Microsoft Graph Files API. |
There was a problem hiding this comment.
"Microsoft Graph Files API" - do we mean "Microsoft Graph driveItem APIs"?
|
|
||
| Your application receives the tenant ID, drive ID, and item ID as query parameters and can use them to open the correct file using the Microsoft Graph Files API. | ||
|
|
||
| #### Setting `urlTemplate` via the Graph API |
There was a problem hiding this comment.
"Setting urlTemplate via the Graph API" - remove "the"
| } | ||
| ``` | ||
|
|
||
| For the full reference, see [Update fileStorageContainerType](/graph/api/filestoragecontainertype-update). |
There was a problem hiding this comment.
"For the full reference" rephase to "For details on how to update fileStorageContainerType"
|
|
||
| ### Fallback behavior when `urlTemplate` is not set | ||
|
|
||
| If `urlTemplate` is not configured on your container type, users who click on non-Office, non-PDF files in Microsoft 365 search results are redirected to `https://aka.ms/spe-openfilelocation`. This page explains that the file is stored in a third-party application and that the user should open it there directly. |
There was a problem hiding this comment.
i recommend rephasing this to "If the urlTemplate property isn’t configured, users who select non-Office or non-PDF files in Microsoft 365 search results are redirected to a generic help page that explains the file is stored in a third-party application and should be opened there."
|
|
||
| #### Search index updates require a re-crawl | ||
|
|
||
| The destination URL for each file is stored in the Microsoft 365 search index when the file is crawled. If you configure or update `urlTemplate` after files have already been indexed, existing search results continue to route to the previous destination until those files are re-crawled. Microsoft 365 performs incremental crawls automatically, but there may be a delay before all files reflect the updated URL. |
There was a problem hiding this comment.
"The destination URL for each file is stored in the Microsoft 365 search index when the file is crawled." - drop "when the file is crawled"
There was a problem hiding this comment.
"If you configure or update urlTemplate after files have already been indexed, existing search results continue to route to the previous destination until those files are re-crawled. Microsoft 365 performs incremental crawls automatically, but there may be a delay before all files reflect the updated URL." rephase to "If you configure or update the urlTemplate after files have been indexed, search results will continue to use the previous destination until the index is updated. Microsoft 365 performs incremental index update automatically, but there may be a delay before updates are reflected."
|
|
||
| ### Limitations | ||
|
|
||
| #### Search index updates require a re-crawl |
There was a problem hiding this comment.
"Search index updates require a re-crawl" rephase to "Updates to the urlTemplate are not instantaneous"
There was a problem hiding this comment.
if we must use the word recrawl, use" recrawl" instead of "re-crawl." That is the word used across other articles.
| > Mentions require target users to [have an Microsoft 365 license assigned to them](../auth.md#mention-users-in-office-documents). | ||
| > Mentions require target users to [have a Microsoft 365 license assigned to them](../auth.md#mention-users-in-office-documents). | ||
| > | ||
| > Mentions are restricted to people inside the consuming tenant's organization. Mentions exclude guests and users from other tenants in a multitenant setting. |
There was a problem hiding this comment.
is it "Mentions" or "@mentions"?
|
|
||
| #### Custom property tokens require `isPatternToken: true` | ||
|
|
||
| Container custom properties are only eligible for use as URL tokens if they were created with `isPatternToken: true`. Properties without this flag cannot be used in the template. |
There was a problem hiding this comment.
"Container custom properties are only eligible for use as URL tokens if they were created with isPatternToken: true. " rephase to "Container custom properties can only be used as URL tokens if they were created with isPatternToken: true. "
There was a problem hiding this comment.
I think we need to explain if there is a way to update an existing custom property and set isPatternToken to true,
There was a problem hiding this comment.
Reading this article again, why is this subsection needed? Didnt we already talk about the token piece earlier in the article?
|
|
||
| #### `{folder-id}` reflects the item's immediate parent | ||
|
|
||
| For files at the root of the container, this token may not resolve and is removed from the final URL. Design your application to handle URLs where `{folder-id}` is absent. |
There was a problem hiding this comment.
"For files at the root of the container, this token may not resolve" - this is leaving room for misinterpretation as it also reads "the token may resolve" and we are suggesting folks to trial and error. If it indeed does not resolve, say so. If it resolves in some circumstances and does not in others, explain the circumstances.
|
|
||
| #### `urlTemplate` is scoped to the container type, not individual containers | ||
|
|
||
| The template applies to all containers of that type across all consuming tenants. Use the `{tenant-id}` token to route users to the correct tenant context within your application. |
There was a problem hiding this comment.
"The template applies to all containers of that type across all consuming tenants" rephase to "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 context within your application." drop the word "context".
|
|
||
| If `urlTemplate` is not configured on your container type, users who click on non-Office, non-PDF files in Microsoft 365 search results are redirected to `https://aka.ms/spe-openfilelocation`. This page explains that the file is stored in a third-party application and that the user should open it there directly. | ||
|
|
||
| If your application stores only Word, Excel, PowerPoint, and PDF files, you may not need to set `urlTemplate` at all. For applications that store any other file types, setting `urlTemplate` is strongly recommended to avoid users encountering this help page from search. |
There was a problem hiding this comment.
"If your application stores only Word, Excel, PowerPoint, and PDF files, you may not need to set urlTemplate at all." - lets avoid using may or may not, It suggests the need of it depends on the circumstances, and we need to explain the circumstances (which we are not doing in this article) or imply the partners to trial and error (which is bad).
There was a problem hiding this comment.
I actually dont think this line is needed at all. Wouldn't the table above suffice? Instead, if a section to talk about fallback is needed, we should just say 1) there is no fallback for WXP files, redirecting them to Office is the only option; 2) there is no fallback to PDF files, redirecting them to embedded viewer is the only option; and 3) non WXP and PDF files fallback to the help page if the urlTempalte is unset.
|
|
||
|  | ||
|
|
||
| ## Controlling where users land when opening SPE files from Microsoft 365 search |
There was a problem hiding this comment.
"SPE" - this is the first time using the acronym. Standard convention is to introduce the acronym along with its full name in the beginning of the article, as "SharePoint Embedded (SPE)", and then use SPE in the article as needed.
| | `{folder-id}` | ID of the item's immediate parent folder; may be absent for root-level files | | ||
| | `{item-id}` | ID of the file; combine with `{drive-id}` and the Graph Files API to open or retrieve the file | | ||
|
|
||
| You can also use container custom properties as tokens, as long as the custom property was created with `isPatternToken: true`. The token format is `{propertyName}` where `propertyName` is the key of the custom property. |
There was a problem hiding this comment.
"You can also use container custom properties as tokens, as long as the custom property was created with isPatternToken: true" rephase to "You can also use container custom properties as tokens, only if they were created with isPatternToken: true"
| https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id} | ||
| ``` | ||
|
|
||
| Then when a user clicks a `.txt` file in a search result, they are redirected to something like: |
There was a problem hiding this comment.
"Then when a user clicks a .txt file in a search result," rephase to "Then when a user opens a .txt file from search result,"
|
|
||
| | File type | `urlTemplate` set? | Destination when clicked in search | | ||
| |---|---|---| | ||
| | Word, Excel, PowerPoint | Yes or No | Opens in Office Web Apps | |
There was a problem hiding this comment.
"Word, Excel, PowerPoint" - what do they mean exactly? Word files can be docx, docm, etc. Excel can be xlsx, xlsm, xlsb, xls - would csv (which can be commonly opened on excel) be supported via this?
|
|
||
| ## Breadcrumb properties on Office documents from SharePoint Embedded | ||
|
|
||
| Breadcrumb properties are used by Office clients to display breadcrumb-style elements within Office client UI that aid your users in associating Office files with your Application. |
There was a problem hiding this comment.
"Breadcrumb properties are used by Office clients to display breadcrumb-style elements within Office client UI that aid your users in associating Office files with your Application" - I am unsure what "aid your users in associating Office files" means.
| ## Opening Office documents from SharePoint Embedded | ||
|
|
||
| Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. AutoSave feature saves your files automatically as your user's work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. | ||
| Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web or in the Office application for a richer viewing and editing experience. The AutoSave feature saves files automatically as your users work and is enabled for each Word, Excel, and PowerPoint file stored in your SharePoint Embedded Application Apps. |
There was a problem hiding this comment.
"Application" - I dont think application or the equivalent needs to be capitalized throughout the doc unless it is the first word in a sentence. Same for "Document" and "File".
"Application Apps" is redundant and should not be used. Please also standardize the usage of "application" vs "applications" vs "app" vs "apps", where applicable.
| If you want others to edit with you, you can easily share files and collaborate with trusted peers for a fresh perspective. When you need help with a presentation, you can invite trusted peers to help you get it into shape. This means that when you work on a file, they can as well. You’ll see their changes and they’ll see yours—as you make them! Use @mentions in comments to get someone's attention. | ||
|
|
||
| - See who else is in the document and where they're working. | ||
| - A presence indicator shows where someone is making changes. See any changes right as they're being made. |
There was a problem hiding this comment.
I think line 51 and 52 are unnecessary. It is standard Office experience as is.
|
|
||
| #### Levels of sharing access | ||
|
|
||
| There are different options for sharing SharePoint Embedded Application Office Documents from: |
There was a problem hiding this comment.
Rephase this to "Users can select who to share their Office documents in SPE containers with:"
| | Token | Value your app receives | | ||
| |---|---| | ||
| | `{tenant-id}` | ID of the consuming tenant; use to make tenant-scoped Graph API calls | | ||
| | `{drive-id}` | Drive ID of the container; use with the Graph Files API to reference the container | |
There was a problem hiding this comment.
I think "Graph Files API" is wrong. There is no Graph resource called Files.
| | `{tenant-id}` | ID of the consuming tenant; use to make tenant-scoped Graph API calls | | ||
| | `{drive-id}` | Drive ID of the container; use with the Graph Files API to reference the container | | ||
| | `{folder-id}` | ID of the item's immediate parent folder; may be absent for root-level files | | ||
| | `{item-id}` | ID of the file; combine with `{drive-id}` and the Graph Files API to open or retrieve the file | |
There was a problem hiding this comment.
I think "Graph Files API" is wrong. There is no Graph resource called Files.
| --- | ||
| title: Office Experiences | ||
| description: Overview of Office experiences with SharePoint Embedded content | ||
| ms.date: 06/18/2025 |
There was a problem hiding this comment.
Date needs to be updated
|
|
||
| ### How file types are handled | ||
|
|
||
| The destination URL for a file in search results depends on the file type, regardless of whether `urlTemplate` is set: |
There was a problem hiding this comment.
"regardless of whether urlTemplate is set" is not entirely true, is it?
There was a problem hiding this comment.
This should rephase as "Selecting SPE content from search results has different behaviors, dependent on the file type and the urlTemplate setting:"
|
|
||
| The destination URL for a file in search results depends on the file type, regardless of whether `urlTemplate` is set: | ||
|
|
||
| | File type | `urlTemplate` set? | Destination when clicked in search | |
There was a problem hiding this comment.
Rephase "Destination when clicked in search" to "Behavior"
| https://app.contoso.com/open?tenant={tenant-id}&drive={drive-id}&item={item-id} | ||
| ``` | ||
|
|
||
| Tokens are enclosed in curly braces and replaced with values for the specific item the user clicked. Any token that cannot be resolved is removed from the URL before the redirect occurs. |
There was a problem hiding this comment.
Rephase "clicked" to "selected"
|
|
||
| ### Fallback behavior when `urlTemplate` is not set | ||
|
|
||
| If `urlTemplate` is not configured on your container type, users who click on non-Office, non-PDF files in Microsoft 365 search results are redirected to `https://aka.ms/spe-openfilelocation`. This page explains that the file is stored in a third-party application and that the user should open it there directly. |
There was a problem hiding this comment.
"search results are redirected to https://aka.ms/spe-openfilelocation. This page explains that the file is stored in a third-party application and that the user should open it there directly." - is this true?
Currently "https://aka.ms/spe-openfilelocation" redirects to "https://learn.microsoft.com/en-us/sharepoint/dev/embedded/development/content-experiences/office-experience". I think a screenshot for https://aka.ms/spe-openfilelocation would be helpful here
| "settings": { | ||
| "urlTemplate": "https://app.contoso.com/open?t={tenant-id}&d={drive-id}&i={item-id}" | ||
| }, | ||
| "etag": "<etag-value>" |
There was a problem hiding this comment.
why do we need to include etag as part of the example?
| |---|---| | ||
| | `{tenant-id}` | ID of the consuming tenant; use to make tenant-scoped Graph API calls | | ||
| | `{drive-id}` | Drive ID of the container; use with the Graph Files API to reference the container | | ||
| | `{folder-id}` | ID of the item's immediate parent folder; may be absent for root-level files | |
There was a problem hiding this comment.
"May be absent" rephase to "unrequired"
| https://app.contoso.com/open?t=72f988bf-86f1-41af-91ab-2d7cd011db47&d=b%21abc123...&i=01ABC... | ||
| ``` | ||
|
|
||
| Your application receives the tenant ID, drive ID, and item ID as query parameters and can use them to open the correct file using the Microsoft Graph Files API. |
There was a problem hiding this comment.
"Your application receives the tenant ID, drive ID, and item ID as query parameters and can use them to open the correct file using the Microsoft Graph Files API." - I recommend rephasing this to "Your application receives a URL with the tenantId, driveId, and driveItemId populated and can call the Microsoft Graph driveItem APIs to open the file.
There was a problem hiding this comment.
One note on consistency - "tenant-id" vs "tenant ID" and the like. Please stick with one convention throughout. I recommend either "tenant-id" or "tenantId" but not "tenant ID". No space when we are referring to the variables.
|
|
||
| The destination URL for each file is stored in the Microsoft 365 search index when the file is crawled. If you configure or update `urlTemplate` after files have already been indexed, existing search results continue to route to the previous destination until those files are re-crawled. Microsoft 365 performs incremental crawls automatically, but there may be a delay before all files reflect the updated URL. | ||
|
|
||
| #### `urlTemplate` is scoped to the container type, not individual containers |
There was a problem hiding this comment.
you can drop "not individual containers"
| ## PDF Preview | ||
|
|
||
| SharePoint Embedded includes a PDF previewer that you can enhance with query parameters appended to the driveItem's `webUrl` property. To get `webUrl`, call the [driveItem GET API](/graph/api/driveitem-get), for example `GET /drives/{drive-id}/items/{item-id}?$select=webUrl`, and retrieve the `webUrl` field. | ||
| SharePoint Embedded includes a PDF previewer that you can enhance with query parameters appended to the driveItem's `webUrl` property. To get `webUrl`, call the [driveItem Graph endpoint](/graph/api/resources/driveitem) and retrieve the `webUrl` field. |
There was a problem hiding this comment.
" PDF previewer" - we referred to this as "embedded previewer" in the other article. Can we standardize the naming convention?
| SharePoint Embedded includes a PDF previewer that you can enhance with query parameters appended to the driveItem's `webUrl` property. To get `webUrl`, call the [driveItem GET API](/graph/api/driveitem-get), for example `GET /drives/{drive-id}/items/{item-id}?$select=webUrl`, and retrieve the `webUrl` field. | ||
| SharePoint Embedded includes a PDF previewer that you can enhance with query parameters appended to the driveItem's `webUrl` property. To get `webUrl`, call the [driveItem Graph endpoint](/graph/api/resources/driveitem) and retrieve the `webUrl` field. | ||
|
|
||
| The parameters are passed as a JSON-encoded `embed` query string: |
There was a problem hiding this comment.
"query string" - is this a query string or object? The next line refers to this as an object.
| @@ -1,7 +1,7 @@ | |||
| --- | |||
| title: File Previews | |||
| description: Preview SharePoint Embedded content | |||
There was a problem hiding this comment.
Is this article centered around PDF experience only?
2 participants
Category
What's in this Pull Request?
Documents URL template...
I can't find the
isPatternTokenin our .csdl only in internal docs so I don't know if it exists yet. Need to check with SPE team before documenting that. otherwise I'll have an accompanying Graph PR if we need to document it.