Getting Started

New here? This page takes you from nothing to your first Copilot report. You need to be comfortable administering Azure and Microsoft 365, but you don't need to know anything about this solution.

The short version: create two app registrations, give the runtime one three or four read permissions, run the installer, assign yourself two portal roles, then give Copilot data a few days to build up. Everything else is optional and can be added later.

What is Microsoft 365 Advanced Analytics?

A free, open-source solution that you deploy into your own Azure subscription. It continuously copies Microsoft 365 activity, above all Microsoft 365 Copilot usage, into an Azure SQL database that you own, and puts a web portal on top of it.

Most organisations use it to answer questions like these:

• Who has a Copilot licence but isn't really using it?
• Who doesn't have a licence yet, but already uses Copilot Chat or Microsoft 365 heavily enough to benefit from one?
• In which apps, and with which agents, do people use Copilot, and is it becoming a habit?
• What do our Copilot Studio agents cost?

It can answer them because it keeps the detail that the Microsoft 365 admin centre summarises or throws away: every Copilot interaction (who, when, in which app, with which agent and which files, but never the prompt or response text), joined to your directory (licences, department, manager), for as long as you choose to keep it.

To see how the pieces fit together, read How it works. It takes five minutes and has a diagram.

What you'll end up with

• One Azure resource group containing an App Service (the web portal plus two background import jobs), an Azure SQL database, a storage account, a key vault and Application Insights. Some optional features add a resource or two. Three options are on by default in a new installer configuration and add resources unless you switch them off in step 5: Azure Monitor health alerts, a Service Bus namespace and an Azure AI Language resource.
• A web portal that colleagues sign in to with their normal work account. Its Copilot Adoption page is where most people spend their time.
• A SQL database you can query yourself or connect Power BI to.

A small proof of concept costs roughly €55–60 a month in Azure, and a production deployment starts at about €160–170 a month. Architecture & costs explains the assumptions.

_{The Copilot Adoption page, shown with fictional data.}

Step 1: Decide what to collect

The solution can import far more than Copilot data, and every import you switch on needs its own permissions and setup. Start with Copilot. You can switch more on later by running the installer again.

You want	Tick these in the installer's Workloads section
Copilot adoption (the recommended start)	Copilot interactions and User Entra ID extended metadata
…plus Microsoft's own Copilot figures, and a way to find heavy Microsoft 365 users who don't have a Copilot licence yet	Also Copilot usage reports (Microsoft Graph) and Usage reports (Teams, OneDrive, SharePoint, Yammer, Outlook)
More than that	See Optional extras below

Step 2: Check you have what you need

This is the complete list for the Copilot setup in step 1. The full Prerequisites page covers every optional feature too; you don't need it yet. From Stable 1857, the installer can also list exactly what the options you choose need: see Prerequisites in step 5.

People who need to help

Who	What they do
Someone allowed to create Entra ID app registrations	Creates the two app registrations (step 3)
A Privileged Role Administrator or Global Administrator	Grants admin consent for the runtime app's permissions (step 3)
An Owner of the Azure subscription	Creates a resource group and gives the installer app access to it (step 4)

Permissions for the runtime app

All of these are application permissions, and all need admin consent. The solution only reads with them.

API	Permission	Why
Office 365 Management APIs	ActivityFeed.Read	Reads Copilot interactions from the audit log
Microsoft Graph	User.Read.All	Reads people: name, department, manager, job title and licences
Microsoft Graph	Organization.Read.All	Reads which licences your organisation has bought, so unassigned Copilot licences can be counted
Microsoft Graph	Reports.Read.All	Only if you ticked either usage-report import

Test configuration and Directory.Read.All. In current builds, the installer's Test configuration also checks for Directory.Read.All when User Entra ID extended metadata is ticked, and reports an error if it isn't granted. That check is stricter than the import: people are read with User.Read.All, and group members (only if you limit imports to Entra groups) with Group.Read.All. Whether to grant the broader permission is your decision. Runtime permissions lists every permission and what it is for.

Microsoft 365 settings

• Auditing must be on in Microsoft Purview. It is on by default, and Copilot interactions are only recorded when it is. See Turn auditing on or off.
• If you ticked the usage-report imports, turn off concealed names. In the Microsoft 365 admin centre, go to Settings → Org settings → Services → Reports and clear Display concealed user, group, and site names in all reports. Otherwise the reports can't be matched to people, and the importer refuses them.

Azure

• A subscription where these resource providers are registered: Microsoft.Web, Microsoft.Sql, Microsoft.Storage, Microsoft.KeyVault, Microsoft.Insights and Microsoft.OperationalInsights. Ticking Usage reports also needs Microsoft.Automation. If you keep the installer's default Service Bus and Azure AI Language options (see step 5), the subscription also needs Microsoft.ServiceBus and Microsoft.CognitiveServices. See Register a resource provider. From Stable 1857 the installer checks this for you, and stops before changing anything if a provider that your chosen options need isn't registered.
• Azure Policy that allows those resources to be created in your chosen region.

A Windows machine to run the installer

• Windows 10 or 11 (a virtual machine is fine) with the .NET Framework 4.8 runtime.
• Outbound HTTPS (port 443) to Microsoft Entra ID (login.microsoftonline.com), Azure Resource Manager (management.azure.com), your key vault (https://<vault-name>.vault.azure.net) and your App Service's deployment endpoint (https://<app-name>.scm.azurewebsites.net), and TCP port 1433 to Azure SQL. Test Configuration also calls Microsoft Graph and the Office 365 Management API with the runtime app. To download the release automatically (Latest stable, step 5), the machine also needs api.github.com, github.com and GitHub's release-download host. See Network & firewall rules.

Step 3: Create the two app registrations

The solution uses two separate identities in Microsoft Entra ID, both in the same tenant as Microsoft 365:

App registration	What it is for
Runtime	Reads Microsoft 365 data while the solution runs, and is the app people sign in to the portal with. It holds the permissions from step 2 and the portal roles from step 6.
Installer	Creates and updates the Azure resources. It needs Azure access only, and no Microsoft 365 permissions.

1. Register both as single-tenant apps and create a client secret for each. Keep each app's client ID and secret value, and your tenant ID, somewhere safe.
2. On the runtime app, add the permissions from step 2 under API permissions, then select Grant admin consent. Every row should show Granted.

Click-by-click instructions: App registrations setup.

Step 4: Prepare Azure

1. Create a resource group for the solution. (The installer can create one itself, but only if its app has rights on the subscription.)
2. Give the installer app the Owner role on that resource group, and the Reader role on the subscription.

That's all. The installer creates everything else, and gives the runtime app the Azure access it needs.

Step 5: Run the installer

1. From the latest release, download ControlPanelApp.zip, extract it to a folder of its own and run AnalyticsInstaller.exe. If Windows SmartScreen blocks it, follow your organisation's policy; see Run the installer.
2. Work down the navigation tree on the left:
   • Workloads: tick the imports you chose in step 1.
   • Accounts & permissions: enter both apps' client IDs and secrets, and your tenant.
   • Azure environment: subscription, region, resource group and a starting performance tier.
   • Hosting & services and Database & storage: resource names. Several must be unique across Azure, so choose a distinctive prefix. Each page has one option that is on by default:
     • Enable Azure Monitor health alerts (Hosting & services) creates an email action group and up to seven alert rules, which Azure bills for. Enter a notification email, or untick it; the installer won't deploy with alerts on and no email. See Installer health monitoring.
     • Service Bus Enable (required for Teams calls) (Database & storage) creates a Service Bus namespace, which needs the Microsoft.ServiceBus provider. Only the Teams calls import uses it, so untick it unless you import calls.
   • Azure AI: Enable cognitive analytics is also ticked by default. It creates an Azure AI Language resource, which needs the Microsoft.CognitiveServices provider and is billed by use. The importers use it for sentiment, language and keyword detection on Teams messages, page comments, sent emails and Copilot prompts, when you import those. Untick it unless you want that. The first time a subscription creates one, it can also fail until someone accepts Microsoft's Responsible AI terms; see Known issues.
   • Networking: leave it off for now. It is for private endpoints.
   • Prerequisites (Stable 1857 and later): a report of everything the options you've chosen need. Export it if someone else has to grant something.
   • SharePoint: leave it alone; it only applies to SharePoint page tracking.
   • Release & packages: leave it on Latest stable.
3. In Review & deploy, select Test Configuration. It changes nothing; it checks your accounts, permissions and settings and, from Stable 1857, that the Azure resource providers are registered. Fix anything it reports.
4. Select Review deployment…, check what will be created, then select Deploy now.
5. When asked, save the configuration to a password-protected file. You will load it again for every upgrade.

Anonymous usage reporting is on by default. Review & deploy has an option, Allow anonymous usage reporting to help improve the product, which starts ticked. It sends the project team anonymous, aggregate statistics about your deployment: the build, which imports are switched on, table sizes and row counts, and bounded adoption aggregates. It never sends names, identities or content. Untick it if you would rather not take part; see Telemetry service for the full list.

More detail: Install with the installer and the installer workspace.

Step 6: Let people sign in

1. Register the portal's address. On the runtime app registration, add a Web redirect URI with your App Service address, over HTTPS and with a trailing slash, for example https://contoso-analytics.azurewebsites.net/, and tick ID tokens. See Runtime app reply URLs.

2. Create the two portal roles on the runtime app registration, then assign them to the right people:

   Role (value)	Lets people…
   Portal.Administration	Use the Administration area: service health, settings and connections
   Portal.SeePII	See individual people: named lists, per-person detail and their exports

   Everyone who can sign in sees the aggregate figures without either role. Nobody holds a role until you assign it, not even you. See Portal permissions.

3. Optional: to limit who can sign in at all, turn on Assignment required for the runtime app's enterprise application and assign the people or groups who should have access.

Step 7: Check it's working

1. Browse to your App Service address and sign in.
2. Open Administration → Service health. Import liveness should show the Office 365 activity importer completing its cycles. The other import job, the App Insights importer, only has work to do when SharePoint page tracking is on; otherwise it waits idle, and that's expected.
3. If anything looks wrong, work through the Verify checklist, then Troubleshooting.

Step 8: Your first Copilot report

Once data has arrived (see below), open Insights → Copilot → Copilot Adoption. Your first fifteen minutes in the user guide walks you through it.

What to expect in the first days

When	What happens
First hour	Sign-in works and Service health shows the import jobs running. People and licences start to arrive; on a large tenant the first full user import takes a while.
First day	Copilot interactions start to appear. Microsoft's audit feed only offers about the last seven days, so your Copilot history starts roughly a week before you installed.
Every day after that	New interactions arrive 2–3 days after they happen. That delay is Microsoft's, not the solution's, so "yesterday" is never complete. Microsoft's usage reports, if you switched them on, are a few days behind too.
Over the following weeks	Longer reporting periods fill up. Until then, a period such as the last 90 days only covers the time since you installed, so keep that in mind when you compare periods.

Need history from before you installed? The optional Copilot audit backfill (Preview) can import older interactions from the unified audit log.

Optional extras

Switch these on when you're ready. Each one has its own setup page.

Extra	What it adds	What it needs
Microsoft's Copilot usage reports	Microsoft's own per-person and tenant Copilot figures	Reports.Read.All
File and meeting details	The names of the files and meetings Copilot worked with	Sites.Read.All, and OnlineMeetings.Read.All with a Teams application access policy
Prompt statistics	Prompt length, attachments and response times, never the text	AiEnterpriseInteraction.Read.All, scoped to a group of people
Older Copilot history (Preview)	Interactions from before you installed	AuditLogsQuery.Read.All
DLP impact	Which agents and people data loss prevention policies blocked	Nothing extra
Prompt categories	What people use Copilot for, by category	An Azure OpenAI deployment and an explicit opt-in
Agent costs	Billed Copilot Studio credits per agent, and Azure spend	Power Platform and Azure Cost Management access
Copilot spend and Copilot investment	Who consumes Copilot credits, and a modelled return from your own cost figures	Credit data from the agent-cost imports or credit history; an administrator saving the investment assumptions
Copilot credit history (preview)	Microsoft's month-to-date Copilot credit readings	A delegated Microsoft Graph connection
Agent 365 package catalog	Your organisation's agent inventory	CopilotPackages.Read.All and a Microsoft Agent 365 licence
Other Microsoft 365 workloads	SharePoint page tracking, Teams, calls, sent email, Power Platform and the Power BI reports	Varies; see Prerequisites

Common first-time problems

Symptom	Usual cause
AADSTS50011 when you sign in	The reply URL is missing or has no trailing slash; see Runtime app reply URLs
No Administration area in the portal	You haven't been assigned Portal.Administration, or you need to sign out and back in
Named lists and exports are hidden	You don't hold Portal.SeePII
No Copilot data after a few days	The Copilot interactions import is off, ActivityFeed.Read isn't consented, or Purview auditing is off
Usage reports are refused	Concealed names are switched on in the Microsoft 365 admin centre
The installer is blocked by SmartScreen	See Run the installer
The deployment stops because a resource provider isn't registered	A subscription administrator has to register it; the installer lists the command. See Tenant & subscription configuration

More answers: Known issues and Troubleshooting.

Where next

• How it works: the moving parts in plain English.
• Copilot Adoption user guide: running a licence review.
• Copilot analytics: everything about the Copilot data.
• Updating the solution: staying current.