Cut 4862 status reporting v2

ModuleChangelog.md

@@ -1,3 +1,21 @@
+## 2.12.0
+
+Release Date: January 15, 2026
+
+#### RELEASE NOTES
+
+```
+This release includes the option to update ADMU status on the JumpCloud system description field when migrating remotely. This allows administrators to track migration progress remotely.
+```
+
+#### FEATURES:
+
+Additional method for remotely migrating system by reading the device description field.
+
+#### IMPROVEMENTS:
+
+Several new tests added to validate new features and existing functionality.
+
 ## 2.11.0
 
 Release Date: January 2, 2026
@@ -56,7 +74,6 @@ Patch release to address several issues.
 - This release introduces the ability to set a device's primary user using the PrimaryUser parameter. This can only be done when using the AutoBindJCUser feature as well as using SystemContext.
 - Profile image permission backup functionality added
 
-
 ## 2.9.4
 
 Release Date: November 06, 2025

jumpcloud-ADMU/Docs/Start-Migration.md

@@ -403,4 +403,4 @@ This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable
 
 ## RELATED LINKS
 
-[https://github.com/TheJumpCloud/jumpcloud-ADMU/wiki/Start-Migration](https://github.com/TheJumpCloud/jumpcloud-ADMU/wiki/Start-Migration)
+[https://github.com/TheJumpCloud/jumpcloud-ADMU/wiki/Start-Migration](https://github.com/TheJumpCloud/jumpcloud-ADMU/wiki/Start-Migration)

jumpcloud-ADMU/Docs/Start-Reversion.md

@@ -0,0 +1,201 @@
+---
+external help file: JumpCloud.ADMU-help.xml
+Module Name: JumpCloud.ADMU
+online version: https://github.com/TheJumpCloud/jumpcloud-ADMU/wiki/Start-Reversion
+schema: 2.0.0
+---
+
+# Start-Reversion
+
+## SYNOPSIS
+Reverts a user migration by restoring original registry files for a specified Windows SID.
+
+## SYNTAX
+
+```
+Start-Reversion [-UserSID] <String> [[-TargetProfileImagePath] <String>] [-form <Boolean>] [-UserName <String>]
+ [-ProfileSize <String>] [-DryRun] [-Force] [-WhatIf] [-Confirm] [<CommonParameters>]
+```
+
+## DESCRIPTION
+This function reverts a user migration by:
+1.
+Looking up the account SID in the Windows registry ProfileList
+2.
+Identifying the .ADMU profile path
+3.
+Restoring original NTUSER.DAT and UsrClass.dat files from backups
+4.
+Preserving migrated files with _migrated suffix for rollback purposes
+
+## EXAMPLES
+
+### EXAMPLE 1
+```
+Start-Reversion -UserSID "S-1-5-21-123456789-1234567890-123456789-1001"
+Reverts the migration for the specified user SID using the registry profile path.
+```
+
+### EXAMPLE 2
+```
+Start-Reversion -UserSID "S-1-5-21-123456789-1234567890-123456789-1001" -TargetProfileImagePath "C:\Users\john.doe"
+Reverts the migration using a specific target profile path instead of the registry value.
+```
+
+### EXAMPLE 3
+```
+Start-Reversion -UserSID "S-1-5-21-123456789-1234567890-123456789-1001" -DryRun
+Shows what would be reverted without making actual changes.
+```
+
+## PARAMETERS
+
+### -UserSID
+The Windows Security Identifier (SID) of the user account to revert.
+
+```yaml
+Type: System.String
+Parameter Sets: (All)
+Aliases:
+
+Required: True
+Position: 1
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -TargetProfileImagePath
+The actual profile path to revert.
+If not specified, will use the path from the registry.
+This path will be validated to ensure it exists and is associated with the UserSID.
+
+```yaml
+Type: System.String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: 2
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -form
+{{ Fill form Description }}
+
+```yaml
+Type: System.Boolean
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -UserName
+{{ Fill UserName Description }}
+
+```yaml
+Type: System.String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -ProfileSize
+{{ Fill ProfileSize Description }}
+
+```yaml
+Type: System.String
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -DryRun
+Shows what actions would be performed without actually executing them.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Force
+Bypasses confirmation prompts and forces the revert operation.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: False
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -WhatIf
+Shows what would happen if the cmdlet runs.
+The cmdlet is not run.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+Parameter Sets: (All)
+Aliases: wi
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
+### -Confirm
+Prompts you for confirmation before running the cmdlet.
+
+```yaml
+Type: System.Management.Automation.SwitchParameter
+Parameter Sets: (All)
+Aliases: cf
+
+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](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+## OUTPUTS
+
+### [PSCustomObject] Returns revert operation results with success status and details.
+## NOTES
+
+## RELATED LINKS

jumpcloud-ADMU/JumpCloud.ADMU.psd1

@@ -3,7 +3,7 @@
 #
 # Generated by: JumpCloud Customer Tools Team
 #
-# Generated on: 12/15/2025
+# Generated on: 1/15/2026
 #
 
 @{
@@ -12,7 +12,7 @@
 RootModule = 'JumpCloud.ADMU.psm1'
 
 # Version number of this module.
-ModuleVersion     = '2.11.0'
+ModuleVersion = '2.12.0'
 
 # Supported PSEditions
 # CompatiblePSEditions = @()
@@ -69,7 +69,7 @@ Description = 'Powershell Module to run JumpCloud Active Directory Migration Uti
 # NestedModules = @()
 
 # Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
-FunctionsToExport = @('Start-Migration' , 'Start-Reversion')
+FunctionsToExport = 'Start-Migration', 'Start-Reversion'
 
 # Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
 CmdletsToExport = '*'

jumpcloud-ADMU/Powershell/Private/DisplayForms/Build-MigrationDescription.ps1

@@ -0,0 +1,120 @@
+function Build-MigrationDescription {
+    <#
+    .SYNOPSIS
+    Builds or updates a migration description object for the device.
+
+    .DESCRIPTION
+    Creates a standardized description array with user migration status.
+    Handles both creating new descriptions and updating existing ones.
+
+    .PARAMETER UserSID
+    The SID of the user being migrated.
+
+    .PARAMETER MigrationUsername
+    The username of the user being migrated.
+
+    .PARAMETER StatusMessage
+    The status message to record.
+
+    .PARAMETER Percent
+    The progress percentage (or "ERROR" for failures).
+
+    .PARAMETER LocalPath
+    The local user profile path.
+
+    .PARAMETER authMethod
+    The authentication method used for reporting.
+    #>
+    param(
+
+        [Parameter(Mandatory = $true)]
+        [string]$UserSID,
+
+        [Parameter(Mandatory = $true)]
+        [string]$MigrationUsername,
+
+        [Parameter(Mandatory = $true)]
+        [string]$StatusMessage,
+
+        [Parameter(Mandatory = $true)]
+        [string]$Percent,
+
+        [Parameter(Mandatory = $false)]
+        [string]$LocalPath,
+
+        [Parameter(Mandatory = $false)]
+        [string]$authMethod
+    )
+
+    # Determine the status value based on percent
+    $statusValue = if ($Percent -eq "ERROR") {
+        "Failed"
+    } elseif ($Percent -eq "100%") {
+        "Completed"
+    } else {
+        "InProgress"
+    }
+
+    # determine the auth method
+    switch ($authMethod) {
+        "systemcontextapi" {
+            # get the systemDescription with system context api
+            $sysContextResult = Invoke-SystemContextAPI -Method GET -Endpoint 'Systems'
+            $ExistingDescription = $sysContextResult.description
+        }
+        "apikey" {
+            # get the systemDescription with api key
+            $apiKeyResult = Invoke-SystemAPI -JcApiKey $script:JumpCloudAPIKey -jcOrgID $script:JumpCloudOrgID -systemId $script:validatedSystemID -method "GET"
+            $ExistingDescription = $apiKeyResult.description
+        }
+        "none" {
+            # if no auth method, exit function return null
+            Write-ToLog -Message "Error fetching existing description: $_" -Level Warning
+            return $null
+        }
+    }
+    # Initialize or update description array
+    if (-not [string]::IsNullOrEmpty($ExistingDescription)) {
+        try {
+            $description = $ExistingDescription | ConvertFrom-Json
+            # Ensure it's always an array
+            if ($description -isnot [array]) { $description = @($description) }
+            # find the userSID in the existing description
+            $foundUser = $description | Where-Object { $_.sid -eq $UserSID }
+            if ($foundUser) {
+                # only update the message and status
+                $foundUser.msg = $StatusMessage
+                $foundUser.st = $statusValue
+            } else {
+                # User not found in existing description, add new entry
+                $description += [PSCustomObject]@{
+                    sid       = $UserSID
+                    un        = $MigrationUsername
+                    localPath = if ($LocalPath) { $LocalPath.Replace('\', '/') } else { $null }
+                    msg       = $StatusMessage
+                    st        = $statusValue
+                    uid       = $null
+                    lastLogin = $null
+                }
+            }
+        } catch {
+            Write-ToLog -Message "Error parsing existing system description JSON: $_" -Level Warning
+            # Fall through to create new description
+            $description = $null
+        }
+    }
+    # Create new description if not already initialized - always as array
+    if (-not $description) {
+        $description = @([PSCustomObject]@{
+                sid       = $UserSID
+                un        = $MigrationUsername
+                localPath = if ($LocalPath) { $LocalPath.Replace('\', '/') } else { $null }
+                msg       = $StatusMessage
+                st        = $statusValue
+                uid       = $null
+                lastLogin = $null
+            })
+    }
+    # Ensure return is always an array (use unary comma for PowerShell 5.1 compatibility)
+    return @(, $description)
+}