How It Works

This page explains, in plain English, what the solution is made of and how data gets from Microsoft 365 to your reports. Read it before you install, or whenever you want to understand why something works the way it does. Ready to set it up? Go to Getting started.

The big picture

flowchart LR
    subgraph M365["Microsoft 365: your tenant"]
        AUDIT["Purview audit log<br/>Copilot interactions"]
        GRAPH["Microsoft Graph<br/>people, licences, usage reports"]
        BILL["Power Platform and Azure billing<br/>optional agent costs"]
        SPO["SharePoint pages<br/>optional page tracking"]
    end

    subgraph AZ["Azure: your subscription, one resource group"]
        O365["Office 365 activity importer<br/>background job"]
        SQL[("Azure SQL database<br/>your analytics data")]
        WEB["Web portal<br/>Insights and Administration"]
        STATE[("Storage account<br/>import checkpoints")]
        KV["Key Vault<br/>runtime secret"]
        APPI["Application Insights<br/>logs and tracker data"]
        AII["App Insights importer<br/>background job"]
    end

    PEOPLE(["People in your organisation"])
    PBI["Power BI or your own SQL queries"]
    INST["Installer<br/>runs on a Windows PC"]

    AUDIT ==>|Office 365 Management Activity API| O365
    O365 ==> SQL
    SQL ==> WEB
    WEB ==>|sign in with Entra ID| PEOPLE
    GRAPH --> O365
    BILL --> O365
    O365 -.- STATE
    KV -.- O365
    SPO -->|tracker script| APPI
    APPI --> AII
    AII --> SQL
    SQL --> PBI
    INST -.->|deploys and updates| AZ

Loading

In one sentence: background jobs in your Azure subscription keep copying Microsoft 365 activity into a SQL database you own, and a web portal turns it into reports. The data stays in your subscription; the only thing sent elsewhere by default is anonymous usage statistics, which you can switch off (see below).

What's in the box

Part	What it does	Where it runs
Installer (AnalyticsInstaller.exe, sometimes called the control panel)	Creates and updates the Azure resources, deploys the code, upgrades the database and tests your configuration. Nothing of it keeps running afterwards.	A Windows PC
Office 365 activity importer	The workhorse. It reads the audit log (Copilot interactions), your directory (people and licences) and any other source you switched on, and writes them to SQL.	App Service, as the continuous WebJob Office365ActivityImporter
App Insights importer	Reads the page views that the SharePoint tracker sends to Application Insights. It only has work to do if you track SharePoint pages; otherwise it waits idle.	App Service, as the continuous WebJob AppInsightsImporter
Web portal	The website people sign in to, with an Insights area (reports, including Copilot Adoption) and an Administration area. It also receives Teams call notifications if you collect calls.	The same App Service
Azure SQL database	Where all the analytics data lives. It's yours: query it, report on it, keep it as long as you like.	Azure SQL Database
Storage account	Bookmarks and checkpoints, so every import carries on where the last one stopped. They live in an Azure Table called AnalyticsState.	Azure Storage
Key Vault	Holds the runtime app's secret.	Azure Key Vault
Application Insights	The solution's own logs and health signals, plus the data from SharePoint page tracking.	Azure Monitor

Some optional features add a resource: an Automation account for the Microsoft 365 usage-report profiling runbooks, Service Bus for Teams call notifications, Azure AI Language for sentiment, language and keyword detection, and an Azure OpenAI deployment for prompt categories. Architecture & costs lists them all, with sizing and prices.

The journey of one Copilot interaction

1. Someone uses Copilot, in Copilot Chat, Teams, Word, Outlook or an agent.
2. Microsoft records it. Microsoft Purview writes an audit record: who, when, in which app, with which agent, and which files and other resources Copilot used. The prompt and response text are not in it.
3. Microsoft publishes it a few days later. The record reaches the Office 365 Management Activity API roughly 2–3 days after the interaction, and the API offers it for 7 days.
4. The importer collects it. On every import cycle, the Office 365 activity importer asks the API for recent records (the last six days, by default), skips the ones it already has and saves the rest to SQL. If it has permission, it also looks up the names of the files and meetings involved.
5. Your directory gives it context. The user import keeps a copy of everyone's licences, department, manager and job title, and records licence changes as it sees them. That's what turns "someone used Copilot" into "a licensed sales manager used Copilot in Word on four days this month".
6. The portal makes sense of it. The Copilot Adoption page combines the two into engagement scores, habits, licence opportunities and trends for whichever period you choose.

Because the API only offers a week of records, anything older than about a week before you installed has to come from the optional Copilot audit backfill (Preview).

The import cycle

The Office 365 activity importer never stops. Each cycle it works through every import you switched on, then pauses for about 10 minutes before starting again (20 minutes with the gentlest tuning preset). Sources that change slowly are fetched less often: Microsoft's Copilot usage reports, for example, are fetched once a day, because Microsoft only updates them every couple of days.

A failure in one import is logged and tried again on the next cycle, without stopping the others. Each import remembers how far it got, so a restart carries on rather than starting over.

Where the data comes from

Data	Source	What it gives you	Needed for Copilot Adoption?
Copilot interactions	Purview audit log, through the Office 365 Management Activity API	Who used Copilot, when, where, and with which agents and files, licensed or not	Yes
People and licences	Microsoft Graph	The licensed population, and your organisation's structure for breakdowns	Yes
Microsoft's Copilot usage reports	Microsoft Graph reports	Microsoft's own per-person and tenant figures	Optional
Microsoft 365 usage reports	Microsoft Graph reports	Activity in Teams, Outlook, SharePoint and OneDrive, used to find people who would benefit from a licence	Optional
Prompt statistics	Microsoft Graph Copilot interaction history	Prompt sizes, attachments and response times	No
Agent costs	Power Platform licensing API and Azure Cost Management	Billed Copilot Studio credits and Azure spend	No
Copilot credit history (preview)	Microsoft Graph cost management (beta)	Month-to-date Copilot credit readings	No
Other Microsoft 365 workloads	Audit log, Microsoft Graph and Application Insights	SharePoint, Teams, calls, email and Power Platform activity	No

What data is collected lists every field, and Copilot analytics covers the Copilot data in depth.

What people see

• The web portal. Everyone signs in with their normal work account. The Insights area has an overview, in-app reports and pages grouped by workload: Copilot (including Copilot Adoption, Copilot investment and Copilot spend), Agents (agent costs), Apps & licences (licence activity), SharePoint & OneDrive and Teams, plus Activity analysis and DLP impact. The Administration area is for whoever runs the service: health, configuration, connections and settings. See The web portal.
• Power BI. Templates for the wider Activity & Usage Analytics reports connect to the same database.
• SQL. Everything is in ordinary tables, documented in Database schema.

Who can see what

Signing in to the portal uses the runtime app registration. On top of that, two Entra ID app roles decide what each person can do:

	Without a role	With Portal.Administration	With Portal.SeePII
Aggregate figures and charts	✔	✔	✔
The Administration area		✔
Named people: lists, per-person detail and their exports			✔

The two roles are independent: Administration doesn't include See PII. You can also limit who may sign in at all. See Portal permissions.

Where your data lives, and what leaves it

Everything the solution imports stays in your SQL database, in your Azure subscription. Its permissions only read Microsoft 365, and it never stores Copilot prompt or response text. Three things are worth knowing:

• Anonymous usage statistics. By default the importer sends the project team anonymous, aggregate statistics: the build, which imports are on, table sizes and row counts, and bounded adoption aggregates. No names, identities or content. Untick Allow anonymous usage reporting in the installer's Review & deploy section to stop it. See Telemetry service.
• Azure AI Language (optional, your own resource). If you configure it, text the solution analyses is sent to it to detect language, sentiment and keywords; with prompt statistics on, that includes prompt text, and the keywords it extracts are stored. See Security model.
• Azure OpenAI (optional, your own deployment). Prompt categories only send prompts to your model after an administrator explicitly opts in.

How it's installed and updated

You run the installer on a Windows PC. It creates whatever is missing in your resource group, deploys the website and both background jobs, and upgrades the database schema. Your settings are saved to an encrypted file. To update, download the new release's installer, load that file and deploy again. See Updating the solution.

Key terms

Term	Meaning
Runtime app	The Entra ID app registration the solution uses to read Microsoft 365, and that people sign in to the portal with.
Installer app	A separate Entra ID app registration that the installer uses to create Azure resources.
Import cycle	One pass of the Office 365 activity importer through every import you switched on.
WebJob	A background program hosted by Azure App Service. Both importers are continuous WebJobs.
Audit log	Microsoft Purview's record of user activity. The solution reads it through the Office 365 Management Activity API.
Copilot interaction	One audit record of someone using Copilot: a turn in a chat, a summary of a meeting, a draft in Word, and so on.
Licensed / unlicensed	Whether someone holds a Microsoft 365 Copilot licence. People without one can still use Copilot Chat, and those interactions are recorded too.
Agent	A Copilot agent, built by Microsoft, by your organisation in Copilot Studio, or by a third party.
Copilot Credits	The unit Microsoft charges Copilot Studio agent usage in. The solution can estimate credits from the audit log and import what was actually billed.
Usage reports	Microsoft's pre-aggregated activity reports, read from Microsoft Graph. Not the same as the audit log.
See PII	The portal permission to see data about identifiable people.
Backfill	Importing Copilot interactions older than the audit feed's one-week window.