Set-VmsDeviceStorage.ps1

function Set-VmsDeviceStorage {
    <#
    .SYNOPSIS
    Set the target storage configuration for a device in XProtect.
    
    .DESCRIPTION
    The `Set-VmsDeviceStorage` cmdlet sets the target storage configuration for a device in XProtect.
    
    .PARAMETER Device
    Tge one or more devices returned by the Get-VmsCamera, Get-Microphone, Get-Speaker, or Get-Metadata cmdlets.
    
    .PARAMETER Destination
    The display name, or the Configuration API Path for the target storage configuration. If the device is already
    recording to the destination, the operation should complete without errors.
    
    .PARAMETER PassThru
    Pass the Device(s) back to the pipeline after a move operation is completed.
    
    .EXAMPLE
    Get-VmsHardware | Get-VmsCamera | Set-VmsDeviceStorage -Destination 'Longterm Storage' -PassThru
    
    Get all enabled cameras on all recording servers and update them to record to the storage configuration with the
    name 'Longterm Storage'. If the storage does not exist, an error will be thrown. If the storage exists and the
    device is already assigned to it, no error will be thrown. Each camera will be returned to the pipeline after the
    operation completes thanks to the "-PassThru" switch.

    .EXAMPLE
    $storageName = 'Longterm storage'
    Get-VmsHardware | ForEach-Object {
        # Get-VmsCamera only returns enabled cameras by default. The -EnableFilter will return all camera channels instead.
        $_ | Get-VmsCamera -EnableFilter All | Set-VmsDeviceStorage -Destination $storageName
        
        # The other Get-<device> cmdlets have not been updated to match this behavior.
        $_ | Get-Microphone | Set-VmsDeviceStorage -Destination $storageName
        $_ | Get-Speaker  | Set-VmsDeviceStorage -Destination $storageName
        $_ | Get-Metadata | Set-VmsDeviceStorage -Destination $storageName
    }

    Gets all cameras, microphones, speakers, and metadata devices from all hardware on all recording servers and assigns
    them all to a storage configuration named "Longterm storage" if it exists.

    .EXAMPLE
    $storageName = 'Longterm storage'
    $recorders = Get-VmsRecordingServer | Out-GridView -OutputMode Multiple
    $recorders | Get-VmsHardware | ForEach-Object {
        # Get-VmsCamera only returns enabled cameras by default. The -EnableFilter will return all camera channels instead.
        $_ | Get-VmsCamera -EnableFilter All | Set-VmsDeviceStorage -Destination $storageName
        
        # The other Get-<device> cmdlets have not been updated to match this behavior.
        $_ | Get-Microphone | Set-VmsDeviceStorage -Destination $storageName
        $_ | Get-Speaker | Set-VmsDeviceStorage -Destination $storageName
        $_ | Get-Metadata | Set-VmsDeviceStorage -Destination $storageName
    }

    Prompts for a selection of one or more recording servers, then proceeds assign all cameras, microphones, speakers,
    and metadata to a storage configuration named "Longterm storage" if it exists.
    
    .NOTES
    Previous versions of XProtect supported a "moveData" boolean (true/false) option, but this was deprecated in MIP SDK
    and no longer has any effect. Previous recordings will not be moved to the new storage configuration. They will
    remain in the old storage configuration and will be deleted over time as recordings reach the maximum retention time
    of that original storage configuration.
    #>
    [CmdletBinding(SupportsShouldProcess)]
    param (
        [Parameter(Mandatory, ValueFromPipeline)]
        [VideoOS.Platform.ConfigurationItems.IConfigurationItem[]]
        $Device,

        [Parameter(Mandatory)]
        [string]
        $Destination,

        [Parameter()]
        [switch]
        $PassThru
    )
    
    process {
        foreach ($currentDevice in $Device) {
            try {
                $taskInfo = $currentDevice.ChangeDeviceRecordingStorage()
                $itemSelection =  $taskInfo.ItemSelectionValues.GetEnumerator() | Where-Object { $_.Value -eq $Destination -or $_.Key -eq $Destination }
                if ($itemSelection.Count -eq 0) {
                    Write-Error -TargetObject $currentDevice "No storage destination available for device '$currentDevice' named '$Destination'" -RecommendedAction "Use one of the available destinations: $($taskInfo.ItemSelectionValues.Keys -join ', ')"
                    continue
                } elseif ($itemSelection.Count -gt 1) {
                    Write-Error -TargetObject $currentDevice "More than one storage destination matching '$Destination' for device '$currentDevice'." -RecommendedAction "Check your recording server storage configuration. The only way you should see this error is if a storage configuration display name matches a storage configuration ID on that recording server."
                    continue
                }
                
                if ($PSCmdlet.ShouldProcess($currentDevice, "Set storage to $($itemSelection.Key)")) {
                    $taskInfo.ItemSelection = $itemSelection.Value
                    $task = $taskInfo.ExecuteDefault()
                    $null = $task | Wait-VmsTask -Title "Change device recording storage: $currentDevice" -Cleanup
                    if ($PassThru) {
                        $currentDevice
                    }
                }
            } catch {
                Write-Error -TargetObject $currentDevice -Exception $_.Exception -Message $_.Exception.Message -Category $_.CategoryInfo.Category
            }
        }
    }
}