Add documentation for the Copilot Insights Cmdlets

sharepoint/sharepoint-ps/sharepoint-online/Get-SPOCopilotAgentInsightsReport.md

@@ -0,0 +1,165 @@
+---
+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
+
+
+
+## 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 the report creation was triggered in UTC. |
+| Status               | The status of the report.                                   |
+| ReportPeriodInDays   | The report duration in days.                                |
+
+If this cmdlet is executed with `-ReportId` as parameter and `-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 last N 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    | RAC status (Yes/No) of the SharePoint site.              |
+| Restrict site discovery | RCD 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 last N 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    | RAC status (Yes/No) of the SharePoint site.              |
+| Restrict site discovery | RCD 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 last N 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 | Name of Copilot agent on the SharePoint site corresponding to that particular site template. |
+
+If this cmdlet is executed with both the parameters, i.e. `-ReportId` and `-Action`, and if the value of `-Action` is set as `View`, it will display the same result as described above. If the value of `-Action` is set to `Download`, it will download the full report in CSV format to the same path from where the command was run.
+
+> [!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 insights 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 insights report of ReportId: `9d946216-afe7-49f5-8267-7b662435c70b` to the same path from where the command was run.
+
+## PARAMETERS
+
+### -ReportId
+
+It is an optional parameter, and 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 is an optional parameter, and it specifies the kind of report to view or download. There are 3 kinds of sub-reports: CopilotAgentsOnSites, TopSites, SiteDistribution.
+
+```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 is an optional parameter, and it specifies whether to view or download a specific report.
+
+```yaml
+Type: ActionType
+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)
+
+[Start-SPOCopilotAgentInsightsReport](./Start-SPOCopilotAgentInsightsReport.md)

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
+
+This cmdlet enables administrator to trigger the build of a new Copilot Agent Insight report for the last N days.
+
+## SYNTAX
+
+```powershell
+Start-SPOCopilotAgentInsightsReport [-ReportPeriodInDays <Int>] [-Force <SwitchParameter>]
+```
+
+## DESCRIPTION
+
+After this cmdlet is executed, the Copilot Agent Insight report generation request for the last N 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 the report creation was triggered in UTC. |
+| Status               | The status of the report.                                   |
+| ReportPeriodInDays   | The report duration in days.                                |
+
+## EXAMPLES
+
+### -----------------------EXAMPLE 1-----------------------------
+
+```powershell
+Start-SPOCopilotAgentInsightsReport
+```
+
+Example 1 generates the Copilot agent insights report for a default duration of 1 day as the parameter `–ReportPeriodInDays` is not provided.
+
+### -----------------------EXAMPLE 2-----------------------------
+
+```powershell
+Start-SPOCopilotAgentInsightsReport –ReportPeriodInDays 14
+```
+
+Example 2 generates the Copilot Agent insights report for a specified duration of 14 days.
+
+## PARAMETERS
+
+### -ReportPeriodInDays
+
+It is an optional parameter, and it specifies the duration of the Copilot Agent insights 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: None
+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)