Viva Insights Sample Code
Shared analysis policy
Shared analysis policy
Read this before computing or publishing results. Query schemas and workflow contracts still own their specific keys, metrics and supported methods. Copyable prompts retain the rules needed without this checkout.
Copyable summary
Use product-specific licence evidence. For documented native licensed-only M365 Copilot metrics, null means unlicensed and zero activity means licensed but inactive. Prefer Copilot Enabled User or Total Copilot enabled days. Do not extend these semantics to unlicensed Copilot Chat or Consumption credits. Investigate conflicting licence evidence. Keep affected eligibility or activity unresolved, and withhold affected rates or estimates until resolved. Within a supplied complete query’s configured scope, absent activity rows contribute zero. Keep failed joins, unavailable sources, out-of-scope periods and known coverage failures unresolved with reasons. Use configured grouping, week start and metric windows; date gaps do not establish cadence. State grain, units and estimand. Count distinct people; do not sum stocks or overlapping windows. Use max(organisation requirement, workflow floor): 5 distinct people for general analysis and 10 for joined-query, dashboard, causal or process workflows. Protect complementary cells and embedded data; never publish individual rankings. Use only HR attributes present in the export. If none suit a requested breakdown, omit it, explain why, and continue with supported overall results. Treat low-activity flags as review candidates, not verified holidays, employment status or job classifications. Value scenarios require explicit conversion and realisation assumptions. Default to association. Make causal claims only with a supported design and compatible estimators. Record unavailable checks and label synthetic data. Check installed API versions, signatures and return types. Separate executed results from expectations and do not silently fork upstream bugs.
Eligibility and activity are separate
For M365 Copilot, prefer Copilot Enabled User, Total Copilot enabled days or dated licence records for the relevant person-period. Positive enabled days establish that a person was enabled for at least part of the period. Zero enabled days establish no enabled days, rather than a licensed inactive week.
Microsoft’s Copilot calculation rules state that native null values indicate no M365 Copilot licence, while zero activity indicates a licensed person with no activity for that metric and period. Apply these documented semantics to the relevant native export fields, including null enabled days. If explicit licence fields are absent, a verified licensed-only metric with these semantics can establish licence status without an external licence list. Do not infer licensing from an arbitrary column containing “Copilot”.
These rules do not apply to unlicensed Copilot Chat metrics, Consumption credits, GitHub Copilot or other products without their own documented contract. Keep licence status unknown when the source or field semantics are genuinely unresolved. Investigate conflicting evidence, such as positive enabled days with unexpectedly null licensed-only activity, before publishing the affected rate. Adoption denominators include licensed people with zero activity and exclude unlicensed people. Withhold an overall rate only where licence status or activity among licensed people remains unresolved.
Missingness has reasons
For the current join contract, assume a supplied query is complete within its configured population, date window and product filters unless a known problem contradicts that assumption. An absent activity row there contributes zero, including an entirely absent in-scope person-week. This does not establish eligibility.
Distinguish native export nulls from nulls introduced by processing. A native licensed-only M365 Copilot null means unlicensed, so exclude that person-period from licensed adoption and usage-segment denominators. Do not turn it into a licensed Non-user, an inactive week or a churn event.
A failed join, unavailable source, out-of-scope person or period, partial boundary week or known coverage failure remains unresolved. A join-created null does not inherit the native export’s unlicensed meaning. Preserve match indicators and missingness reasons before classifying values. Do not blanket-fill a panel after a join. Legacy runners may require explicit completeness configuration before building a non-user panel; record that implementation gate rather than changing the meaning of nulls or reusing another export’s evidence.
Cadence, grain and estimand
Read configured grouping, week start and metric measurement windows first. Observed date gaps diagnose alignment and coverage, but cannot establish cadence: sparse daily activity can look weekly. If configuration is unknown, stop the affected aggregation or label it unresolved. Do not expand totals into invented daily observations.
State date window, grain, metric/unit, eligible population and estimand on each published chart or table. Distinguish a person-weighted summary from a person-period-weighted mean. Count distinct people in denominators. Do not sum stocks or overlapping windows. Verify key uniqueness and additivity separately before joining or summing.
Privacy and interpretation
Use max(organisation requirement, workflow floor) distinct people per
published group: generic analysis has a floor of 5; joined-query,
dashboard, causal and process workflows have a floor of 10. A workflow may require
more. Apply the same rule to tables, charts, embedded data and downloadable
aggregates. Suppress complementary cells or entire breakdowns if totals reveal
small cells. Pseudonymisation is not permission to publish individual rankings.
Keep person-level working data local and approved.
Low-collaboration, holiday-week and inactive-week helper flags are review candidates, not verified holidays, employment status or job classifications. Use approved calendar/HR evidence before asserting those facts. Document any exclusion and its effect on the population.
Claims and methods
Default to association for observational data. Choose a supported identifying design before estimators or causal claims. Select compatible diagnostics, not every estimator. Readiness-only, unavailable checks and null findings are valid outputs. Fixed effects, DML or a passing placebo do not by themselves establish causality. Label fabricated data and injected effects prominently.
Assisted hours, actions, credits and collaboration are not measured time saved, productivity or realised ROI. Value scenarios require explicit conversion, realisation, price and population assumptions.
Package and evidence boundary
Inspect installed package versions, signatures and return types before using a recipe. Hosted documentation may describe a different release. Do not silently fork an upstream bug. Record executed commands and observed results separately from expected agent behaviours or historical validation notes.
See workflow support for executable versus guided, synthetic-only, inspect-only and unsupported capabilities.