Copilot Adoption Settings

This page is for administrators. It explains the settings that decide how Copilot Adoption scores people, bands them and recommends actions, how to change them safely, and how to keep particular people out of the reclaim figures. Programme leads don't need to change anything here, but the figures they read follow these rules.

Changing the score weights and adoption levels

There are 33 governed settings (Stable 1854 or later; Stable 1852 has only the six weights and band thresholds). Open Administration → Copilot & reporting → Copilot Adoption settings (#/admin/copilot-adoption-settings). The editor requires Administration (Portal.Administration); report readers do not need that role. These are tenant-wide decision rules, not per-reader preferences or App Service settings.

Illustrative local fixture: the picture does not prove a saved Azure Table version or a persisted rule change.

Plan a rule change

1. Agree the licence/enablement question and record the current settings version. Export a baseline workbook before changing rules.
2. Change one coherent group at a time. Review the page's 28-day active-day preview, default values and validation messages. A changed denominator/threshold can move people without any change in their usage.
3. If changing seat-reclaim grace days, explicitly confirm its effect on seat recommendations before saving. Resetting that field needs the same confirmation. The grace period counts from when the person's Entra account was created, not from when their Copilot licence was assigned, so raising it doesn't protect an existing employee who has only just been given a licence: exclude them from reclaim instead. The solution never removes a licence automatically.
4. Save, reload and check the version/history. If another administrator saved first, reload rather than overwriting their work.
5. Refresh the report and export a new workbook. Compare only like-for-like rules; do not present a score increase caused by a rule change as improved adoption.

Engagement and habit controls

Setting	Default	Rule
Frequency / depth / breadth weights	50% / 30% / 20%	Whole percentages from 0 to 100 that must add up to exactly 100
Developing / Established / Champion thresholds	25 / 50 / 75	Whole scores with 1 ≤ Developing < Established < Champion ≤ 100. Trialling is everything below Developing
Frequency target ratio (frequencyTargetRatio)	0.6	Target share of working days; used with working days per week
Working days per week (workingDaysPerWeek)	5	Scales expected active days, not actual days observed
Depth target interactions per active day (depthTargetInteractionsPerActiveDay)	5	Intensity target; not a task-completion target
Depth minimum active days (depthMinActiveDays)	3	Evidence needed for full intensity credit
Breadth target apps (breadthTargetApps)	3	Distinct supported app surfaces for full breadth credit. Since Stable 1859 (PR #821): it also decides who is told to Add another app: people in no more than half these apps (details)
Moderate / Frequent / Daily minimum active days	6 / 11 / 20	Strictly ordered bucket boundaries; normalization remains fixed at 28 days

At the defaults, a 28-day frequency target is 28 × 5/7 × 0.6 = 12 active days before applicable observation/seat-held-day adjustments. Habit buckets are unweighted frequency, not the weighted engagement bands. Moving Established changes the headline habit rate; changing a raw frequency bucket does not redefine Established.

Licence, Cowork and agent decisions

Controls	Defaults	Interpretation and safeguard
Opportunity recommendation score; proven-demand minimum active days	50; 3	Recommendation threshold and observed unlicensed Copilot demand
Opportunity weights: unlicensed Copilot / collaboration / email / documents	35 / 25 / 20 / 20	A separate percentage group, totalling exactly 100
Cowork workload minimum score; fluency minimum score; regular-use minimum days	50; 50; 3	Independent readiness gates, not engagement-band thresholds
Cowork weights: collaboration / meetings / email / documents	20 / 35 / 25 / 20	Its own percentage group, totalling exactly 100
Agent review inactivity; retirement inactivity; new-agent days; minimum users	30; 90; 30; 3	Review precedes retirement; newness is 1–118 days and shorter than retirement. Minimum users cannot be below three
Seat-reclaim grace days (reclaimGraceDays)	30	Never-used seats on accounts created fewer than this many days ago are review-only, not Probable reclaims. It counts from the account's creation date, not the licence assignment (see Reclaim tiers). Saves/resets that change this require explicit seat-impact confirmation
Segment minimum (minSeatsPerSegment)	5	May increase, never below five seats; this is not a permission bypass

All three weight groups are independent. The editor validates finite numeric targets, whole-number fields, ordered boundaries and supported ranges server-side as well as in the form. A rejected request is not a saved configuration: correct every validation error, then save again against the current version.

These rows account for 33 fields: six original weights/bands, five engagement targets, three habit boundaries, six opportunity controls, seven Cowork controls, four agent controls, reclaim grace and segment minimum.

Not editable: history/query windows, row/performance caps, modelled-time coefficients, the 28-day habit normalization, and activation windows. Activation-window reporting isn't available: a reserved option you may see in a payload or workbook is not activation reporting. Account age and period-clipped seat-held days do not establish first-observed seat tenure or reassignment semantics.

How changes apply, and where they are stored

When a change applies. On the next report or export requested on any web server, without a restart. Effective settings participate in analysis-cache identity. A report already open keeps the settings it was calculated with until refreshed. Reset to defaults restores all 33 fields, not just the original six.

How readers can tell. While any value differs from its default, every tab of the report shows a banner with the values in use and the defaults; the How this is calculated tab always says which settings it documents; and the Excel export's Settings sheet notes each customised value with its default. The report never names who made the change.

History. The page lists the last 50 changes: when, who (the administrator's sign-in name), and each field's old/new values. Conditional saves reject stale versions with settingsChanged; an older client must not silently erase newer customised rules. History is administrative personal data: do not put it in public screenshots or issues.

Where they are stored. In AnalyticsState, partition CopilotAdoptionSettings, row Current (the Storage connection string). There is no database change. Without a Storage connection string the editor shows defaults read-only and refuses to save. Prefer Reset to defaults to deleting Current: deleting that row also loses the change history.

Storage failures and timed-out saves. A ten-second storage deadline covers opening the Table, reading settings and conditionally saving/resetting them. If configured storage is unreadable or times out, the report refuses with "The Copilot Adoption score settings couldn't be read, so this report isn't available right now." (HTTP 503, code copilotAdoptionSettingsUnavailable), even if a previous analysis is cached; it never quietly substitutes defaults. Fix Table connectivity/permissions and refresh. After a save times out, reload the current settings and history before trying again: the write may have completed without an acknowledgement reaching you. Do not retry an old version blindly. Cancelling your wait does not stop shared analysis another reader is using.

Anonymous usage statistics are not affected. If enabled, weekly anonymised adoption figures use default rules for comparability; they can differ from a customised tenant report. Neither opting in to telemetry nor saving a rule grants prompt-processing consent.

Excluding people from reclaim

Usage data can't show that someone is on long-term leave or works part-time, or that an account is a service account or a shared mailbox. An administrator can exclude such a person, so that their seat is never counted as reclaimable.

What an exclusion does. While it is active, the person's reclaim tier is Excluded from reclaim, and their recommended action reads "Excluded from reclaim - {reason}. Review after {date}.", or "… Permanent until an admin changes it." when there is no review date. The seat stays in the licensed population and in every adoption figure, but not in Reclaimable licences. An exclusion doesn't change the person's band, score or licence, and it only matters while they hold a Copilot seat. See Reclaim tiers.

There is no portal page for exclusions today. They are rows in the analytics database table dbo.copilot_adoption_reclaim_exclusions, maintained with SQL by someone with write access to that database:

Column	Meaning
user_id	The person's dbo.users.id. Their exclusions are deleted with them
reason	Required, up to 100 characters. Shown in the person's recommended action
note	Optional, up to 1,000 characters
excluded_by	Required. Who made the decision
excluded_utc	When, in UTC. Defaults to the time of the insert
review_after_utc	Optional. The exclusion stops applying after this UTC time. NULL means permanent

An exclusion is active while its review_after_utc is NULL or in the future. A person can have several rows: they stay excluded while any of them is active, and the newest active row supplies the reason.

Add an exclusion. A synthetic example; user_name is the person's sign-in name (UPN). Check that it inserted exactly one row:

INSERT INTO dbo.copilot_adoption_reclaim_exclusions (user_id, reason, note, excluded_by, review_after_utc)
SELECT id, N'Long-term leave', N'Returns in April', N'admin@contoso.com', '2027-04-30'
FROM dbo.users
WHERE user_name = 'megan.bowen@contoso.com';

List the exclusions:

SELECT u.user_name, e.reason, e.excluded_by, e.excluded_utc, e.review_after_utc,
       CASE WHEN e.review_after_utc IS NULL OR e.review_after_utc > SYSUTCDATETIME()
            THEN 'active' ELSE 'lapsed' END AS status
FROM dbo.copilot_adoption_reclaim_exclusions AS e
JOIN dbo.users AS u ON u.id = e.user_id
ORDER BY u.user_name, e.excluded_utc DESC;

End an exclusion by setting the review date of every active row for that person to now. Don't just end the newest row: an older permanent row would keep the person excluded. Updating rather than deleting keeps the record of the decision:

UPDATE e
SET review_after_utc = SYSUTCDATETIME()
FROM dbo.copilot_adoption_reclaim_exclusions AS e
JOIN dbo.users AS u ON u.id = e.user_id
WHERE u.user_name = 'megan.bowen@contoso.com'
  AND (e.review_after_utc IS NULL OR e.review_after_utc > SYSUTCDATETIME());

The person is then shown as exclusion expired (see below), which prompts a fresh look at their seat. To remove the record entirely instead, DELETE their rows; that also deletes the history of the decision.

Good to know:

• When a change shows. On the next analysis. A cached analysis can be up to 10 minutes old, so refresh the report after that.
• Lapsed exclusions are flagged, not honoured. Once every row for a person has passed its review date, their tier reads "… - exclusion expired" on the Licensed users tab, and the Excel report's Headline figures sheet counts Expired exclusions, so they can be reviewed again.
• Past date ranges use today's exclusions, like department and account status.
• Treat reason and note as personal data. Readers with See PII see the reason in the person's recommended action and its CSV export. Keep both factual (Long-term leave, Shared mailbox), and leave out health or other sensitive details.

---

Previous: Copilot Adoption Setup · Next: Copilot Adoption Leadership Comparison

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