feat: Add functions for scheduling forwarding vacation mode (KelvinTegelaar#1985)

Frontend PR: KelvinTegelaar/CIPP#5800

Author: KelvinTegelaar

Modules/CIPPCore/Public/Entrypoints/HTTP Functions/Email-Exchange/Administration/Invoke-ExecScheduleForwardingVacation.ps1

@@ -0,0 +1,99 @@
+function Invoke-ExecScheduleForwardingVacation {
+    <#
+    .FUNCTIONALITY
+        Entrypoint
+    .ROLE
+        Exchange.Mailbox.ReadWrite
+    #>
+    [CmdletBinding()]
+    param($Request, $TriggerMetadata)
+
+    $APIName = $Request.Params.CIPPEndpoint
+    $Headers = $Request.Headers
+
+    try {
+        $TenantFilter = $Request.Body.tenantFilter
+        $Users = @($Request.Body.Users)
+        $ForwardOption = $Request.Body.forwardOption
+        $ForwardInternal = $Request.Body.ForwardInternal.value ?? $Request.Body.ForwardInternal
+        $ForwardExternal = $Request.Body.ForwardExternal
+        $KeepCopy = if (-not [string]::IsNullOrWhiteSpace($Request.Body.KeepCopy)) { [System.Convert]::ToBoolean($Request.Body.KeepCopy) } else { $false }
+        $StartDate = $Request.Body.startDate
+        $EndDate = $Request.Body.endDate
+
+        $UserUPNs = @($Users | ForEach-Object { $_.addedFields.userPrincipalName ?? $_.value ?? $_ })
+
+        if ($UserUPNs.Count -eq 0) {
+            throw 'At least one user is required.'
+        }
+
+        $UserDisplay = ($UserUPNs | Select-Object -First 3) -join ', '
+        if ($UserUPNs.Count -gt 3) { $UserDisplay += " (+$($UserUPNs.Count - 3) more)" }
+
+        $SharedParams = [PSCustomObject]@{
+            TenantFilter  = $TenantFilter
+            Users         = $UserUPNs
+            ForwardOption = $ForwardOption
+            KeepCopy      = $KeepCopy
+            APIName       = $APIName
+        }
+
+        switch ($ForwardOption) {
+            'internalAddress' {
+                if ([string]::IsNullOrWhiteSpace($ForwardInternal)) {
+                    throw 'Forwarding target is required for internal forwarding.'
+                }
+                $SharedParams.ForwardInternal = $ForwardInternal
+                $TargetValue = $ForwardInternal
+            }
+            'ExternalAddress' {
+                if ([string]::IsNullOrWhiteSpace($ForwardExternal)) {
+                    throw 'Forwarding target is required for external forwarding.'
+                }
+                $SharedParams.ForwardExternal = $ForwardExternal
+                $TargetValue = $ForwardExternal
+            }
+            default {
+                throw "$ForwardOption is not a valid forwarding option."
+            }
+        }
+
+        Add-CIPPScheduledTask -Task ([PSCustomObject]@{
+                TenantFilter  = $TenantFilter
+                Name          = "Add Forwarding Vacation Mode: $UserDisplay -> $TargetValue"
+                Command       = @{ value = 'Set-CIPPVacationForwarding'; label = 'Set-CIPPVacationForwarding' }
+                Parameters    = ($SharedParams | Select-Object *, @{ n = 'Action'; e = { 'Add' } })
+                ScheduledTime = [int64]$StartDate
+                PostExecution = $Request.Body.postExecution
+                Reference     = $Request.Body.reference
+            }) -hidden $false
+
+        Add-CIPPScheduledTask -Task ([PSCustomObject]@{
+                TenantFilter  = $TenantFilter
+                Name          = "Remove Forwarding Vacation Mode: $UserDisplay"
+                Command       = @{ value = 'Set-CIPPVacationForwarding'; label = 'Set-CIPPVacationForwarding' }
+                Parameters    = [PSCustomObject]@{
+                    TenantFilter = $TenantFilter
+                    Users        = $UserUPNs
+                    Action       = 'Remove'
+                    APIName      = $APIName
+                }
+                ScheduledTime = [int64]$EndDate
+                PostExecution = $Request.Body.postExecution
+                Reference     = $Request.Body.reference
+            }) -hidden $false
+
+        $Result = "Successfully scheduled forwarding vacation mode for $UserDisplay."
+        $StatusCode = [HttpStatusCode]::OK
+    } catch {
+        $ErrorMessage = Get-CippException -Exception $_
+        $Result = "Failed to schedule forwarding vacation mode: $($ErrorMessage.NormalizedError)"
+        Write-LogMessage -headers $Headers -API $APIName -message $Result -Sev Error -tenant $TenantFilter -LogData $ErrorMessage
+        $StatusCode = [HttpStatusCode]::InternalServerError
+    }
+
+    return ([HttpResponseContext]@{
+            StatusCode = $StatusCode
+            Body       = @{ Results = $Result }
+        })
+}

Modules/CIPPCore/Public/Set-CIPPVacationForwarding.ps1

@@ -0,0 +1,55 @@
+function Set-CIPPVacationForwarding {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)] [string]$TenantFilter,
+        [Parameter(Mandatory)] [ValidateSet('Add', 'Remove')] [string]$Action,
+        [object[]]$Users,
+        [ValidateSet('internalAddress', 'ExternalAddress')] [string]$ForwardOption,
+        [string]$ForwardInternal,
+        [string]$ForwardExternal,
+        [bool]$KeepCopy,
+        [string]$APIName = 'Forwarding Vacation Mode',
+        $Headers
+    )
+
+    $Results = [System.Collections.Generic.List[string]]::new()
+    $Users = @($Users)
+
+    foreach ($upn in $Users) {
+        if ([string]::IsNullOrWhiteSpace($upn)) { continue }
+
+        try {
+            if ($Action -eq 'Remove') {
+                $result = Set-CIPPForwarding -UserID $upn -Username $upn -TenantFilter $TenantFilter -Headers $Headers -APIName $APIName -Disable $true
+            } else {
+                switch ($ForwardOption) {
+                    'internalAddress' {
+                        if ([string]::IsNullOrWhiteSpace($ForwardInternal)) {
+                            throw 'ForwardInternal is required for internal forwarding.'
+                        }
+
+                        $result = Set-CIPPForwarding -UserID $upn -Username $upn -TenantFilter $TenantFilter -Headers $Headers -APIName $APIName -Forward $ForwardInternal -KeepCopy $KeepCopy
+                    }
+                    'ExternalAddress' {
+                        if ([string]::IsNullOrWhiteSpace($ForwardExternal)) {
+                            throw 'ForwardExternal is required for external forwarding.'
+                        }
+
+                        $result = Set-CIPPForwarding -UserID $upn -Username $upn -TenantFilter $TenantFilter -Headers $Headers -APIName $APIName -ForwardingSMTPAddress $ForwardExternal -KeepCopy $KeepCopy
+                    }
+                    default {
+                        throw "Unsupported forward option: $ForwardOption"
+                    }
+                }
+            }
+
+            $Results.Add($result)
+        } catch {
+            $ErrorMessage = Get-CippException -Exception $_
+            $Results.Add("Failed to set forwarding for ${upn}: $($ErrorMessage.NormalizedError)")
+            Write-LogMessage -headers $Headers -API $APIName -tenant $TenantFilter -message "Failed to set forwarding for ${upn}: $($ErrorMessage.NormalizedError)" -Sev Error -LogData $ErrorMessage
+        }
+    }
+
+    return $Results
+}

Modules/CIPPCore/Public/Set-CIPPVacationOOO.ps1

@@ -77,9 +77,9 @@ function Set-CIPPVacationOOO {
             $result = Set-CIPPOutOfOffice @SplatParams
             $Results.Add($result)
         } catch {
-            $err = (Get-CippException -Exception $_).NormalizedError
-            $Results.Add("Failed to set OOO for ${upn}: $err")
-            Write-LogMessage -headers $Headers -API $APIName -tenant $TenantFilter -message "Failed OOO for ${upn}: $err" -Sev Error
+            $err = Get-CippException -Exception $_
+            $Results.Add("Failed to set OOO for ${upn}: $($err.NormalizedError)")
+            Write-LogMessage -headers $Headers -API $APIName -tenant $TenantFilter -message "Failed OOO for ${upn}: $($err.NormalizedError)" -Sev Error -LogData $err
         }
     }
     return $Results