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.
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 restore access, such as unarchiving the container."
|
|
||
| ## 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.
This 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."
|
|
||
| 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 users can share their files by sending a link."
|
|
||
| #### 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 easily 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.
There was a problem hiding this comment.
"Application" - I dont think application needs to be capitalized throughout the doc. Please also standardize application vs applications vs app vs apps vs "Application apps", where applicable.
| > [!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"? 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 fileStorageContainerType updates"
|
|
||
| ### 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"
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.