Skip to content

copilotinteractions-v1.2.0

Choose a tag to compare

View all tags
@Rance9 Rance9 released this 09 Dec 18:05
· 88 commits to release since this release
copilotinteractions-v1.2.0
49c1338

Release Notes: v1.2.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.2.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.2.0 introduces a single, compliance-focused enhancement: the new -CountryCodes parameter. This addition lets administrators scope Copilot interaction exports to users whose Entra usageLocation aligns with approved ISO 3166-1 alpha-2 country codes. The feature executes before any network request so that only in-region accounts are queried, helping organizations respect data residency policies without building post-processing filters.

Key Features

1. Country-Scoped Data Collection (-CountryCodes)

  • Accepts one or more ISO 3166-1 alpha-2 codes (for example, US, DE, JP) to limit which users are queried.
  • Runs the filter before any Copilot interaction requests, ensuring out-of-scope users never leave the Entra directory cache stage.
  • Works across all script modes, including incremental runs (-UseWatermark) and metadata-only exports (-OnlyUserInfo).

2. Alias and Locale Normalization

  • Supports friendly country names ("United Kingdom", "Germany") by resolving them through .NET region metadata.
  • Recognizes reserved aliases such as UK, GBR, and common casing variants, automatically remapping them to their canonical two-letter codes.
  • Logs the normalization outcome for each supplied value so operators can verify the exact filter applied during the session.

3. Skipped User Transparency & Outputs

  • Detects users without an Entra usageLocation, records the omission reason, and excludes them from collection.
  • Emits a CountryFilter_Users_<timestamp>.txt roster listing each included user when at least one match is found; nothing is written if the filter yields zero results.
  • Integrates with existing verbose logging and summary output so analysts can trace how the new filter impacted tenant-wide coverage.

Key Improvements

Area What Changed in v1.2.0 Why It Matters
Compliance Filtering New -CountryCodes parameter gates Copilot data collection to users whose Entra usageLocation matches approved ISO codes. Provides a first-mile control for regional data residency and legal separation needs.
Input Normalization Friendly country names, aliases, and mixed casing are resolved to canonical ISO 3166-1 alpha-2 values before filtering. Minimizes operator error and lets teams reuse HR or legal-approved country lists without manual remixing.
Audit Trail Skipped users (missing usageLocation) and normalized code mappings are surfaced in the console log. Makes it clear which accounts were excluded, supporting compliance reviews and remediation.
Output Artifacts Matching users are optionally written to CountryFilter_Users_<timestamp>.txt when at least one account qualifies. Leaves a lightweight breadcrumb trail proving which users were processed during a run.
Documentation & Guidance Help text and markdown documentation explain how the new filter interacts with watermark, user-only, and append scenarios. Ensures operators understand that the filter works everywhere without modifying existing workflows.

Why This Release Matters

Question What v1.2.0 Delivers
Do I have to change existing automation scripts? No. The new filter is opt-in; if you omit -CountryCodes, the export behaves exactly like v1.1.0.
How do I enforce country boundaries up front? Provide one or more ISO codes (or friendly names) via -CountryCodes; users outside those regions are never queried.
What if some users are missing usageLocation? They are skipped automatically, and the console logs why so you can update their Entra profiles before rerunning.
Can I supply multiple regions or alias values? Yes. The script expands comma-separated lists, normalizes casing, and maps aliases like UK or United Kingdom to the correct ISO code.
  • Compliance & Privacy Teams: Gain confidence that only approved regions are included in each export job.
  • Regional Admins: Run targeted collections for EMEA, APAC, or country-specific programs without duplicating scripts.
  • Operations Teams: Review the new include/skip logs and optional roster file to verify the scope of each run.

What's Included in v1.2.0

Core Script

PAX_CopilotInteractions_Content_Audit_Log_Processor_v1.2.0.ps1

Key Parameters

# Compliance Filtering (New in v1.2.0)
-CountryCodes <String[]>         # Optional ISO 3166-1 alpha-2 list (e.g., US,DE,JP); resolves aliases and friendly names via region metadata

# Plays nicely with existing flows
-OnlyUserInfo                     # Filter still applies when exporting user metadata only
-UseWatermark                     # Incremental processing respects the same country scope
-AppendFile <String>              # Append logic unchanged; filtered rows append just like prior releases

Core Features

✅ Country-level scoping via the new `-CountryCodes` parameter
✅ Built-in ISO alias resolution and friendly name support for easy list reuse
✅ Transparent skip logging for users missing `usageLocation`, plus optional roster output
✅ Compatible with watermarking, append, and user-only modes with no workflow changes

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