diff --git a/assets/spfx/spfx-matrix.json b/assets/spfx/spfx-matrix.json index 8b2c1ec8d..66ddda059 100644 --- a/assets/spfx/spfx-matrix.json +++ b/assets/spfx/spfx-matrix.json @@ -1,4 +1,17 @@ [ + { + "spfx": "1.21.1", + "url": "https://learn.microsoft.com/sharepoint/dev/spfx/release-1.21.1", + "node": [ + "v22" + ], + "typescript": [ + "v5.3" + ], + "react": [ + "v17.0.1" + ] + }, { "spfx": "1.21.0", "url": "https://learn.microsoft.com/sharepoint/dev/spfx/release-1.21", diff --git a/docs/apis/export-amr-api.md b/docs/apis/export-amr-api.md index 82a13e719..fe7248b8f 100644 --- a/docs/apis/export-amr-api.md +++ b/docs/apis/export-amr-api.md @@ -1,7 +1,7 @@ --- title: "SharePoint Asynchronous Metadata Read (AMR) API Introduction" -description: This document is an overview on how to read metadata from SharePoint, targeted to SharePoint migration tool developers. -ms.date: 04/18/2024 +description: Overview how to read metadata from SharePoint, targeted to SharePoint migration tool developers. +ms.date: 07/23/2025 ms.author: ranren author: underreview manager: dapodean @@ -15,9 +15,9 @@ ms.collection: --- # SharePoint Asynchronous Metadata Read (AMR) API Introduction -The SharePoint Asynchronous Metadata Read (AMR) API asynchronously exports metadata from SharePoint and OneDrive. +The SharePoint Asynchronous Metadata Read (AMR) API enables the asynchronous export of metadata from SharePoint and OneDrive. -Use AMR API to export metadata from SharePoint, for incremental migration, and post-migration validation. +Use AMR API to export metadata from SharePoint for incremental migration and post-migration validation. AMR is designed exclusively for import scenarios. It exhibits poor scalability when handling requests for metadata, permissions, or versions. We can't provide performance assurances for AMR usage in data export scenarios, such as cross-tenant migrations. @@ -33,6 +33,11 @@ Export metadata from SharePoint in three steps: ### Provision the destination containers and the queue +> [!IMPORTANT] +> Use [GetMigrationJobProgress API](migration-job-progress-api-reference.md) to retrieve migration job status. +> +> Provisioning Azure Queues for migration job status tracking is no longer required. Deprecation of Azure Queues is planned for the second half of 2026. Until then, Azure Queues will remain available for status retrieval. + Use `ProvisionMigrationContainers` method to provision the containers. Check [Use Azure Blob Storage Containers and Azure Queues with Migration API](migration-azure.md) for details. You can also use your own containers and queues if needed. ### Use `CreateSPAsyncReadJob` method to start the export @@ -47,11 +52,16 @@ Check [AMR API Reference](amr-api-reference.md) for details. ### Checking status +> [!IMPORTANT] +> Use [GetMigrationJobProgress API](migration-job-progress-api-reference.md) to retrieve migration job status. +> +> Provisioning Azure Queues for migration job status tracking is no longer required. Deprecation of Azure Queues is planned for the second half of 2026. Until then, Azure Queues will remain available for status retrieval. + Check Azure Queue supplied for export status. Monitor events as listed in [Events](migration-events.md) for details. -AMR API exports metadata in the manifest container supplied, under folder named by `JobID`. Check [Manifest files](migration-manifest.md) for the format and validation of the metadata. +AMR API exports metadata in the manifest container supplied, under a folder named by `JobID`. Check [Manifest files](migration-manifest.md) for the format and validation of the metadata. -AMR API splits manifest package larger than 25 MB into multiple manifest files per request. +AMR API splits manifest packages larger than 25 MB into multiple manifest files per request. ## Best practice @@ -59,7 +69,7 @@ AMR API is powerful. Ensure good performance to achieve the scale for large migr ### Export security and permissions on top level if possible -Exporting security with `IncludeSecurity` consumes more resources and slows down the export. It's faster to export these metadata at upper-level folder first, then export the children without them. +Exporting security with `IncludeSecurity` consumes more resources and slows down the export. It's faster to export this metadata at the upper-level folder first, then export the children without them. ### Metadata export on a single item @@ -90,9 +100,9 @@ AMR API processes jobs through a queue mechanism with preconfigured workload man ### Lab-tested performance baseline -We tested the performance in lab setting. AMR API exported about 400 items per second for every 250-K objects, in the average case. The peak performance reached 700 items per second. +We tested the performance in a lab setting. AMR API exported about 400 items per second for every 250-K objects, in the average case. The peak performance reached 700 items per second. -There are multiple factors that affect the real-life performance. These factors include: +Multiple factors affect real-life performance. These factors include: - The number of items that are being exported - The way AMR API is implemented @@ -108,6 +118,6 @@ To ensure good user experiences for all Microsoft 365 customers, SharePoint uses ### Tenant-to-Tenant migrations -AMR isn't intended for scenario where contents from a SharePoint tenant are moved to another. This type of migration requires the use of many resource-heavy read options. The long processing time of these read options slows down the overall migration significantly. +AMR isn't intended for scenarios where contents from a SharePoint tenant are moved to another. This type of migration requires the use of many resource-heavy read options. The long processing time of these read options slows down the overall migration significantly. Microsoft provides no performance guarantee in this scenario. Use Graph or CSOM as needed. diff --git a/docs/apis/migration-api-overview.md b/docs/apis/migration-api-overview.md index 53abe345b..d09416b7e 100644 --- a/docs/apis/migration-api-overview.md +++ b/docs/apis/migration-api-overview.md @@ -1,7 +1,7 @@ --- title: "SharePoint Import Migration API" -description: "This article provides overview information on how to use the SharePoint Migration API." -ms.date: 07/03/2024 +description: "This article provides an overview of how to use the SharePoint Migration API." +ms.date: 07/16/2025 ms.author: ranren author: underreview manager: dapodean @@ -15,7 +15,7 @@ ms.collection: --- # SharePoint Migration API Introduction -The SharePoint Migration API imports contents into SharePoint at scale. It processes content and manifest packages as jobs in a queue. The API provides process status and logs, making it easy to monitor the progress of each migration job. +The SharePoint Migration API imports content into SharePoint at scale. It processes content and manifest packages as jobs in a queue. The API provides process status and logs, making it easy to monitor the progress of each migration job. Use Migration API to migrate content from file shares, SharePoint Server, and other cloud-based services. @@ -27,7 +27,7 @@ We applied quota on *Share with Me* items per user. Check [ShareWithMe event quo ### November 2024 -Migration API supports generating logs of all file-level events during migration to support auditing. +We enabled logging all file-level events during migration, such as file deletion, to support auditing. ### July 2024 @@ -47,6 +47,11 @@ Start a migration job with three steps. Check the guidance in each of the steps ### Provision the destination containers and the queue +> [!IMPORTANT] +> Use [GetMigrationJobProgress API](migration-job-progress-api-reference.md) to retrieve migration job status. +> +> Provisioning Azure Queues for migration job status tracking is no longer required. Deprecation is planned for the second half of 2026. Until then, Azure Queues will remain available for status retrieval. + Use the `ProvisionMigrationContainers` method to provision the containers. Check [Use Azure Blob Storage Containers and Azure Queues with Migration API](migration-azure.md) for details. You can also use your own containers and queues if needed. ### Prepare the content @@ -65,7 +70,10 @@ Check [Manifest files](migration-manifest.md) to see the detailed requirements. The `CreateMigrationJob` method creates a migration job, which is queued up for processing. Migration API manages the queue and returns status and logs. Use the `CreateMigrationEncrypted` method to migrate encrypted contents. Check [SharePoint Migration API Reference](migration-api-reference.md) for details. -Upon creation of a new migration job, Migration API returns the Job ID. Track the status of the import with the `GetMigrationJobStatus` method if needed, with the Azure Queue supplied. +> [!IMPORTANT] +> Use GetMigrationJobProgress API to track migration job status. + +Upon creation of a new migration job, Migration API returns the Job ID. Track the status of the import with [GetMigrationJobProgress API](migration-job-progress-api-reference.md). Migration API generates logs in the manifest container. Check the log entries for migration results. @@ -79,7 +87,7 @@ Migration generates workload to the SharePoint backend differently from end user Don't use user mode in your migration solution. Running migration in user mode triggers increased throttling, resulting in poor performance. -To learn more on how to register an app ID and how to implement app-based authentication, check [How to register an app ID](/azure/active-directory/develop/active-directory-v2-registration-portal) and [Microsoft Graph Auth guidance](/graph/auth). +To learn more about how to register an app ID and how to implement app-based authentication, check [How to register an app ID](/azure/active-directory/develop/active-directory-v2-registration-portal) and [Microsoft Graph Auth guidance](/graph/auth). ### Microsoft Entra ID Permissions @@ -88,17 +96,17 @@ Permissions and consent in the Azure Active Directory v1.0 endpoint](/azure/acti For SharePoint and OneDrive migration scenarios, follow the Microsoft Entra ID permission specification. -For migration tools that rely on end-user signed in and presence, use Delegated permission. +For migration tools that rely on end-user sign-in and presence, use Delegated permission. For service-based migration tools that run without a signed-in user present, such as applications that run as background services, use Application permission. ### App IDs -You can choose to share a single App ID to cover multiple migration solutions created or create individual App ID for each of the products. Make sure to register App IDs. Sharing App IDs doesn't affect performance or throttling. +You can choose to share a single App ID to cover multiple migration solutions created or create an individual App ID for each of the products. Make sure to register App IDs. Sharing App IDs doesn't affect performance or throttling. ### Keep destination SharePoint Site unactivated -To avoid migration issues, deactivate the target site for users until the migration completion. The source could remain active, allowing read and write to keep productivity. Switch users to the new SharePoint destination sites after migration completion. +To avoid migration issues, deactivate the target site for users until migration completion. The source could remain active, allowing read and write access to keep productivity. Switch users to the new SharePoint destination sites after migration completion. ## Performance diff --git a/docs/apis/migration-api-reference.md b/docs/apis/migration-api-reference.md index 25d87245b..0db09f400 100644 --- a/docs/apis/migration-api-reference.md +++ b/docs/apis/migration-api-reference.md @@ -1,7 +1,7 @@ --- title: "SharePoint Migration API Reference Guide" description: "This article provides in-depth information on how to use the SharePoint Migration API." -ms.date: 04/28/2024 +ms.date: 07/16/2025 ms.author: ranren author: underreview manager: dapodean @@ -172,6 +172,9 @@ See Return value in `CreateMigrationJob` method. ## GetMigrationJobStatus method +> [!IMPORTANT] +> Use [GetMigrationJobProgress API](migration-job-progress-api-reference.md) to retrieve migration job status. Deprecation of GetMigrationJobStatus API is planned for the second half of 2026. Until then, it will remain available for status retrieval. + Retrieves the processing status for a designated migration job. Migration API removes completed migration jobs from the timer job queue. Check the notification queue and/or log outputs for import results. diff --git a/docs/apis/migration-job-progress-api-reference.md b/docs/apis/migration-job-progress-api-reference.md new file mode 100644 index 000000000..d6f6eff66 --- /dev/null +++ b/docs/apis/migration-job-progress-api-reference.md @@ -0,0 +1,171 @@ +--- +title: "SharePoint Migration Job Progress API" +description: "This article explains how to retrieve migration job status with GetMigrationJobProgress API." +ms.date: 06/15/2025 +ms.author: jihongzuo +author: shiongzuo +manager: dapodean +audience: ISV +ms.subservice: migration-tool +ms.topic: article +ms.localizationpriority: high +ms.collection: + - SPMigration + - m365-collaboration +--- +# SharePoint GetMigrationJobProgress API + +After submitting a migration job—whether an import job or an Asynchronous Metadata Read (AMR) job—you can use the GetMigrationJobProgress API to track its progress. The API is available via both SDK and REST interfaces. + +It returns a sequence of job status events, including: JobQueued, JobStart, JobProgress, JobError, and JobEnd. + +## Permissions + +Use application-based authentication when submitting a migration job. Ensure the application is granted the Sites.Read.All permission or higher. + +## GetMigrationJobProgress Method (SDK) + +### Syntax + +```csharp +public ClientResult Site.GetMigrationJobProgress( + Guid jobId, + String nextToken +) +``` + +### Method Parameters + +| Name | Type | Required | Description | +| :--------- | :------- | :------- | :----------------------------------------------------- | +| jobId | Guid | Yes | Unique identifier of the migration job | +| nextToken | String | Yes | Token for paging position. Use "0" for initial request | + +For a completed job, requests using nextToken are idempotent—repeating the same request will consistently return the same result. + +### Return Values + +| Name | Type | Description | +| :--------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------ | +| Logs | IList | Returns a collection of job status events when new progress is available, or an empty collection if there are no updates. | +| NextToken | String | Returns an updated string value when new progress is available, or the same value as the nextToken parameter if there are no updates. | + +### Method Usage Example + +```csharp +ClientResult result = context.Site.GetMigrationJobProgress(jobId, nextToken ?? "0"); +context.ExecuteQuery(); +IList logs = result.Value.Logs; +string newNextToken = result.Value.NextToken; +``` + +## GetMigrationJobProgress REST API + +### HTTP Request + +```http +GET https://{site_url}/_api/site/GetMigrationJobProgress(jobId='{jobId}',nextToken=0) +``` + +### URI Parameters + +| Name | Type | Required | Description | +| :--------- | :------- | :------- | :----------------------------------------------------- | +| jobId | Guid | Yes | Unique identifier of the migration job | +| nextToken | String | Yes | Token for paging position. Use "0" for initial request | + +### Request Headers + +| Header | Required | +| :------------------------------------- | :------- | +| Authorization: Bearer {token} | Yes | +| Accept: application/json;odata=verbose | Yes | + +### Response + +A JSON object when the HTTP status code is 200. + +An empty JSON object when the HTTP status code is other than 200. + +### Error Handling + +| Status Code | Meaning | Action | +| :---------- | :------------- | :---------------------------------------------------------------------- | +| 403 | Unauthorized | Ensure the app/user has at least Sites.Read.All permissions. | +| 429 | Too Many Requests | Parse Retry-After header and retry after the specified delay. | +| 500 | Internal Server Error | Parse error responses to identify internal errors. Do Not Retry. | +| 503 | Service Unavailable | Parse Retry-After header and retry after the specified delay. | + +| Internal Error Code | Meaning | +| :------------------ | :---------------------------------------------- | +| -2147213145 | Job not found | +| -2147213146 | Job status expired (valid for less than 5 days) | + +### API Usage Example + +#### Request Sample + +```http +GET https://contoso.sharepoint.com/_api/site/GetMigrationJobProgress(jobId=' 3e280efa-78a3-4ba1-bac6-e447aa538ca5', nextToken=0) +``` + +#### Successful Response Sample + +Status code: 200 +Response body: + +```json +{ + "d": { + "GetMigrationJobProgress": { + "Logs": { + "__metadata": { + "type": "Collection(Edm.String)" + }, + "results": [ + "{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"SiteId\":\"48f1898f-77d9-4a1b-bddc-1f49bb6dc134\",\"DbId\":\"de6b85cd-726e-4b13-ae04-629798fddbf3\",\"TotalRetryCount\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:18:48.132\",\"CorrelationId\":\"91884a0c-5ee8-4e1f-a23f-e4f7ec170182\",\"Event\":\"JobQueued\"}", + "{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"SiteId\":\"48f1898f-77d9-4a1b-bddc-1f49bb6dc134\",\"WebId\":\"7206fc09-e4af-48b3-8730-ed7321396d7a\",\"DbId\":\"de6b85cd-726e-4b13-ae04-629798fddbf3\",\"FarmId\":\"f77d7b6c-ef43-4609-8fce-0e93142ce8a0\",\"ServerId\":\"44af885c-393b-4236-9417-bae7a9edc44e\",\"SubscriptionId\":\"82abb045-250e-4186-ba83-b9295930f272\",\"TotalRetryCount\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:51.129\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobStart\"}", + "{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"TotalRetryCount\":\"0\",\"ObjectType\":\"ListItem\",\"Url\":\"\",\"Id\":\"cb471d5f-593f-4a63-b59e-8eae3e35b08a\",\"SourceListItemIntId\":\"3\",\"TargetListItemIntId\":\"3\",\"ErrorCode\":\"-2147286782\",\"ErrorType\":\"Microsoft.SharePoint.SPException\",\"Message\":\"Attempted to use an object that has ceased to exist. (Exception from HRESULT: 0x80030102 (STG_E_REVERTED)) \",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:55.490\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobError\"}", + "{\"MigrationType\":\"None\",\"MigrationDirection\":\"Import\",\"TotalRetryCount\":\"0\",\"FilesCreated\":\"0\",\"BytesProcessed\":\"0\",\"ObjectsProcessed\":\"4\",\"TotalExpectedSPObjects\":\"15\",\"TotalErrors\":\"3\",\"TotalWarnings\":\"0\",\"WaitTimeOnSqlThrottlingMilliseconds\":\"0\",\"TotalDurationInMs\":\"0\",\"CpuDurationInMs\":\"0\",\"SqlDurationInMs\":\"0\",\"SqlQueryCount\":\"0\",\"IsShallowCopy\":\"False\",\"CreatedOrUpdatedFileStatsBySize\":\"{}\",\"ObjectsStatsByType\":\"{\\\"SPUser\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":124,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPFolder\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":153,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPDocumentLibrary\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":404,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPFile\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":0,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0},\\\"SPListItem\\\":{\\\"Count\\\":1,\\\"TotalTime\\\":1880,\\\"AccumulatedVersions\\\":0,\\\"ObjectsWithVersions\\\":0}}\",\"TotalExpectedBytes\":\"0\",\"FilesCreatedIrrespectiveOfVersions\":\"0\",\"BytesProcessedOnlyCurrentVersion\":\"0\",\"JobId\":\"3e280efa-78a3-4ba1-bac6-e447aa538ca5\",\"Time\":\"05/20/2025 09:20:57.380\",\"CorrelationId\":\"7d3e7a8e-4445-4ce0-adb1-078e78cbf686\",\"Event\":\"JobEnd\"}" + ] + }, + "NextToken": "1764", + "__metadata": { + "type": "SP.MigrationJobProgress" + } + } + } +} +``` + +#### Error Response Sample + +Status code: 500 +Response body: + +```json +{ + "error": { + "code": "-2147213145, Microsoft.SharePoint.SPException", + "innererror": { + "message": "Job not found", + "stacktrace": "STACK_TRACE" + }, + "message": { + "lang": "en-US", + "value": "Job not found" + } + } +} +``` + +## Best Practice + +Begin with `nextToken=0`, store the returned token, and poll at certain intervals. This method is well-suited for long-running jobs and helps ensure no updates are missed. + +Since migration jobs typically take several minutes or more, polling every minute is advised, while adhering to the [guideline](https://aka.ms/spo429) to avoid throttling. + +## See Also + +- [SharePoint Migration API](migration-api-overview.md) +- [Migration Events](migration-events.md) diff --git a/docs/apis/syntex/syntex-model-rest-api.md b/docs/apis/syntex/syntex-model-rest-api.md index 746de3421..277c633dd 100644 --- a/docs/apis/syntex/syntex-model-rest-api.md +++ b/docs/apis/syntex/syntex-model-rest-api.md @@ -1,7 +1,7 @@ --- -title: Microsoft Syntex document understanding model REST API -description: Overview of the Microsoft Syntex document understanding model REST API. -ms.date: 10/20/2022 +title: Unstructured document understanding model REST API +description: Overview of the document understanding model REST API. +ms.date: 07/21/2025 ms.author: chucked author: chuckedmonson manager: pamgreen @@ -12,7 +12,7 @@ ms.collection: m365initiative-syntex ms.localizationpriority: medium --- -# Microsoft Syntex unstructured document processing model REST API +# Unstructured document processing model REST API You can use the SharePoint REST interface to create an unstructured document processing model, apply or remove the model to one or more libraries, and obtain or update information about the model. @@ -29,14 +29,14 @@ Before you get started, make sure that you're familiar with the following: ## REST commands -The following REST commands are available for working with Syntex unstructured document processing models: +The following REST commands are available for working with unstructured document processing models: - [Create model](rest-createmodel-method.md) – Creates a model and its associated content type. -- [GetByUniqueId](rest-getbyuniqueid-method.md) – Gets or updates information about a Syntex unstructured document processing model. -- [GetByTitle](rest-getbytitle-method.md) – Gets or updates information about a Syntex unstructured document processing model using the model title. +- [GetByUniqueId](rest-getbyuniqueid-method.md) – Gets or updates information about an unstructured document processing model. +- [GetByTitle](rest-getbytitle-method.md) – Gets or updates information about an unstructured document processing model using the model title. - [Apply model](rest-applymodel-method.md) – Applies (or syncs) a trained unstructured document processing model to one or more libraries. - [Get model and library information](rest-getmodelandlibraryinfo.md) – Gets information about a model and the library where it has been applied. -- [UpdateModelSettings](rest-updatemodelsettings-method.md) – Updates available models settings (associated retention label and model description) for a Syntex unstructured document processing model. +- [UpdateModelSettings](rest-updatemodelsettings-method.md) – Updates available models settings (associated retention label and model description) for an unstructured document processing model. - [BatchDelete](rest-batchdelete-method.md) – Removes an applied unstructured document processing model from one or more libraries. - [Create file classification request](rest-createclassificationrequest.md) – Creates a request to classify a specified file or files using the applied model. - [Create folder classification request](rest-createclassificationrequest.md) – Creates a request to classify an entire folder using the applied model. diff --git a/docs/apis/webhooks/sharepoint-webhooks-using-azd-template.md b/docs/apis/webhooks/sharepoint-webhooks-using-azd-template.md index 838fa9f1e..1de5d665e 100644 --- a/docs/apis/webhooks/sharepoint-webhooks-using-azd-template.md +++ b/docs/apis/webhooks/sharepoint-webhooks-using-azd-template.md @@ -2,7 +2,7 @@ title: Create Azure Functions for SharePoint webhooks using an azd template description: Use Azure Developer cli (azd) to deploy an Azure function app that connects to your SharePoint Online tenant, to register and manage webhooks, and process the notifications from SharePoint. -ms.date: 03/11/2025 +ms.date: 07/07/2025 ms.localizationpriority: low --- # Azure Functions for SharePoint webhooks using azd @@ -13,7 +13,7 @@ This article uses the [Azure function app for SharePoint webhooks public templat ## Prerequisites -- [Node.js 20](https://www.nodejs.org/) +- [Node.js 22](https://www.nodejs.org/) - [Azure Functions Core Tools](/azure/azure-functions/functions-run-local) - [Azure Developer CLI (azd)](/azure/developer/azure-developer-cli/install-azd) - An Azure subscription that trusts the same Microsoft Entra ID directory as the SharePoint tenant diff --git a/docs/business-apps/power-automate/guidance/require-doc-approval.md b/docs/business-apps/power-automate/guidance/require-doc-approval.md index 3dd73b2d9..c5c548834 100644 --- a/docs/business-apps/power-automate/guidance/require-doc-approval.md +++ b/docs/business-apps/power-automate/guidance/require-doc-approval.md @@ -84,10 +84,10 @@ You must ensure you enter the correct site and library name. However, you can ge - Using the *Id* property from the *trigger output* - Comments - Using the *comments* property from the *approval response* - - ETAG -- Using the *ETag* property from the *Get file metadata* action output +- ETAG + - Using the *ETag* property from the *Get file metadata* action output -You can now use the content approval status action to approve and reject the document based on the approval response. +You can now use the content approval status action to approve or reject the document based on the approval response. The end result is that: diff --git a/docs/declarative-customization/formatting-advanced.md b/docs/declarative-customization/formatting-advanced.md index ad197c1d9..5a4d79813 100644 --- a/docs/declarative-customization/formatting-advanced.md +++ b/docs/declarative-customization/formatting-advanced.md @@ -1,12 +1,12 @@ --- title: Advanced formatting concepts description: Advanced formatting concepts -ms.date: 08/24/2022 +ms.date: 07/16/2025 ms.localizationpriority: high --- # Advanced formatting concepts -You can use some of the following features to make your view and column formatting more information rich and interactable. +You can use some of the following features to make your view and column formatting more information-rich and interactive. ## Create a button to launch a Flow @@ -14,7 +14,7 @@ The following screenshot shows a list with a Flow button added to the Action col ![screenshot of the sample](../images/sp-columnformatting-flow.png) -You can use column formatting to create buttons that, when selected, run Flows on the corresponding list item. For flows that are [solution-aware](/power-automate/overview-solution-flows), the Flow Launch Panel will be displayed after choosing the button and you must select Run Flow to start the flow. For flows that aren't solution-aware, The Flow Launch Panel will be displayed after choosing the button and the Flow will just run. +You can use column formatting to create buttons that, when selected, run Flows on the corresponding list item. For flows that are [solution-aware](/power-automate/overview-solution-flows), the Flow Launch Panel will be displayed after choosing the button, and you must select Run Flow to start the flow. For flows that aren't solution-aware, the Flow Launch Panel will be displayed after selecting the button, and the Flow will just run. To use the sample below, you must substitute the ID of the Flow you want to run. This ID is contained within the `actionParams` property of the `customRowAction` attribute inside the `button` element. @@ -30,43 +30,44 @@ To obtain the ID of a flow that is solution-aware: To obtain the ID of a flow that isn't solution-aware: -1. Select **Flow > See your flows** in the SharePoint list where the Flow is configured. +1. Switch to the environment in which the Flow is hosted. 1. Select the Flow you want to run. -1. Copy the ID from the end of the URL. +1. Select Export > Get flow identifier. +1. Copy the ID. -```JSON -{ - "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json", - "elmType": "button", - "customRowAction": { - "action": "executeFlow", - "actionParams": "{\"id\": \"edf627d9-20f4-45ba-8bc9-4494bf2ff1be\"}" - }, - "attributes": { - "class": "ms-fontColor-themePrimary ms-fontColor-themeDarker--hover" - }, - "style": { - "border": "none", - "background-color": "transparent", - "cursor": "pointer" - }, - "children": [ + ```JSON { - "elmType": "span", + "$schema": "https://developer.microsoft.com/json-schemas/sp/v2/column-formatting.schema.json", + "elmType": "button", + "customRowAction": { + "action": "executeFlow", + "actionParams": "{\"id\": \"edf627d9-20f4-45ba-8bc9-4494bf2ff1be\"}" + }, "attributes": { - "iconName": "Flow" + "class": "ms-fontColor-themePrimary ms-fontColor-themeDarker--hover" }, "style": { - "padding-right": "6px" - } - }, - { - "elmType": "span", - "txtContent": "Send to Manager" + "border": "none", + "background-color": "transparent", + "cursor": "pointer" + }, + "children": [ + { + "elmType": "span", + "attributes": { + "iconName": "Flow" + }, + "style": { + "padding-right": "6px" + } + }, + { + "elmType": "span", + "txtContent": "Send to Manager" + } + ] } - ] -} -``` + ``` Additionally, you can use `headerText` and `runFlowButtonText` options within the `actionParams` property to customize portions of the Flow panel itself! See the [button elements](./formatting-syntax-reference.md#customrowaction) portion of the Detailed syntax reference for more details. @@ -82,9 +83,9 @@ On hover - Metadata on the column "Status" is made available in column formattin ![Preview Image 2](../images/HoverImage-2.png) -You can use formatting to define custom call out that can be commissioned basis user-defined actions like click or hover. +You can use formatting to define a custom callout that can be commissioned user-defined basis, actions like click or hover. -This example uses `customCardProps`, `openOnEvent`, `directionalHint` and `isBeakVisible`: +This example uses `customCardProps`, `openOnEvent`, `directionalHint`, and `isBeakVisible`: ```JSON { @@ -110,20 +111,20 @@ This example uses `customCardProps`, `openOnEvent`, `directionalHint` and `isBea ## Default cards on hover -Users can now have profile card or file hover card on formatters too, some of the things users can now do: +Users can now have a profile card or a file hover card on formatters too. Some of the things users can now do: -1. Profile card or File Hover card on any column -1. Profile card or Hover card with view formatting +- Profile card or File Hover card on any column +- Profile card or Hover card with view formatting -Hover on a filename with formatting with default file card: +Hover on a filename with formatting with the default file card: ![Preview Image 3](../images/HoverImage-3.png) -Hover on a person column with formatting with default Profile card: +Hover on a person column with formatting with the default Profile card: ![Preview Image 4](../images/HoverImage-4.png) -Both the example uses defaultHoverField +This example uses `defaultHoverField`: ```JSON { @@ -257,9 +258,9 @@ The following image shows a list with a Gallery layout referencing the Category ## Inline Editing With inline editing, formatters have the ability to load field editors to edit field data on an item. -Users need to have edit permissions on the list item and the field type should belong to set of supported types for this feature to work. +Users need to have edit permissions on the list item, and the field type should belong to a set of supported types for this feature to work. -A special json property `inlineEditField` is used with value as the field internal name __`[$FieldName]`__ at the target element in the json. +A special JSON property `inlineEditField` is used with value as the field internal name __`[$FieldName]`__ at the target element in the JSON. ```json { @@ -287,7 +288,7 @@ List of supported field types for inline editing: ### Hover Borders and Customizations -The inline editing adds a hover border on the elements to indicate these elements have an associated action. The default border is `neutralSecondary`, and on click, the editor appears with a `themePrimary` border. These border colors can be overridden via setting style on the same element with `inlineEditField` by using some special attributes - `--inline-editor-border-width`, `--inline-editor-border-style`, `--inline-editor-border-radius`, and `--inline-editor-border-color`. +The inline editing adds a hover border on the elements to indicate that these elements have an associated action. The default border is `neutralSecondary`, and on click, the editor appears with a `themePrimary` border. These border colors can be overridden via setting style on the same element with `inlineEditField` by using some special attributes - `--inline-editor-border-width`, `--inline-editor-border-style`, `--inline-editor-border-radius`, and `--inline-editor-border-color`. ```json { @@ -307,7 +308,7 @@ The inline editing adds a hover border on the elements to indicate these element With the new `setValue` and `customRowAction` properties, formatters can render action buttons that modify the item internally without opening editors or forms. `setValue` also allows setting multiple field values of the item at once. -The below JSON will set value of `FieldInternalName_1`, `FieldInternalName_2`, and `FieldInternalName_3`with the values provided: +The below JSON will set the value of `FieldInternalName_1`, `FieldInternalName_2`, and `FieldInternalName_3`with the values provided: ```json { @@ -361,15 +362,15 @@ The below JSON will set value of `FieldInternalName_1`, `FieldInternalName_2`, a - `addDays` and `addMinutes`, two new functions to support [expressions](./formatting-syntax-reference.md#expressions) like seven days from today - an empty string `""` clears the field value - Multi-Choice and Multi-Person: - - Multi value fields are special, as they need an array value to save multiple values. + - Multi-value fields are special, as they need an array value to save multiple values. - `appendTo`, `removeFrom`, and `replace`, three functions that can operate on multivalue fields. - `appendTo([$MultiChoiceField], 'MyValue')` - `removeFrom([$MultiUserField], @me)`: removes all occurrences that match the second parameter - - `replace([$MultiChoiceField], 'Choice 1', 'Choice 3')`: replaces all occurrences of second parameter with third. + - `replace([$MultiChoiceField], 'Choice 1', 'Choice 3')`: replaces all occurrences of the second parameter with the third. - Person field values: - user name or email - An empty string `""` clears the field value - an [expression](./formatting-syntax-reference.md#expressions) which returns these values - > [!NOTE] - > A query runs with the string value provided on people column and the first person in the returned results is used. + > [!NOTE] + > A query runs with the string value provided on the people column, and the first person in the returned results is used. diff --git a/docs/declarative-customization/formatting-syntax-reference.md b/docs/declarative-customization/formatting-syntax-reference.md index da8ed5d22..bf3f244cf 100644 --- a/docs/declarative-customization/formatting-syntax-reference.md +++ b/docs/declarative-customization/formatting-syntax-reference.md @@ -53,6 +53,9 @@ An optional property that specifies the text content of the element specified by An optional property that specifies style attributes to apply to the element specified by `elmType`. This is an object with name-value pairs that correspond to CSS names and values. The values of each property in the style object can either be a string (including special strings) or an Expression object. The following style attributes are allowed. +> [!CAUTION] +> Float style prop no longer supported in custom formatter. Users are encouraged to use Gallery View as a more stable alternative. + ```javascript 'background-color' 'fill' @@ -163,7 +166,7 @@ An optional property that specifies style attributes to apply to the element spe 'clear' 'clip' 'display' -'float' +'float' (Deprecated) 'left' 'overflow' 'position' diff --git a/docs/declarative-customization/list-form-conditional-show-hide.md b/docs/declarative-customization/list-form-conditional-show-hide.md index 2df4a772d..1d4afe455 100644 --- a/docs/declarative-customization/list-form-conditional-show-hide.md +++ b/docs/declarative-customization/list-form-conditional-show-hide.md @@ -1,7 +1,7 @@ --- title: Show or hide columns in a list form description: Customize which columns to show or hide using a conditional formula in the list form by constructing a simple formula that are equations performing conditional checks on values in a SharePoint list or library. -ms.date: 04/03/2025 +ms.date: 07/28/2025 ms.localizationpriority: high --- @@ -58,7 +58,7 @@ For example, the following formula checks if the value for the *Category* column Returning _true_ shows the column on the form while returning _false_ hides the column. -The column is represented by specifying the **internal name** of the field surrounded by square brackets and preceded by a dollar sign: `[$InternalName]`. For example, to get the value of a field with an internal name of "ProductName", use `[$ProductName]`. +The column is represented by specifying the **internal name** of the field preceded by a dollar sign and surrounded by square brackets: `[$InternalName]`. For example, to get the value of a field with an internal name of "ProductName", use `[$ProductName]`. #### Unsupported column types in conditional formulas diff --git a/docs/declarative-customization/view-commandbar-formatting.md b/docs/declarative-customization/view-commandbar-formatting.md index 1cd0b5675..f7f56e8e3 100644 --- a/docs/declarative-customization/view-commandbar-formatting.md +++ b/docs/declarative-customization/view-commandbar-formatting.md @@ -1,13 +1,13 @@ --- title: Command bar customization syntax reference description: Command bar customization syntax reference -ms.date: 03/14/2025 +ms.date: 05/21/2025 ms.localizationpriority: high --- # Command bar customization syntax reference -Command bar customization helps personalize a list to suit specific requirements. The JSON based feature allows basic changes to the command bar, including modification of icon and/or text, hiding existing options or repositioning commands. +Command bar customization helps personalize a list to suit specific requirements. The JSON-based feature allows basic changes to the command bar, including modification of icon and/or text, hiding existing options, or repositioning commands. ## commandBarProps @@ -87,20 +87,39 @@ Mandatory property to uniquely identify a command in the Command bar. Valid keys 'pinToQuickAccess' 'unpinFromQuickAccess' 'manageForms' +'favoriteCommand' +'createCopilot' ``` -## 🚀 Recent updates to `commandBarCustomization` Keys +## ⚠️ Recent updates to `commandBarCustomization` Keys -> [NOTE!] -> Some keys in the `commandBarCustomization` schema have been updated. To ensure your custom formatter works correctly, update your existing JSON with these new keys. +> Some keys in the commandBarCustomization schema have been updated. To ensure your custom formatter functions correctly, please update your existing JSON to reflect these new keys. > -> | Original Key | Current Key | +> | Original Key | New Key | > |--------------|-------------| -> | `new` | `newComposite` | -> | `upload` | `uploadCommand` | +> | `new` | `newComposite` (Document Library)| +> | `upload` | `UploadCommand` | > | `sync` | `syncCommand` | > | `addShortcut`| `addShortcutToOneDriveCommand` | > | `pinToQuickAccess` | `PinToQuickAccessCommand` | +> | `pinItem` | `pinItemCommand` | +> | `properties` | `propertiesCommand` | +> | `versionHistory` | `versionHistoryCommand` (currently not working) | +> +> Additionally, the following new command keys are now available: +> > +> - `stasherContextMenuCommand` (Add shortcut) +> - `stasherCommand.myFiles` (Add shortcut --> my Files) +> - `stasherCommand.otherLocations` (Add shortcut --> Other locations) +> - `PublishCommand` +> - `complianceDetails` (right click context menu --> More --> Compliance details) +> - `more` (right click context menu --> More) +> - `previewFileCommand` (right click context menu --> Preview) +> +> Please note that the JSON schema at https://developer.microsoft.com/json-schemas/sp/v2/command-bar-formatting.schema.json has not yet been updated to reflect these new command keys. + +> [!IMPORTANT] +> Command bar customizations also affect the item context menu (right-click menu). If a command is hidden in the command bar, it will also be hidden in the context menu. ## hide @@ -154,7 +173,7 @@ The following example shows a sample Command bar formatting JSON to do the follo ## position -An optional property that specifies the position where the command will be placed in the command bar. The value of this property can either be a number, string or an Expression object. If the value is not provided then the command will be placed in it's default position. This property follows zero-based indexing. +An optional property that specifies the position where the command will be placed in the command bar. The value of this property can either be a number, a string, or an Expression object. If the value is not provided then the command will be placed in it's default position. This property follows zero-based indexing. ## sectionType @@ -164,8 +183,9 @@ An optional property that specifies the section where the customized command wil - Overflow The following example shows a sample Command bar formatting JSON to do the following: + - Puts the 'New' command at the third position in the primary section of the Command bar. -- Puts the 'Share' command at the second position in the overflow menu of the Command bar. +- Puts the 'Share' command in the second position in the overflow menu of the Command bar. - Puts the 'Alert me' command at the fourth position in the primary section of the Command bar. ```JSON @@ -193,7 +213,7 @@ The following example shows a sample Command bar formatting JSON to do the follo ## selectionModes -An optional property that specifies the selection modes in which the command customization will be applied. If the value is not provided then the customization will be applied in all the selection modes in which the command is available. The value of this property can be array of strings where the following strings are allowed: +An optional property that specifies the selection modes in which the command customization will be applied. If the value is not provided, then the customization will be applied in all the selection modes in which the command is available. The value of this property can be an array of strings where the following strings are allowed: - NoSelection - SingleSelection diff --git a/docs/embedded/administration/consuming-tenant-admin/ctaUX.md b/docs/embedded/administration/consuming-tenant-admin/ctaUX.md index 424850d11..052f26f50 100644 --- a/docs/embedded/administration/consuming-tenant-admin/ctaUX.md +++ b/docs/embedded/administration/consuming-tenant-admin/ctaUX.md @@ -1,30 +1,35 @@ --- -title: Manage Containers in SharePoint Admin Center -description: This article describes how administrator can manage containers in SPAC. -ms.date: 10/16/2024 +title: Manage containers in SharePoint Admin Center +description: This article describes how administrators can manage containers in the SharePoint Admin Center (SPAC). +ms.date: 07/09/2025 ms.localizationpriority: high --- # Manage SharePoint Embedded containers in SharePoint Admin Center -The organizations that use the SharePoint Embedded applications on their Microsoft 365 (Microsoft 365) tenants are the consuming tenants and the persona that is responsible for managing these applications on their Microsoft 365 tenancy is the consuming tenant administrator (CTA). Consuming tenant administrators can manage containers through a graphical user interface (GUI) using the [SharePoint Administrator Center](https://go.microsoft.com/fwlink/?linkid=2185219). +The organizations that use the SharePoint Embedded applications on their Microsoft 365 tenants are the consuming tenants and the persona that is responsible for managing these applications on their Microsoft 365 tenancy is the consuming tenant administrator (CTA). Consuming tenant administrators can manage containers through a graphical user interface (GUI) using the [SharePoint Administrator Center](https://go.microsoft.com/fwlink/?linkid=2185219). -To manage SharePoint Embedded containers, CTA need to be assigned the Microsoft 365 SharePoint Embedded Administrator role. Global Administrators in Microsoft 365 have all the permissions of the SharePoint Embedded Administrator role. A global administrator can assign a user the SharePoint Embedded administrator role to act as a consuming tenant admin for SharePoint Embedded. This role is available in both Microsoft Entra and the Microsoft 365 Admin Center. -For information on SharePoint Embedded admin role, see [SharePoint Embedded Admin](../adminrole.md). +To manage SharePoint Embedded containers, the CTA needs to be assigned the SharePoint Embedded Administrator role. + +For information on the SharePoint Embedded Administrator role, see [SharePoint Embedded Admin](../adminrole.md). The following actions are supported in SharePoint Admin Center: 1. View active containers in the tenant 1. View deleted containers in the tenant -1. View detailed information of a container +1. View detailed information about a container 1. Delete a container 1. Restore a deleted container 1. Permanently deleted a container - -**Global admin** will also see "Active Containers" and "Deleted Containers" page along with Site administration pages when they sign in to SharePoint Admin Center. +2. Sort active containers in the tenant +3. Filter active containers in the tenant +4. Set sensitivity label on active containers +5. Add users to different roles on a container +6. Reassign users from existing roles on a container +7. Remove users from existing roles on a container ![Active Containers global admin](../../images/ctaux1.png) -**SharePoint Embedded admin** will only see "Active Containers" and "Deleted Containers" page when they sign in to SharePoint Admin Center. +**SharePoint Embedded Administrator** will only see the "Active containers" and "Deleted containers" page when they sign in to SharePoint Admin Center. ![Active Containers SPE admin](../../images/ctaux2.png) @@ -32,13 +37,16 @@ The following actions are supported in SharePoint Admin Center: The Active Containers page displays all the active containers within the tenant, providing a comprehensive overview and management capabilities. This page includes the following metadata for each container: -1. **Container name :** Name of the container provided by the container owner -1. **Application name :** Name of the SharePoint Embedded application the container belongs to -1. **Publisher name :** The name of the organization that owns the application -1. **Storage :** The total storage of the files stored in the containers -1. **Owners :** Users assigned the owner role on the container -1. **Sensitivity label :** Name of the label assigned to the container -1. **Created on :** Date and time when the container was created +1. **Container name:** Name of the container provided by the container owner. +1. **Application name:** Name of the SharePoint Embedded application the container belongs to. +1. **Publisher:** The name of the organization that owns the application. For all publishers other than Microsoft, the value is currently stored as "Other" +1. **Ownership type:** Mentions whether the container is tenant-owned, user-owned, or group-owned. +1. **Principal owner:** The user whose lifecycle impacts the lifecycle of the container. There is no prinicipal owner for a tenant owned container, while it is a user for a user owned container and a group for a group owned containers. +1. **Storage:** The total storage of the files stored in the containers. +1. **Owners:** Users assigned the owner role on the container. +1. **Owner count:** The count of number of owners of the container. +1. **Sensitivity label:** Name of the label assigned to the container. +1. **Created on:** Date and time when the container was created. ![Active Container Properties](../../images/ctaux3.png) @@ -50,21 +58,22 @@ The detailed container view provides a deeper dive into container-specific metad ![Container Details](../../images/ctaux4.png) -1. **Membership:** This panel shows the user permissions for different users associated with the container. +1. **Membership:** This panel shows the user permissions for different users associated with the container. The admin can manage the membership on a container through this panel. > [!IMPORTANT] > The SharePoint Embedded platform supports four distinct [roles](../../development/sharing-and-perm.md): Owner, Manager, Writer, and Reader. The SharePoint Embedded application on your tenant may not utilize all four roles and might refer to these roles using different names. -> ![SharePoint Embedded Membership Roles](../../images/ctaux5.png) ## Deleted Containers -The deleted containers page lists all containers in the tenants deleted container collection. It lists the following metadata: +The deleted containers page lists all containers in the tenant's deleted container collection. It lists the following metadata: 1. Container name 1. Application name -1. Publisher name +1. Publisher +1. Ownership type +1. Principal owner 1. Storage 1. Owners 1. Sensitivity label @@ -78,7 +87,7 @@ The deleted containers page lists all containers in the tenants deleted containe > [!WARNING] > Deleting a container may cause unexpected issues for the SharePoint Embedded application it belongs to and may interrupt the application's usage. This action should only be performed by admins when absolutely necessary. -Deleting a container can have implications on the functionality of a SharePoint Embedded app, Here are some examples of the potential issues that an application can encounter when deleting a container. +Deleting a container can have implications on the functionality of a SharePoint Embedded app Here are some examples of the potential issues that an application can encounter when deleting a container. 1. **Data Loss:** Deleting a container removes all its content. If the SharePoint Embedded application relies on the data stored within the deleted container, the app might no longer function as expected or might lose access to critical information. 1. **Broken Links:** If the SharePoint Embedded application contains links or references to the deleted container, those links become broken, leading to errors or malfunctioning features within the app. @@ -87,7 +96,7 @@ A container can be deleted from the Active containers page for any business reas ![Container Deletion Process](../../images/ctaux7.png) -This opens a side panel that warns the user about the effect on the associated SPE application due to the deletion of a container and inform the user about the restoration policy. The CTA can at this stage either cancel the panel and go back to the active containers page or proceed further with the deleting by clicking on “Delete container”. +This opens a side panel that warns the user about the effect on the associated SPE application due to the deletion of a container and informs the user about the restoration policy. The CTA can at this stage either cancel the panel and go back to the active containers page or proceed further with the deleting by clicking on “Delete container”. ![Container deletion selection](../../images/ctaux8.png) @@ -95,7 +104,7 @@ The selected container is successfully deleted and moved into the deleted contai ![Deleted SPE Container](../../images/ctaux9.png) -**Deleted containers are permanently purged after 93 days unless there is a retention policy applied to the containers** +**Deleted containers are permanently purged after 93 days unless there is a retention policy applied to the containers.** ## Restore a container @@ -110,7 +119,6 @@ Restoration of the container happens in the background and the status of the sam ## Permanently delete a container > [!WARNING] -> > Deleting a container may cause unexpected issues for the SharePoint Embedded application it belongs to and may interrupt the application's usage. This action should only be performed by admins when absolutely necessary. The CTA can permanently delete a deleted container from the deleted container collection if they decide to. @@ -119,17 +127,92 @@ The CTA selects the container to be permanently deleted. The “Permanently dele ![Permanent SPE Container deletion](../../images/ctaux12.png) -Upon clicking the button, a pop-up appears. warning the CTA on the action they're performing. If sure, the CTA can proceed and select on “Delete”. Otherwise the CTA can cancel the action. +Upon clicking the button, a pop-up appears. warning the CTA on the action they're performing. If sure, the CTA can proceed and select “Delete”. Otherwise, the CTA can cancel the action. ![Container Deletion warning](../../images/ctaux13.png) -Upon clicking Delete, the container is permanently deleted and the status of the same appears in the top-right corner of the page. Upon successful deletion, the container is permanently removed from the deleted container collection and can't be restored. +Upon clicking Delete, the container is permanently deleted, and the status of the same appears in the top-right corner of the page. Upon successful deletion, the container is permanently removed from the deleted container collection and can't be restored. ![SPE Container Deleted](../../images/ctaux15-n.png) -## Coming Soon +## Sorting on Active containers page + +The CTA can perform their compliance and storage management tasks better through the use of sorting capabilities on the Active containers page. Currently, sorting is supported on the following columns: +1. Storage +1. Created on + +![ SPE Container Sorting](../../images/sorting.png) + +## Filtering on Active containers page + +The CTA can perform their compliance and storage management tasks better through the use of filtering capabilities on the Active containers page. Currently, filtering is supported on the following columns: + +1. Application name: The filter provides the list of all Microsoft SharePoint Embedded applications along with all SharePoint Embedded applications published by other publishers that is registered in the tenant. +1. Publisher: Describes whether the application is Microsoft-owned or published by an "Other" publisher. +1. Ownership type: The filter provides the options of Tenant, User, and Group, irrespective of the type of containers present in the tenant. +1. Principal owner: The filtering experience is a people picker experience. +1. Owner count: This filter provides a range of owner count for the administrator to choose from. +1. Created on: This filter provides a range of dates for the administrator to choose from. + +> [!IMPORTANT] +> The behaviour of the filtering experience on the Active containers page differs from the experience on the Active sites page in SharePoint Admin Center. + +![ SPE Container Filtering](../../images/filter.png) + +## Searching on Active Containers Page + +The search bar on the Active Containers Page can be used to search containers in the active state by their "container name". +![SPE Container Search](../../images/search.png) + +## Editing the sensitivity label of a container on the Active containers page + +The sensitivity label of a container can be set on the Active container page, on the detailed panel of a container. Under the settings panel, the administrator can set the sensitivity label from a list of available sensitivity label. + +![SPE Container Sensitivity](../../images/sensitivity-label.png) + +## Managing user membership of a container + +The administrator can manage the membership of users of a container on the Active container page, on the detailed panel of a container. Under the membership panel, the administrator can view the four roles and the corresponding users in each role. The administrator can: + +**Add a user to a role:** The administrator can navigate to the desired role using the left panel and click on the Add option. This opens up a picker, using which the administrator can select a user from the tenant and assign the role. In case the selected user is already assigned to a different role, the role is displayed when the role is selected and the operation changes from Add to Reassign. + +![SPE Container owner-one](../../images/add-owners-one.png) + +![SPE Container owner-two](../../images/add-owners-two.png) + +**Reassign user to another role:** The administrator can navigate to the desired user under a role using the left panel. On selecting the user, the Reassign option appears. On selecting the option, a drop-dowm menu appears and the administrator can select the role to which the user needs to be reassigned to. + +![ SPE Container reassingn](../../images/reassign-user.png) + +**Remove user from a role:** The administrator can navigate to the desired user under a role using the left panel. On selecting the user, the Remove option appears. On selecting the option, a pop-up screen appears, and the administrator can confirm the removal of the user from the role. + +![SPE Container remove](../../images/remove-user.png) + +## Sorting on the Deleted Containers Page + +Similar to the sorting experience on the Active containers page, the CTA can use sorting capabilities on the Deleted containers page. Currently, sorting is supported on the following columns: + +1. Storage +1. Created on +1. Deleted on + +![ SPE Container Sorting_on_Delete](../../images/sorting-on-deleted.png) + +## Filtering on the Deleted containers page + +The CTA can perform their compliance and storage management tasks better through the use of filtering capabilities on the Deleted containers page, on the following columns: + +1. Application name: The filter provides the list of all Microsoft SharePoint Embedded applications along with all SharePoint Embedded applications published by other publishers that is registered in the tenant. +2. Publisher: Describes whether the application is Microsoft-owned or published by an "Other" publisher. +3. Ownership type: The filter provides the options of Tenant, User, and Group, irrespective of the type of containers present in the tenant. +4. Principal owner: The filtering experience is a people picker experience. +5. Owner count: This filter provides a range of owner counts for the administrator to choose from. +6. Created on: This filter provides a range of dates for the administrator to choose from. +7. Deleted on: This filter provides a range of dates for the administrator to choose from. + +![ SPE Container Filter_on_Delete](../../images/filter-on-delete.png) + +## Upcoming features -1. Sort containers by created date and storage -1. Filter containers by created date, application name and publisher name -1. Edit sensitivity label of a container -1. Add and remove users to/from a container +1. Search on the Deleted containers page +1. Sorting and filtering on the Sensitivity Label column diff --git a/docs/embedded/development/auth.md b/docs/embedded/development/auth.md index 94229f1de..6e20ceb95 100644 --- a/docs/embedded/development/auth.md +++ b/docs/embedded/development/auth.md @@ -1,7 +1,7 @@ --- title: SharePoint Embedded Authentication and Authorization description: This article describes the authentication and authorization model for SharePoint Embedded applications. -ms.date: 04/09/2025 +ms.date: 06/24/2025 ms.localizationpriority: high --- @@ -11,13 +11,13 @@ To use SharePoint Embedded, your application needs to use Microsoft Graph. Learn ## Overview -Here are some key principles with SharePoint Embedded authentication and authorization: +Here are some key principles of SharePoint Embedded authentication and authorization: - Applications interact with SharePoint Embedded via Microsoft Graph. - Applications need container type application permissions to access containers of that container type. -- When using access on behalf of a user, applications can only access containers that the user is a member of. -- When using access without a user, applications can access containers enabled by the container type application permissions they have been granted. -- Applications use access on behalf of users whenever possible to enhance security and audibility +- Applications can only access containers that the user is a member of when using access on behalf of a user. +- Applications can access all containers enabled by their container type application permissions when using access without a user. +- Applications use access on behalf of users whenever possible to enhance security and accountability ## Pre-Requisites @@ -51,11 +51,12 @@ SharePoint Embedded operations [without a user](/graph/auth-v2-service) require Currently, there are two types of operations with exceptional access patterns: -- Operations not exposed via Microsoft Graph -- Operations involving searching SharePoint Embedded content +- [Operations not exposed via Microsoft Graph](#operations-not-exposed-via-microsoft-graph) +- [Operations involving searching SharePoint Embedded content](#operations-involving-searching-sharepoint-embedded-content) +- [Operations that require a user license](#operations-that-require-a-user-license) > [!IMPORTANT] -> Make sure you understand and consider these exceptional access patterns as they may have repercussions on how SharePoint Embedded content for your application may be accessed, both by your application and other applications. +> Consider the repercussions of these exceptional access patterns on how your application and other applications can access SharePoint Embedded content in your container type. #### Operations not exposed via Microsoft Graph @@ -63,7 +64,7 @@ There are two types of operations that aren't accessible via Microsoft Graph tod - [Container type management](../getting-started/containertypes.md) on owning tenants, which are performed via PowerShell cmdlets. - [Container type registration](../getting-started/register-api-documentation.md) on consuming tenants, exposed via SharePoint REST API v2. -- [SharePoint Embedded copilot](./declarative-agent/spe-da.md) exposed via SharePoint REST API v2 permissions. +- [SharePoint Embedded agent](./declarative-agent/spe-da.md) exposed via SharePoint REST API v2 permissions. To perform [container type management](../getting-started/containertypes.md) operations, you must be a [SharePoint Embedded Administrator](/entra/identity/role-based-access-control/permissions-reference#sharepoint-embedded-administrator) or [Global Administrator](/entra/identity/role-based-access-control/permissions-reference#global-administrator). @@ -74,19 +75,31 @@ To [register a container type](../getting-started/register-api-documentation.md) | Container.Selected | 19766c1b-905b-43af-8756-06526ab42875 | Application | In the context of SharePoint Embedded, enables container type registration on a consuming tenant. | > [!NOTE] -> Container type management on owning tenants and registration on consuming tenants will become Microsoft Graph operations soon and this step will no longer be needed. Stay tuned. +> Container type management on owning tenants and registration on consuming tenants will become Microsoft Graph operations soon, and this permission will no longer be needed. Stay tuned. -To use the [SharePoint Embedded copilot](./declarative-agent/spe-da.md) experience (in the Preview stage) in your application, you will also need the `Container.Selected` permission on the `Office 365 SharePoint Online` resource. Please note that, as mentioned above, this permission is also required to register a container type today, which means that your application must have been granted consent to it interact with SharePoint Embedded in consuming tenants. +To use the [SharePoint Embedded agent](./declarative-agent/spe-da.md) experience (in the Preview stage) in your application, you also need the `Container.Selected` permission on the `Office 365 SharePoint Online` resource. #### Operations involving searching SharePoint Embedded content -This refers only to the search scenarios in [Search Content](./content-experiences/search-content.md), and not the enumeration scenarios. +This section refers only to the search scenarios in [Search Content](./content-experiences/search-content.md), and not the enumeration scenarios. -To use [Microsoft Search](/microsoftsearch/overview-microsoft-search) on SharePoint Embedded content, you must request the Delegated [`Files.Read.All`](/graph/permissions-reference#filesreadall) Microsoft Graph permission on top of `FileStorageContainer.Selected` normally used for SharePoint Embedded access. During the Preview stage of this feature, the `Files.Read.All` application permission will grant applications access to search capabilities on all SharePoint Embedded content. +To use [Microsoft Search](/microsoftsearch/overview-microsoft-search) on SharePoint Embedded content, you must request the Delegated [`Files.Read.All`](/graph/permissions-reference#filesreadall) Microsoft Graph permission on top of `FileStorageContainer.Selected`, normally used for SharePoint Embedded access. During the Preview stage of this feature, the `Files.Read.All` application permission grants applications access to search capabilities on all SharePoint Embedded content. > [!NOTE] > Microsoft Search support for SharePoint Embedded content is in Preview and is subject to change. The access requirements for Microsoft Search on SharePoint Embedded content will align with the SharePoint Embedded authorization model in the future. Stay tuned. +#### Operations that require a user license + +SharePoint Embedded is designed to work without the need for end users to have any kind of Microsoft 365 product licenses assigned to them. However, there are certain operations that don't abide by this principle yet. + +##### List containers + +The [List containers](/graph/api/filestorage-list-containers?tabs=http) operation returns a `403 Forbidden` response code if called on behalf of a user that doesn't have a OneDrive. There are plans to remove this dependency soon. This dependency doesn't apply to the List containers operation when called without a user context (app-only mode). + +##### Mention users in Office documents + +The common [Office experience](./content-experiences/office-experience.md) includes reviewing documents and adding comments to those documents. For users to show up in the @mentions people picker, they need to have a Microsoft 365 license assigned to them. + ### Container type application permissions SharePoint Embedded applications need to be granted container type application permissions by the owner application before they can access containers of the given container type. Container type application permissions are granted to applications via [container type registration](../getting-started/register-api-documentation.md). @@ -110,7 +123,7 @@ SharePoint Embedded applications need to be granted container type application p | Full | Has all permissions for containers of this container type. | > [!NOTE] -> The combination of Microsoft Graph permissions and container type application permissions encompass the client authorization for applications. +> The combination of Microsoft Graph permissions and container type application permissions encompasses the client authorization for applications. ### Container permissions @@ -130,12 +143,22 @@ Any user accessing a container must be a member of the container. Membership to Here are some actions you can take next: -1. Configure your SharePoint Embedded [application manifest](/entra/identity-platform/reference-app-manifest#requiredresourceaccess-attribute) (you may use [Entra PowerShell](/powershell/entra-powershell/manage-apps#assign-permissions-to-an-app) or the [Azure CLI](/cli/azure/ad/app/permission#az-ad-app-permission-add)) to request the required permissions: +1. Configure your SharePoint Embedded [application manifest](/entra/identity-platform/reference-app-manifest#requiredresourceaccess-attribute) (you can use [Microsoft Entra PowerShell](/powershell/entra-powershell/manage-apps#assign-permissions-to-an-app) or the [Azure CLI](/cli/azure/ad/app/permission#az-ad-app-permission-add)) to request the required permissions: + - Microsoft Graph (resourceAppId: `00000003-0000-0000-c000-000000000000`) - `FileStorageContainer.Selected` (type: `Scope`, ID: `085ca537-6565-41c2-aca7-db852babc212`) to access containers on consuming tenants - Office 365 SharePoint Online (resourceAppId: `00000003-0000-0ff1-ce00-000000000000`) - `Container.Selected` (type: `Role`, ID: `19766c1b-905b-43af-8756-06526ab42875`) to register a container on consuming tenants -1. [Grant admin consent](/entra/identity/enterprise-apps/grant-admin-consent?pivots=portal) to your application on both owning and consuming tenants (which can be the same tenant). + +1. [Grant admin consent](/entra/identity-platform/v2-admin-consent) to your application on both owning and consuming tenants (which can be the same tenant). + + > [!NOTE] + > The `Container.Selected` application permission is hidden, which can cause issues with granting admin consent using the Enterprise apps pane in the Azure portal. Instead, [construct the admin consent URL](/entra/identity-platform/v2-admin-consent#request-the-permissions-from-a-directory-admin) and provide it to your Microsoft Entra directory administrator. For example: + > + > `https://login.microsoftonline.com/{tenant}/v2.0/adminconsent?client_id={client_id}` + > + > Make sure the Microsoft Entra directory administrator [confirms a successful response](/entra/identity-platform/v2-admin-consent#successful-response). + 1. [Create a new container type](../getting-started/containertypes.md) on the owning tenant. 1. [Register a container type](../getting-started/register-api-documentation.md) on the consuming tenant. 1. [Create a container](/graph/api/filestoragecontainer-post) diff --git a/docs/embedded/development/content-experiences/office-experience.md b/docs/embedded/development/content-experiences/office-experience.md index dd6d48c17..4add48ca4 100644 --- a/docs/embedded/development/content-experiences/office-experience.md +++ b/docs/embedded/development/content-experiences/office-experience.md @@ -1,7 +1,7 @@ --- title: Office Experiences description: Overview of Office experiences with SharePoint Embedded content -ms.date: 05/21/2024 +ms.date: 06/18/2025 ms.localizationpriority: high --- @@ -11,16 +11,21 @@ Office file experiences for SharePoint Embedded platform will work in a similar ## Opening Office documents from SharePoint Embedded -Office documents from SharePoint Embedded apps can be opened for viewing and editing in Office web, or in 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. 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. -## View or restore a previous version of Office document from SharePoint Embedded +## 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. +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. ## 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. +> [!NOTE] +> Mentions require target users to [have an 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. + ### Share your documents #### Send an email invite @@ -34,7 +39,7 @@ Share your SharePoint Embedded documents by sending an email invitation to speci Creating a shareable link makes it simple to share your SharePoint Embedded document in an email, document, or IM. -- Select Share, Copy Link and Paste the link wherever you want +- Select Share, Copy Link, and Paste the link wherever you want - Change any permissions of the link if needed #### Co-Author @@ -45,13 +50,13 @@ If you want others to edit with you, you can easily share files and collaborate - A presence indicator shows where someone is making changes. See any changes right as they're being made. - See changes made by others and see what's happened while you were away. -### Levels of sharing access +#### Levels of sharing access There are different options for sharing SharePoint Embedded Application Office Documents from: | 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 forwarded from someone else. This might include people outside of your organization. | +| 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 \** 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. | | Reshare the link with specific people | **People with existing access**  can be used by people who already have access to the document or folder. It doesn't change the permissions on the item. Use this if you just want to send a link to somebody who already has access. | diff --git a/docs/embedded/development/declarative-agent/spe-da-adv.md b/docs/embedded/development/declarative-agent/spe-da-adv.md index 2a04298bd..54b6c5c3a 100644 --- a/docs/embedded/development/declarative-agent/spe-da-adv.md +++ b/docs/embedded/development/declarative-agent/spe-da-adv.md @@ -1,25 +1,33 @@ --- -title: SharePoint Embedded copilot Advanced Topics -description: Learn how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses in SharePoint Embedded copilot. -ms.date: 3/03/2025 +title: SharePoint Embedded agent Advanced Topics +description: Learn how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses in SharePoint Embedded agent. +ms.date: 06/10/2025 ms.localizationpriority: high --- -# SharePoint Embedded copilot Advanced Topics Overview +# SharePoint Embedded agent Advanced Topics Overview -This advanced guide covers how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses. We’ll explore how these concepts work together to ensure your copilot retrieves relevant information from your data and returns grounded answers. +This advanced guide covers how the semantic index powers Retrieval-Augmented Generation (RAG) to provide accurate, context-aware AI responses. We explore how these concepts work together to ensure your agent retrieves relevant information from your data and returns grounded answers. ## Caveats ### Configuration -#### Required ContainerType Configuration +#### Required Container Type Configuration ##### DiscoverabilityDisabled -This [flag](../../administration/developer-admin/dev-admin.md#container-type-configuration-properties) prevents copilot from discovering [drive items](/graph/api/resources/driveitem) in the specified container type. If you have an existing container type and are setting this value to false, please wait 24 hours to ensure the container type configuration is fully propagated before creating a new container, uploading files there, and trying out copilot on folders/files of that new container. +The [`discoverabilityDisabled`](../../administration/developer-admin/dev-admin.md#container-type-configuration-properties) property controls whether Microsoft 365 can discover [drive items](/graph/api/resources/driveitem) within a specific container type. -The following is an example of how to set the flag to false with [Set-SPOContainerTypeConfiguration](/powershell/module/SharePoint-online/set-spocontainertypeconfiguration#examples) +If you’re updating an existing container type to set this property to `false`, allow up to **24 hours** for the configuration change to fully propagate before: + +- Creating new containers, +- Uploading files to containers, or +- Using SPE agent to interact with folders or files. + +This ensures the agent can correctly access and surface the content. + +Here is an example of how to set `discoverabilityDisabled` to `false` with [Set-SPOContainerTypeConfiguration](/powershell/module/SharePoint-online/set-spocontainertypeconfiguration#examples) ```powershell Set-SPOContainerTypeConfiguration -ContainerTypeId 4f0af585-8dcc-0000-223d-661eb2c604e4 -DiscoverabilityDisabled $false @@ -31,65 +39,99 @@ Discoverability can also be disabled using the Visual Studio Code SharePoint Emb ##### CSP Policies -The Content-Security-Policy (CSP) for embedded chat hosts ensures that only specified hosts can load the chat component. This helps in securing the application by restricting which domains can embed the chat component. +The Content-Security-Policy (CSP) for embedded chat hosts ensures that only specified hosts can load the chat component. Specifically, the `CopilotEmbeddedChatHosts` setting is used in a [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) header as a `frame-ancestors` value. This helps in securing the application by restricting which domains can embed the chat component. + +The SPE Administrator on the owning tenant can set this setting by using the `Set-SPOContainerTypeConfiguration` cmdlet: -It is intended to allow consuming tenant SPE admins to set an allowlist of hosts that they will allow to embed the SPE copilot in an iFrame. Specifically, the value they set here will be used in a Content-Security-Policy header as a frame-ancestors value. +```powershell +# Note this MUST be run in Windows PowerShell. It will not work in PowerShell. +Import-Module -Name "Microsoft.Online.SharePoint.PowerShell" +Connect-SPOService "https://-admin.sharepoint.com" +# Login with your admin account. +# ... + +Set-SPOContainerTypeConfiguration -ContainerTypeId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -CopilotEmbeddedChatHosts @("http://localhost:3000", "https://contoso.sharepoint.com", "https://fabrikam.com") + +# This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly. +# Replication of this configuration on consuming tenants can take up to 24 hours +# ... + +# Confirm setting value +Get-SPOContainerTypeConfiguration -ContainerTypeId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX + +# On a consuming tenant, you may confirm the setting value as follows +Get-SPOApplication -OwningApplicationId | Select-Object CopilotEmbeddedChatHosts + +OwningApplicationId : +OwningApplicationName : SharePoint Embedded App +Applications : {} +CopilotEmbeddedChatHosts : {http://localhost:3000, https://contoso.sharepoint.com, https://fabrikam.com} +``` > [!NOTE] > -> If this configuration is not set, the [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) will default be set to -> [frame-ancestors](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors): ‘none’ which means no one can embed the copilot. +> If this configuration isn't set, the [Content-Security-Policy](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy) is by default set to +> [frame-ancestors](https://developer.mozilla.org/docs/Web/HTTP/Headers/Content-Security-Policy/frame-ancestors): "none", which means no one can embed the agent. -Below are example commands to use the [Connect to SharePoint Online using PowerShell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online) commands: +A SharePoint Embedded Administrator on a consuming tenant may override the values specified by the owning application, by using the consuming tenant cmdlets: - [Set-SPOApplication](/powershell/module/SharePoint-online/set-spoapplication) to set the `CopilotEmbeddedChatHosts` property. - [Get-SPOApplication](/powershell/module/SharePoint-online/get-spoapplication) to get the `CopilotEmbeddedChatHosts` property. +> [!NOTE] +> +> A consuming tenant override must be a subset of what the owning tenant configured for `CopilotEmbeddedChatHosts`. An administrator +> in a consuming tenant cannot set values that the application owner has not specified for the container type. The override capabilities +> is intended for consuming tenant administrators to enable the agent in only a subset of hosts that the owning application has defined. + +Here's an example of how a consuming tenant can override the setting: + ```powershell # Note this MUST be run in Windows PowerShell. It will not work in PowerShell. Import-Module -Name "Microsoft.Online.SharePoint.PowerShell" Connect-SPOService "https://-admin.sharepoint.com" # Login with your admin account. -... +# ... -Set-SPOApplication -OwningApplicationId 423poi45 -CopilotEmbeddedChatHosts "http://localhost:3000 https://contoso.sharepoint.com https://fabrikam.com" +Set-SPOApplication -OwningApplicationId XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX -CopilotEmbeddedChatHosts @("https://contoso.sharepoint.com", "https://fabrikam.com") -# This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly. -... +# This will set the container type configuration “CopilotEmbeddedChatHosts” accordingly +# Note that @("https://contoso.sharepoint.com", "https://fabrikam.com") is a subset of what we defined in the owning tenant +# Those values were @("http://localhost:3000", "https://contoso.sharepoint.com", "https://fabrikam.com") + +# Confirm the configuration Get-SPOApplication -OwningApplicationId | Select-Object CopilotEmbeddedChatHosts OwningApplicationId : OwningApplicationName : SharePoint Embedded App Applications : {} -SharingCapability : ExternalUserAndGuestSharing -OverrideTenantSharingCapability : False -CopilotEmbeddedChatHosts : {http://localhost:*} +CopilotEmbeddedChatHosts : {https://contoso.sharepoint.com, https://fabrikam.com} ``` #### Optional Configuration ##### Authentication and 3P Cookies -The iFrame used by SharePoint Embedded copilot attempts to authenticate using third-party cookies. If third-party cookies are disabled in the user's browser, the iFrame will not be able to authenticate automatically. In such cases, a popup will be displayed prompting the end user to log in manually. This ensures that the authentication process can still be completed even when third-party cookies are not available. +The `iframe` used by SharePoint Embedded agent authenticates users using third-party cookies. If third-party cookies are disabled in the user's browser, the iframe can't authenticate automatically. In this case, a popup prompts the user to sign in manually, ensuring that authentication can still be completed. ## Advanced Topics ### Application Scoping -Application scoping in SharePoint Embedded copilot (SPE copilot) involves defining the boundaries and context within which the tool operates, ensuring its features and capabilities are tailored to meet the specific needs of different applications. This process helps customize the copilot's functionality, making it more effective and relevant for various use cases. +Application scoping in SharePoint Embedded agent (SPE agent) involves defining the boundaries and context within which the tool operates, ensuring its features and capabilities are tailored to meet the specific needs of different applications. This process helps customize the agent's functionality, making it more effective and relevant for various use cases. -When SPE copilot users query the LLM, it will only have access to files that the **User+Application** have access to. The effective permissions for the copilot session will be the intersection of your SharePoint Embedded application's permissions and the user's permissions. +When SPE agent users query the LLM, it will only have access to files that the **User+Application** have access to. The effective permissions for the agent session will be the intersection of your SharePoint Embedded application's permissions and the user's permissions. -![Venn Diagram with SPE application access on left, SPE copilot in middle and consuming tenant user on right, overlapped area is what copilot can access](../../images/speco-appscopingvenn.png) +![Venn Diagram with SPE application access on left, SPE agent in middle and consuming tenant user on right, overlapped area is what agent can access](../../images/speco-appscopingvenn.png) ### Information Architecture -Files in SharePoint Embedded are naturally [semantic indexed](spe-da-adv.md#semantic-index). This semantic index underpins retrieval augmented generation [(RAG)](spe-da-adv.md#rag--retrieval-augmented-generation-) workflows by providing relevant context from your stored content at query time. In essence, it [grounds](spe-da-adv.md#grounding) the AI responses, ensuring they directly reference accurate information in your containers rather than relying on general knowledge alone. +Files in SharePoint Embedded are naturally [semantic indexed](spe-da-adv.md#semantic-index). This semantic index underpins retrieval augmented generation [(RAG)](spe-da-adv.md#retrieval-augmented-generation-rag) workflows by providing relevant context from your stored content at query time. In essence, it [grounds](spe-da-adv.md#grounding) the AI responses, ensuring they directly reference accurate information in your containers rather than relying on general knowledge alone. ![How RAG works in SPE](../../images/speco-ragm365.png) -With SharePoint Embedded copilot, you can further ground the large language models (LLM) reponses on [specific files or drive items.](spe-da-adv.md#scoping-your-copilot-to-specific-content). +With SharePoint Embedded agent, you can further ground the large language models (LLM) response on [specific files or drive items.](spe-da-adv.md#scoping-your-agent-to-specific-content). ### Semantic index @@ -99,7 +141,7 @@ The semantic index allows for quick and accurate searches based on data similari ### Retrieval-Augmented Generation (RAG) -RAG relies on having relevant source materials stored in a repository, which can be queried at runtime​, data is retrieved from the index and is used to augment the prompt sent to the large language model (LLM)​: +RAG enables you to reference relevant source materials stored in a repository at runtime. The data is retrieved from the index and is used to augment the prompt sent to the large language model (LLM). Some benefits of RAG​: - Treat data sources as knowledge without having to train your model​ - Uses search (retrieval) results as additional context in your prompt​ @@ -111,11 +153,11 @@ The LLM uses the data to inform and construct the response. ### Grounding -Grounding in the context of SPE copilot refers to the process of providing input sources to the large language model (LLM) related to the user's prompt. This helps improve the specificity of the prompt and ensures that the responses are relevant and actionable to the user's specific task. The data the copilot is grounded on will be on the contents of the container type in the copilot application. Behind the scenes SPE copilot uses M365 Copilot, [learn more about it's architecture here](/copilot/microsoft-365/microsoft-365-copilot-architecture) +Grounding in the context of SPE agent refers to the process of providing input sources to the large language model (LLM) related to the user's prompt. This helps improve the specificity of the prompt and ensures that the responses are relevant and actionable to the user's specific task. The data the agent is grounded on will be the contents of the container type in the agent application. Behind the scenes, SPE agent uses Microsoft 365 Copilot. [Learn more about Microsoft 365 Copilot architecture](/copilot/microsoft-365/microsoft-365-copilot-architecture). -### Scoping your copilot to specific content +### Scoping your agent to specific content -SharePoint Embedded (SPE) copilot has the ability to restrict the data sources it has access to, below are provided types, and this [example](https://github.com/microsoft/SharePoint-Embedded-Samples/blob/main/Samples/spe-typescript-react-azurefunction/react-client/src/providers/ChatController.ts#L15) shows how to configure the SDK +SharePoint Embedded (SPE) agent has the ability to restrict the data sources it has access to. The sample code below shows the available data source types. [This example](https://github.com/microsoft/SharePoint-Embedded-Samples/blob/main/Samples/spe-typescript-react-azurefunction/react-client/src/providers/ChatController.ts#L15) shows how to configure the SDK. ```typescript export type IDataSourcesProps = @@ -158,13 +200,17 @@ export enum DataSourceType { ##### Language/Locale -The copilot iframe dynamically loads localization settings to ensure that the chat interface is displayed in the appropriate language. These settings are derived from SharePoint, which provides a comprehensive set of localization options. +The agent `iframe` dynamically loads localization settings to ensure that the chat interface is displayed in the appropriate language. These settings are derived from SharePoint, which provides a comprehensive set of localization options. -When the copilot iframe is initialized, it retrieves the current localization settings from SharePoint. These settings dictate the language and regional preferences for the chat interface, ensuring that all UI elements, messages, and interactions are presented in the user's preferred language. This seamless integration with SharePoint's localization framework allows copilot to provide a consistent an +When the agent iframe is initialized, it retrieves the current localization settings from SharePoint. These settings dictate the language and regional preferences for the chat interface, ensuring that all UI elements, messages, and interactions are presented in the user's preferred language. -You can have this localized by setting your language options in the SharePoint account settings: [Change your personal language and region settings - Microsoft Support](https://support.microsoft.com/en-us/office/change-your-personal-language-and-region-settings-caa1fccc-bcdb-42f3-9e5b-45957647ffd7) note, if your M365 setting is different from your Sharepoint account langauge settings it will take precedence, you can change your M365 language settings here: [Change your display language in Microsoft 365](https://support.microsoft.com/en-us/topic/change-your-display-language-and-time-zone-in-microsoft-365-for-business-6f238bff-5252-441e-b32b-655d5d85d15b) +You can have this localized by setting your language options in the SharePoint account settings: [Change your personal language and region settings - Microsoft Support](https://support.microsoft.com/office/change-your-personal-language-and-region-settings-caa1fccc-bcdb-42f3-9e5b-45957647ffd7). + +> [!NOTE] +> +> If your M365 language setting is different from your SharePoint account language setting, your M365 language setting takes precedence. You can change your M365 language setting here: [Change your display language in Microsoft 365](https://support.microsoft.com/topic/change-your-display-language-and-time-zone-in-microsoft-365-for-business-6f238bff-5252-441e-b32b-655d5d85d15b). -An additional locale option can be passed in through the `ChatLaunchConfig` to further set the language the copilot will respond in: +An additional locale option can be passed in through the `ChatLaunchConfig` to further set the language the agent responds in: ```typescript const [chatConfig] = React.useState({ diff --git a/docs/embedded/development/declarative-agent/spe-da.md b/docs/embedded/development/declarative-agent/spe-da.md index 805461488..3e7026291 100644 --- a/docs/embedded/development/declarative-agent/spe-da.md +++ b/docs/embedded/development/declarative-agent/spe-da.md @@ -1,7 +1,7 @@ --- -title: SharePoint Embedded copilot -description: Details copilot integration with SharePoint Embedded applications -ms.date: 02/19/2025 +title: SharePoint Embedded agent +description: Details usage and billing for SharePoint Embedded agents +ms.date: 05/12/2025 ms.localizationpriority: high --- @@ -9,11 +9,13 @@ ms.localizationpriority: high > [!NOTE] > -> SharePoint Embedded copilot is currently in private preview. Stay tuned for latest API and SDK changes on this page. +> SharePoint Embedded agent is currently in private preview. Stay tuned for latest API and SDK changes on this page. > -> Currently, to use SPE copilot, the consuming tenant user of the application is required to have a [Microsoft 365 Copilot license](/copilot/microsoft-365/microsoft-365-copilot-licensing). In the future, the license-based model will be replaced with a consumption-based model. Stay tuned for billing model announcements during the preview period. +> SPE agent consumption-based model will be available in May 2025! Starting May 1st, standard billing model will be available to all private preview customers and this rollout is expected to complete by May 15th. This means that starting May 15th, to use SPE agent within an SPE application, you will need to use standard Container Type. SPE Agent interactions, including those from Microsoft 365 Copilot license users, will be billed to the Azure subscription associated with your Container Type. Learn more about [SharePoint Embedded billing management](/sharepoint/dev/embedded/administration/billing/billingmanagement). +> +> We are actively working on enabling Direct-to-Customer billing model for SPE agent. Stay tuned for more announcements. -SharePoint Embedded copilot enables you to build Microsoft 365 Copilot functionality into your application through a simple SDK. This copilot chat control offers the following features: +SharePoint Embedded agent enables you to add AI capabilities into your application through a simple SDK. This chat control offers the following features: - Reason over documents in SharePoint Embedded containers using RAG. - Developers can configure the application code to limit the search scope to files, folders, and containers. @@ -23,15 +25,15 @@ Watch this demo to learn more about how to configure this functionality. > [!VIDEO https://www.youtube.com/embed/30i7q09EtQo?si=MwLtbrGKnzv7a6My] -## Why use SharePoint Embedded copilot +## Why use SharePoint Embedded agent -SharePoint Embedded copilot harness a semantic index to power Retrieval-Augmented Generation (RAG), securely referencing your data within the Microsoft 365 boundary at query time. This ensures accurate, grounded AI responses while reducing reliance on broad knowledge models. A pay-as-you-go billing model is on the horizon, aligning costs with actual usage. +SharePoint Embedded agent harness a semantic index to power Retrieval-Augmented Generation (RAG), securely referencing your data within the Microsoft 365 boundary at query time. This ensures accurate, grounded AI responses while reducing reliance on broad knowledge models. A pay-as-you-go billing model is on the horizon, aligning costs with actual usage. -![Diagram illustrating SPE copilot is AI ready](../../images/speco-apparch.png) +![Diagram illustrating SPE agent is AI ready](../../images/speco-apparch.png) -## How to use SharePoint Embedded copilot +## How to use SharePoint Embedded agent -### How to build your copilot +### How to build your agent Currently, you can use the React SDK library written in TypeScript to build your application. Plans to support additional frameworks and environments will be announced. The SDK is configured with the containerId instance of your containerType, as well as the authorization and authentication token logic you provide through a callback. It will embed itself as an iFrame into your host application. By default, the iFrame is given a `frame-ancestors` property that prevents it from being embedded by any host until configured. Details are provided below. @@ -41,30 +43,30 @@ Follow the [quick start guide](../tutorials/spe-da-vscode.md) to get started wit ### API Documentation -The SharePoint Embedded React TypeScript NPM Package, available at [here](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/feature/copilot-react-sdk/sharepointembedded-chatembedded-react/docs/index.md), provides the SDK for integrating SharePoint Embedded copilot into your client applications. +The SharePoint Embedded React TypeScript NPM Package, available at [here](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/feature/copilot-react-sdk/sharepointembedded-chatembedded-react/docs/index.md), provides the SDK for integrating SharePoint Embedded agent into your client applications. ## Frequently Asked Questions -### Is consumption-based billing available for SPE copilot? +### Is consumption-based billing available for SPE agent? -Currently you need a Microsoft 365 Copilot license enabled for your user to use SharePoint Embedded copilot. When consumption-based billing is enabled, you will no longer require a license, however, you will be required to use a Standard Container type. +Yes, starting May 15th you will need to use standard Container Type to use SPE agent within an SPE application. SharePoint Embedded agent interactions, including those from Microsoft 365 Copilot license users, will be billed to the Azure subscription associated with your Container Type. Learn more about [SharePoint Embedded billing management](/sharepoint/dev/embedded/administration/billing/billingmanagement) -***Trial Container Types expire after 30 days, for this reason we recommend starting off with Standard Container types. Currently there is no upgrade path from Trial to Standard container types.*** +***Trial Container Types expire after 30 days, for this reason we recommend starting off with Standard Container types. There is no upgrade path from Trial to Standard container types.*** -### Should I use a standard or trial container type? +### Should I use a standard or trial Container Type? -Once consumption-based billing is enabled, we will be disabling the use of this feature with Trial Container types and it will only be enabled on Standard container types going forward. Please follow this [guide](../../getting-started/containertypes.md) to get started on creating your Standard Container type. +Once consumption-based billing is enabled, we will be disabling the use of this feature with Trial Container Types and it will only be enabled on Standard Container Types going forward. Please follow this [guide](../../getting-started/containertypes.md) to get started on creating your Standard Container Type. -## SharePoint Embedded copilot Support +## SharePoint Embedded agent Support ### Chat Control Feedback Dialog -If you encounter any issues with the chat control, please use the thumbs up and down feedback buttons to report the problem. This method is preferred for sending feedback because it provides us with telemetry data that helps us diagnose and troubleshoot the issue more effectively. +If you encounter any issues with the chat control, please use the thumbs up or down feedback buttons to report the problem. This method is preferred for sending feedback because it provides us with telemetry data that helps us diagnose and troubleshoot the issue more effectively. When you click the thumbs down button, a feedback dialog will appear. Please include any relevant information in this dialog. -![SPE copilot Feedback Modal preview](../../images/speco-feedbackcombined.png) +![SPE agent Feedback Modal preview](../../images/speco-feedbackcombined.png) ## Advanced Topics Overview -The [advanced topics](spe-da-adv.md) delve into how SharePoint Embedded copilot use a semantic index to facilitate Retrieval-Augmented Generation (RAG), ensuring responses are accurately grounded in your stored content. You’ll also learn how to scope your copilot to specific data sources, set up various file formats, and configure locale options to tailor the copilot experience. By exploring concepts like grounding, semantic indexing, and RAG workflows, you can optimize your copilot’s effectiveness and maintain security within the Microsoft 365 boundary. +The [advanced topics](spe-da-adv.md) delve into how SharePoint Embedded agent use a semantic index to facilitate Retrieval-Augmented Generation (RAG), ensuring responses are accurately grounded in your stored content. You’ll also learn how to scope your agent to specific data sources, set up various file formats, and configure locale options to tailor the agent experience. By exploring concepts like grounding, semantic indexing, and RAG workflows, you can optimize your agent’s effectiveness and maintain security within the Microsoft 365 boundary. diff --git a/docs/embedded/development/limits-calling.md b/docs/embedded/development/limits-calling.md index fbfe89264..feb4fd012 100644 --- a/docs/embedded/development/limits-calling.md +++ b/docs/embedded/development/limits-calling.md @@ -1,7 +1,7 @@ --- title: Limits and Calling Patterns description: This article explains the limits of SharePoint Embedded. -ms.date: 11/16/2024 +ms.date: 05/21/2024 ms.localizationpriority: high --- @@ -10,15 +10,15 @@ ms.localizationpriority: high This document explains the limits of SharePoint Embedded during public preview. > [!NOTE] -> These are preview limits which are subject to change. +> These are preview limits that are subject to change. ## Size limits -The following table defines the size limits of containers" +The following table defines the size limits of containers: | Resource | Limit | | --------------------------------------------------------- | ------------------------------------------------------ | -| Container types that a partner tenant can create | 5* | +| Container types that a partner tenant can create | 25* | | Container types that an app can own | 1 | | Containers of a container type per consuming tenant | 100k* | | Storage per container type per consuming tenant | 100 TB* | @@ -44,7 +44,7 @@ In general, the following are the best practices to handle throttling: - Avoid request spikes. - Honor the `Retry-After` HTTP header. -In both cases, a `Retry-After` header is included in the response indicating how long the calling application should wait before retrying or making a new request. Throttled requests count towards usage limits, so failure to honor `Retry-After` might result in more throttling. +In both cases, a `Retry-After` header is included in the response, indicating how long the calling application should wait before retrying or making a new request. Throttled requests count towards usage limits, so failure to honor `Retry-After` might result in more throttling. ## API rate limits @@ -53,7 +53,7 @@ SharePoint Embedded provides various APIs. Different APIs have different costs d | Resource units per request | Operations | | -------------------------- | -------------------------------------------------------------------------- | | 1 | Single item query, such as get item | -| 2 | Multi-item query, such as list children Create, update, delete, and upload | +| 2 | Multi-item query, such as list children, create, update, delete, and upload | | 5 | All permission resource operations, including $expand=permissions | > [!NOTE] diff --git a/docs/embedded/development/tutorials/spe-da-vscode.md b/docs/embedded/development/tutorials/spe-da-vscode.md index d490aad6f..1a75bcce5 100644 --- a/docs/embedded/development/tutorials/spe-da-vscode.md +++ b/docs/embedded/development/tutorials/spe-da-vscode.md @@ -1,23 +1,23 @@ --- -title: Sharepoint Embedded copilot Tutorial -description: Sharepoint Embedded copilot Tutorial with the SDK and the VS Code SharePoint Embedded Extension -ms.date: 02/27/2025 +title: SharePoint Embedded agent Tutorial +description: Sharepoint Embedded agent tutorial with the SDK and the VS Code SharePoint Embedded Extension +ms.date: 06/10/2025 ms.localizationpriority: high --- -# Tutorial for getting started with SharePoint Embedded copilot +# Tutorial for getting started with SharePoint Embedded agent ## Prerequisites > [!NOTE] > -> 1. You will need to create create a SharePoint Embedded application. If you don't have one, you can easily build a sample application using the instructions [here](#getting-started-using-the-sharepoint-embedded-visual-studio-code-extension). -> 1. You must specify a standard container type at creation time. Depending on the purpose, you may or may not need to provide your Azure Subscription ID. A container type set for trial purposes can't be converted for production; or vice versa. +> 1. You will need to create a SharePoint Embedded application. If you don't have one, you can easily build a sample application using the instructions [here](#getting-started-using-the-sharepoint-embedded-visual-studio-code-extension). +> 1. You must specify a standard container type at creation time. Depending on the purpose, you may or may not need to provide your Azure Subscription ID. A container type set for trial purposes can't be converted for production, or vice versa. > 1. You must use the latest version of SharePoint PowerShell to configure a container type. For permissions and the most current information about Windows PowerShell for SharePoint Embedded, see the documentation at [Intro to SharePoint Embedded Management Shell](/powershell/SharePoint/SharePoint-online/introduction-SharePoint-online-management-shell). > -> - Set the **ChatEmbeddedHosts** property of your container type configuration to `http://localhost:8080` to be able to work through the quick start below, refer to [the CSP section above for more information](../declarative-agent/spe-da-adv.md#csp-policies) -> - Set the **DiscoverabilityDisabled** property of your container type configuration to `false` so that copilot can find the files in your created container refer to the [Discoverability Disabled section above for more information](../declarative-agent/spe-da-adv.md#discoverabilitydisabled) -> - Ensure that copilot for Microsoft 365 is available for your organization. You have two ways to get a developer environment for copilot: +> - Set the **CopilotChatEmbeddedHosts** property of your container type configuration to `http://localhost:8080` to be able to work through the quick start below, refer to [the CSP section above for more information](../declarative-agent/spe-da-adv.md#csp-policies). +> - Set the **DiscoverabilityDisabled** property of your container type configuration to `false` so that the agent can find the files in your created container. Refer to the [Discoverability Disabled section above for more information](../declarative-agent/spe-da-adv.md#discoverabilitydisabled). +> - Ensure that Copilot for Microsoft 365 is available for your organization. You have two ways to get a developer environment for Copilot: > - A sandbox Microsoft 365 tenant with M365 Copilot (available in limited preview through [TAP membership](https://developer.microsoft.com/microsoft-365/tap)). > - An [eligible Microsoft 365 or Office 365 production environment](/microsoft-365-copilot/extensibility/prerequisites#customers-with-existing-microsoft-365-and-copilot-licenses) with a M365 Copilot license. @@ -28,7 +28,7 @@ ms.localizationpriority: high ```console # Install the SDK with npm -npm install "https://download.microsoft.com/download/e2d6b1ec-7168-4787-b8de-4a9862f10744/microsoft-sharepointembedded-copilotchat-react-1.0.8.tgz" +npm install "https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz" ``` #### If you want to verify checksums @@ -36,11 +36,11 @@ npm install "https://download.microsoft.com/download/e2d6b1ec-7168-4787-b8de-4a9 In MacOS/Linux ```console -version="1.0.8"; +version="1.0.9"; -url="https://download.microsoft.com/download/e2d6b1ec-7168-4787-b8de-4a9862f10744/microsoft-sharepointembedded-copilotchat-react-1.0.8.tgz"; +url="https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz"; -expected_checksum="16E652BBD2A1990D488060EE4E3C02917D782DE013568A6FC5C37C170D307F99"; +expected_checksum="3bdf19830ffc098b253cc809f969f50fba236ad95fe85123e7b15c7cf58ecf6b"; package_path="microsoft-sharepointembedded-copilotchat-react-$version.tgz"; @@ -50,9 +50,9 @@ curl -o $package_path $url && [ "$(sha256sum $package_path | awk '{ print $1 }') In Windows: ```powershell -$version = "1.0.8" -$url = "https://download.microsoft.com/download/e2d6b1ec-7168-4787-b8de-4a9862f10744/microsoft-sharepointembedded-copilotchat-react-1.0.8.tgz" -$expected_checksum = "16E652BBD2A1990D488060EE4E3C02917D782DE013568A6FC5C37C170D307F99" +$version = "1.0.9" +$url = "https://download.microsoft.com/download/970802a5-2a7e-44ed-b17d-ad7dc99be312/microsoft-sharepointembedded-copilotchat-react-1.0.9.tgz" +$expected_checksum = "3BDF19830FFC098B253CC809F969F50FBA236AD95FE85123E7B15C7CF58ECF6B" $package_path = "microsoft-sharepointembedded-copilotchat-react-$version.tgz" Invoke-WebRequest -Uri $url -OutFile $package_path @@ -323,18 +323,18 @@ function App() { ![VS Code file explorer with ChatSideBar.tsx in open window with relevant code to uncomment highlighted](../../images/speco-uncommentchatsidebar.png) -1. Navigate to `react-client\src\routes\App.tsx` and set the react state of the showSidebar variable to `true` +1. Navigate to `react-client\src\routes\App.tsx` and set the React state of the `showSidebar` variable to `true` ![VS Code file explorer with App.tsx open with line of showSidebar variable useState function input changed from false to true to enable showing chat side bar](../../images/speco-setshowsidebartrue.png) -1. You can follow the instructions of the `README.md` file in the root of the project for further npm commands. Run `npm run start` in the root of the project to start your application with the SPE copilot functionality enabled. +1. You can follow the instructions of the `README.md` file in the root of the project for further npm commands. Run `npm run start` in the root of the project to start your application with the SPE agent functionality enabled. > [!NOTE] > `npm run start` Should be done in the root folder of the sample project. `\SharePoint-Embedded-Samples\Samples\spe-typescript-react-azurefunction` ![VS Code terminal in root folder of SPE Typescript project cloned earlier and npm run start command typed in](../../images/speco-runnpmrunstart.png) -1. Sign in with a user who has an M365 Copilot license enabled. +1. Sign in with a user who has a Microsoft 365 Copilot license enabled. ![SPE Typescript App running in Edge with sign in buttons](../../images/speco-reacttypescripthomepage.png) @@ -346,7 +346,7 @@ function App() { ![SPE Typescript App running in edge with a created container from above ContosoCompanyContainer](../../images/speco-createdcontainer.png) -1. Click the container and upload your files. Once a container has been created and you have navigated inside it, your copilot chat experience will become enabled. +1. Click the container and upload your files. Once a container has been created and you have navigated inside it, your agent chat experience will become enabled. ![SPE Typescript App running in edge inside a created container page of ContosoCompanyContainer](../../images/speco-spechatenabled.png) diff --git a/docs/embedded/getting-started/spembedded-for-vscode.md b/docs/embedded/getting-started/spembedded-for-vscode.md index de401ff69..343a842f5 100644 --- a/docs/embedded/getting-started/spembedded-for-vscode.md +++ b/docs/embedded/getting-started/spembedded-for-vscode.md @@ -1,7 +1,7 @@ --- title: SharePoint Embedded for Visual Studio Code description: Installation and getting started with SharePoint Embedded for Visual Studio Code -ms.date: 03/03/2025 +ms.date: 07/16/2025 ms.localizationpriority: high --- @@ -10,34 +10,40 @@ ms.localizationpriority: high The SharePoint Embedded Visual Studio Code extension helps developers get started for free with SharePoint Embedded application development. > [!IMPORTANT] -> To start building with SharePoint Embedded you will need administrative access to Microsoft 365 tenant. -> If you do not already have a tenant, you can get your own tenant with the [Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program), [Microsoft Customer Digital Experience](https://cdx.transform.microsoft.com/), or create a free trial of an [Microsoft 365 E3 license](https://www.microsoft.com/microsoft-365/enterprise/microsoft365-plans-and-pricing). +> To start building with SharePoint Embedded, you'll need administrative access to a Microsoft 365 tenant. +> If you don't already have a tenant, you can get your own tenant with the [Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program), [Microsoft Customer Digital Experience](https://cdx.transform.microsoft.com/), or create a free trial of a [Microsoft 365 E3 license](https://www.microsoft.com/microsoft-365/enterprise/microsoft365-plans-and-pricing). ## Install SharePoint Embedded for Visual Studio Code 1. Open a new window in [Visual Studio Code](https://code.visualstudio.com/) and navigate to "**Extensions**" on the activity bar. 1. Search "SharePoint Embedded" in the Extensions view. You can also view the extension in [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=SharepointEmbedded.ms-sharepoint-embedded-vscode-extension). 1. Select **"Install"** and the SharePoint Embedded icon will appear on the activity bar. +1. If already installed, please update to the latest version if one is available. 1. Select the icon to open the SharePoint Embedded view and create a container type with trial configuration. ![SharePoint Embedded VS Extensions](../images/vsx-images/n1downloadvsx.png) ### Sign in with admin credentials -To use the extension, you must sign into a Microsoft 365 tenant with an administrator account. - -If you don't already have a tenant, you can get a tenant through the [Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program), [Microsoft Customer Digital Experience](https://cdx.transform.microsoft.com/), or create a free trial of an [Microsoft 365 E3 license](https://www.microsoft.com/en-us/microsoft-365/enterprise/microsoft365-plans-and-pricing). +To use the extension, you must sign in to a Microsoft 365 tenant with an administrator account. ![Install](../images/vsx-images/n2vsx-signin.png) - Authentication opens a new tab in an external browser to grant permissions -- Select **Accept** on the pop-up window prompting admin consent + + ![authorize and authenticate the extension to your M365 Entra tenant](../images/vsx-images/auth-allow-extension-uri.png) + +- Review the requested permissions carefully, then select **Accept** on the pop-up window prompting admin consent -![consentperms](../images/vsx-images/n3vsx-grant-admin-consent.png) + ![review before consenting to the permissions the extension is asking for](../images/vsx-images/n3vsx-grant-admin-consent.png) + +After successful authorization, select open on the dialog to be redirected to VSCode: + +![authorization completed in browser now redirecting to visual studio code](../images/vsx-images/auth-redirect.png) ## Create a container type with a trial configuration -Once signed in, you are prompted to create a [container type with trial configuration](./containertypes.md#trial-container-type). A container type lets you get started calling SharePoint Embedded APIs and building a proof-of-concept application using SharePoint Embedded. Learn more about [container types](containertypes.md). +Once signed in, you're prompted to create a [container type with trial configuration](./containertypes.md#trial-container-type). A container type lets you get started calling SharePoint Embedded APIs and building a proof-of-concept application using SharePoint Embedded. Learn more about [container types](containertypes.md). ![home screen](../images/vsx-images/n4vsx-home-screen.png) @@ -60,20 +66,25 @@ Every container type is owned by a Microsoft Entra ID application. The first ste > [!NOTE] > If you choose an existing application, the extension will update that app's configuration settings for it to work with both SharePoint Embedded and this extension. Doing this is NOT recommended on production applications. -After your container type is created and your application is configured, you'll be able to view your Local tenant registration as a tree in the left nav-bar. +After your container type is created and your application is configured, you'll be able to view your local tenant registration as a tree in the left nav-bar. ## Register your container type After creating your container type, you'll need to register that container type on your local tenant. Learn more about container type [registration](./register-api-documentation.md). - Follow the prompts and select **Register on local tenant** on the lower right corner of the VS Code window + + ![local tenant registration popup](../images/vsx-images/local-tenant-registration-popup.png) + - If you don't see the prompt, you can right-click on your `` and select **Register** from the menu -![register](../images/vsx-images/n7aregister-ct.png) + ![register](../images/vsx-images/n7aregister-ct.png) + +### Grant permissions -#### Grant permissions +Review permissions and follow the prompt to grant admin consent -When registering your container type you'll need to grant permissions to access your application +![grant admin consent popup](../images/vsx-images/auth-grant-admin-consent-popup.png) An external browser window will pop open for you to sign-in and grant admin consent @@ -103,8 +114,63 @@ With your free trial container type created, you can use the extension to load o ![Load Sample App](../images/vsx-images/n15vsxsa-c.png) +When loading the sample application, you'll be notified that it will create plain text secrets to authenticate on your local machine. + +![sample app plain text secrets notice](../images/vsx-images/sample-app-app-secrets-notice.png) + +If no client secret is found on your application, it will ask if you would like to create one. Press OK to proceed. + +![sample app creating client secret](../images/vsx-images/sample-app-create-client-secret.png) + +> [!IMPORTANT] +> This isn't intended for production environments. [Find out more on how to setup Application Registration for production environments here.](/entra/identity-platform/quickstart-register-app) + +## Using Sample App + +In your terminal, run the following command, this will start the sample application, which consists of 2 parts: + +1. **React Client Application** - The frontend user interface running on port 8080 +1. **Azure Function Application Server** - The backend API server that handles SharePoint Embedded operations + +```console +# Navigate to your sample application directory +cd [your-path]\SharePoint-Embedded-Samples\Samples\spe-typescript-react-azurefunction + +# Install dependencies and start the application +npm run start +``` + +> [!NOTE] +> The initial startup may take a few minutes as dependencies are installed and both applications are built. Wait for both console outputs to appear before navigating to the application. + +This will install the dependencies and run the server and client application, once running, you'll see the following in the terminal, after which you can navigate to http://localhost:8080 to access the application. + +![function api console logs](../images/vsx-images/fn-api-logs.png) + +![client app console logs](../images/vsx-images/client-app-logs.png) + +Once both applications are running successfully: + +1. Open your web browser and navigate to **http://localhost:8080** +1. Sign in using your Microsoft 365 administrator account (the same account used in the VS Code extension) +1. On the home page, select **"Containers"** to begin creating containers and uploading files +1. Follow the on-screen prompts to interact with your SharePoint Embedded containers + +![home-page-for-spe-sample-app](../images/vsx-images/spe-sample-app-home.png) + +> [!IMPORTANT] +> This sample application stores authentication secrets in plain text for development purposes only. Never use this configuration in a production environment. + +### Troubleshooting + +If you encounter issues: + +- **Port already in use**: If port 8080 is already in use, the application will automatically try the next available port +- **Dependencies not installing**: Try running `npm install` manually before `npm run start` +- **Authentication errors**: Ensure your Microsoft Entra ID app is properly configured with the correct redirect URIs + ## Export Postman Environment -The [SharePoint Embedded Postman Collection](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/main/Postman) allows you to explore and call the SharePoint Embedded APIs. The Collection requires an environment file with variables used for authentication and various identifiers. This extension automates the generation of this populated environment file so you can import it into Postman and immediately call the SharePoint Embedded APIs. +The [SharePoint Embedded Postman Collection](https://github.com/microsoft/SharePoint-Embedded-Samples/tree/main/Postman) allows you to explore and call the SharePoint Embedded APIs. The Collection requires an environment file with variables used for authentication and various identifiers. This extension automates the generation of this populated environment file so you can import it into Postal worker and immediately call the SharePoint Embedded APIs. ![Export Postman Environment](../images/vsx-images/n14postman-c.png) diff --git a/docs/embedded/images/add-owners-one.png b/docs/embedded/images/add-owners-one.png new file mode 100644 index 000000000..bba134252 Binary files /dev/null and b/docs/embedded/images/add-owners-one.png differ diff --git a/docs/embedded/images/add-owners-two.png b/docs/embedded/images/add-owners-two.png new file mode 100644 index 000000000..fe7af04ed Binary files /dev/null and b/docs/embedded/images/add-owners-two.png differ diff --git a/docs/embedded/images/filter-on-delete.png b/docs/embedded/images/filter-on-delete.png new file mode 100644 index 000000000..87599873d Binary files /dev/null and b/docs/embedded/images/filter-on-delete.png differ diff --git a/docs/embedded/images/filter.png b/docs/embedded/images/filter.png new file mode 100644 index 000000000..6f1eacbeb Binary files /dev/null and b/docs/embedded/images/filter.png differ diff --git a/docs/embedded/images/reassign-user.png b/docs/embedded/images/reassign-user.png new file mode 100644 index 000000000..5ae1447ed Binary files /dev/null and b/docs/embedded/images/reassign-user.png differ diff --git a/docs/embedded/images/remove-user.png b/docs/embedded/images/remove-user.png new file mode 100644 index 000000000..ffa8d357a Binary files /dev/null and b/docs/embedded/images/remove-user.png differ diff --git a/docs/embedded/images/search.png b/docs/embedded/images/search.png new file mode 100644 index 000000000..02c1c3ffc Binary files /dev/null and b/docs/embedded/images/search.png differ diff --git a/docs/embedded/images/sensitivity-label.png b/docs/embedded/images/sensitivity-label.png new file mode 100644 index 000000000..5180a30a0 Binary files /dev/null and b/docs/embedded/images/sensitivity-label.png differ diff --git a/docs/embedded/images/sorting-on-deleted.png b/docs/embedded/images/sorting-on-deleted.png new file mode 100644 index 000000000..961e81d55 Binary files /dev/null and b/docs/embedded/images/sorting-on-deleted.png differ diff --git a/docs/embedded/images/sorting.png b/docs/embedded/images/sorting.png new file mode 100644 index 000000000..3f495f85c Binary files /dev/null and b/docs/embedded/images/sorting.png differ diff --git a/docs/embedded/images/vsx-images/auth-allow-extension-uri.png b/docs/embedded/images/vsx-images/auth-allow-extension-uri.png new file mode 100644 index 000000000..f71029396 Binary files /dev/null and b/docs/embedded/images/vsx-images/auth-allow-extension-uri.png differ diff --git a/docs/embedded/images/vsx-images/auth-grant-admin-consent-popup.png b/docs/embedded/images/vsx-images/auth-grant-admin-consent-popup.png new file mode 100644 index 000000000..a8b8485e7 Binary files /dev/null and b/docs/embedded/images/vsx-images/auth-grant-admin-consent-popup.png differ diff --git a/docs/embedded/images/vsx-images/auth-redirect.png b/docs/embedded/images/vsx-images/auth-redirect.png new file mode 100644 index 000000000..ee09cc6bb Binary files /dev/null and b/docs/embedded/images/vsx-images/auth-redirect.png differ diff --git a/docs/embedded/images/vsx-images/client-app-logs.png b/docs/embedded/images/vsx-images/client-app-logs.png new file mode 100644 index 000000000..61c81ce0f Binary files /dev/null and b/docs/embedded/images/vsx-images/client-app-logs.png differ diff --git a/docs/embedded/images/vsx-images/fn-api-logs.png b/docs/embedded/images/vsx-images/fn-api-logs.png new file mode 100644 index 000000000..dc0263c40 Binary files /dev/null and b/docs/embedded/images/vsx-images/fn-api-logs.png differ diff --git a/docs/embedded/images/vsx-images/local-tenant-registration-popup.png b/docs/embedded/images/vsx-images/local-tenant-registration-popup.png new file mode 100644 index 000000000..e233afcf7 Binary files /dev/null and b/docs/embedded/images/vsx-images/local-tenant-registration-popup.png differ diff --git a/docs/embedded/images/vsx-images/sample-app-app-secrets-notice.png b/docs/embedded/images/vsx-images/sample-app-app-secrets-notice.png new file mode 100644 index 000000000..1ade7d0fb Binary files /dev/null and b/docs/embedded/images/vsx-images/sample-app-app-secrets-notice.png differ diff --git a/docs/embedded/images/vsx-images/sample-app-create-client-secret.png b/docs/embedded/images/vsx-images/sample-app-create-client-secret.png new file mode 100644 index 000000000..2bddaef4f Binary files /dev/null and b/docs/embedded/images/vsx-images/sample-app-create-client-secret.png differ diff --git a/docs/embedded/images/vsx-images/spe-sample-app-home.png b/docs/embedded/images/vsx-images/spe-sample-app-home.png new file mode 100644 index 000000000..575c8da11 Binary files /dev/null and b/docs/embedded/images/vsx-images/spe-sample-app-home.png differ diff --git a/docs/embedded/whats-new.md b/docs/embedded/whats-new.md new file mode 100644 index 000000000..4a0ba7af0 --- /dev/null +++ b/docs/embedded/whats-new.md @@ -0,0 +1,19 @@ +--- +title: What's new in SharePoint Embedded? +description: Updates about Microsoft SharePoint Embedded. +ms.date: 06/23/2025 +ms.localizationpriority: medium +--- + +# What's new in SharePoint Embedded + +## June 2025 + +- The `CopilotEmbeddedChatHosts` container type setting is now required to use [SharePoint Embedded agent](./development/declarative-agent/spe-da-adv.md#csp-policies). It must be set by the application owner via [`Set-SPOContainerTypeConfiguration`](/powershell/module/sharepoint-online/set-spocontainertypeconfiguration) and can optionally be overridden by consuming tenant administrators via [`Set-SPOApplication`](/powershell/module/SharePoint-online/set-spoapplication). + +## May 2025 + +- The limit of container types that a partner tenant can create has been increased to 25 by default. See [Limits and Calling Patterns](./development/limits-calling.md#size-limits). +- SharePoint Embedded agent switched to a consumption-based model for all users regardless of whether they have a Copilot license or not. See [SharePoint Embedded agent](./development/declarative-agent/spe-da.md). +- The guidance on how to grant admin consent to a SharePoint Embedded application has been updated to use URL-based admin consent. See [Authentication and authorization](./development/auth.md#whats-next). +- Documented an exceptional access pattern for operations that may require a user license. See [Authentication and authorization](./development/auth.md#operations-that-require-a-user-license). diff --git a/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md b/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md index 6798bf0f7..f239f0fb8 100644 --- a/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md +++ b/docs/general-development/how-to-avoid-getting-throttled-or-blocked-in-sharepoint-online.md @@ -1,7 +1,7 @@ --- title: Avoid getting throttled or blocked in SharePoint Online description: Learn about throttling in SharePoint Online and learn how to avoid being throttled or blocked. -ms.date: 04/11/2025 +ms.date: 06/12/2025 ms.assetid: 33ed8106-d850-42b1-8d7f-5ba83901149c ms.localizationpriority: high --- @@ -22,6 +22,7 @@ Does this sound familiar? You're running an application - for example, to scan f ## What is throttling? SharePoint Online uses throttling to maintain the optimal performance and reliability of the SharePoint Online service. Throttling limits the number of API calls or operations within a time window to prevent the overuse of resources. + > [!NOTE] > Recent updates to this article enhance transparency to already existing throttling rules in the system @@ -31,23 +32,23 @@ When usage limits are exceeded, SharePoint Online throttles any further requests For requests that a user performs directly in the browser, SharePoint Online redirects you to the throttling information page, and the requests fail. -For requests that an application makes, including [Microsoft Graph](/graph), CSOM, or REST calls, SharePoint Online returns HTTP status code 429 ("Too many requests") or 503 ("Server Too Busy") and the requests will fail. +For requests that an application makes, including [Microsoft Graph](/graph), CSOM, or REST calls, SharePoint Online returns HTTP status code 429 ("Too many requests") or 503 ("Server Too Busy"), and the requests will fail. - HTTP 429 indicates the calling application sent too many requests in a time window and exceeded a predetermined limit. - HTTP 503 indicates the service isn't ready to handle the request. The common cause is that the service is experiencing more temporary load spikes. -In both cases, a `Retry-After` header is included in the response indicating how long the calling application should wait before retrying or making a new request. Throttled requests count towards usage limits, so failure to honor `Retry-After` may result in more throttling. +In both cases, a `Retry-After` header is included in the response, indicating how long the calling application should wait before retrying or making a new request. Throttled requests count towards usage limits, so failure to honor `Retry-After` may result in more throttling. If the offending application continues to exceed usage limits, SharePoint Online may completely block the application or specific request patterns from the application; in this case, the application will keep getting HTTP status code 503, and Microsoft will notify the tenant of the block in the Office 365 Message Center. ### Resource units -Some limits are measured in terms of API costs, [Microsoft Graph APIs](/graph) have a predetermined resource unit cost per request: +Some limits are measured in terms of API costs. [Microsoft Graph APIs](/graph) have a predetermined resource unit cost per request: -| Resource units per request | Operations | -| -------------------------- | ------------------------------------------------------------------------------------------------------------ | -| 1 |
  • Single item query, such as get item
  • Delta with a token
  • Download file from drive item | -| 2 |
  • Multi item query, such as list children, except delta with a token
  • Create, update, delete and upload | +| Resource units per request | Operations | +| -------------------------- | -------------------------------------------------------------------------------------------------------------- | +| 1 |
  • Single item query, such as get item
  • Delta with a token
  • Download file from drive item | +| 2 |
  • Multi item query, such as list children, except delta with a token
  • Create, update, delete, and upload | | 5 |
  • All permission resource operations, including `$expand=permissions` | > [!NOTE] @@ -57,11 +58,11 @@ Some limits are measured in terms of API costs, [Microsoft Graph APIs](/graph) h Throttling limits the number of calls and operations collectively made by applications on behalf of a user to prevent the overuse of resources. -That said, it's rare for a user to get throttled in SharePoint Online. The service is robust, and it's designed to handle high volume. If you do get throttled, 99% of the time it is because of custom code, such as custom web parts, complex list view and queries, or custom apps users run. That doesn’t mean that there aren’t other ways to get throttled, just that they’re less common. For example, one user syncing a large amount of data across 10 machines at the same time could trigger throttling. +That said, it's rare for a user to get throttled in SharePoint Online. The service is robust, and it's designed to handle high volume. If you do get throttled, 99% of the time it is because of custom code, such as custom web parts, complex list views and queries, or custom apps users run. That doesn’t mean that there aren’t other ways to get throttled, just that they’re less common. For example, one user syncing a large amount of data across 10 machines at the same time could trigger throttling. | Category | Type of throttling | Time interval | Limit | |--------------|------------------------------|-------------------|-----------| -| User | RPS | 5 min | 3,000 | +| User | Requests | 5 min | 3,000 | | User | Ingress | 1 H | 50 GB | | User | Egress | 1 H | 100 GB | | User | Delegation Token Request | 5 min | 50 | @@ -74,15 +75,15 @@ That said, it's rare for a user to get throttled in SharePoint Online. The servi Some throttling limits are applied at the Tenant level to ensure the operations collectively made do not overuse resources. -When a customer enables Multi-Geo, each geo gets its own limits (usage measurement not shared across geos). For the limits that are dependent on license count, the total tenant user license counts is used (total users across all geos). +When a customer enables Multi-Geo, each geo gets its own limits (usage measurement not shared across geos). For the limits that are dependent on license count, the total tenant user license count is used (total users across all geos). | Category | Type of throttling | Time interval | Tenant license count | Limit | |--------------|--------------------------------------|-------------------|--------------------------|-----------| -| Tenant | [Resource Units](#resource-units) | 5 min | 0 - 1,000 | 18,750 | -| Tenant | [Resource Units](#resource-units) | 5 min | 1,001 - 5,000 | 37,500 | -| Tenant | [Resource Units](#resource-units) | 5 min | 5,001 - 15,000 | 56,250 | -| Tenant | [Resource Units](#resource-units) | 5 min | 15,001 - 50,000 | 75,000 | -| Tenant | [Resource Units](#resource-units) | 5 min | 50,000+ | 93,750 | +| Tenant | [Resource Units](#resource-units) | 5 min | 0 - 1,000 | 18,750 | +| Tenant | [Resource Units](#resource-units) | 5 min | 1,001 - 5,000 | 37,500 | +| Tenant | [Resource Units](#resource-units) | 5 min | 5,001 - 15,000 | 56,250 | +| Tenant | [Resource Units](#resource-units) | 5 min | 15,001 - 50,000 | 75,000 | +| Tenant | [Resource Units](#resource-units) | 5 min | 50,000+ | 93,750 | | Tenant | Assign Sensitivity Label | 5 min | no license bound | 100 | | Tenant | PeopleManagerAPIs | 5 min | 0 - 1,000 | 3,000 | | Tenant | PeopleManagerAPIs | 5 min | 1,001 - 5,000 | 6,000 | @@ -119,9 +120,9 @@ For multitenant applications: | Per APP Per Tenant | [Resource Units](#resource-units) | 1 min | 5,001 - 15,000 | 3,750 | | Per APP Per Tenant | [Resource Units](#resource-units) | 1 min | 15,001 - 50,000 | 5,000 | | Per APP Per Tenant | [Resource Units](#resource-units) | 1 min | 50,000+ | 6,250 | -| Per APP Per Tenant | Ingress | 1 H | no license bound | 400 GB | -| Per APP Per Tenant | Egress | 1 H | no license bound | 400 GB | -| Per APP Per Tenant | Specific Sharing APIs | 5 min | no license bound | 300 | +| Per APP Per Tenant | Ingress | 1 H | no license bound | 400 GB | +| Per APP Per Tenant | Egress | 1 H | no license bound | 400 GB | +| Per APP Per Tenant | Specific Sharing APIs | 5 min | no license bound | 300 | > [!NOTE] > Displayed limits are default values. Microsoft may change these limits at any time. Your experience may vary @@ -130,7 +131,7 @@ For multitenant applications: | Category | Type of throttling | Time interval | Limit | |-------------------------------|--------------------------------------|-------------------|-----------| -| SharePoint Embedded containers| [Resource Units](#resource-units) | 1 min | 3,000 | +| SharePoint Embedded containers| [Resource Units](#resource-units) | 1 min | 3,000 | | Per Site | Anonymous Link | 5 min | 3,000 | | Per Site | Anonymous Egress (Download) | 2 H | 100 GB | | Per Site | External sharing emails | 1 H | 200 | @@ -146,23 +147,23 @@ Below is a quick summary of the best practices to handle throttling: - Avoid request spikes - Choose [Microsoft Graph APIs](/graph) over CSOM and REST APIs when possible - Use the `Retry-After` and `RateLimit` HTTP headers -- Decorate your traffic so we know who you are (see section on traffic decoration best practice more on that below) -- Consider using [Graph Data Connect for SharePoint](https://techcommunity.microsoft.com/blog/microsoft_graph_data_connect_for_sharepo/links-about-microsoft-graph-data-connect-for-sharepoint/4069045) for broad sites analytics +- Decorate your traffic so we know who you are (see section on traffic decoration best practice, more on that below) +- Consider using [Graph Data Connect for SharePoint](https://techcommunity.microsoft.com/blog/microsoft_graph_data_connect_for_sharepo/links-about-microsoft-graph-data-connect-for-sharepoint/4069045) for broad site analytics - Understand if [service prioritization in SharePoint](https://aka.ms/SharePointPrioritization) is the right fit for your scenario As stated earlier, [Microsoft Graph](/graph) is cloud born APIs that have the latest improvements and optimizations. In general, [Microsoft Graph](/graph) consumes fewer resources than CSOM and REST to achieve the same functionality. Hence, adopting [Microsoft Graph](/graph) can improve the application's performance and reduce throttling. -If you do run into throttling, we require using the `Retry-After` HTTP header to ensure minimum delay until the throttle is removed. The `RateLimit` HTTP headers send you early signals when you're close to limits and you can proactively reduce requests to avoid hitting the throttle. +If you do run into throttling, we require using the `Retry-After` HTTP header to ensure minimum delay until the throttle is removed. The `RateLimit` HTTP headers send you early signals when you're close to limits, and you can proactively reduce requests to avoid hitting the throttle. Delta with a token is the most efficient way to scan content in SharePoint, and we talk more in detail at the [best practices for scanning applications](https://aka.ms/ScanGuidance). To help applications that follow the guidance, we lower the resource unit cost of delta requests with a token to 1 resource unit, although it's a multi-item query. The delta request without a token is considered a multi-item query and costs 2 resource units per request. In [batching](/graph/json-batching), requests in a batch are evaluated individually by resource units. -CSOM and REST don't have a predetermined resource unit cost and they usually consume more resource units than [Microsoft Graph APIs](/graph) to achieve the same functionality. In addition to resource unit limits, CSOM and REST are also subject to other internal resource limits, so if applications call CSOM and REST, they may experience more throttling than the limits described in this document. We highly recommend you choose [Microsoft Graph APIs](/graph) over CSOM and REST APIs when possible. +CSOM and REST don't have a predetermined resource unit cost, and they usually consume more resource units than [Microsoft Graph APIs](/graph) to achieve the same functionality. In addition to resource unit limits, CSOM and REST are also subject to other internal resource limits, so if applications call CSOM and REST, they may experience more throttling than the limits described in this document. We highly recommend you choose [Microsoft Graph APIs](/graph) over CSOM and REST APIs when possible. -Since application limits are in resource units, the actual request rate, such as requests per minute, depends on the application’s API choice and the corresponding API resource unit cost. In general, you can estimate the request rate using an average of 2 resource units per request and divide resource unit limits by 2 to get the estimated request rate. +Since application limits are in resource units, the actual request rate, such as requests per minute, depends on the application’s API choice and the corresponding API resource unit cost. In general, you can estimate the request rate using an average of 2 resource units per request, and divide resource unit limits by 2 to get the estimated request rate. -Although each application has its limits within a tenant and we allow tenants to run more than one application, multiple applications running against the same tenant share the same resource bucket, and in rare occurrences can cause rate limiting when too many applications send requests at the time. +Although each application has its limits within a tenant, and we allow tenants to run more than one application, multiple applications running against the same tenant share the same resource bucket, and in rare occurrences can cause rate limiting when too many applications send requests at the time. ### Retry-after header @@ -174,7 +175,7 @@ Throttled requests count towards usage limits, so failure to honor `Retry-After` ### RateLimit headers - preview -In addition to the `Retry-After` header in the response to throttled requests, SharePoint Online also returns the [IETF RateLimit headers](https://github.com/ietf-wg-httpapi/ratelimit-headers) for selected limits in certain conditions to help applications manage rate limiting. We recommend applications to take advantage of these headers to avoid hitting throttle. +In addition to the `Retry-After` header in the response to throttled requests, SharePoint Online also returns the [IETF RateLimit headers](https://github.com/ietf-wg-httpapi/ratelimit-headers) for selected limits in certain conditions to help applications manage rate limiting. We recommend applications to take advantage of these headers to avoid hitting the throttle. - `RateLimit-Limit` contains the limit in the current time window. - `RateLimit-Remaining` indicates the remaining quota in the current window. @@ -201,7 +202,7 @@ Below are some examples to help you understand the `RateLimit` headers: RateLimit-Reset: 5 ``` -- An application has consumed 100% of its resource unit quota, so it gets throttled due to this policy. The request is throttled and the `RateLimit` headers are returned. The `Retry-After` matches the `RateLimit-Reset`. +- An application has consumed 100% of its resource unit quota, so it gets throttled due to this policy. The request is throttled, and the `RateLimit` headers are returned. The `Retry-After` matches the `RateLimit-Reset`. There are instances where the `Retry-After` returns a smaller value. In such cases, the general rule of thumb is to honor the greater of the two values. ``` HTTP/1.1 429 Too Many Requests @@ -211,7 +212,7 @@ Below are some examples to help you understand the `RateLimit` headers: RateLimit-Reset: 31 ``` -- An application has consumed 90% of its resource unit quota but its consumption has already reached other limits that the `RateLimit` headers don't support. In this case, the request is throttled and the `RateLimit` headers aren't returned to avoid confusion although the condition to return the headers is satisfied. +- An application has consumed 90% of its resource unit quota, but its consumption has already reached other limits that the `RateLimit` headers don't support. In this case, the request is throttled and the `RateLimit` headers aren't returned to avoid confusion, although the condition to return the headers is satisfied. ``` HTTP/1.1 429 Too Many Requests @@ -268,19 +269,19 @@ The most common causes of per-user throttling in SharePoint Online are client-si - **Unsupported use cases** - Unsupported use of SharePoint Online may experience throttling. Using SharePoint and OneDrive as an intermediary service between Microsoft 365 and another repository is an example of an unsupported use case. + Unsupported use of SharePoint Online may result in throttling. Using SharePoint and OneDrive as an intermediary service between Microsoft 365 and another repository is an example of an unsupported use case. - **Creating multiple AppIDs for the same application** - Don't create separate AppIDs where the applications essentially perform the same operations, such as backup or data loss prevention. Applications running against the same tenant ultimately share the same resource as the tenant. Historically some applications have tried this approach to get around the application throttling but ended up exhausting the tenant’s resource and causing multiple applications to be throttled in the tenant. + Don't create separate AppIDs where the applications essentially perform the same operations, such as backup or data loss prevention. Applications running against the same tenant ultimately share the same resources as the tenant. Historically, some applications have tried this approach to get around the application throttling but ended up exhausting the tenant’s resource and causing multiple applications to be throttled in the tenant. ## Scenario specific limits ### When using app-only authentication with Sites.Read.All permission -When you're using SharePoint Online search APIs with app-only authentication and the app having **Sites.Read.All** permission (or stronger), the app will be registered with full permissions, and is allowed to query all your SharePoint Online content (including the user’s private OneDrive for Business content). +When you're using SharePoint Online search APIs with app-only authentication and the app has **Sites.Read.All** permission (or stronger), the app will be registered with full permissions, and is allowed to query all your SharePoint Online content (including the user’s private OneDrive for Business content). -To ensure the service remains fast and reliable, queries using such permission are throttled at 25 requests per second. The search query will return an HTTP 429 response. When waiting for throttling recovery, you should ensure to pause all search query requests you may be making to the service using similar app-only permission. Making more calls while receiving throttle responses will extend the time it takes for your app to become unthrottled. +To ensure the service remains fast and reliable, queries using such permission are throttled at 25 requests per second. The search query will return an HTTP 429 response. When waiting for throttling recovery, you should ensure to pause all search query requests you may be making to the service using a similar app-only permission. Making more calls while receiving throttle responses will extend the time it takes for your app to become unthrottled. ### When searching using delegated user permissions @@ -292,7 +293,7 @@ To ensure service stability, the service will throttle delegated user requests t When searching using a result source that requests people results, we may throttle any requests exceeding an organization-wide limit of 25 requests per second. This limit applies to all SharePoint search CSOM and REST requests using either the out-of-the-box "Local People Results" result source or a custom people search result source. -If you have applications or components, that are causing your people search requests to get throttled, we recommend that you: +If you have applications or components that are causing your people search requests to get throttled, we recommend that you: 1. Consider if the requests are necessary for your application. For example, if you're using a custom search site, that makes many simultaneous queries, check whether some of those requests can be removed without any significant impact on your organization's search experience. Alternatively, consider trying our modern people search experience in [Microsoft Search](/microsoftsearch/get-started-search-in-sharepoint-online) by searching from the [SharePoint](https://sharepoint.com/) start page. People search in Microsoft Search has been optimized for better performance and more relevant results. 1. Avoid making concurrent requests. For example, instead of issuing 10 requests all at once, issue them consecutively - only issue the next query after the previous one has been completed. You may need to consider caching these results if you need them quickly, for example of a page load. diff --git a/docs/solution-guidance/multigeo-managedmetadata.md b/docs/solution-guidance/multigeo-managedmetadata.md index 49d6b1c9c..b11e8980e 100644 --- a/docs/solution-guidance/multigeo-managedmetadata.md +++ b/docs/solution-guidance/multigeo-managedmetadata.md @@ -1,7 +1,7 @@ --- title: Manage metadata in a Multi-Geo tenant description: Managed metadata that you define for the default geo location of a Multi-Geo tenant is automatically replicated to the tenant's satellite locations, and is only available to the sites hosted in that geo location. -ms.date: 06/13/2022 +ms.date: 07/02/2025 ms.localizationpriority: medium --- @@ -23,13 +23,14 @@ The following are important points to know about managed metadata in Multi-Geo t - Create term groups, term sets, and terms in the default geo location. This ensures that they are consistently available across all the geo-locations in your tenant. - When term groups, term sets, and terms are replicated across geo-locations, they retain their ID. This allows you to reference term groups, term sets, and terms based on ID, regardless of the geo-location your code is running in. - For term sets and terms to be replicated across geo-locations, they need to be set as Available for Tagging. -- The incremental replication process runs hourly. The full replication job runs every three days. +- The incremental replication process runs hourly. The full replication job runs every seven (7) days. - When you programmatically create a term set in the default geo location, that term set is automatically replicated. You don't have to make any changes to the APIs. - In some cases, you might want a term group, term set, or terms to be available only in a satellite location, for example, a term that relates to a confidential project that applies to a specific geolocation. In that case, you can choose to create the relevant terms in the applicable geo-location. - If you want the term group to be available only in the default location, use the `Set-SPOTenantTaxonomyReplicationParameters` PowerShell cmdlet to explicitly specify which term groups from the default location are replicated. This cmdlet is part of the [SharePoint Online Management Shell](https://www.microsoft.com/download/details.aspx?id=35588). > [!NOTE] > In a multi-geo scenario, there are protected or special term sets within the term store space that will not be replicated, nor will anything under them be replicated. Those groups are: + > - People > - Search Dictionaries > - System diff --git a/docs/sp-add-ins/replace-an-expiring-client-secret-in-a-sharepoint-add-in.md b/docs/sp-add-ins/replace-an-expiring-client-secret-in-a-sharepoint-add-in.md index 43eeca53e..97d666d95 100644 --- a/docs/sp-add-ins/replace-an-expiring-client-secret-in-a-sharepoint-add-in.md +++ b/docs/sp-add-ins/replace-an-expiring-client-secret-in-a-sharepoint-add-in.md @@ -30,6 +30,9 @@ Ensure the following before you begin: - You have installed Microsoft Graph Powershell SDK: [Install the Microsoft Graph PowerShell SDK](/powershell/microsoftgraph/installation) - You're a tenant administrator (or having **Application.ReadWrite.All** permission) for the Microsoft 365 tenant where the add-in was registered with the **AppRegNew.aspx** page. +> [!Important] +> Microsoft Graph PowerShell versions 2.26 and up resulted in issues, if you've problems please downgrade to version 2.25 or lower. + ## Understand the type of your ACS principal before renewing the secret Historically ACS principals were created as Microsoft Entra service principals having the `servicePrincipalType` set to `Legacy`. As of December 2024 the Microsoft Entra principal creation has been streamlined and ACS principals are now created as application principals in Microsoft Entra. If you browse the Microsoft Entra applications you'll now be able to see the ACS principal you've created as of December 2024. ACS principal creation typically is done using `appregnew.aspx`. diff --git a/docs/spfx/compatibility.md b/docs/spfx/compatibility.md index abdfa5b20..55dc39aae 100644 --- a/docs/spfx/compatibility.md +++ b/docs/spfx/compatibility.md @@ -1,12 +1,12 @@ --- title: SharePoint Framework development tools and libraries compatibility description: Find which versions of the SharePoint Framework are compatible with each version of SharePoint, development tools, and libraries. -ms.date: 04/16/2025 +ms.date: 05/15/2025 ms.localizationpriority: high --- # SharePoint Framework development tools and libraries compatibility -As the SharePoint Framework (SPFx) evolves, so do the various development tools and libraries that it uses. +As the SharePoint Framework (SPFx) evolves, so do the various development tools and libraries it uses. ## SharePoint Framework version compatibility @@ -28,12 +28,13 @@ For more information about SharePoint Framework development with SharePoint 2016 ## SPFx development environment compatibility -As each new version of the SharePoint Framework is released, support for newer library versions is constantly added to ensure that the toolset remains current. +As each new version of the SharePoint Framework is released, support for newer library versions is constantly added to ensure the toolset remains current. The following table lists SharePoint Framework and compatible versions of common tools and libraries: | SPFx | Node.js (LTS) | TypeScript | React | | ------------------------------- | --------------- | -------------- | ----------- | +| [1.21.1](release-1.21.1.md) | v22 | v5.3 | v17.0.1 | | [1.21.0](release-1.21.md) | v22 | v5.3 | v17.0.1 | | [1.20.0](release-1.20.md) | v18 | v4.5, v4.7 | v17.0.1 | | [1.19.0](release-1.19.md) | v18 | v4.5, v4.7 | v17.0.1 | diff --git a/docs/spfx/extensions/get-started/building-simple-field-customizer.md b/docs/spfx/extensions/get-started/building-simple-field-customizer.md index d8b579063..6a9b6dd86 100644 --- a/docs/spfx/extensions/get-started/building-simple-field-customizer.md +++ b/docs/spfx/extensions/get-started/building-simple-field-customizer.md @@ -1,15 +1,19 @@ --- title: Build your first Field Customizer extension description: Extensions are client-side components that run inside the context of a SharePoint page. Extensions can be deployed to SharePoint Online, and you can use modern JavaScript tools and libraries to build them. -ms.date: 12/14/2023 +ms.date: 06/19/2025 ms.custom: scenarios:getting-started --- - # Build your first Field Customizer extension +> [!WARNING] +> Microsoft [announced the deprecation of SharePoint Framework field customizers](https://admin.microsoft.com/AdminPortal/home#/MessageCenter/:/messages/MC1094051) on June 13, 2025. +> +> While the original announcement included a retirement date, that has been revised and there is no set timeline. Refer to the Microsoft 365 Message Center post [MC1094051](https://admin.microsoft.com/AdminPortal/home#/MessageCenter/:/messages/MC1094051) for further information. + Extensions are client-side components that run inside the context of a SharePoint page. Extensions can be deployed to SharePoint Online, and you can use modern JavaScript tools and libraries to build them. -You can follow these steps by watching the video on the Microsoft 365 Platform Communtiy (PnP) YouTube Channel: +You can follow these steps by watching the video on the Microsoft 365 Platform Community (PnP) YouTube Channel: > [!Video https://www.youtube.com/embed/mBZ7Sq_KfDA] diff --git a/docs/spfx/use-aadhttpclient.md b/docs/spfx/use-aadhttpclient.md index 0677a9355..e3d7d5800 100644 --- a/docs/spfx/use-aadhttpclient.md +++ b/docs/spfx/use-aadhttpclient.md @@ -1,62 +1,62 @@ --- -title: Connect to Azure AD-secured APIs in SharePoint Framework solutions -description: Use the AadHttpClient class to connect to Azure AD-secured APIs in SharePoint Framework solutions. -ms.date: 01/11/2024 +title: Connect to Entra ID-secured APIs in SharePoint Framework solutions +description: Use the AadHttpClient class to connect to Entra ID-secured APIs in SharePoint Framework solutions. +ms.date: 07/01/2025 ms.localizationpriority: high --- -# Connect to Azure AD-secured APIs in SharePoint Framework solutions +# Connect to Entra ID-secured APIs in SharePoint Framework solutions -When building SharePoint Framework solutions, you might need to connect to an API secured by using Azure Active Directory (Azure AD). SharePoint Framework allows you to specify which Azure AD applications and permissions your solution requires, and a global or SharePoint administrator can grant the necessary permissions if they haven't yet been granted. By using the **AadHttpClient**, you can easily connect to APIs secured by using Azure AD without having to implement the OAuth flow yourself. +When building SharePoint Framework solutions, you might need to connect to an API secured by using Entra ID. SharePoint Framework allows you to specify which Entra ID applications and permissions your solution requires, and a global or SharePoint administrator can grant the necessary permissions if they haven't yet been granted. By using the **AadHttpClient**, you can easily connect to APIs secured by using Entra ID without having to implement the OAuth flow yourself. ## Web API permissions overview -Azure AD secures a number of resources, from Microsoft 365 to custom line-of-business applications built by the organization. To connect to these resources, applications must obtain a valid access token that grants them access to a particular resource. Applications can obtain an access token as part of the [OAuth authorization flow](/azure/active-directory/develop/active-directory-protocols-oauth-code). +Entra ID secures a number of resources, from Microsoft 365 to custom line-of-business applications built by the organization. To connect to these resources, applications must obtain a valid access token that grants them access to a particular resource. Applications can obtain an access token as part of the [OAuth authorization flow](/azure/active-directory/develop/active-directory-protocols-oauth-code). Client-side applications that are incapable of storing a secret, such as SharePoint Framework solutions, use a specific type of OAuth flow named [OAuth implicit flow](/azure/active-directory/develop/active-directory-dev-understanding-oauth2-implicit-grant). Developers building client-side solutions are responsible for implementing authorization by using the OAuth implicit flow in their application. In SharePoint Framework solutions, that's already done as part of the framework through **MSGraphClient** and **AadHttpClient**, both of which are introduced in SharePoint Framework v1.4.1. > [!NOTE] -> If you build solutions on a version of the SharePoint Framework earlier than v1.4.1, you can still connect to resources secured with Azure AD. In this case, you need to implement the OAuth implicit flow by directly using [Microsoft identity platform authentication libraries](/azure/active-directory/develop/reference-v2-libraries). For more information, see [Connect to Azure AD-secured APIs in SharePoint Framework solutions](use-aadhttpclient.md). +> Using the `AADHttpClient` with SharePoint Framework directly using [Microsoft Authentication Library for JavaScript](https://learn.microsoft.com/javascript/api/overview/msal-overview) is not supported with SPFx v1.4.1 and beyond. `AADHttpClient` is the recommended approach to authenticate for using Entra ID secured resources. -As part of the SharePoint Framework, a specific process is defined for how developers can request permissions and administrators can manage permissions to resources secured with Azure AD. The following schema illustrates this process. +As part of the SharePoint Framework, a specific process is defined for how developers can request permissions and administrators can manage permissions to resources secured with Entra ID. The following schema illustrates this process. -![Schema illustrating the flow of requesting, granting and using permissions to Azure AD applications](../images/webapipermissions-logical.png) +![Schema illustrating the flow of requesting, granting and using permissions to Entra ID applications](../images/webapipermissions-logical.png) -Developers building a SharePoint Framework solution that requires access to specific resources secured with Azure AD list these resources along with the required permission scopes in the solution manifest. When deploying the solution package to the app catalog, SharePoint creates permission requests and prompts the administrator to manage the requested permissions. For each requested permission, a global or SharePoint administrator can decide whether they want to grant or deny the specific permission. +Developers building a SharePoint Framework solution that requires access to specific resources secured with Entra ID list these resources along with the required permission scopes in the solution manifest. When deploying the solution package to the app catalog, SharePoint creates permission requests and prompts the administrator to manage the requested permissions. For each requested permission, a global or SharePoint administrator can decide whether they want to grant or deny the specific permission. -All permissions are granted to the whole tenant and not to a specific application that has requested them. When the administrator grants a specific permission, its added to the **SharePoint Online Client Extensibility** Azure AD application, which is provisioned by Microsoft in every Azure AD and which is used by the SharePoint Framework in the OAuth flow to provide solutions with valid access tokens. +All permissions are granted to the whole tenant and not to a specific application that has requested them. When the administrator grants a specific permission, its added to the **SharePoint Online Client Extensibility** Entra ID application, which is provisioned by Microsoft in every Entra ID and which is used by the SharePoint Framework in the OAuth flow to provide solutions with valid access tokens. ## Discover available applications and permissions -The target Azure AD that secures your Microsoft 365 tenant determines which applications you can request permissions for in your solution. The list of available applications might depend on the Microsoft 365 license that the organization is using and which line-of-business applications they registered in Azure AD. If you have sufficient permissions, there are several ways that you can see which applications and permission scopes are available in your tenant. +The target Entra ID that secures your Microsoft 365 tenant determines which applications you can request permissions for in your solution. The list of available applications might depend on the Microsoft 365 license that the organization is using and which line-of-business applications they registered in Entra ID. If you have sufficient permissions, there are several ways that you can see which applications and permission scopes are available in your tenant. -### Use Azure portal or Azure AD admin center +### Use the Azure portal or Entra ID portal -One way to see the available applications in Azure AD is by navigating to the [Azure portal](https://ms.portal.azure.com/) or to the [Azure AD admin center](https://aad.portal.azure.com). +One way to see the available applications in Entra ID is by navigating to the [Azure portal](https://portal.azure.com/) or to the [Entra ID portal](https://entra.microsoft.com). -1. In the Azure AD admin center, in the left navigation, select the **Enterprise applications** link. +1. In the Entra ID admin center, in the left navigation, select the **Enterprise applications** link. - ![The 'Enterprise applications' link highlighted in the Azure AD portal](../images/webapipermissions-aadportal-enterpriseappslink.png) + ![The 'Enterprise applications' link highlighted in the Entra ID portal](../images/webapipermissions-aadportal-enterpriseappslink.png) 1. On the **Enterprise applications** blade, in the **Manage** group, select the **All applications** link. - ![The 'All applications' link highlighted in the Azure AD portal](../images/webapipermissions-aadportal-allappslink.png) + ![The 'All applications' link highlighted in the Entra ID portal](../images/webapipermissions-aadportal-allappslink.png) 1. To quickly find the application to which you want to connect, you can filter the overview either by application type (_Microsoft Applications_ or _Enterprise Applications_), or you can search for it by using its name or ID. - For example, if you want to request additional permissions to the Microsoft Graph, in the search box you would search for `graph`. + For example, if you want to request additional permissions to the Microsoft Graph, in the search box, you would search for `graph`. - ![Searching for 'graph' in the list of available Azure AD applications in the Azure AD portal](../images/webapipermissions-aadportal-searchgraph.png) + ![Searching for 'graph' in the list of available Entra ID applications in the Entra ID portal](../images/webapipermissions-aadportal-searchgraph.png) 1. After you find the application, select it to get additional information. On the application's blade, in the **Manage** group, select **Properties** to open the application's properties. - ![The 'Properties' link highlighted on the application blade in the Azure AD portal](../images/webapipermissions-aadportal-graphpropertieslink.png) + ![The 'Properties' link highlighted on the application blade in the Entra ID portal](../images/webapipermissions-aadportal-graphpropertieslink.png) 1. From the list of properties, copy the value of the **Object ID** property, which you need to request additional permission scopes to the Microsoft Graph. Instead, you can copy the application's **Name** and use it in the permission request instead. - ![The value of the 'Object ID' property copied to the clipboard in the Azure AD portal](../images/webapipermissions-aadportal-graphobjectidcopied.png) + ![The value of the 'Object ID' property copied to the clipboard in the Entra ID portal](../images/webapipermissions-aadportal-graphobjectidcopied.png) > [!NOTE] > While the **Object ID** is unique for each tenant, the application's **Name** is the same across all tenants. If you want to build your solution once and deploy it to different tenants, you should use the application's **Name** when requesting additional permissions in your solution. @@ -91,26 +91,26 @@ One way to see the available applications in Azure AD is by navigating to the [A azure login ``` -1. After you're connected, execute the following command to list all available Azure AD applications: +1. After you're connected, execute the following command to list all available Entra ID applications: ```console - azure ad sp list --query "sort_by([*].{displayName: displayName, objectId: objectId}, &displayName)" -o table + Entra ID sp list --query "sort_by([*].{displayName: displayName, objectId: objectId}, &displayName)" -o table ``` - Running this command lists all Azure AD applications available in your tenant, sorted by displayName. For each application, the command displays its displayName and objectId. Additionally, the output is formatted as a table. + Running this command lists all Entra ID applications available in your tenant, sorted by displayName. For each application, the command displays its displayName and objectId. Additionally, the output is formatted as a table. ### Get the list of permission scopes exposed by the application -Each Azure AD application exposes a number of permission scopes. These permission scopes often relate to specific resources or operations inside the application. To get the list of permissions available for the application you would like to connect to, consult its documentation. For the list of permission scopes available in the Microsoft Graph, see [Microsoft Graph permissions reference](/graph/permissions-reference). +Each Entra ID application exposes a number of permission scopes. These permission scopes often relate to specific resources or operations inside the application. To get the list of permissions available for the application you would like to connect to, consult its documentation. For the list of permission scopes available in the Microsoft Graph, see [Microsoft Graph permissions reference](/graph/permissions-reference). -## Request permissions to an Azure AD application +## Request permissions to an Entra ID application -If your SharePoint Framework solution requires permissions to specific resources secured with Azure AD, such as Microsoft Graph or enterprise applications, you can specify these resources along with the necessary permissions in the configuration of your solution. +If your SharePoint Framework solution requires permissions to specific resources secured with Entra ID, such as Microsoft Graph or enterprise applications, you can specify these resources along with the necessary permissions in the configuration of your solution. 1. In your SharePoint Framework project, open the **config/package-solution.json** file. 1. To the `solution` property, add the `webApiPermissionRequests` property that lists all the resources and corresponding permissions that your solution needs. - Following is an example of a SharePoint Framework solution requesting access to read user calendars by using the Microsoft Graph: + The following is an example of a SharePoint Framework solution requesting access to read user calendars by using the Microsoft Graph: ```json { @@ -170,25 +170,25 @@ If your SharePoint Framework solution requires permissions to specific resources > [!NOTE] > No matter if the administrator denies or approves the requested permissions, the solution can be deployed and used on sites. When building solutions that require additional permissions, you should never assume that the requested permissions have been granted. -### Requesting permissions to Azure AD applications in another tenant +### Requesting permissions to Entra ID applications in another tenant -The previous steps address adding a permission request to an Azure AD application defined in the same Azure AD tenant as your SharePoint Online tenant. However, when you want to grant a permission for an Azure AD application defined in another tenant (a multitenant Azure AD application), you must first add a service principal for that Azure AD application to your tenant. +The previous steps address adding a permission request to an Entra ID application defined in the same Entra ID tenant as your SharePoint Online tenant. However, when you want to grant a permission for an Entra ID application defined in another tenant (a multitenant Entra ID application), you must first add a service principal for that Entra ID application to your tenant. > [!NOTE] > This capability was added in the [SPFx v1.15.2 release](release-1.15.2.md). > [!IMPORTANT] -> Azure AD applications have two types of principals. The application object is created when the Azure AD app is created; it is a *global* representation of the application across all tenants. +> Entra ID applications have two types of principals. The application object is created when the Entra ID app is created; it is a *global* representation of the application across all tenants. > -> Permissions are granted to service principals which are the *local* representation of the app for use in a specific tenant. +> Permissions are granted to service principals, which are the *local* representation of the app for use in a specific tenant. > -> When you create an Azure AD application in a tenant, both the application object & service principal are created in that tenant. But when you want to use the Azure AD application in another tenant, you must create a service principal for that application in your tenant. +> When you create an Entra ID application in a tenant, both the application object & service principal are created in that tenant. But when you want to use the Entra ID application in another tenant, you must create a service principal for that application in your tenant. > -> To learn more about Azure AD application principals, objects, and service principals, see: [Application and service principal objects in Azure Active Directory](/azure/active-directory/develop/app-objects-and-service-principals). +> To learn more about Entra ID application principals, objects, and service principals, see: [Application and service principal objects in Entra ID](/azure/active-directory/develop/app-objects-and-service-principals). > -> To learn more about single and multitenant Azure AD applications, see: [Tenancy in Azure Active Directory](/azure/active-directory/develop/single-and-multi-tenant-apps). +> To learn more about single and multitenant Entra ID applications, see: [Tenancy in Entra ID](/azure/active-directory/develop/single-and-multi-tenant-apps). -When you want to grant SharePoint Online permissions to an Azure AD application defined to another tenant, the service principal needs to already exist on the tenant where SharePoint Online operates. Prior to SPFx v1.15.2, , SharePoint expected the service principal already existed. But SPFx v1.15.2 introduced a way to register the service principal during the permission request approval process. +When you want to grant SharePoint Online permissions to an Entra ID application defined to another tenant, the service principal needs to already exist on the tenant where SharePoint Online operates. Prior to SPFx v1.15.2, SharePoint expected the service principal to already exist. But SPFx v1.15.2 introduced a way to register the service principal during the permission request approval process. To do this, you must include two additional properties in the SPFx project's **package-solution.json** file's `webApiPermissionRequests` entry: @@ -199,7 +199,7 @@ To do this, you must include two additional properties in the SPFx project's **p .. "webApiPermissionRequests": [ { - "resource": "", + "resource": "", "scope": "", "appId": "", "replyUrl": "" @@ -210,19 +210,19 @@ To do this, you must include two additional properties in the SPFx project's **p The two additional properties are: -- `appId`: This is the application object's ID for which a service principal will get created in the tenant. -- `replyUrl`: This is the URL used by Azure AD during the consent and registration experience of the permission request. +- `appId`: This is the application object's ID for which a service principal will be created in the tenant. +- `replyUrl`: This is the URL used by Entra ID during the consent and registration experience of the permission request. > [!IMPORTANT] -> If either `appid` or `replyUrl` are included, they are both required. In other words, include both properties (*if you're referencing an Azure AD app registered in another tenant from your SharePoint Online tenant*) or neither property (*if you're referencing an Azure AD app registered in the same tenant as your SharePoint Online tenant*). +> If either `appid` or `replyUrl` is included, they are both required. In other words, include both properties (*if you're referencing an Entra ID app registered in another tenant from your SharePoint Online tenant*) or neither property (*if you're referencing an Entra ID app registered in the same tenant as your SharePoint Online tenant*). ## Manage permission requests -When you deploy SharePoint Framework solutions that request permissions to Azure AD applications, administrators are prompted to manage the permission request provided with the solution. Permission requests can be managed in several ways. +When you deploy SharePoint Framework solutions that request permissions to Entra ID applications, administrators are prompted to manage the permission request provided with the solution. Permission requests can be managed in several ways. ### Manage permissions in the new SharePoint admin center -To learn how to use the API access page in the new SharePoint admin center, see [Manage access to Azure AD-secured APIs](/sharepoint/api-access). +To learn how to use the API access page in the new SharePoint admin center, see [Manage access to Entra ID-secured APIs](/sharepoint/api-access). ### Manage permissions with PowerShell @@ -288,11 +288,11 @@ Global and SharePoint administrators can use the [CLI for Microsoft 365](https:/ > [!NOTE] > Revoking a permission doesn't trigger any changes to the app catalog or any of the deployed applications. The only consequence of revoking a permission is that any application used in the tenant will not be able to connect to the resources for which the permission has been revoked. -## Connect to Azure AD applications using the AadHttpClient +## Connect to Entra ID applications using the AadHttpClient -Introduced in v1.4.1, the SharePoint Framework simplifies connecting to APIs secured with Azure AD. Using the new **AadHttpClient**, you can easily connect to APIs secured with Azure AD without having to implement authentication and authorization yourself. +Introduced in v1.4.1, the SharePoint Framework simplifies connecting to APIs secured with Entra ID. Using the new **AadHttpClient**, you can easily connect to APIs secured with Entra ID without having to implement authentication and authorization yourself. -Internally, the **AadHttpClient** implements the Azure AD OAuth flow leveraging Microsoft identity platform authentication libraries by using the **SharePoint Online Client Extensibility** service principal to obtain a valid access token. The **SharePoint Online Client Extensibility** service principal is provisioned by Microsoft and is available in the Azure AD of all Microsoft 365 tenants. +Internally, the **AadHttpClient** implements the Entra ID OAuth flow, leveraging Microsoft identity platform authentication libraries by using the **SharePoint Online Client Extensibility** service principal to obtain a valid access token. The **SharePoint Online Client Extensibility** service principal is provisioned by Microsoft and is available in the Entra ID of all Microsoft 365 tenants. 1. To use the **AadHttpClient** in your SharePoint Framework solution, add the following `import` clause in your main web part file: @@ -319,7 +319,7 @@ Internally, the **AadHttpClient** implements the Azure AD OAuth flow leveraging ``` > [!NOTE] - > Each instance of the **AadHttpClient** is linked to the specific resource, which is why you need to create a new instance of the client for each resource that you want to connect to. + > Each instance of the **AadHttpClient** is linked to a specific resource, which is why you need to create a new instance of the client for each resource that you want to connect to. 1. After you instantiate the **AadHttpClient** for your resource, you can issue a web request to communicate with your API; in this example, the API returns a list of orders represented by the custom **Order** interface defined elsewhere in the project: @@ -356,9 +356,9 @@ It's only possible to request additional permissions through a SharePoint Framew ### Granted permissions apply to the entire tenant -Although permissions to Azure AD resources are being requested by a SharePoint Framework solution, once granted, they apply to the entire tenant and can be leveraged by any client-side request in that tenant. This includes SPFx solutions and non-SPFx solutions because. +Although permissions to Entra ID resources are being requested by a SharePoint Framework solution, once granted, they apply to the entire tenant and can be leveraged by any client-side request in that tenant. This includes SPFx solutions and non-SPFx solutions because. -### Removing solution doesn't revoke permissions +### Removing the solution doesn't revoke permissions Removing the solution that initially requested the particular permission doesn't revoke the granted permission. Administrators have to manually revoke permissions granted through SharePoint Framework application requests. @@ -366,13 +366,13 @@ Removing the solution that initially requested the particular permission doesn't Revoking previously granted permissions doesn't invalidate access tokens issued to users. Instead, these access tokens remain valid until they expire. -### Permission request doesn't affect solution deployment +### Permission request doesn't affect the solution deployment No matter if the administrator denies or approves permissions requested by the solution, the solution can be deployed and used on sites. When building solutions that require additional permissions, you should never assume that the requested permissions have been granted. ### Control the SharePoint Online Client service principal -All permissions granted through web API requests are stored with the **SharePoint Online Client Extensibility** Azure AD application. If administrators don't want developers to use the web API request model and the **MSGraphClient** and **AadHttpClient** in their solutions, they can disable the **SharePoint Online Client Extensibility** service principal through PowerShell by using the **Disable-SPOTenantServicePrincipal** cmdlet. +All permissions granted through web API requests are stored with the **SharePoint Online Client Extensibility** Entra ID application. If administrators don't want developers to use the web API request model and the **MSGraphClient** and **AadHttpClient** in their solutions, they can disable the **SharePoint Online Client Extensibility** service principal through PowerShell by using the **Disable-SPOTenantServicePrincipal** cmdlet. The service principal can be re-enabled by using the **Enable-SPOTenantServicePrincipal** cmdlet. Instead, it's also possible to enable and disable the **SharePoint Online Client Extensibility** service principal through the CLI for Microsoft 365 by using the **[spo serviceprincipal set](https://pnp.github.io/cli-microsoft365/cmd/spo/serviceprincipal/serviceprincipal-set/)** command. diff --git a/docs/spfx/viva/overview-viva-connections.md b/docs/spfx/viva/overview-viva-connections.md index 3ead56284..d201914ff 100644 --- a/docs/spfx/viva/overview-viva-connections.md +++ b/docs/spfx/viva/overview-viva-connections.md @@ -6,7 +6,7 @@ ms.localizationpriority: high --- # Overview of Viva Connections Extensibility -[Microsoft Viva Connections](https://www.microsoft.com/microsoft-viva) is available as a desktop via the installable Microsoft Teams client, tablet and as mobile app in Microsoft Teams. All of these experiences, desktop & mobile, use the **SharePoint Framework (SPFx) or bots for all customizations and extensibility opportunities**. +[Microsoft Viva Connections](https://www.microsoft.com/microsoft-viva) is available as a desktop via the installable Microsoft Teams client, tablet and as mobile app in Microsoft Teams. All of these experiences, desktop & mobile, use the **SharePoint Framework (SPFx) for all customizations and extensibility opportunities**. Viva Connections has a set of out of the box cards that are exposed through the dashboard feature. This dashboard **can be adjusted and configured based on the company requirements**. You can introduce new cards and experiences based on your business requirements. @@ -17,13 +17,13 @@ Viva Connections dashboard is available in the desktop, tablet and mobile experi ## Extensibility opportunities -Viva Connections personalization and extensibility model is based on the **Adaptive Card Extensions (ACEs)** which can be created using the widely adopted SharePoint Framework (SPFx) as client-side extensibility or by using server-side implementations using a bot. +Viva Connections personalization and extensibility model is based on the **Adaptive Card Extensions (ACEs)** which can be created using the widely adopted SharePoint Framework (SPFx) as client-side extensibility. To learn more about customizing modern pages in SharePoint with SPFx, see [Overview of SPFx client-side web parts](../web-parts/overview-client-side-web-parts.md) & [Overview of SPFx Extensions](../extensions/overview-extensions.md). ### Viva Connections desktop experience -The Viva Connections desktop experience can be extended and customized using Adaptive Card Extensions (ACEs). Developers can use both SPFx and the bot powered option to introduce new Viva Connections Adaptive Card extensions to customize the dashboard based on the business requirements. +The Viva Connections desktop experience can be extended and customized using Adaptive Card Extensions (ACEs). Developers can use SPFx to introduce new Viva Connections Adaptive Card extensions to customize the dashboard based on the business requirements. ![Example Viva Connections desktop layout as available in 2024](./images/viva-connections-desktop.png) @@ -33,26 +33,11 @@ The Viva Connections mobile experience is aligned with the desktop experience an ![Example Viva Connections mobile layout as available in 2024](./images/viva-connections-mobile-and-tablet.png) -## Choosing the right model - -Here are the considerations on choosing the right extensibility model for your deployment: - -- SPFx created ACEs pattern is suitable for you when - - Your team is familiar with client-side web stack development - - You've built other extensibility to Microsoft 365 using SPFx - for SharePoint, Microsoft Teams, Office or Outlook - - You want the extensibility to be automatically hosted in the Microsoft 365 without costs - -- Bot powered ACEs is suitable for you when - - You have an existing bot that is used in the Microsoft Teams - you can easily extend that to be exposed in the Viva Connections as well - - You've implemented Microsoft 365 extensibility with server-side implementation hosted in Microsoft Azure - ## Start building for Microsoft Viva Connections Here are the resources to get started on creating your first Adaptive Card Extension (ACE) depending on your chosen path: - [Build your first SharePoint Adaptive Card Extension with SPFx](get-started/build-first-sharepoint-adaptive-card-extension.md) -- [Overview of Bot Powered Adaptive Card Extensions](bot-powered/Overview-Bot-Powered-ACEs.md) -- [Building your first Bot Powered Adaptive Card Extension](bot-powered/Building-Your-First-Bot-Powered-ACE.md) - [Advanced Card View Functionality](get-started/advanced-card-view-functionality.md) - [Advanced Quick View Functionality](get-started/advanced-quick-view-functionality.md) - [Adaptive Card Extensions and Teams Apps](get-started/adaptive-card-extensions-and-teams.md) diff --git a/docs/toc.yml b/docs/toc.yml index 49c132ab7..df170f5f2 100644 --- a/docs/toc.yml +++ b/docs/toc.yml @@ -320,7 +320,7 @@ - name: JavaScript libraries href: spfx/web-parts/guidance/use-existing-javascript-libraries.md - name: SharePoint Online Support for Content Security Policy (CSP) - href: /spfx/content-securty-policy-trusted-script-sources.md + href: spfx/content-securty-policy-trusted-script-sources.md - name: CSS styles href: spfx/web-parts/guidance/reference-third-party-css-styles.md - name: Connect to APIs @@ -554,6 +554,8 @@ items: - name: Overview href: embedded/overview.md + - name: What's New + href: embedded/whats-new.md - name: Scenarios and Use Cases href: embedded/scenarios-and-use-cases.md - name: Getting Started @@ -622,13 +624,13 @@ href: /training/modules/sharepoint-embedded-setup - name: SharePoint Embedded - building applications href: /training/modules/sharepoint-embedded-create-app - - name: SharePoint Embedded copilot ( Private Preview ) + - name: SharePoint Embedded agent ( Private Preview ) items: - - name: SharePoint Embedded copilot Overview + - name: SharePoint Embedded agent Overview href: embedded/development/declarative-agent/spe-da.md - - name: SharePoint Embedded copilot Tutorial + - name: SharePoint Embedded agent Tutorial href: embedded/development/tutorials/spe-da-vscode.md - - name: SharePoint Embedded copilot Advanced Topics + - name: SharePoint Embedded agent Advanced Topics href: embedded/development/declarative-agent/spe-da-adv.md - name: Microsoft Teams items: @@ -678,26 +680,6 @@ href: spfx/viva/design/quick-view-samples.md - name: Adaptive Card Extensions Iconography Limitations href: spfx/viva/get-started/fluent-icons-limitations.md - - name: Bot Powered Adaptive Card Extensions - items: - - name: Overview of Bot Powered Adaptive Card Extensions - href: spfx/viva/bot-powered/Overview-Bot-Powered-ACEs.md - - name: Understanding Bot Powered Adaptive Card Extensions - href: spfx/viva/bot-powered/Understanding-Bot-Powered-ACEs.md - - name: Building your first Bot Powered ACE with .NET - href: spfx/viva/bot-powered/Building-Your-First-Bot-Powered-ACE.md - - name: Building your first Bot Powered ACE with Microsoft Teams Toolkit and TypeScript - href: spfx/viva/bot-powered/Building-Your-First-Bot-Powered-ACE-TTK-TS.md - - name: Extending an existing Teams Bot to become a Bot Powered Adaptive Card Extension - href: spfx/viva/bot-powered/Extending-existing-Teams-Bot.md - - name: Authentication and Authorization in Bot Powered ACEs - href: spfx/viva/bot-powered/AuthN-and-AuthZ-in-Bot-Powered-ACEs.md - - name: Building Bot Powered ACEs with Microsoft Entra ID and Single Sign-on (SSO) - href: spfx/viva/bot-powered/AuthN-and-AuthZ-in-Bot-Powered-ACEs-Entra.md - - name: Building Bot Powered ACEs with Magic Code authentication - href: spfx/viva/bot-powered/AuthN-and-AuthZ-in-Bot-Powered-ACEs-Magic-Code.md - - name: Bringing Bot Powered ACEs to the marketplace - href: spfx/viva/bot-powered/publish-to-marketplace-overview.md - name: Tutorials items: - name: Build your first SharePoint Adaptive Card Extension @@ -2315,13 +2297,15 @@ href: apis/amr-api-reference.md - name: Azure container and queue href: apis/migration-azure.md + - name: Migration Job Progress API + href: apis/migration-job-progress-api-reference.md - name: Migration Content Package href: apis/migration-content-package.md - name: Manifest Files href: apis/migration-manifest.md - name: Events href: apis/migration-events.md - - name: Microsoft Syntex REST API + - name: Document processing REST API items: - name: Overview href: apis/syntex/syntex-model-rest-api.md