Learn Editor: Update Get-TenantPrivateChannelMigrationStatus.md

Author: rohanbharadwaj

teams/teams-ps/MicrosoftTeams/Get-TenantPrivateChannelMigrationStatus.md

@@ -13,7 +13,7 @@ title: Get-TenantPrivateChannelMigrationStatus
 
 ## SYNOPSIS
 
-You use the `Get-TenantPrivateChannelMigrationStatus` cmdlet to check the status of private channel migration for your tenant.
+Gets the private channel migration status for a tenant.
 
 ## SYNTAX
 
@@ -22,66 +22,139 @@ Get-TenantPrivateChannelMigrationStatus [<CommonParameters>]
 ```
 
 ## DESCRIPTION
-The `Get-TenantPrivateChannelMigrationStatus` cmdlet allows tenant administrators to track the status of the private channel migration for their Microsoft Teams organization. More details about the migration can be found [here](https://techcommunity.microsoft.com/blog/microsoftteamsblog/new-enhancements-in-private-channels-in-microsoft-teams-unlock-their-full-potent/4438767#)
 
-**Note:** This cmdlet requires tenant administrator permissions to execute.
+Gets the private channel migration status for the current tenant, including per-channel details for channels that were skipped or failed during migration.
+
+More details about the migration can be found [here](https://techcommunity.microsoft.com/blog/microsoftteamsblog/new-enhancements-in-private-channels-in-microsoft-teams-unlock-their-full-potent/4438767#).
+
+Note: This cmdlet requires tenant administrator permissions to execute.
 
 ## EXAMPLES
 
 ### Example 1
-This example retrieves the private channel migration status for the current tenant.
+
+Gets the migration status for a tenant where all channels have been migrated.
 
 ```powershell
 Get-TenantPrivateChannelMigrationStatus
 
-
 TenantId                     : 12345678-1234-1234-1234-123456789abc
 MigrationStatus              : Completed
 MigrationStartTimeStamp      : 2025-10-09T10:15:00.456Z
 MigrationCompletionTimeStamp : 2025-10-09T12:45:00.789Z
+Details                      : {"totalChannels":10,"migratedChannels":10,"failedChannels":0,"ownerlessChannels":0,"remainingChannels":0}
+```
+
+### Example 2
+
+Gets the migration status for a tenant where some channels require admin attention.
+
+```powershell
+Get-TenantPrivateChannelMigrationStatus
+
+TenantId                     : 94d200e4-2df1-45b9-bc3e-53cfa7cf4997
+MigrationStatus              : RequiresAdminAttention
+MigrationStartTimeStamp      : 2026-02-10T06:48:20.000Z
+MigrationCompletionTimeStamp :
+Details                      : {"totalChannels":10,"migratedChannels":6,"failedChannels":1,"ownerlessChannels":2,"remainingChannels":1,"ownerlessChannelsDetails":[{"channelThreadId":"19:70c903e82053408790c3941f614a4d36@thread.tacv2","teamId":"12025f7b-4e7d-4d4c-b597-10f52de1c198"},{"channelThreadId":"19:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6@thread.tacv2","teamId":"b94ac03c-ba25-4e79-89ab-d23f707863f7"}],"failedChannelsDetails":[{"channelThreadId":"19:07soOXSzSPB9aYC_2B94KJikrIWmDmK4W7cXith31FM1@thread.tacv2","teamId":"b94ac03c-ba25-4e79-89ab-d23f707863f7"}]}
+```
+
+### Example 3
+
+Parses the Details JSON and lists channels by category.
+
+```powershell
+$result = Get-TenantPrivateChannelMigrationStatus
+$details = $result.Details | ConvertFrom-Json
+
+Write-Host "Total: $($details.totalChannels), Migrated: $($details.migratedChannels), Failed: $($details.failedChannels), Ownerless: $($details.ownerlessChannels)"
+
+# List ownerless channels
+if ($details.ownerlessChannelsDetails) {
+    foreach ($ch in $details.ownerlessChannelsDetails) {
+        Write-Host "  Channel: $($ch.channelThreadId), Team: $($ch.teamId)"
+    }
+}
+
+# List failed channels (no action needed)
+if ($details.failedChannelsDetails) {
+    foreach ($ch in $details.failedChannelsDetails) {
+        Write-Host "  Channel: $($ch.channelThreadId), Team: $($ch.teamId)"
+    }
+}
 ```
 
 ## PARAMETERS
 
 ### 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).
 
 ## INPUTS
 
 ### None
-This cmdlet does not accept pipeline input.
 
 ## OUTPUTS
 
 ### System.Object
 
-This cmdlet returns a `PrivateChannelMigrationStatusResponse` object with the following properties:
+Returns a `PrivateChannelMigrationStatusResponse` object with the following properties:
+
+| Property | Type | Description |
+|---|---|---|
+| `TenantId` | String | The Microsoft Entra tenant identifier. |
+| `MigrationStatus` | String | Overall migration status for the tenant. Possible values: `NotStarted`, `InProgress`, `Completed`, `RequiresAdminAttention`. |
+| `MigrationStartTimeStamp` | DateTime | When migration started for this tenant. Empty if migration has not started. |
+| `MigrationCompletionTimeStamp` | DateTime | When migration completed. Only populated when all channels are done. |
+| `Details` | String | JSON string containing channel counts and per-channel detail arrays. |
 
-**TenantId**: The Azure AD tenant identifier for your organization.
+### Migration status values
 
-**MigrationStatus**: The current migration status for private channels in your tenant.
+| Value | Description |
+|---|---|
+| `NotStarted` | No private channels have been processed for this tenant. |
+| `InProgress` | Migration is underway. |
+| `Completed` | All private channels have been successfully migrated. |
+| `RequiresAdminAttention` | One or more channels were skipped because they have no owners. If these channels are still in use, a tenant admin or Teams service admin can add an owner to unblock migration. Failed channels do not require admin action and are retried automatically. |
 
-**MigrationStartTimeStamp**: The timestamp when the migration started for this tenant.
+### Details JSON fields
 
-**MigrationCompletionTimeStamp**: The timestamp when the migration completed for this tenant.
+| Field | Type | Description |
+|---|---|---|
+| `totalChannels` | Integer | Total number of private channels for this tenant. |
+| `migratedChannels` | Integer | Number of channels migrated successfully. |
+| `failedChannels` | Integer | Number of channels where migration failed. No admin action is needed. |
+| `ownerlessChannels` | Integer | Number of channels skipped because they have no owners. |
+| `remainingChannels` | Integer | Number of channels still in progress or not yet started. |
+| `ownerlessChannelsDetails` | Array | Per-channel details for ownerless channels. Each entry contains `channelThreadId` and `teamId`. |
+| `failedChannelsDetails` | Array | Per-channel details for failed channels. Each entry contains `channelThreadId` and `teamId`. |
+
+### Channel detail object
+
+| Field | Type | Description |
+|---|---|---|
+| `channelThreadId` | String | The unique identifier of the private channel. |
+| `teamId` | String | The unique identifier (GroupId) of the parent team. This is the same value used by the `-GroupId` parameter in [Get-Team](https://learn.microsoft.com/powershell/module/microsoftteams/get-team), [Get-TeamChannel](https://learn.microsoft.com/powershell/module/microsoftteams/get-teamchannel), and [Microsoft Graph team resource](https://learn.microsoft.com/graph/api/resources/team). |
 
 ## NOTES
-- This cmdlet requires tenant administrator permissions
-- The cmdlet connects to the Teams and Channels service to retrieve migration status information
-- Private channels remain functional throughout the migration process
-- This enhancement helps make private channels more scalable, manageable, and compliant
 
-Common migration status values include:
-- **NotStarted**: Migration has not yet begun
-- **InProgress**: Migration is currently running
-- **Completed**: Migration has finished successfully
+- This cmdlet requires tenant administrator permissions.
+- Private channels remain functional throughout the migration process.
+- The `Details` property is returned as a JSON string. Use `ConvertFrom-Json` to parse it.
+- When no ownerless or failed channels exist, the respective detail arrays may be empty or omitted from the JSON.
+- Failed channels do not require admin action. They are retried automatically.
+- Ownerless channels were skipped because they have no owners. If these channels are still in use, a tenant admin or Teams service admin can add an owner using [Add-TeamUser](https://learn.microsoft.com/powershell/module/microsoftteams/add-teamuser) and [Add-TeamChannelUser](https://learn.microsoft.com/powershell/module/microsoftteams/add-teamchanneluser).
 
 ## RELATED LINKS
+
 [New enhancements in Private Channels in Microsoft Teams unlock their full potential](https://techcommunity.microsoft.com/blog/microsoftteamsblog/new-enhancements-in-private-channels-in-microsoft-teams-unlock-their-full-potent/4438767)
 
 [Microsoft Teams PowerShell Overview](https://learn.microsoft.com/powershell/teams/)
 
 [Get-Team](https://learn.microsoft.com/powershell/module/microsoftteams/get-team)
 
-
 [Get-TeamChannel](https://learn.microsoft.com/powershell/module/microsoftteams/get-teamchannel)
+
+[Add-TeamUser](https://learn.microsoft.com/powershell/module/microsoftteams/add-teamuser)
+
+[Add-TeamChannelUser](https://learn.microsoft.com/powershell/module/microsoftteams/add-teamchanneluser)