Skip to content

User Licence Diagnostics

Sam Betts edited this page Oct 22, 2026 · 2 revisions

Available in Stable build 1854. PR #766 shipped through release #767. Directory comparison is read-only; Refresh this person is a separately authorised queued write. Screenshots, where supplied, use synthetic Contoso data and do not prove a deployed refresh succeeded.

When the portal shows someone as unlicensed who holds a licence in the Microsoft 365 admin center (or the other way round), the cause is rarely the one it looks like. A stale import, a person outside the user scope, a SKU the Copilot rules don't recognise, a report period that reads licence history rather than today's licences, and a report served from cache all look the same on a report page. A single "last updated" date can't tell them apart.

The licence and data diagnostics on Administration > User data lookup take one person and show the evidence for each of those causes side by side. They can also re-read that one person from the directory and correct the database for them alone.

Released stored-licence freshness card with fictional Contoso scope, stored licences and directory-comparison controls

Local fixture only: this does not demonstrate a real Graph comparison, queued refresh or persisted database correction.

Who can use it

Everything here is about one named person, so it needs both portal permissions: Administration and See PII. See Portal permissions. That includes the refresh action and the record of who asked for it.

How to open it

  • Administration > User data lookup: enter the person's sign-in name (UPN).
  • Troubleshoot this person on a person's row in Copilot Adoption's licensed-user and opportunity lists. This opens the lookup with that report's period and seat selection already applied. The person's identity travels in the browser's page state, never in the URL, so it does not end up in browser history or server logs.

The diagnostics answer for someone the import has never stored too, because that is often the question.

What each section tells you

Section The question it answers
What the evidence suggests A short list of findings in plain language: "no licence assignments are stored", "the user import is overdue", "the licensing catalogue and the Copilot rules disagree about this SKU", "this person is outside the user scope". Findings describe the evidence; none of them is a verdict on Entra ID.
How fresh are the stored licences? When the profile was last written, when the user import last completed, when licences were last refreshed for the tenant, and when this person was last confirmed. See Reading the timestamps.
Stored licences Every licence the database holds for the person, whether it counts as a Microsoft 365 Copilot seat, the rule that decided it, and whether this build's licensing catalogue lists it.
Licence history When a licence refresh observed each holding start or end. The real change happened between the previous refresh and the observing one, so these dates bracket a change rather than date it exactly.
Compare with Microsoft Graph What the directory assigns now, beside what the database holds. Read-only. See Comparing with the directory.
Refresh this person from the directory Corrects the database for this one person. See One-person refresh.
Why does a report count this person this way? Re-runs Copilot Adoption's or Licence Activity's own licence rule for this one person, with the report's period and seat selection. See Report verdicts.
Copilot seat rules and catalogue Which SKUs count as Copilot seats in this build, the rules version, the licensing-catalogue identifier, and every licence in the tenant where the catalogue and the rules disagree.
Data held and import freshness For each kind of data (audit events, Teams activity, Copilot interactions and so on): the newest record stored for this person, when the import that feeds it last completed, and whether that source can be re-read for one person at all. "None stored" is not the same as "no activity": the source may be switched off, out of scope, or not imported yet.

Reading the timestamps

Shown as Means Does not mean
Profile last written by the import When the user import last changed this person's row That their licences were checked then. An unchanged person isn't rewritten, so an old date is normal.
User import last completed (whole tenant) When the scheduled user import last finished That this person was in it
Last licence refresh recorded (whole tenant) The last tenant-wide licence refresh in licence history That this person's licences were confirmed
Last confirmed for this person When a one-person refresh read a complete answer from the directory and applied all of it Anything before the feature existed: until a refresh runs, it says Not recorded

All times are shown in UTC, so they can be compared with the importer's logs.

Comparing with the directory

Compare with Microsoft Graph reads the person's licences now, with the solution's runtime app registration (User.Read.All, which the user import already needs). Each row says one of:

  • Match: both agree.
  • Only in directory: the database is behind. Check the freshness section, then use a one-person refresh.
  • Only in database: the licence was removed in Entra ID after the last licence refresh. A refresh corrects it.
  • Cannot tell: the directory's answer was incomplete, or the comparison cannot be made at the database's level of detail.

Notes you may see:

  • Several SKUs share this licence name: the database files licences by product name, so two SKUs with the same name are one licence in the database and cannot be told apart.
  • Stored under an older product name: Microsoft renamed the product. The next scheduled import refiles it under the current name.
  • Copilot seat plans switched off for this person: the person holds a Copilot SKU, but an administrator disabled its Copilot service plans. The report still counts the seat. The person can't use Copilot.

The comparison is only offered for people confirmed to be in the user scope. Nobody outside the scope is read from the directory. While the scope can't be resolved, the comparison is unavailable rather than guessed.

Report verdicts

The verdict uses the report's own rule, so it answers the question the report asked. The rule depends on the period:

  • A rolling period (for example, the last 28 days) uses the licences stored now. Someone whose licence was removed yesterday counts as unlicensed for the whole period.
  • A past period uses licence history: anyone who held a counted licence at any point in it counts. History only knows what a refresh observed, and nothing from before history tracking began.
  • A what-if seat selection on Copilot Adoption changes which licences count. The verdict shows when one was applied.
  • Licence Activity always uses the licences stored now. Its period selects activity, not licences.

The verdict is recomputed from the data stored now. If the data changed since you looked at the report, it can differ from what you saw. Admins can also copy the exact query the verdict ran.

One-person refresh

Refresh this person from the directory asks the importer to re-read one person's profile and licences from Microsoft Graph and correct the database for them alone.

Released one-person refresh card with fictional Contoso data and illustrative request controls

Local synthetic fixture only: the displayed state is not evidence that a request was queued, Microsoft Graph was called or a database change persisted.

What it does

  • Adds licences the directory assigns that the database lacks.
  • Removes licences the database holds that the directory no longer assigns, but only when the directory's answer is complete.
  • Updates the standard profile fields: account enabled, email, postal code, department, job title, office, usage location, country or region, state, company and manager.
  • Records the change in licence history as seen by a one-person refresh, with no earlier bound: the change happened at an unknown time before the refresh saw it.
  • Makes Copilot Adoption and Licence Activity drop cached figures computed before the change, typically within a minute. There is nothing to rebuild.
  • Records the person as confirmed when the answer was complete and fully applied.

What it never does

  • It doesn't add people. Only the scheduled user import adds people.
  • It doesn't read or change anyone outside the user scope, or anyone while the scope can't be resolved.
  • It doesn't remove a licence on an incomplete answer, or remove a licence filed under an older product name for a SKU the person still holds. The scheduled import refiles that one.
  • It doesn't reset the tenant-wide user import (use Administration > User import for that). It doesn't change anyone else's licence history, or record a tenant-wide licence refresh.
  • It doesn't update organisation attributes. The scheduled import reads those for everyone.

When it runs

The request is queued in the solution's AnalyticsState Azure table (UserRefresh partition), and the importer web job picks it up at its next safe point: the start of its next import cycle, or straight after its Graph import. The page follows the request and shows the result when it finishes.

  • While the scheduled user import is running (on any instance), requests wait for it to finish. The two never write the same person at the same time. See How it fits with the scheduled import.
  • A request no importer picks up within 24 hours lapses.
  • A request interrupted three times fails, rather than retrying forever.
  • Asking again while a request is waiting returns the waiting request, rather than queueing a second one. At most 25 requests can wait at once.

Results

Result Meaning
Updated The database now matches the directory for this person
Already correct Nothing needed changing; the person is now recorded as confirmed
Partly applied Some changes were applied, some held back for lack of evidence; the notes say which and why
Not refreshed A decision rather than a failure: out of scope, scope unresolved, not in the database, a different account in the directory, or the import switched off
Failed Microsoft Graph refused or couldn't be read, or an unexpected error; nothing was changed
Lapsed No importer picked the request up within 24 hours. Check the importer on the Health page.

Requirements

  • Azure Storage configured for the solution (the Storage connection string). Without it, the page explains that the action isn't available.
  • The user metadata and licence import (GraphUsersMetadata) switched on.

Retention and audit

Requests, their results and who asked are kept for 30 days, then deleted by the importer (once a day). The page shows each person's ten most recent requests. Requests are personal data, so they are visible only with Administration and See PII.

How it fits with the scheduled import

The scheduled user import reads every licence holder from Graph, then writes the differences, often an hour later on a large tenant. A one-person refresh that landed in between would be overwritten by that older reading. To prevent this:

  • Every writer of users and licences takes the SQL Server application lock AnalyticsEngine/UsersAndLicences: the scheduled import from its first Graph read to its last write, and the one-person refresh while it works. They take turns, across any number of importer instances.
  • The scheduled import checks it still holds the lock before every batch it writes, and keeps the lock's connection alive while it reads Graph. If the lock is lost (for example, the connection drops), it stops writing and retries on the next cycle.
  • The scheduled import also marks itself as running in Azure Table storage. One-person refreshes wait while that mark is present, even if the lock was lost, so a batch already being written can never land after theirs. The mark expires five minutes after the import's last heartbeat.

Log lines

Search the importer's Application Insights traces (or its WebJob log) for:

Log line Meaning
User refresh - request <id> finished: <result> (...) A one-person refresh finished, with counts of what changed
User refresh - another writer of users and licences holds the lock; queued one-person refreshes wait for the next cycle. The scheduled import (or another instance) was writing; the request waits
User refresh - the scheduled user import is still running; queued one-person refreshes wait for the next cycle. The scheduled import's running mark was present; the request waits
User import - another writer of users and licences (...) held the users-and-licences lock for 5 minute(s). Skipping this cycle's user import The scheduled import waited five minutes for a refresh and gave up; it runs on the next cycle
User import - lost the users-and-licences writer lock before the <phase> The lock's connection dropped part-way; the import stopped writing and retries on the next cycle
User refresh - deleted <n> expired refresh record(s). The daily clean-up of records older than 30 days

Limits

  • Graph is eventually consistent: a licence assigned seconds ago may not show yet. Compare again shortly.
  • The database files licences by product name, so two SKUs sharing a name can't be compared separately.
  • A one-person refresh covers the profile and licences only. Activity data (mail sent, Copilot interactions, usage reports, audit events) can't be re-read for one person from this page. The Data held and import freshness section says which sources could in principle be.
  • History created before this feature cannot be made more precise: a refresh only says when it saw a change.

See also: Troubleshooting > A person shows as unlicensed (or licensed) when they shouldn't.

Start here

Copilot analytics

Using the portal

Install & configure

Beyond Copilot

Operate

Upgrading from an older build

Reference

Project

Clone this wiki locally