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, Copilot, etc.). Power Platform is gated separately by ImportPowerPlatform below.	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.
ImportPowerPlatform	Power Platform workload — PowerApps, Power Automate, Power BI and Copilot Studio (all delivered via the Audit.General feed). Opt-in / default off (newer workload); when off these events are dropped at ingest and their staging merges don't run. Enabling it also subscribes the importer to Audit.General.	ActivityFeed.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.
ResolveCopilotResourceMetadata	True	Resolve Copilot file/meeting metadata (file name/site, meeting name/date) from the Graph. Set False to keep only Copilot agent metadata (agent id/name/type, cost, messages, accessed resources) and skip the per-event Graph resolution — this removes serial, network-bound calls from the save path when only Copilot agent-level reporting is needed. Optional; not written by the installer.
AUDIT_PERBATCH_DEDUP_CACHE	off	Safety valve. The audit importer builds its "already-processed" dedup cache once per cycle by default. Set true to revert to the older per-batch rebuild (much slower and higher memory on large tenants). Optional; not written by the installer.
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	Non-fresh Graph imports*	Effect
High	20	10 min	every cycle	Fastest, highest peak CPU — full pre-feature behaviour.
Balanced (default)	8	10 min	daily (24h)	Modestly eased; the recommended default.
Gentle	3	20 min	daily (24h)	Lowest CPU; imports take longer but stay well below 100%.

*Non-fresh Graph imports = user metadata, user Teams apps, and the Teams crawl. Audit events and web-traffic hits keep their normal cycle cadence at every level.

Upgrade note: the default is Balanced, so existing installs ease up automatically after upgrading. Setting ImportAggressiveness=High fully restores the previous behaviour (including running the non-fresh Graph imports every cycle); Gentle gives the quietest footprint.

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	preset (High 0 / Balanced 24 / Gentle 24)	Minimum hours between the static non-fresh imports (user metadata, user Teams apps). 0 = run every cycle.
GraphTeamsImportIntervalHours	preset (High 0 / Balanced 24 / Gentle 24)	Minimum hours between Teams crawls. Separate from the above because Teams analytics (channel messages/reactions) is fresher — lower it to keep Teams current without un-gating the static imports. 0 = run every cycle.
ForceGraphMetadataImport	off	One-off: bypass the gate for all of the non-fresh Graph imports on the next cycle(s). See Forcing a re-import.
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.

The gate's "last run" timestamps are stored in Redis when it's configured (so the gate survives WebJob restarts), otherwise in an in-memory fallback (the gate still works but resets whenever the WebJob restarts). Redis read/write failures are fail-open — a cache blip never skips an import.

Forcing a re-import (clearing the last-run flags)

The non-fresh Graph imports run only once per their interval. To force them to run again now:

1. Config flag (recommended). Set ForceGraphMetadataImport=true on App Service → Configuration, let one import cycle run, then set it back to false (or remove it). While true it bypasses the gate every cycle.
2. Restart the WebJob — only when Redis is not configured (the in-memory gate is cleared on restart).
3. Clear the Redis flags — when Redis is configured. The keys are stored unprefixed in Redis database 0; delete the ones you want to re-run:

   DEL GraphUsersMetadataLastImported
   DEL GraphUserAppsLastImported
   DEL GraphTeamsLastImported
   DEL UserActivityLastImported     # daily usage reports (use ForceUsageReportsImport instead if you prefer)
   

   Use redis-cli, the Azure Portal cache Console blade, or any Redis client. The next cycle re-runs the cleared sections.

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.