Deployment Guidance
The following sections document the steps required to deploy the Microsoft 365 Advanced Analytics Engine solution components.
The deployment can be done automatically or manually - but installation is highly recommended to be done with the installer/control-panel application if possible.
First, go ahead and read the prerequisites page. Then come back here once you have understood them.
Useful references while you configure: the Configuration reference (every app setting and connection string) and the Security & permissions model (how the runtime account authenticates and what it can access).
Solution assets are available on the GitHub Releases page: https://github.com/pnp/Microsoft365-Analytics-Insights/releases
This page contains the latest stable & testing builds.
The primary package you will need is the installer/control-panel application which is what installs the solution. The installer will install or update an install but can also test the readiness of the configuration loaded without making any changes.
Copy the Microsoft 365 Advanced Analytics Engine solution component build assets provided to a machine that complies with the installer machines prerequisites.
To deploy via the installer, you need only download that which will then download the other assets automatically. The installer is in ControlPanelApp; download, extract and run AnalyticsInstaller.exe (note: it's called "Control Panel" as it was originally intended to do more than just install the solution).
If you are deploying manually or you're installing a specific build via the installer, you will need to download the assets manually:
| Package | Description |
|---|---|
| AITrackerInstaller.zip | JavaScript + PowerShell to insert into SPO sites to track web-usage. |
| AppInsightsImporter.zip | This is the web-job binaries to import data from Application Insights |
| Office365ActivityImporter.zip | This is the web-job binaries to import activity from Microsoft 365. |
| Website.zip | The app service website contents including the Graph webhook endpoint for call tracking. |
The installer can install a specific build if needed:
Unless otherwise requested, we recommend installing the latest stable build.
Before being able to run the installation process either manually or automatically, the following information is needed.
| Entra ID | Description |
|---|---|
| Installation service principal credentials | The service principal used by the installer/control-panel to create Azure resources. |
| Run-time service principal credentials | The service principal used by the runtime web-job to import Microsoft 365 activity & Graph data. |
| Azure | Description |
|---|---|
| Resource group name | The target resource group for all Azure resources created. |
| Azure location | Region to create resources in. |
| Subscription details | The ID + Name of the subscription to be used. Can be autodetected if installer account has permissions to read Azure subscriptions. |
| Tags | Some organizations need to create resources with tags. |
| Application Insights name | Name of resource to create. |
| App service & app service plan names | Names of App Service to create + plan. App Service name must be unique. |
| Azure cognitive services app (optional) | Endpoint + key |
| Automation Account name | Name of automation account to create. |
| Blob storage account name | Name of storage account to create. Must be unique. |
| Azure Cache for Redis | Connection string |
| Azure Service Bus | Connection string |
| SQL Server name, admin username and password | Configuration for the database server to create. Must be a unique name. |
| SQL Database name | Name of the database to create on the SQL Server. |
| SharePoint | Description |
|---|---|
| Site collection URLs | Where to deploy the tracking script & enable activity tracking. One URL per line. |
| App catalog URL | Site collection of app catalogue for tenant. |
| SharePoint sign-in | The installer opens your browser once so you can sign in. Use an account that is a SharePoint administrator and a site collection administrator on each of the supplied site collections. No password is stored, and no app registration is needed. |
| Sign-in app ID | Optional. Only for tenants that block the built-in SharePoint Online Management Shell app — see Legacy SPO web setup. If set, Sign-in tenant is required too. |
There are two methods to deploy the solution: automatic via the control-panel application, and manually. If you are using the control-panel/installer automatic method (recommended), you need an installation service principal.
Express version:
If you just want a quick overview of the installation process:
- Register an application in Entra ID to install solution with.
- Register an application in Entra ID to read Microsoft 365 activity data.
- Setup solution dependencies:
- Via the installer – recommended as it automates many parts of the solution setup.
-
Manually – fallback for if the installer route isn't an option.
- Create Azure resources & configure app service with corresponding keys.
- Upload web-jobs.
- (Optional) Install SharePoint extension application.
- (Optional) Run PowerShell to staple AITracker.js to site collections.
- Verify success: data is flowing & web-jobs are running continuously.
Pre-Flight Checklist:
Before installing, please check the following is verified:
- Runtime service account is created with permissions added and approved (see "Prerequisite Permissions").
- Azure service providers enabled (see "Prerequisite Azure & Microsoft 365 Configuration").
- HTTPS access to the App Service SCM endpoint and SQL port 1433 are open from the installer machine (see "Prerequisite Firewall Rules").
- Microsoft 365 reports anonymisation is disabled - https://learn.microsoft.com/en-us/microsoft-365/troubleshoot/miscellaneous/reports-show-anonymous-user-name
- Recommended: run a "test configuration" from installer before attempting any installation:
When no errors are seen here, there's a good chance the installer will work. Any errors should be reviewed before installing.
Before running the installer, create and configure the two Entra ID app registrations (installer + runtime). This is a one-time setup. See App registrations setup.
Note: Follow these steps using the installer application. For manual installation and creation of the required Azure resources, visit this page: Install manually
The first step is to set up the data collection.
There is an installer application to help setup everything, but it needs permissions in Entra ID to do so. If it doesn't work because of permissions or any other reason, the manual installation is the fallback method & explained too.
Important: The installer account needs to be in the same tenant as Microsoft 365.
Extract the control panel application & run AnalyticsInstaller.exe. You may be interrupted by Windows SmartScreen:
Click "more info" and then "run anyway". If you don't have that option, you need to configure Windows Defender SmartScreen to only warn (the default Windows setting).
All the Azure resources will be created in a single resource group. We recommend pre-creating this resource group and assigning owner rights to the installer account for this group only.
The installer can also create the resource group if the installer account has the right permissions on the subscription.
Next, we need to fill out the remaining configuration. Trying to save the configuration will tell you if there's any validation errors/missing data.
Note: the screenshots in this documentation may not reflect the exact experience of the installer you see. The same information will be there however, just maybe differently presented.
Pick the data-sources you wish to import:
Later, you can also reconfigure which sources to include or ignore.
At this point you should have both service accounts filled out in the installer from the above configuration.
The resource group needs to be the same name as the group we created previously (or not if we wish the installer to try and create the group).
Make sure a subscription is selected. The refresh button will use the supplied installer account details to try and refresh this. If it fails, you can enter the details manually.
The performance tier configuration gives you a chance to configure an initial pricing tier for the environment. This only applies for resources created for the 1st time (if Azure resources are found already the performance settings are left untouched) and are the general recommendations for each type of environment.
Later, we highly recommend tuning the performance tier to your specific needs.
The following resources need unique names in Azure as they will by default have public endpoints, so public & unique DNS names are needed:
- Key vault
- Storage
- SQL Server
- Redis
- App Service name (the plan can be shared)
- Cognitive Services
Change these to something that's unlikely to exist already.
On this page, Azure PaaS storage related resources related can be configured. Again, names must be unique. You can use the default SQL server username if you'd like.
If you want the solution's PaaS resources locked to a virtual network with private endpoints (no public access), configure the VNet, subnets and options on the Networking tab. Leave it disabled for a standard public deployment.
See Private endpoints for the full private-networking guide and what still needs doing manually afterwards.
Note: This tab appears when Track web traffic or the audit log import is enabled on the Targets tab — the site list scopes both. But the SharePoint install (and the sign-in it needs) only happens when Track web traffic is on. With web tracking off, the site list is used purely as a URL filter, nothing is deployed to SharePoint, you are never asked to sign in, and none of the SharePoint prerequisites below apply.
This page lists the site collections where AITracker is to be installed, and the app-catalogue URL to install the SharePoint Framework Extension package to.
How to create an app-catalogue: https://learn.microsoft.com/en-us/sharepoint/use-app-catalog
The "domain" field is taken from the Entra ID domain backing SharePoint & Microsoft 365.
Installing the tracker is a highly privileged operation, so the installer asks you to sign in interactively. When the install reaches the SharePoint stage it opens your default web browser once; the resulting token is reused for the app catalog and for every target site, and is held in memory for the duration of the install only. No SharePoint password is ever stored in the configuration file.
The account you sign in with needs:
- SharePoint Administrator (or Global Administrator) — to upload and tenant-deploy the SPFx package to the tenant app catalog.
-
Site Collection Administrator on each site collection listed above — to create and secure the
SPOInsightslibrary and register the tracking custom actions.
Because this is a normal browser sign-in, MFA, Conditional Access, passkeys and FIDO2 all work.
No app registration is required. Any OAuth sign-in needs an Entra ID app registration behind it; rather than make you create one, the installer reuses an app Microsoft already publishes — the one behind the SharePoint Online Management Shell PowerShell module, the same identity Connect-SPOService uses. In most tenants it's already present, so there is nothing to create or consent to. It is a delegated sign-in, so it grants no standing access: the installer can only do what the signed-in administrator could already do.
Sign-in app ID and Sign-in tenant are only for tenants that block that app, or organisations that want their own consent record — see Optional: use your own Entra ID app registration. If you do set your own app ID, the tenant is required too.
Upgrading from an older release? The old embedded Internet Explorer pop-up login has been replaced by this browser sign-in. Nothing about already-tracked sites changes, and there is nothing to re-run. See Legacy SPO web setup for the previous behaviour.
Before installing, click Test configuration to validate the settings and connectivity. It makes no changes and can auto-detect an existing SQL target. Resolve anything that fails before you install.
App Service content deployment uses Kudu over HTTPS/443. There is no separate FTP connectivity test or passive-port requirement.
When everything's filled out, you should be ready to install. You can specify what tasks are to be done by the installer, from complete install & validation to just updating the solution components if needed.
Click "Install/Upgrade" button once ready.
If there are any validation errors, this is when you'll see them:
When the installer has all the required data it will begin the process.
Assuming there are no validation errors, the installer settings are saved locally so you don't need to configure everything again.
Handle Installer Errors
If possible that errors will occur the first time at least; naming conflicts etc. These should be logged by the installer so you can make any configuration changes needed.
Save Configuration file
In order so you don't have to fill out everything again, you can save the configuration data as a JSon file for later. The files are encrypted (or at least the sensitive fields in the file are), so a password is needed to load & save configuration files:
Once you are ready to go, click "install/upgrade" to apply your chosen configuration.
You'll see the installer will create any resources that do not exist yet and will also run any actions specified above. If you're upgrading an existing solution, it's highly recommended you allow schema upgrades.
Any errors found will be logged & the installation can be run several times without any risk. If you do have any errors please verify the solution prerequisites are ready (see prerequisites).
Once the analytics engine has been installed, you can choose to enable some additional features listed here. These are optional and your requirements will vary depending on how you want to use the whole solution.
On the administration website is also where you can give analytics deeper access to Teams content; specifically channel chat.
Important: for enabled sites, chat content is read but never stored – just metadata for channel chat including:
- Languages used
- Sentiment analysis (positive vs negative).
- Keywords.
In order to do this though, a user has to give analytics access to each Team proactively.
Note: the page can take a few seconds to load the 1st time.
Teams that have access given will be crawled next import cycle; usually 3-4 of hours later latest.
If you're running Yammer analytics, you need to grant access to Yammer data as an administrator so the importer can read anything.
Open the administration website and navigate to "/yammerauth" page.
You'll be asked to login and authorise the application.
Once successful, Yammer will redirect back to the analytics site with a code that'll be converted into an access key & stored in Redis for yammer crawling.
The Yammer export uses the export endpoint to retrieve data.
There is an extension where you can enable enhanced user activity analytics capabilities to the solution, so you can report on aggregate usage stats per demographic like "job title", "department" etc.
This gives the ability to split the data by demographic and see which workloads and Microsoft 365 capabilities aren't being harnessed at a much more granular level than standard reports.
Enabling this extension will provision additional tables in the SQL database. There are two Power BI reports that use these extra tables to give you these statistics.
Review the instructions here to setup the analytics extensions: Set up analytics