Merge pull request #1460 from kris6673/issue4166

Feat: Add TERRL status alert

Author: KelvinTegelaar

Modules/CIPPCore/Public/Alerts/Get-CIPPAlertTERRL.ps1

@@ -0,0 +1,39 @@
+function Get-CIPPAlertTERRL {
+    <#
+    .FUNCTIONALITY
+        Entrypoint
+    #>
+    [CmdletBinding()]
+    Param (
+        [Parameter(Mandatory = $false)]
+        [Alias('input')]
+        $InputValue,
+        $TenantFilter
+    )
+
+    try {
+        # Set threshold with fallback to 80%
+        $Threshold = if ([string]::IsNullOrWhiteSpace($InputValue)) { 80 } else { [int]$InputValue }
+
+        # Get TERRL status
+        $TerrlStatus = New-ExoRequest -tenantid $TenantFilter -cmdlet 'Get-LimitsEnforcementStatus'
+
+        if ($TerrlStatus) {
+            $UsagePercentage = [math]::Round(($TerrlStatus.ObservedValue / $TerrlStatus.Threshold) * 100, 2)
+
+            if ($UsagePercentage -gt $Threshold) {
+                $AlertData = [PSCustomObject]@{
+                    UsagePercentage    = $UsagePercentage
+                    CurrentVolume      = $TerrlStatus.ObservedValue
+                    ThresholdLimit     = $TerrlStatus.Threshold
+                    EnforcementEnabled = $TerrlStatus.EnforcementEnabled
+                    Verdict            = $TerrlStatus.Verdict
+                    Message            = 'Tenant is at {0}% of their TERRL limit (using {1} of {2} messages). Tenant Enforcement Status: {3}' -f $UsagePercentage, $TerrlStatus.ObservedValue, $TerrlStatus.Threshold, $TerrlStatus.Verdict
+                }
+                Write-AlertTrace -cmdletName $MyInvocation.MyCommand -tenantFilter $TenantFilter -data $AlertData
+            }
+        }
+    } catch {
+        Write-AlertMessage -tenant $($TenantFilter) -message "Could not get TERRL status for $($TenantFilter): $(Get-NormalizedError -message $_.Exception.message)"
+    }
+}

cspell.json

@@ -4,66 +4,67 @@
     "dictionaryDefinitions": [],
     "dictionaries": [],
     "words": [
-      "Intune",
-      "Entra",
-      "GDAP",
-      "CIPP",
-      "CIPP-API",
-      "OBEE",
-      "TNEF",
-      "winmail",
-      "AITM",
-      "Yubikey",
-      "Sherweb",
-      "Autotask",
-      "Connectwise",
-      "Datto",
-      "Bluetrait",
-      "ADMS",
-      "SSPR",
-      "PSTN",
-      "Passwordless",
+        "ADMS",
+        "AITM",
+        "Autotask",
+        "Bluetrait",
+        "CIPP",
+        "CIPP-API",
+        "Connectwise",
+        "Datto",
+        "Entra",
+        "GDAP",
+        "Intune",
+        "OBEE",
+        "Passwordless",
+        "PSTN",
+        "Sherweb",
+        "SSPR",
+        "Terrl",
+        "TNEF",
+        "winmail",
+        "Yubikey"
     ],
     "ignoreWords": [
-      "tenantid",
-      "APINAME",
-      "CIPPBPA",
-      "CIPPCA",
-      "CIPPSPO",
-      "CIPPAPI",
-      "Addins",
-      "Helptext",
-      "ADDEDCOMPONENT",
-      "ADDEDDATE",
-      "POWERSHELLEQUIVALENT",
-      "RECOMMENDEDBY",
-      "UPDATECOMMENTBLOCK",
-      "DISABLEDFEATURES",
-      "pscustomobject",
-      "microsoftonline",
-      "mdo_safeattachments",
-      "mdo_highconfidencespamaction",
-      "mdo_highconfidencephishaction",
-      "mdo_phisspamacation",
-      "mdo_spam_notifications_only_for_admins",
-      "mdo_antiphishingpolicies",
-      "mdo_phishthresholdlevel",
-      "mdo_autoforwardingmode",
-      "mdo_blockmailforward",
-      "mdo_zapspam",
-      "mdo_zapphish",
-      "mdo_zapmalware",
-      "mdo_safedocuments",
-      "mdo_commonattachmentsfilter",
-      "mdo_safeattachmentpolicy",
-      "mdo_safelinksforemail",
-      "mdo_safelinksforOfficeApps",
-      "exo_storageproviderrestricted",
-      "exo_individualsharing",
-      "exo_outlookaddins",
-      "exo_mailboxaudit",
-      "exo_mailtipsenabled",
-      "mip_search_auditlog",
+        "tenantid",
+        "APINAME",
+        "CIPPBPA",
+        "CIPPCA",
+        "CIPPSPO",
+        "CIPPAPI",
+        "Addins",
+        "Helptext",
+        "ADDEDCOMPONENT",
+        "ADDEDDATE",
+        "POWERSHELLEQUIVALENT",
+        "RECOMMENDEDBY",
+        "UPDATECOMMENTBLOCK",
+        "DISABLEDFEATURES",
+        "pscustomobject",
+        "microsoftonline",
+        "mdo_safeattachments",
+        "mdo_highconfidencespamaction",
+        "mdo_highconfidencephishaction",
+        "mdo_phisspamacation",
+        "mdo_spam_notifications_only_for_admins",
+        "mdo_antiphishingpolicies",
+        "mdo_phishthresholdlevel",
+        "mdo_autoforwardingmode",
+        "mdo_blockmailforward",
+        "mdo_zapspam",
+        "mdo_zapphish",
+        "mdo_zapmalware",
+        "mdo_safedocuments",
+        "mdo_commonattachmentsfilter",
+        "mdo_safeattachmentpolicy",
+        "mdo_safelinksforemail",
+        "mdo_safelinksforOfficeApps",
+        "exo_storageproviderrestricted",
+        "exo_individualsharing",
+        "exo_outlookaddins",
+        "exo_mailboxaudit",
+        "exo_mailtipsenabled",
+        "mip_search_auditlog"
     ],
     "import": []
 }