Client usage
primedocs records which clients are actually in use, and in which versions. Before a server update, the statistics answer whether outdated desktop clients are still running or old add-in manifests are still in circulation, and they show how usage is distributed across desktop, web and the Office add-ins. In the Web Admin, the data is evaluated in the Version Overview.
Recorded data
One entry is kept per combination of user, client type and version:
| Field | Content |
|---|---|
| User | The primedocs user who used the client. |
| Client type | One of the types listed below. |
| Version | Version of the client or of the manifest (max. 100 characters). |
| Machine name | Desktop client only. The web-based clients (primedocs Web and the web add-ins) report no machine name. |
| First seen | Time the combination was first reported (UTC). |
| Last seen | Time of the most recent report (UTC). |
Client types
| Client type | Application | Reported version |
|---|---|---|
Desktop | primedocs desktop client with the Office COM add-ins | Installed application version |
Web | primedocs Web in the browser | Version of the web app |
OfficeAddin | Office web add-in in Word, Excel or PowerPoint | Version of the deployed add-in manifest |
OutlookAddin | Outlook web add-in | Version of the deployed add-in manifest |
TeamsAddin | primedocs as a Teams app | Version of the deployed Teams manifest |
SharePoint | primedocs through the SharePoint extension (SPFx) | Version of the deployed package (sppkg) |
How usage is recorded
- Desktop client: reports its version and the machine name to the sync service when synchronisation starts.
- primedocs Web and web add-ins: report on authenticated requests to the server. The web add-ins additionally submit their type and the version of the manifest that launched them. The manifest version is available at runtime neither through Office.js nor through the Teams SDK, and is therefore passed along by the manifest itself.
- A report is recorded at most once every 24 hours per user, client type and version.
- Recording is non-critical: if it fails, the user's request is still processed normally and the error is only written to the log.
Add-in and SharePoint deployments rolled out before this tracking was introduced report no manifest version and appear with the version unknown. This is a reliable indicator that an update of the manifest or package is due there. The same value is used for reports whose version is empty or consists exclusively of characters that occur in no version scheme.
An entry is identified by user, client type and version. The machine name is not part of that. If the same user later reports the same desktop version from a second machine, the machine name recorded first remains in place. The number of distinct machines is therefore a lower bound, not an inventory.
Retention
A background job deletes entries whose last use is older than the retention period. The default is 90 days. A different value is set through the userClientUsageRetentionDays attribute on the <syncBehavior> element of the primedocs.config:
<syncBehavior maxConcurrentClients="30" initialAverageSyncTimeInSeconds="10" timeoutInSeconds="120" userClientUsageRetentionDays="180" />
A value of 0 or lower falls back to the 90 days.
Querying through the Health Monitor
The detailed endpoint of the Health Monitor returns the usage per datasource under userClientUsages, grouped by client type and version and sorted by count in descending order:
GET {HealthMonitorUrl}/v1/status/detailed
| Field | Content |
|---|---|
type | Client type |
version | Version or manifest version |
clientCount | Number of users with this combination |
lastSeenOnUtc | Most recent use across all entries of this combination |
First seen and machine name are not included here. The Admin API provides those. The values are cached for the duration of the Health Monitor interval and are therefore not up to the minute.
Querying through the Admin API
The Admin API provides the same data in two shapes. Both endpoints require a token with the scope pd_AdminWebApi and the SysAdmin or Developer role. For this, an API client needs the attribute roles="SysAdmin" in primedocs.config, see primedocs.config.
Summary per type and version
GET .../api/v3/{datasourceId}/Admin/ClientUsages/Summary
Returns one entry per combination of client type and version under clients, sorted by type and version:
| Field | Content |
|---|---|
type | Client type (Unknown for a type this API version does not know) |
version | Version or manifest version |
userCount | Number of distinct users |
machineCount | Number of distinct machine names (0 for the web-based clients) |
firstSeenOnUtc | Earliest first use of this combination |
lastSeenOnUtc | Most recent last use of this combination |
Individual entries
GET .../api/v3/{datasourceId}/Admin/ClientUsages?query={searchterm}&page=1&pageSize=100
Returns the individual entries (one per user, client type and version), starting with the most recent use. The response follows the general response structure and pagination.
| Field | Content |
|---|---|
userId | ID of the user |
userTitle | Display name of the user |
type | Client type |
version | Version or manifest version |
machineName | Machine name (null for the web-based clients) |
firstSeenOnUtc | First use |
lastSeenOnUtc | Last use |
The optional query parameter restricts the result to entries whose display name, version or machine name contains the search term. Whether case is distinguished follows the collation of the database.
# Retrieve the client usage summary
$apiRequestHeaders = @{ "Authorization" = "Bearer $accessToken" }
$apiUrl = "https://{instance}/webapi/api/v3/$($datasourceId)/Admin/ClientUsages/Summary"
$summary = Invoke-RestMethod -Uri $apiUrl -Method GET -Headers $apiRequestHeaders
$summary.clients | Format-Table type, version, userCount, machineCount, lastSeenOnUtc