Microsoft Viva Insights OData Query Download

This repository provides sample Python and R code to download Microsoft Viva Leader Insights (Workplace Analytics) flexible queries as .csv files using an OData link.

The key use case is to enable analysts to automate the download of flexible queries without going through the Web Experience.

The code itself is primarily based on ms-identity-python-daemon.

Pre-requisites

You will need:

• EITHER
  • python 3.x or after
  • R 3.6 or after
• Admin access to Workplace Analytics
• Admin access to Azure Active Directory

Python pre-requisites

For Python users, you will need to install the following packages with pip install:

• sys
• json
• csv
• logging
• param
• requests
• msal

R pre-requisites

For R users, you will need to install the following packages with install.packages():

• AzureAuth
• httr
• dplyr
• purrr
• readr

Set up a daemon console

You will need to create a daemon console. Follow the steps below to create one:

Choose the Azure AD tenant where you want to create your applications

As a first step you'll need to:

1. Sign in to the Azure portal using either a work or school account or a personal Microsoft account.
2. If your account is present in more than one Azure AD tenant, select Directory + Subscription at the top right corner in the menu on top of the page, and switch your portal session to the desired Azure AD tenant.
3. In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations.

Register the client app (daemon-console)

1. Navigate to the Microsoft identity platform for developers App registrations page.

2. Select New registration.

   • In the Name section, enter a meaningful application name that will be displayed to users of the app, for example daemon-console.
   • In the Supported account types section, select Accounts in this organizational directory only ({tenant name}).
   • Select Register to create the application.

3. On the app Overview page, find the Application (client) ID value and record it for later. You'll need it to configure the Visual Studio configuration file for this project.

4. From the Certificates & secrets page, in the Client secrets section, choose New client secret:

   • Type a key description (of instance app secret),
   • Select a key duration of either In 1 year, In 2 years, or Never Expires.
   • When you press the Add button, the key value will be displayed, copy, and save the value in a safe location.
   • You'll need this key later to configure the project in Visual Studio. This key value will not be displayed again, nor retrievable by any other means, so record it as soon as it is visible from the Azure portal.

5. In the list of pages for the app, select API permissions

   • Click the Add a permission button and then,
   • Ensure that the APIs my organization uses tab is selected
   • In the search bar, type in Workplace Analytics.
   • Select Application permissions, then ensure that the Analyst box is checked. This will allow the app to access queries as an Analyst.
   • Select the Add permissions button

6. At this stage permissions are assigned correctly but the client app does not allow interaction. Therefore no consent can be presented via a UI and accepted to use the service app. Click the Grant/revoke admin consent for {tenant} button, and then select Yes when you are asked if you want to grant consent for the requested permissions for all account in the tenant. You need to be an Azure AD tenant admin to do this.

See here for the original documentation.

Usage

To run the code, clone this repository or download it as a zipped file.

Go into dl_query.py or dl_query.R, and change the parameters in the upfront section.

There are a number of parameters that you must set prior to running dl_query.py:

1. par_authority: url for your tenant, e.g. https://login.microsoftonline.com/[your tenant]/. For R users, you can omit the https://login.microsoft.com/ prefix.
2. par_client_cred: secret used for generating the token
3. par_client_id: client id
4. par_odata: OData url used for downloading the query
5. par_outfile: string specifying the name of the output .csv file

Ensure that you have changed the parameters and saved the appropriate. file.

For Python users, in PowerShell, ensure your directory is changed to the repository root, run:

python dl_query.py

For R users, you can run dl_query.R directly with R or from within RStudio.

This should then save a CSV file in the root directory with the file name specified with the par_outfile parameter.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.