Copilot Adoption Setup

This page is for administrators setting up Copilot Adoption. It covers the installer choices and runtime permissions the page needs, which imports answer which questions, who can see what, and how to check that data is arriving. Once data is flowing, use Settings to tune the rules and exclude people from reclaim, Leadership comparison to add the optional leadership card, and Troubleshooting when something looks wrong.

If you are deploying the solution mainly to use the Copilot Adoption page, you do not need to grant every permission in the full prerequisites list. That list covers all workloads and optional features. This page separates the small baseline for Copilot Adoption from permissions that add optional data.

These Microsoft 365 API permissions belong on the solution's runtime app registration and require administrator consent.

On this page: Minimum for the core data · Optional data · Which imports answer which questions · Who can view the results · Check that the data is arriving · Upgrading

Minimum for the core Copilot Adoption data

API	Application permission	Why it is needed
Office 365 Management APIs	ActivityFeed.Read	Reads the audit feed, including Copilot Audit.General events. These events provide the core interaction history used to analyse licensed and unlicensed Copilot use.
Microsoft Graph	User.Read.All	Imports user identities and metadata so audit events can be matched to people and the page can classify and segment users.

In the installer's Workloads section, tick Copilot interactions (the Copilot import, which subscribes the importer to the Audit.General feed) and User Entra ID extended metadata (the GraphUsersMetadata user import, which supplies identities and licences). You don't need Audit data (SharePoint) (ActivityLog): it only subscribes to SharePoint audit events and brings in no Copilot data. See Copilot analytics → Data source.

Without the audit-feed permission, Copilot interaction data is not collected. Without user-directory access, the tool cannot reliably match activity to the people and licence population it analyses.

What Test Configuration checks. With User Entra ID extended metadata ticked, the installer's Test Configuration reports an error for each of User.Read.All, Directory.Read.All and Organization.Read.All that the runtime app doesn't hold, so grant all three if you want a clean test. The import itself reads people with User.Read.All, and group members (only when you limit imports to Entra groups) with Group.Read.All, so whether to grant the broader Directory.Read.All is your decision. Organization.Read.All is covered next.

The standard user import also reads the tenant's subscribed SKU list to classify licences and count the seats you have bought. Organization.Read.All allows that efficient tenant-wide lookup. It isn't strictly required at runtime, but without it:

• licence lookups fall back to one Graph call per user with User.Read.All, which is much slower, especially in large tenants;
• the page still counts assigned seats, but shows purchased and unassigned Copilot seats as Unknown rather than zero, with the warning "Purchased and unassigned Copilot seats are unknown …".

For a production deployment, grant Organization.Read.All.

For the full page, also tick Usage reports. In the installer's Workloads section, Usage reports (Teams, OneDrive, SharePoint, Yammer, Outlook) imports the Microsoft 365 usage reports (the GraphUsageReports import, which needs Reports.Read.All; see the next table). Licence opportunities uses them to find heavy Microsoft 365 users who don't have a licence, and the Cowork tab uses them to predict readiness. Without them, licence candidates are ranked only on unlicensed Copilot Chat use, and nobody can be identified as a Cowork candidate.

Add these only for the corresponding optional data

API	Application permission	Add it when...	If not granted
Microsoft Graph	Reports.Read.All	You tick Usage reports (GraphUsageReports, recommended above) or enable GraphCopilotUsageReports. These import the Microsoft 365 usage reports that Licence opportunities and Cowork readiness use, and Microsoft's official Copilot usage reports.	These report imports are unavailable; audit-derived Copilot interaction analysis still works. GraphCopilotUsageReports is off by default, and Microsoft's Copilot usage-report endpoints are available in the global cloud only.
Microsoft Graph	Sites.Read.All	You want SharePoint file metadata resolved for Copilot audit events.	File-level enrichment may be incomplete; the audit events themselves can still be imported.
Microsoft Graph	OnlineMeetings.Read.All	You want meeting details resolved for Copilot audit events. This also requires a Teams application access policy for the app.	Meeting details are skipped; core Copilot Adoption analysis still works.
Microsoft Graph	AiEnterpriseInteraction.Read.All	You separately enable CopilotInteractionHistory to import prompt-derived interaction statistics. This is not required by the Copilot Adoption page and is not granted by the installer.	The separate interaction-history import is unavailable.

Group.Read.All is not needed for the core Copilot Adoption page. It is needed by other features, such as resolving groups used to scope the optional interaction-history import. Other permissions in Prerequisites apply to other workloads or features and are not part of this Copilot Adoption baseline.

Which imports answer which questions

These are independent imports. Enabling one does not supply the others.

Feed or setting	Enables	Required access and operational checks
User metadata: Graph directory, organisational SKUs and licence assignments	Seat classification and denominators; department/manager attributes; licence history after completed refreshes	Runtime Graph application grant User.Read.All, plus Organization.Read.All for purchased and unassigned seats (they show as Unknown without it), and the documented group grants for import scoping. Test Configuration checks User.Read.All, Directory.Read.All and Organization.Read.All; see the minimum above. Confirm the user/licence refresh succeeded
Copilot interactions: Copilot import from the Office 365 Management Activity API	Audit-sourced engagement, unlicensed Chat use, app/agent usage, Cowork interactions, resource/embedded-DLP evidence and growth history	Admin-consented ActivityFeed.Read, tenant auditing and sufficient retained history. The live feed normally arrives about 2–3 days late
Power Platform activity: ImportPowerPlatform, including Copilot Studio authoring	Builder counts	ActivityFeed.Read plus auditing enabled in the relevant Power Platform environments. Creation/publishing/sharing is not the Copilot interaction feed
Microsoft Copilot usage reports: GraphCopilotUsageReports	Licensed-user fallback evidence and the official tenant prompt line	Admin-consented Graph application Reports.Read.All; global Microsoft cloud. Confirm report date, version and concealment status
Microsoft 365 usage reports: Teams, Outlook, SharePoint and OneDrive	Licence opportunity and Cowork workload/readiness forecasts	The installer's Usage reports workload, with Reports.Read.All, workload reports enabled and their dated snapshots available. These are report-derived workloads, not Copilot task counts
Optional Copilot AI interaction history plus separate Prompt categories opt-in	Prompt statistics and sampled goal-category facts	Explicit application AiEnterpriseInteraction.Read.All consent, the user's M365_COPILOT_BUSINESS_CHAT service plan, pilot/user rotation and cap; a compatible model and durable administrator opt-in for categories
Optional Copilot Studio credits	Capacity snapshot and separate billed-agent consumption evidence	Capacity: Power Platform Reader for the runtime enterprise application. Consumption: delegated billing permissions and a connected authorised administrator, with durable credential storage
Optional Agent 365 package catalog	Catalog of packages that exist and usage metrics Microsoft supplies	Tenant Agent 365 licence, application CopilotPackages.Read.All with consent, global cloud, explicit off-default import toggle
Optional DLP.All: ImportDlp	The separate tenant-wide DLP view for other workloads	Explicit ActivityFeed.ReadDlp consent. Not needed for Copilot-embedded DLP or its governance signals; never combine the feeds

Use Prerequisites, Configuration Reference, App Registrations Setup, Agent Costs Setup and Prompt Categories for setup. This page does not replace their consent or networking instructions.

Who can view the results

The API permissions above control what the runtime app can import; they do not grant people access to the portal.

• Any signed-in portal user can view aggregate Copilot Adoption results.
• To view identifiable per-user information or its exports, assign the user the Portal.SeePII app role on the runtime app registration.
• Portal.Administration is not required to use the Copilot Adoption page. It is needed for the admin pages: Copilot Adoption settings, the leadership group, Service health, the prompt-category opt-in, the billing connection and the Agent 365 catalog report. It does not grant See PII.
• Switching off the global report filter for your own view needs both roles. Neither role overrides the small-group suppression on any report; see Portal permissions.
• Keep portal-role enforcement on: don't switch it off to make a small cohort reportable. See Portal permission verification.

These are separate from the installer's Azure RBAC permissions and the runtime app's Azure data-plane roles, which are still required to deploy and operate the solution. See Prerequisites for the complete deployment requirements.

Check that the data is arriving

A passing Test Configuration doesn't prove that Copilot data is arriving. After the first import cycles, check each source you enabled. Administration → Service health (needs Administration) shows the import runs and their failures. To see what has actually been stored, run these read-only queries against the analytics database. They return only dates and counts; don't post the results publicly.

-- 1. Licences: each licence type, how many people hold it, and when purchases were last read
SELECT lt.name, lt.sku_id, COUNT(ul.user_id) AS assigned_users, lt.subscribed_sku_refreshed_utc
FROM dbo.license_types AS lt
LEFT JOIN dbo.user_license_type_lookups AS ul ON ul.license_type_id = lt.id
GROUP BY lt.name, lt.sku_id, lt.subscribed_sku_refreshed_utc
ORDER BY assigned_users DESC;

-- 2. Copilot audit interactions: the newest one, and how many in the last seven days
SELECT MAX(time_stamp) AS newest_interaction_utc FROM dbo.copilot_chats;
SELECT COUNT_BIG(*) AS interactions_last_7_days
FROM dbo.copilot_chats
WHERE time_stamp >= DATEADD(day, -7, SYSUTCDATETIME());

-- 3. Microsoft 365 usage reports (licence opportunities and Cowork readiness)
SELECT MAX([date]) AS newest_teams_report_date FROM dbo.teams_user_activity_log;

-- 4. Microsoft's Copilot usage report, only if GraphCopilotUsageReports is on
SELECT MAX([date]) AS newest_copilot_report_date FROM dbo.copilot_usage_user_activity_log;

Check	Healthy	If not
1. Licences	Your Copilot licence types are listed with the number of holders you expect, and subscribed_sku_refreshed_utc is recent	No rows: the user import hasn't completed yet. By default it runs about once a day. A NULL refresh time after the import has run: Organization.Read.All is probably missing, so purchased seats show as Unknown
2. Audit interactions	The newest interaction is two to four days old, and the seven-day count isn't zero	NULL: no Copilot audit data at all. Check that Copilot interactions is ticked, ActivityFeed.Read has admin consent and auditing is on for the tenant. Older than about a week: check that the Office 365 activity importer is running
3. Usage reports	A date a few days ago	NULL: Usage reports isn't ticked, or Reports.Read.All is missing
4. Copilot usage report	A date a few days ago	NULL: the import is off (it is optional), or the tenant isn't in Microsoft's global cloud

Then open Copilot Adoption. Its warnings say what it couldn't calculate and why; see Warnings you might see.

Data arriving isn't the same as complete history. A recent interaction proves that data arrives, not that every day did. A new installation has only what it has imported since it started, so a 90-day period on a two-week-old installation still covers two weeks of evidence. To bring in older interactions, see the Copilot audit backfill (Preview).

Upgrading

These pages describe the latest stable release. To upgrade, follow Updating the solution: the installer applies every pending database migration. An installation that hasn't yet applied the Stable 1852 schema and is upgraded by hand needs that release's migrations, in order, first: see Upgrade to Build 1852 → Exact migration and manual-script order.

Related guidance

• Copilot Adoption Settings — the 33 rules behind the scores, and reclaim exclusions.
• Copilot Adoption Leadership Comparison — the optional leadership card, its Graph permission and storage.
• Copilot Adoption Troubleshooting — symptoms, telemetry and diagnostic queries.
• Copilot analytics — Copilot event collection, Microsoft usage reports, and optional interaction history.
• Full permissions list — permissions for every supported workload.

---

Next: Copilot Adoption Settings: tune the rules and exclude people from reclaim.

Administrators' path: Setup → Settings → Leadership comparison → Troubleshooting