Skip to main content

Essentials

Getting Started

Set up R or Python for Viva Insights analytics. Install the vivainsights package, export your first query, and avoid the most common data pitfalls.

Getting Started with Viva Insights Analytics

Welcome to Viva Insights sample code! This guide will help you set up your development environment and get started with analyzing Viva Insights data using R or Python. For custom KPIs, multi-query joins, and automated reporting patterns once you’re up and running, see Essentials and Advanced Analytics.

Last validated August 10, 2026 against vivainsights R 0.7.2 / Python 0.4.2.

Show code in:
Remembers your choice on this device.

Prerequisites

R

Python

  • Python 3.9 or higher. Download Python. Python 3.7 and 3.8 have reached end-of-life and are not supported.
  • pip, usually included with Python.
  • A virtual environment (recommended), so this project’s packages stay isolated from others.

Install the vivainsights package

install.packages("vivainsights")

Add other packages only as your analysis needs them. tidyverse is a common companion for data wrangling, and igraph / visNetwork are useful if you plan to render network graphs yourself instead of using the package’s built-in network_p2p() / network_g2g() plots.

python -m venv viva-insights-env

# Activate the virtual environment
# Windows:
viva-insights-env\Scripts\activate
# macOS/Linux:
source viva-insights-env/bin/activate

pip install vivainsights

vivainsights installs pandas as a dependency. Add other packages such as jupyter, matplotlib, or networkx only as your analysis needs them.

Verify your installation

library(vivainsights)
packageVersion("vivainsights")
help(package = "vivainsights")

import vivainsights as vi
print(vi.__version__)

Export your data from Viva Insights

Person query data is the most common starting point: one row per person per period, with HR attributes like organization, function, and level as columns. Other query types (Meeting Query, Person-to-Person, Group-to-Group, Person-to-Group) have different grains and are used for more specific analyses.

To export a query, use the query designer in the Viva Insights Analyst portal. Since the exact navigation can change between product releases, follow the current steps in Microsoft’s own Analyst portal documentation rather than a screenshot that may go stale.

Load and explore your data

library(vivainsights)

# Load person query data and standardize variable names
person_data <- import_query("path/to/your/person_query.csv")

# Quick exploration
check_query(person_data)
create_bar(person_data, metric = "Collaboration_hours")

Whilst you can use read.csv() for reading the .csv query into your R environment, we recommend using the import_query() function instead from the vivainsights package. import_query() standardizes variable names and ‘cleans’ special characters, ensuring that you minimize the number of errors arising from variable name mismatches.

No query export handy yet? Use the package’s built-in sample dataset instead:

person_data <- pq_data

import vivainsights as vi

# Load person query data and standardize variable names
person_data = vi.import_query("path/to/your/person_query.csv")

# Quick exploration
print(person_data.info())
vi.create_bar(person_data, metric="Collaboration_hours")

Whilst you can use pd.read_csv() for reading the .csv query into your Python environment, we recommend using the import_query() function instead from the vivainsights package. import_query() standardizes variable names and ‘cleans’ special characters, ensuring that you minimize the number of errors arising from variable name mismatches.

No query export handy yet? Use the package’s built-in sample dataset instead:

person_data = vi.load_pq_data()

Avoid these common pitfalls

A handful of issues account for most of the confusing results people run into with a first export:

  • IsManager and similar flags often arrive as "Yes"/"No" text rather than booleans, so a filter like IsManager == TRUE silently matches nothing.
  • "#N/A" sometimes arrives as a literal string rather than a true null, which can inflate a group’s row count with a bogus category.
  • Viva Insights suppresses small groups (commonly under 5 people) in the portal. Reproduce that same threshold locally, or your numbers will not match what stakeholders see in the portal.
  • Holiday and low-activity weeks shift population-level averages in ways that can look like a real behavioral change.

These are documented in full, with the fix for each, in the Viva Insights Analysis skill’s data pitfalls reference and the schema documentation.

Common analysis patterns

Time trend:

create_trend(person_data, metric = "Collaboration_hours")

vi.create_trend(person_data, metric="Collaboration_hours")

Distribution by group:

create_boxplot(person_data, metric = "Meeting_hours", hrvar = "Organization")

vi.create_boxplot(person_data, metric="Meeting_hours", hrvar="Organization")

For organizational network analysis (who collaborates with whom, across groups or individuals), see the dedicated Network Analysis page.

Next steps

Once your environment is set up:

  1. Explore the examples. Browse the utility scripts for runnable, real-world patterns.
  2. Read the data pitfalls guide above before you draw conclusions from a first export.
  3. Try a Frontier Analytics prompt or Skill. If you have a coding agent (GitHub Copilot, Claude Code, or similar), Frontier turns an export into a finished dashboard, deck, or report.
  4. Move on to Essentials or Advanced Analytics for custom KPIs, multi-query joins, machine learning, and statistical testing.

Helpful resources

Need help?

Last updated: Aug 10, 2026 Edit this page on GitHub