microsoft/PAX purview-v1.8.0

purview-v1.8.0

Repository: microsoft/PAX

Tag: purview-v1.8.0

Published: 2025-11-10T22:36:26Z

Prerelease: no

Release notes:

Release Notes: v1.8.0

Release Information

• Version: 1.8.0
• Release Date: 2025-11-07
• Released By: Brian Middendorf (@microsoft)
• Previous Version: v1.7.4

---

Overview

Version 1.8.0 is a major feature release introducing dual-mode architecture with Microsoft Graph API as the new default, Entra ID user enrichment, enhanced Excel export capabilities, improved operational resilience, and simplified CSV output behavior (now defaults to separate files per activity type). This release represents a significant evolution in data enrichment and modernization while maintaining full backward compatibility.

What Changed

1. Dual-Mode Architecture (Graph API + EOM)

• Microsoft Graph API is now the default for audit log retrieval (replaces Exchange Online Management as default)
• New -UseEOM switch enables legacy EOM mode when needed
• Graph API provides foundation for advanced features (Entra enrichment, future enhancements)
• EOM mode preserved for -GroupNames filtering and legacy compatibility scenarios

1a. CSV Export Default Behavior Change (`-CombineOutput` Simplified)

• BREAKING CHANGE: CSV exports now default to separate files per activity type (was: combined file)
• Simplified `-CombineOutput` parameter: Now a simple switch (was: nullable bool with complex logic)
• New default: CSV produces one file per activity type (e.g., Purview_CopilotInteraction_Export_.csv, Purview_ConnectedAIAppInteraction_Export_.csv)
• To combine: Add -CombineOutput switch to merge all activity types into single Purview_Audit_CombinedUsageActivity_.csv
• Excel unchanged: Still defaults to multi-tab workbook (one tab per activity type); use -CombineOutput for single combined tab
• Rationale: Separate files enable parallel processing, easier activity-specific analysis, and align with Excel multi-tab default behavior

Migration Note: If your automation expects a single CSV file, add -CombineOutput to maintain v1.7.4 behavior:

# v1.7.4 default behavior (combined CSV)
./PAX_Purview_Audit_Log_Processor_v1.7.4.ps1 -StartDate 2025-10-01 -EndDate 2025-10-02
# Output: Single combined CSV

# v1.8.0 NEW default behavior (separate CSVs)
./PAX_Purview_Audit_Log_Processor_v1.8.0.ps1 -StartDate 2025-10-01 -EndDate 2025-10-02
# Output: Separate CSV per activity type

# v1.8.0 with -CombineOutput (matches v1.7.4 behavior)
./PAX_Purview_Audit_Log_Processor_v1.8.0.ps1 -StartDate 2025-10-01 -EndDate 2025-10-02 -CombineOutput
# Output: Single combined CSV (same as v1.7.4)

2. Entra ID User Enrichment (`-IncludeUserInfo`)

• New feature: Comprehensive user profile enrichment from Microsoft Entra ID
• Includes: DisplayName, GivenName, Surname, Department, JobTitle, Manager, M365 Copilot license detection, AccountEnabled, LastSignIn, and more
• Graph API exclusive feature (not available with -UseEOM)
• Output: Separate EntraUsers_MAClicensing_.csv (CSV mode) or embedded EntraUsers_MAClicensing tab (Excel mode)
• Automatic license SKU detection for M365 Copilot entitlements

2a. User-Only Export Mode (`-OnlyUserInfo`)

• New feature: Export ONLY Entra user directory and license data (skips all audit log queries)
• Ultra-fast execution (5-15 seconds vs. minutes/hours for audit queries)
• Ideal for license compliance snapshots, user directory exports, and periodic licensing audits
• Compatible with: -OutputPath, -Auth, -ExportWorkbook
• NOT compatible with `-AppendFile` (EntraUsers data represents point-in-time snapshots, not time-based activity data)
• Incompatible with: All audit-related parameters (dates, activity types, filtering, explosion, etc.)
• Output: Standalone EntraUsers_MAClicensing_.csv or Excel workbook with single tab

3. Excel Export Enhancements

• Combined mode file naming: Purview_Audit_CombinedUsageActivity_.xlsx (new naming convention)
• Entra-enriched naming: Purview_Audit_CombinedUsageActivity_EntraUsers_MAClicensing_.xlsx
• EntraUsers_MAClicensing tab automatically embedded in Excel workbooks when -IncludeUserInfo used

4. Redesigned `-AppendFile` Parameter (Global Output Feature)

> ⚡ BREAKING CHANGE: -AppendFile redesigned from boolean switch to string parameter accepting filename or full path

Overview: The -AppendFile parameter enables incremental dataset building across multiple script executions - a critical feature for enterprise customers managing continuous audit trails, multi-month datasets, and scheduled reporting workflows.

What Changed:

• v1.7.4 and earlier: -AppendFile was a switch parameter (boolean flag) with pattern-based file discovery
• v1.8.0 and later: -AppendFile accepts a string value (filename or full path) for explicit control

Why This Matters:

• Fortune 500 use case: Organizations building 90-day rolling audit datasets updated daily via scheduled tasks
• Predictable behavior: Explicit filename/path eliminates ambiguity in multi-file scenarios
• Better automation: Scheduled tasks can specify exact files without pattern-matching logic
• Path flexibility: Support both relative filenames (with -OutputPath) and absolute paths

Core Capabilities:

✅ Dual Format Support: Works with both CSV and Excel exports ✅ Live & Offline Modes: Supports live API queries and offline replay (-RAWInputCSV) ✅ Smart Header Validation: CSV exits on mismatch; Excel creates timestamped duplicate tabs ✅ File Lock Detection: Pre-flight checks identify files open in Excel or with permission issues ✅ Multi-Tab Intelligence: Excel mode handles multiple activity types independently

Usage Examples:

# Relative filename (uses -OutputPath directory)
-AppendFile "Report.csv" # → Appends to \Report.csv
-AppendFile "Monthly_Audit.xlsx" # → Appends to \Monthly_Audit.xlsx

# Absolute path (ignores -OutputPath)
-AppendFile "C:\Data\Archive\Q4_Audit.xlsx" # → Exact path specified
-AppendFile "\\FileShare\Reports\Audit.csv" # → Network path supported

Restrictions:

| Restriction | Reason | |-------------|--------| | ❌ Cannot use with -IncludeUserInfo | EntraUsers data is point-in-time snapshots, not time-based activity | | ❌ Cannot use with -OnlyUserInfo | Same reason (EntraUsers mode outputs user...