AsBuiltReport.Microsoft.ExchangeOnline

0.1.0

Src/Private/Get-AbrExoAddressLists.ps1

function Get-AbrExoAddressLists {
    <#
    .SYNOPSIS
    Documents Exchange Online email address policies and address book configuration.
    Note: Get-GlobalAddressList, Get-AddressList, Get-OfflineAddressBook are classic
    Exchange cmdlets not available in EXO v3 REST mode. Email Address Policies are
    documented using Get-EmailAddressPolicy which IS available in REST mode.
    .NOTES
        Version: 0.1.0
        Author: Pai Wei Sing
    #>
    [CmdletBinding()]
    param (
        [Parameter(Position = 0, Mandatory)]
        [string]$TenantId
    )

    begin {
        Write-PScriboMessage -Message "Collecting Exchange Online Address List configuration for $TenantId."
        Show-AbrDebugExecutionTime -Start -TitleMessage 'AddressLists'
    }

    process {
        Section -Style Heading2 'Email Address Policies' {
            Paragraph "The following section documents email address policies and address book configuration for tenant $TenantId."
            BlankLine

            #region Email Address Policies
            try {
                Write-Host " - Retrieving Email Address Policies..."
                $EAPolicies = Get-EmailAddressPolicy -ErrorAction Stop | Sort-Object Priority

                if ($EAPolicies -and @($EAPolicies).Count -gt 0) {
                    Section -Style Heading3 'Email Address Policies' {
                        Paragraph "Email address policies define how email addresses are automatically assigned to recipients. $(@($EAPolicies).Count) policy/policies are configured in tenant $TenantId."
                        BlankLine

                        $EapObj = [System.Collections.ArrayList]::new()
                        foreach ($Policy in $EAPolicies) {
                            $eapInObj = [ordered] @{
                                'Policy Name'           = $Policy.Name
                                'Priority'              = $Policy.Priority
                                'Enabled'               = $Policy.Enabled
                                'Recipient Filter'      = if ($Policy.RecipientFilter) {
                                                              ($Policy.RecipientFilter -replace '\s+', ' ').Trim()
                                                          } else { 'All Recipients' }
                                'Email Address Format'  = ($Policy.EnabledEmailAddressTemplates -join ', ')
                                'Last Updated'          = if ($Policy.WhenChanged) { $Policy.WhenChanged.ToString('yyyy-MM-dd') } else { '--' }
                            }
                            $EapObj.Add([pscustomobject](ConvertTo-HashToYN $eapInObj)) | Out-Null
                        }

                        $null = (& {
                            if ($HealthCheck.ExchangeOnline.Mailboxes) {
                                $null = ($EapObj | Where-Object { $_.Enabled -eq 'No' } | Set-Style -Style Warning | Out-Null)
                            }
                        })

                        $EapTableParams = @{ Name = "Email Address Policies - $TenantId"; List = $false; ColumnWidths = 20, 8, 8, 30, 24, 10 }
                        if ($Report.ShowTableCaptions) { $EapTableParams['Caption'] = "- $($EapTableParams.Name)" }
                        if ($EapObj.Count -gt 0) { $EapObj | Table @EapTableParams }
                        $script:ExcelSheets['Email Address Policies'] = $EapObj
                    }
                } else {
                    Paragraph "No custom email address policies configured. The default policy applies to all recipients."
                }
            } catch {
                Write-ExoError 'AddressLists' "Unable to retrieve email address policies: $($_.Exception.Message)"
                Paragraph "Unable to retrieve email address policies: $($_.Exception.Message)"
            }
            #endregion

            #region Address Book Note
            Section -Style Heading3 'Global Address List & Offline Address Book' {
                Paragraph "Exchange Online includes a default Global Address List (GAL) and Offline Address Book (OAB) that are automatically maintained. Custom address lists can be managed via the Exchange Admin Center or classic PowerShell (requires Basic Auth or Remote PowerShell, not EXO v3 REST)."
                BlankLine
                Paragraph "To view address lists using classic Exchange PowerShell, connect using: Connect-ExchangeOnline -UseRPSSession `$true (deprecated in EXO v3) or use the Exchange Admin Center at admin.exchange.microsoft.com."
            }
            #endregion
        }
    }

    end {
        Show-AbrDebugExecutionTime -End -TitleMessage 'AddressLists'
    }
}