Configuration Reference

Configuration reference

All of these settings are written for you by the installer. This page documents them for tuning and troubleshooting.

On a deployed solution the settings live on the App Service → Configuration:

• Application settings — the appSettings keys below.
• Connection strings — the SQL / Redis / Service Bus / Storage entries below.

When running locally they come from the project's App.config / Web.config. See also Security & permissions model for how the secrets are protected, and What data is collected for what each import produces.

Almost everything defaults to opt-in / off, so an unconfigured install will not start writing data unexpectedly.

Connection strings

Name	Purpose
SPOInsightsEntities	The analytics SQL database (Entity Framework). The single source of reporting data.
Redis	Azure Cache for Redis (token & lookup cache). Authenticates with Entra ID RBAC when the cache has access keys disabled (no password in the string).
ServiceBus	Service Bus namespace (Teams Calls queue). Only present when the Calls import is enabled. Authenticated with Entra ID RBAC — the SAS key in the string is ignored.
Storage, AzureWebJobsStorage, AzureWebJobsDashboard	The storage account (WebJobs host + blob storage for logs and PowerShell SQL extensions).

What to import — ImportJobSettings

The single ImportJobSettings app setting is a ;-separated list of flags controlling which importers run. Every flag defaults to False (opt-in). Example:

GraphUsageReports=True;GraphTeams=True;ActivityLog=True;WebTraffic=True

Flag	Enables	Needs
WebTraffic	SharePoint web tracking (page hits, clicks, sessions, page metadata) via the AITracker JavaScript.	Application Insights + AITracker deployed to sites.
ActivityLog	Audit-log import from the Office 365 Management Activity API (SharePoint, Exchange, Azure AD, Power Platform, Copilot, etc.).	ActivityFeed.Read.
GraphUsageReports	Daily/weekly usage reports (SharePoint, Teams, Outlook, OneDrive, Yammer, Microsoft 365 apps).	Reports.Read.All.
GraphTeams	Teams metadata (teams, channels, tabs) and optional deep chat analytics.	Group.Read.All (+ delegated perms for deep analytics).
GraphUsersMetadata	User attributes & SKUs for all seen users.	User.Read.All, Organization.Read.All.
GraphUserApps	Teams apps installed per user.	TeamsAppInstallation.ReadForUser.All.
Calls	Teams call records (via the webhook + Service Bus queue).	CallRecords.Read.All + Service Bus.
SentEmails	Sent-email import from each user's sentitems folder.	Mail.Read.

See Prerequisites → Permissions for the full permission detail and What data is collected for the resulting data.

Identity & authentication

Setting	Purpose
ClientID, ClientSecret, TenantGUID	The runtime service principal used to call Microsoft Graph / Microsoft 365 and to authenticate to Azure resources via RBAC.
TenantDomain	The tenant's onmicrosoft.com domain.
AADInstance	Azure AD authority. Default https://login.microsoftonline.com/.
KeyVaultUrl	Key Vault that holds the runtime secret / certificate.
UseClientCertificate	True to authenticate the runtime account with a certificate instead of a client secret. See Certificate authentication.

Cognitive Services (optional)

Setting	Purpose
CognitiveEndpoint	Azure AI Language endpoint (sentiment / key-phrase / language detection).
CognitiveKey	Key for the above. Optional — when key auth is disabled the runtime falls back to Entra ID RBAC (Cognitive Services User role).

Anonymous usage telemetry (optional, opt-in)

Setting	Purpose
StatsApiUrl	Endpoint of the Telemetry Service to report anonymous, opt-in usage stats to. Leave blank to disable.
StatsApiSecret	Shared secret used to sign the telemetry payload.

No tenant data is ever sent — see Telemetry Service.

Tuning & advanced

These are rarely changed. Most are set by the installer or left at their defaults.

Setting	Default	Purpose
MetadataRefreshMinutes	24 hours	How often SharePoint page metadata is refreshed. See Product notes.
ChunkSize	1.00:00:00 (1 day)	Time window per Activity API download chunk.
DaysBeforeNowToDownload	6	How many days back the activity importer downloads on each run.
ReadHitsDaysBeforeToday	(unset)	How many days back to start reading web-traffic hits from Application Insights. Can also be passed via the -readHitsDaysBeforeToday command-line argument.
TimeChunkOverlapMinutes	5	Overlap between time chunks to avoid missing events at boundaries.
MaxSummaryFetchConcurrency	(importer default)	Parallelism when fetching usage-report summaries.
ForceUsageReportsImport	off	Forces a usage-reports import even if one ran recently (diagnostics).
ContentTypesListAsString	Audit.SharePoint	Which Office 365 Management Activity API content types to subscribe to.
UserGroupsFilter	(unset)	Restrict imports to members of specific Entra ID groups.
WebAppURL	(set by installer)	Public URL of the admin/website app service.
AppInsightsConnectionString	(set by installer)	Application Insights connection string used for the solution's own logging/telemetry.
AppInsightsContainerName	(set by installer)	The Application Insights resource the AITracker web-traffic data is read from.

Reducing importer CPU usage (aggressiveness)

The two importer WebJobs (Office365ActivityImporter and AppInsightsImporter) run continuously on the same App Service plan as the website (Basic B1 = 1 vCPU by default, B2 in production). Each WebJob wakes on a fixed cycle and, by default, fans work out across many threads — so on a small plan you can see short bursts of 100% CPU, which may trip tenant CPU alerts.

These settings let you trade a little import speed for lower, steadier CPU without losing freshness on the data that needs it. Audit events and web-traffic hits keep their normal cycle cadence at every level — only the burst concurrency (and, at Gentle, the cycle pause) change. The other Graph imports (user metadata, user Teams apps, Teams crawl) change very little intraday, so by default they now run once a day instead of every cycle.

All of these are optional — they are not written by the installer. To change them, add the key on App Service → Configuration → Application settings and restart the WebJobs.

ImportAggressiveness — one-setting preset

Value	Audit-load threads	Cycle pause	Effect
High	20	10 min	Fastest, highest peak CPU (the behaviour before this feature).
Balanced (default)	8	10 min	Modestly eased: lower audit burst + non-fresh Graph imports daily-gated.
Gentle	3	20 min	Lowest CPU; imports take longer but stay well below 100%.

Upgrade note: the default is Balanced, so existing installs ease up automatically after upgrading. To keep the previous behaviour set ImportAggressiveness=High; for the quietest footprint set Gentle.

Individual overrides

Any of these override the value the preset would otherwise supply:

Setting	Default	Purpose
MaxAuditReportLoadConcurrency	preset (High 20 / Balanced 8 / Gentle 3)	Max parallel threads used to full-load audit reports from the Activity API. The main per-cycle CPU lever.
ImportCyclePauseMinutes	preset (High/Balanced 10 / Gentle 20)	Minutes a WebJob waits between import cycles.
GraphMetadataImportIntervalHours	24	Minimum hours between the "non-fresh" Graph imports (user metadata, user Teams apps, Teams crawl). 0 = run every cycle (legacy). Requires Redis to persist the gate across cycles.
ImportStartStaggerMinutes	half the cycle pause	One-off delay before the hits WebJob's first cycle, so the two WebJobs don't peak on the shared plan at the same time. 0 disables.

If CPU is still a concern at Gentle, the other lever is to scale the App Service plan up (e.g. B2/B3 or a Standard tier with more vCPUs) — see Architecture and costs.