|
| 1 | +function Invoke-CIPPStandardAutoArchive { |
| 2 | + <# |
| 3 | + .FUNCTIONALITY |
| 4 | + Internal |
| 5 | + .COMPONENT |
| 6 | + (APIName) AutoArchive |
| 7 | + .SYNOPSIS |
| 8 | + (Label) Configure Auto-Archiving Threshold |
| 9 | + .DESCRIPTION |
| 10 | + (Helptext) Configures the auto-archiving threshold percentage for the tenant. When a mailbox exceeds this threshold, the oldest items are automatically moved to the archive mailbox. Archive must be enabled manually or via the CIPP standard 'Enable Online Archive for all users'. More information can be found in [Microsoft's documentation.](https://learn.microsoft.com/en-us/exchange/security-and-compliance/messaging-records-management/auto-archiving) |
| 11 | + (DocsDescription) Configures the auto-archiving threshold at the organization level. Auto-archiving automatically moves the oldest items from a user's primary mailbox to their archive mailbox when mailbox usage exceeds the configured threshold percentage. This prevents mail flow disruptions caused by full mailboxes. Valid range is 80-100, where 100 disables auto-archiving for the tenant. More information can be found in [Microsoft's documentation.](https://learn.microsoft.com/en-us/exchange/security-and-compliance/messaging-records-management/auto-archiving) |
| 12 | + .NOTES |
| 13 | + CAT |
| 14 | + Exchange Standards |
| 15 | + TAG |
| 16 | + EXECUTIVETEXT |
| 17 | + Configures automatic archiving of mailbox items when storage approaches capacity, preventing email delivery failures due to full mailboxes. This proactive storage management ensures business continuity and reduces helpdesk tickets related to mailbox quota issues. |
| 18 | + ADDEDCOMPONENT |
| 19 | + {"type":"number","name":"standards.AutoArchive.AutoArchivingThresholdPercentage","label":"Auto-Archiving Threshold Percentage (80-100, default 96, 100 disables)","defaultValue":96} |
| 20 | + IMPACT |
| 21 | + Low Impact |
| 22 | + ADDEDDATE |
| 23 | + 2025-12-11 |
| 24 | + POWERSHELLEQUIVALENT |
| 25 | + Set-OrganizationConfig -AutoArchivingThresholdPercentage 80-100 |
| 26 | + RECOMMENDEDBY |
| 27 | + UPDATECOMMENTBLOCK |
| 28 | + Run the Tools\Update-StandardsComments.ps1 script to update this comment block |
| 29 | + .LINK |
| 30 | + https://docs.cipp.app/user-documentation/tenant/standards/list-standards |
| 31 | + #> |
| 32 | + |
| 33 | + param($Tenant, $Settings) |
| 34 | + $TestResult = Test-CIPPStandardLicense -StandardName 'AutoArchive' -TenantFilter $Tenant -RequiredCapabilities @('EXCHANGE_S_STANDARD', 'EXCHANGE_S_ENTERPRISE', 'EXCHANGE_S_STANDARD_GOV', 'EXCHANGE_S_ENTERPRISE_GOV', 'EXCHANGE_LITE') |
| 35 | + |
| 36 | + if ($TestResult -eq $false) { |
| 37 | + Write-Host "We're exiting as the correct license is not present for this standard." |
| 38 | + return $true |
| 39 | + } |
| 40 | + |
| 41 | + # Get the threshold value from settings |
| 42 | + $DesiredThreshold = [int]($Settings.AutoArchivingThresholdPercentage) |
| 43 | + |
| 44 | + # Validate the threshold is within valid range |
| 45 | + if ($DesiredThreshold -lt 80 -or $DesiredThreshold -gt 100) { |
| 46 | + Write-LogMessage -API 'Standards' -Tenant $Tenant -Message "Invalid AutoArchivingThresholdPercentage value: $DesiredThreshold. Must be between 80 and 100." -Sev Error |
| 47 | + return |
| 48 | + } |
| 49 | + |
| 50 | + try { |
| 51 | + $CurrentState = (New-ExoRequest -tenantid $Tenant -cmdlet 'Get-OrganizationConfig' -Select 'AutoArchivingThresholdPercentage').AutoArchivingThresholdPercentage |
| 52 | + } catch { |
| 53 | + $ErrorMessage = Get-CippException -Exception $_ |
| 54 | + Write-LogMessage -API 'Standards' -Tenant $Tenant -Message "Could not get the AutoArchive state for $Tenant. Error: $($ErrorMessage.NormalizedError)" -Sev Error -LogData $ErrorMessage |
| 55 | + return |
| 56 | + } |
| 57 | + |
| 58 | + $CorrectState = $CurrentState -eq $DesiredThreshold |
| 59 | + |
| 60 | + if ($Settings.remediate -eq $true) { |
| 61 | + Write-Host 'Time to remediate' |
| 62 | + |
| 63 | + if ($CorrectState) { |
| 64 | + Write-LogMessage -API 'Standards' -Tenant $Tenant -Message "Auto-archiving threshold is already set to $CurrentState%." -Sev Info |
| 65 | + } else { |
| 66 | + try { |
| 67 | + $null = New-ExoRequest -tenantid $Tenant -cmdlet 'Set-OrganizationConfig' -cmdParams @{ AutoArchivingThresholdPercentage = $DesiredThreshold } |
| 68 | + Write-LogMessage -API 'Standards' -Tenant $Tenant -Message "Auto-archiving threshold has been set to $DesiredThreshold%." -Sev Info |
| 69 | + } catch { |
| 70 | + $ErrorMessage = Get-CippException -Exception $_ |
| 71 | + Write-LogMessage -API 'Standards' -Tenant $Tenant -Message "Failed to set auto-archiving threshold. Error: $($ErrorMessage.NormalizedError)" -Sev Error -LogData $ErrorMessage |
| 72 | + } |
| 73 | + } |
| 74 | + } |
| 75 | + |
| 76 | + if ($Settings.alert -eq $true) { |
| 77 | + |
| 78 | + if ($CorrectState) { |
| 79 | + Write-LogMessage -API 'Standards' -Tenant $Tenant -Message "Auto-archiving threshold is correctly set to $CurrentState%." -Sev Info |
| 80 | + } else { |
| 81 | + Write-StandardsAlert -message "Auto-archiving threshold is set to $CurrentState% but should be $DesiredThreshold%." -object @{ CurrentThreshold = $CurrentState; DesiredThreshold = $DesiredThreshold } -tenant $Tenant -standardName 'AutoArchive' -standardId $Settings.standardId |
| 82 | + Write-LogMessage -API 'Standards' -Tenant $Tenant -Message "Auto-archiving threshold is set to $CurrentState% but should be $DesiredThreshold%." -Sev Info |
| 83 | + } |
| 84 | + } |
| 85 | + |
| 86 | + if ($Settings.report -eq $true) { |
| 87 | + Add-CIPPBPAField -FieldName 'AutoArchive' -FieldValue $CorrectState -StoreAs bool -Tenant $Tenant |
| 88 | + |
| 89 | + if ($CorrectState) { |
| 90 | + $FieldValue = $true |
| 91 | + } else { |
| 92 | + $FieldValue = @{ CurrentThreshold = $CurrentState; DesiredThreshold = $DesiredThreshold } |
| 93 | + } |
| 94 | + Set-CIPPStandardsCompareField -FieldName 'standards.AutoArchive' -FieldValue $FieldValue -Tenant $Tenant |
| 95 | + } |
| 96 | +} |
0 commit comments