Merge pull request #774 from Shweta2024/bhagatshweta-copilotinsights

Add documentation for the Copilot Insights Cmdlets
MicrosoftDocs · Dec 13, 2024 · 732046c · 732046c
2 parents d787d19 + d50a7b4
commit 732046c
Show file tree

Hide file tree

Showing 3 changed files with 270 additions and 0 deletions.
diff --git a/sharepoint/sharepoint-ps/sharepoint-online/Get-SPOCopilotAgentInsightsReport.md b/sharepoint/sharepoint-ps/sharepoint-online/Get-SPOCopilotAgentInsightsReport.md
@@ -0,0 +1,163 @@
+---
+external help file: sharepointonline.xml
+Module Name: Microsoft.Online.SharePoint.PowerShell
+online version: https://learn.microsoft.com/powershell/module/sharepoint-online/get-spocopilotagentinsightsreport
+applicable: SharePoint Online
+title: Get-SPOCopilotAgentInsightsReport
+schema: 2.0.0
+author: bhagatshweta
+ms.author: bhagatshweta
+ms.reviewer:
+manager: hikakar
+---
+
+# Get-SPOCopilotAgentInsightsReport
+
+## SYNOPSIS
+
+This cmdlet enables the administrator to check status of all active and available reports when no report ID is present and to view or download a report if report ID is present.
+
+## SYNTAX
+
+```powershell
+Get-SPOCopilotAgentInsightsReport [-ReportId <Guid>] [-Content <SPOCopilotAgentInsightType>] [-Action <ActionType>]
+```
+
+## DESCRIPTION
+
+If this cmdlet is executed without any parameters, it displays the status of all active and completed reports with the following properties:
+
+| Property             | Description                                                      |
+|:---------------------|:-----------------------------------------------------------------|
+| Id                   | The unique Id of the report.                                     |
+| CreatedDateTimeInUtc | The date and time in UTC when the report creation was triggered. |
+| Status               | The status of the report.                                        |
+| ReportPeriodInDays   | The report duration in days.                                     |
+
+> [!NOTE]
+> All reports adhere to any retention timeline as per [Data Access Governance](/sharepoint/data-access-governance-reports).
+
+## EXAMPLES
+
+### -----------------------EXAMPLE 1-----------------------------
+
+```powershell
+Get-SPOCopilotAgentInsightsReport
+```
+
+Example 1 enables administrator to view the status of all active and completed reports.
+
+### -----------------------EXAMPLE 2-----------------------------
+
+```powershell
+Get-SPOCopilotAgentInsightsReport –ReportId 9d946216-afe7-49f5-8267-7b662435c70b
+```
+
+Example 2 enables administrator to view the Copilot agent insight report of ReportId: `9d946216-afe7-49f5-8267-7b662435c70b`.
+
+### -----------------------EXAMPLE 3-----------------------------
+
+```powershell
+Get-SPOCopilotAgentInsightsReport – ReportId 9d946216-afe7-49f5-8267-7b662435c70b -Action Download
+```
+
+Example 3 enables administrator to download the Copilot agent insight report of ReportId: `9d946216-afe7-49f5-8267-7b662435c70b` to the same path from where the command was run.
+
+## PARAMETERS
+
+### -ReportId
+
+It specifies the unique Id of the report to be viewed or downloaded.
+
+```yaml
+Type: Guid
+Parameter Sets: (All)
+Aliases:
+Applicable: SharePoint Online
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Content
+
+It specifies the kind of report to view or download. There are 3 kinds of sub-reports: CopilotAgentsOnSites, TopSites, SiteDistribution.
+
+If this cmdlet is executed with `-Content` as `CopilotAgentsOnSites`, a report with list of all sites on which a Copilot agent is created along with the names of the Copilot agent created in the specified number of days will be displayed with the following properties:
+
+| Property                        | Description                                                     |
+|:--------------------------------|:----------------------------------------------------------------|
+| Site name                       | The name of the SharePoint site.                                |
+| URL                             | The URL of the SharePoint site.                                 |
+| Template                        | The Site template of the SharePoint site.                       |
+| Site owner                      | Name of the owner of the SharePoint site.                       |
+| Copilot name                    | Name of Copilot agent on the SharePoint site.                   |
+| Sensitivity                     | The sensitivity label of the SharePoint site.                   |
+| Restrict site access enabled    | Restrict site access status (Yes/No) of the SharePoint site.    |
+| Restrict site discovery enabled | Restrict site discovery status (Yes/No) of the SharePoint site. |
+| External sharing                | External Sharing status (Yes/No) of the SharePoint site.        |
+
+If this cmdlet is executed with `-ReportId` as parameter and `-Content` as `TopSites`, the top 100 records summarizing the number of Copilot agents on sites created in the specified number of days will be displayed with the following properties:
+
+| Property                        | Description                                                     |
+|:--------------------------------|:----------------------------------------------------------------|
+| Site name                       | The name of the SharePoint site.                                |
+| URL                             | The URL of the SharePoint site.                                 |
+| Template                        | The Site template of the SharePoint site.                       |
+| Site owner                      | Name of the owner of the SharePoint site.                       |
+| Copilot agents                  | Number of Copilot agents on the SharePoint site.                |
+| Sensitivity                     | The sensitivity label of the SharePoint site.                   |
+| Restrict site access enabled    | Restrict site access status (Yes/No) of the SharePoint site.    |
+| Restrict site discovery enabled | Restrict site discovery status (Yes/No) of the SharePoint site. |
+| External sharing                | External Sharing status (Yes/No) of the SharePoint site.        |
+
+If this cmdlet is executed with `-ReportId` as parameter and `-Content` as `SiteDistribution`, a report showing Copilot distribution across sites in the specified number of days will be displayed with the following properties:
+
+| Property       | Description                                                                                  |
+|:---------------|:---------------------------------------------------------------------------------------------|
+| Site template  | The Site template of the SharePoint site.                                                    |
+| Sites          | Number of sites corresponding to that particular site template.                              |
+| Copilot agents | Number of Copilot agents on the SharePoint site corresponding to that particular site template. |
+
+```yaml
+Type: SPOCopilotAgentInsightType
+Parameter Sets: (All)
+Aliases:
+Applicable: SharePoint Online
+
+Required: False
+Position: Named 
+Default value: CopilotAgentsOnSites
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Action
+
+It determines whether a report would be viewed or downloaded. If the value of `-Action` is set as `View`, it will display the output on the PowerShell screen. Else if the value of `-Action` is set as `Download`, it will download the full report in CSV format to the same path from where the command was run.
+
+```yaml
+Type: ActionType
+Parameter Sets: (All)
+Aliases:
+Applicable: SharePoint Online
+ 
+Required: False
+Position: Named
+Default value: View
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+
+## RELATED LINKS
+
+[Getting started with SharePoint Online Management Shell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online)
+
+[Start-SPOCopilotAgentInsightsReport](./Start-SPOCopilotAgentInsightsReport.md)
diff --git a/sharepoint/sharepoint-ps/sharepoint-online/Start-SPOCopilotAgentInsightsReport.md b/sharepoint/sharepoint-ps/sharepoint-online/Start-SPOCopilotAgentInsightsReport.md
@@ -0,0 +1,99 @@
+---
+external help file: sharepointonline.xml
+Module Name: Microsoft.Online.SharePoint.PowerShell
+online version: https://learn.microsoft.com/powershell/module/sharepoint-online/start-spocopilotagentinsightsreport
+applicable: SharePoint Online
+title: Start-SPOCopilotAgentInsightsReport
+schema: 2.0.0
+author: bhagatshweta
+ms.author: bhagatshweta
+ms.reviewer:
+manager: hikakar
+---
+
+# Start-SPOCopilotAgentInsightsReport
+
+## SYNOPSIS
+
+Using this cmdlet, administrators may trigger the build of a new Copilot agent insight report for the specified number of days.
+
+## SYNTAX
+
+```powershell
+Start-SPOCopilotAgentInsightsReport [-ReportPeriodInDays <Int>] [-Force <SwitchParameter>]
+```
+
+## DESCRIPTION
+
+After this cmdlet is executed, the Copilot agent insight report generation request for the specified number of days gets queued in the pipeline and the below metadata is displayed with the following properties:
+
+| Property             | Description                                                      |
+|:---------------------|:-----------------------------------------------------------------|
+| Id                   | The unique Id of the report.                                     |
+| CreatedDateTimeInUtc | The date and time in UTC when the report creation was triggered. |
+| Status               | The status of the report.                                        |
+| ReportPeriodInDays   | The report duration in days.                                     |
+
+## EXAMPLES
+
+### -----------------------EXAMPLE 1-----------------------------
+
+```powershell
+Start-SPOCopilotAgentInsightsReport
+```
+
+Example 1 generates the Copilot agent insight report for a default duration of 1 day since the parameter `–ReportPeriodInDays` is not provided.
+
+### -----------------------EXAMPLE 2-----------------------------
+
+```powershell
+Start-SPOCopilotAgentInsightsReport –ReportPeriodInDays 14
+```
+
+Example 2 generates the Copilot agent insight report for a specified duration of 14 days.
+
+## PARAMETERS
+
+### -ReportPeriodInDays
+
+It specifies the duration of the Copilot agent insight report in days. The possible values of ReportPeriodInDays are: 1, 7, 14, 28. If this parameter is not provided, it generates the report for a default duration of 1 day.
+
+```yaml
+Type: Int
+Parameter Sets: (All)
+Aliases:
+Applicable: SharePoint Online
+
+Required: False
+Position: Named
+Default value: 1
+Accept pipeline input: False
+Accept wildcard characters: False 
+```
+
+### -Force
+
+It is an optional parameter which is used to bypass confirmation prompts and execute the command without interruptions.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases: 
+Applicable: SharePoint Online
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### CommonParameters
+
+This cmdlet supports the common parameters: `-Debug`, `-ErrorAction`, `-ErrorVariable`, `-InformationAction`, `-InformationVariable`, `-OutVariable`, `-OutBuffer`, `-PipelineVariable`, `-Verbose`, `-WarningAction`, and `-WarningVariable`. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+
+## Related Links
+
+[Getting started with SharePoint Online Management Shell](/powershell/sharepoint/sharepoint-online/connect-sharepoint-online)
+
+[Get-SPOCopilotAgentInsightsReport](./Get-SPOCopilotAgentInsightsReport.md)
diff --git a/sharepoint/sharepoint-ps/sharepoint-online/sharepoint-online.md b/sharepoint/sharepoint-ps/sharepoint-online/sharepoint-online.md
@@ -99,6 +99,10 @@ The following cmdlet references are for SharePoint Online.
 
 {{Manually Enter Get-SPOAppInfo Description Here}}
 
+### [Get-SPOCopilotAgentInsightsReport](Get-SPOCopilotAgentInsightsReport.md)
+
+{{Gets the status of all active and available reports when no report ID is present, and allows to view or download a report if report ID is present.}}
+
 ### [Get-SPOCrossGeoMovedUsers](Get-SPOCrossGeoMovedUsers.md)
 
 {{Manually Enter Get-SPOCrossGeoMovedUsers Description Here}}
@@ -608,6 +612,10 @@ This cmdlet is not currently active in production and may be removed in the futu
 
 {{Manually Enter Set-SPOUser Description Here}}
 
+### [Start-SPOCopilotAgentInsightsReport](Start-SPOCopilotAgentInsightsReport.md)
+
+{{Triggers the build of a new Copilot agent insight report for the specified number of days.}}
+
 ### [Start-SPOSiteContentMove](Start-SPOSiteContentMove.md)
 
 {{Manually Enter Start-SPOSiteContentMove Description Here}}