Skip to content

copilotinteraction-v1.1.0

Choose a tag to compare

View all tags
@Rance9 Rance9 released this 01 Dec 22:57
· 80 commits to release since this release
copilotinteraction-v1.1.0
57d3c82

Release Notes: v1.1.0

Release Information

⚠️ Important Usage & Compliance Disclaimer

Please note:

While this tool helps customers better understand their Microsoft 365 Copilot interaction data, Microsoft has no visibility into the data that customers input into this script/tool, nor does Microsoft have any control over how customers will use this script/tool in their environment.

Customers are solely responsible for securing, storing, and processing all exported data in compliance with their organization's policies and all applicable laws and regulations, including but not limited to data privacy, security, and regulatory requirements (e.g., GDPR, HIPAA, PCI DSS, and data residency obligations).

This script outputs highly sensitive Copilot interaction content, including user prompts and Copilot responses, which may contain confidential, regulated, or personally identifiable information (PII). By using this script, you acknowledge and agree:

  • You must implement appropriate safeguards, including encryption, access controls, and data classification, before running or sharing outputs generated by this script.
  • Do not run this script on shared or unmanaged devices. Ensure that only authorized personnel have access to the exported data.
  • Apply data loss prevention (DLP) policies and sensitive information detection where possible.

Microsoft provides this script "as-is" without warranties of any kind and disclaims all liability for any loss, breach, or misuse of data arising from or related to your use of this script. Microsoft does not provide support for custom modifications or downstream uses of this script. All operational risk and compliance obligations rest with you.

✅ Additional Guidance

Consult Your Compliance Team
Before using this script, consult your organization's legal and compliance teams to confirm that your planned usage aligns with internal policies and external regulatory requirements.

Retention & eDiscovery Obligations
Data exported by this script may fall under retention, legal hold, or eDiscovery obligations. Ensure that your organization's compliance policies are applied to any exported files.

🔐 Security Best Practices Checklist
  • ☑ Rotate credentials regularly (client secrets or certificates) and never hard-code secrets in scripts.
  • ☑ Run only in secure environments (managed devices, trusted networks).
  • ☑ Apply encryption at rest and in transit for all exported files.
  • ☑ Restrict access to exported data to authorized personnel only.
  • ☑ Enable DLP and sensitivity labels to prevent accidental sharing.
  • ☑ Validate storage location (e.g., secure SharePoint or encrypted file share).
  • ☑ Review logs and outputs for sensitive content before distribution.
  • ☑ Apply retention and deletion policies to exported data in line with compliance requirements.
🧪 Experimental Script Notice

This is an experimental script. On occasion, you may notice small deviations from metrics in the official Microsoft 365 Copilot Dashboards. We will continue to iterate based on your feedback. Currently available in English only.

Installation

Download v1.1.0 (This Version)

Use the direct download link below to obtain this specific version:

Related Assets

Prerequisites

  • PowerShell: 5.1 or later (PowerShell 7+ recommended for parallel processing performance)
  • Microsoft Graph PowerShell SDK: Auto-installed by script if missing (Microsoft.Graph.Authentication module)
  • ImportExcel Module: Auto-installed by script if missing (required only when using -ExportWorkbook)
  • Microsoft Entra ID App Registration: Required with the following Application permissions (all three required for every script run):
    • AiEnterpriseInteraction.Read.All - Read Copilot interaction history for all users
    • User.Read.All - Read user directory and license information
    • Organization.Read.All - Read organization and related resources
    • All permissions require tenant admin consent

Overview

Version 1.1.0 keeps the default CopilotInteractions export lightweight while adding an opt-in path to capture every nested artifact. Existing jobs keep running on the updated 12-column schema (reduced from 13), and operators can now turn on -IncludeExtended whenever they need richer analytics.

Key Features

1. -IncludeExtended Opt-In Metadata

  • Adds locale, ETag, and flattened identity set fields (FromUser*, FromApp*, FromDevice*).
  • Appends boolean/count columns that flag contexts, attachments, links, mentions, and history windows.
  • Writes dedicated CSV files or Excel tabs for each nested artifact, including:
    • CopilotInteractions_Contexts_* / Contexts tab with one row per context object (type, source application, title, and snippet).
    • ..._Attachments_* / Attachments tab detailing file names, drive identifiers, sharing state, and source messages.
    • ..._Links_* / Links tab listing resolved URLs, display text, and classification metadata.
    • ..._Mentions_* / Mentions tab capturing mentioned users/apps with IDs and role context.
    • History metadata remains summarized in the main dataset (counts plus first/last timestamps); no separate history export is generated.

2. Streamlined Base Schema

  • Removes the legacy JSON Contexts column from the default export.
  • Moves detailed context, attachment, link, and mention fields exclusively into the extended metadata datasets produced by -IncludeExtended.
  • Trims the main dataset from 13 down to 12 columns so existing automations continue to ingest the lean schema without changes.
  • Automatically diverts append jobs to a fresh timestamped file if the header no longer matches.

3. Export Telemetry Enhancements

  • Console summaries now call out when extended datasets are generated.
  • Excel mode reports each tab that was created (Interactions, Users, Contexts, Attachments, Links, Mentions).
  • Child dataset generation logs include row counts, making validation easier for long runs.

4. Documentation & Help Updates

  • In-script help and markdown documentation cover the new columns and sample filenames.
  • Advanced usage examples demonstrate combining -IncludeExtended with -IncludeBody.
  • Release notes, download links, and diagrams all align with the new metadata flow.

Key Improvements

Area What Changed in v1.1.0 Why It Matters
Extended Metadata -IncludeExtended flattens nested identities and emits dedicated context/attachment/link/mention datasets. Analysts can follow every artifact without parsing JSON blobs.
Default Schema Base CSV/Excel now ships with 12 columns (down from 13) and the contexts JSON column removed. Existing automations stay lightweight while extended data remains opt-in.
Append Handling Schema mismatch automatically rolls to a fresh timestamped file and logs the reason. Protects historical exports from header drift.
Export Telemetry Completion messages and Excel logs list every dataset or tab produced. Operators can confirm outputs without opening each file.
Documentation Script help and markdown docs include the new columns, filenames, and samples. Keeps admins aligned with how to consume the richer metadata.

Why This Release Matters

Question What v1.1.0 Delivers
Do existing automations break? No change unless you opt into -IncludeExtended; the default schema is unchanged except for removing the JSON Contexts column.
How do I inspect contexts and attachments quickly? Enable -IncludeExtended to receive normalized CSVs or Excel tabs for contexts, attachments, links, mentions, and history summaries.
What happens when appending to an older CSV? The script checks the header; if it differs, it creates a new export and explains the reason in the console.
Can I combine extended metadata with prompts? Yes—-IncludeExtended works alongside -IncludeBody, keeping prompt text opt-in to minimize PII exposure.
  • Security Teams: Trace every context and attachment that shaped a Copilot response.
  • Compliance Officers: Build richer audit packages without bloating the baseline export.
  • Operations Teams: Rely on improved telemetry to confirm exactly which datasets were created.

What's Included in v1.1.0

Core Script

PAX_CopilotInteractions_Content_Audit_Log_Processor_v1.1.0.ps1

Key Parameters

# User Selection
-UserPrincipalNames <String[]>    # Specific user(s) to query
-UserListFile <String>            # File with list of users (one per line)

# Date Range Controls
-StartDate <DateTime>             # Query start date (local time accepted)
-EndDate <DateTime>               # Query end date (local time accepted)
-DaysBack <Int>                   # Days back from EndDate (default: 180)

# App Filtering
-CopilotApps <String[]>           # Filter by Copilot host app (Word, Excel, etc.)

# Content Options
-IncludeBody                      # Include user prompts in Body field
-IncludeExtended                  # Flatten extended metadata and emit child datasets/tabs
-MaxBodyLength <Int>              # Max characters for Body field (default: 10000)
-IncludeUserInfo                  # Enrich with Entra ID user profiles and MAC licensing
-OnlyUserInfo                     # Export only Entra ID users and MAC licensing
-IncludeStats                     # Generate usage statistics by user, app, and date

# Export Formats
-OutputPath <String>              # Custom export directory (default: C:\Temp)
-ExportWorkbook                   # Export to Excel instead of CSV

# Incremental Processing
-UseWatermark                     # Enable watermark-based incremental exports
-WatermarkFile <String>           # Custom watermark file path
-AppendFile <String>              # Append to existing file (schema-aware)

# Authentication (Service Principal)
-TenantId <String>                # Microsoft Entra ID Tenant ID
-ClientId <String>                # App Registration Client ID
-ClientSecret <String>            # App Registration Client Secret

# Performance
-ParallelBatchThrottle <Int>      # Concurrent user queries (default: 25)
-ParallelMode <String>            # Auto/On/Off (default: Auto)

# Metrics & Diagnostics
-EmitMetricsJson                  # Generate performance metrics JSON
-MetricsPath <String>             # Custom metrics output path

Core Features

✅ Opt-in extended metadata via `-IncludeExtended` with normalized child datasets
✅ 12-column default schema for lean automations and CSV compatibility
✅ Schema-aware append logic that rolls to a new file when headers differ
✅ CSV or Excel exports with optional Entra ID user enrichment and stats
✅ Incremental watermark processing and parallel execution still available
✅ Detailed telemetry that lists every dataset/tab created per run

Support

For questions or issues, refer to the documentation:

Managed and released by the Microsoft Copilot Growth ROI Advisory Team. Please reach out to copilot-roi-advisory-team-gh@microsoft.com with any feedback.

Assets 3
Loading