Client-Nutzung

primedocs hält fest, welche Clients in welchen Versionen tatsächlich im Einsatz sind. Die Auswertung beantwortet vor einem Server-Update, ob noch veraltete Desktop-Clients laufen oder alte Add-in-Manifeste im Umlauf sind, und zeigt, wie sich die Nutzung auf Desktop, Web und die Office-Add-ins verteilt. Ausgewertet werden die Daten im Web-Admin in der Versionsübersicht.

Erfasste Daten

Pro Kombination aus Benutzer, Client-Typ und Version wird ein Eintrag geführt:

Feld	Inhalt
Benutzer	Der primedocs-Benutzer, der den Client verwendet hat.
Client-Typ	Einer der unten aufgeführten Typen.
Version	Version des Clients bzw. des Manifests (max. 100 Zeichen).
Rechnername	Nur beim Desktop Client. Die webbasierten Clients (primedocs Web und Web Add-Ins) melden keinen Rechnernamen.
Erster Einsatz	Zeitpunkt, zu dem die Kombination erstmals gemeldet wurde (UTC).
Letzter Einsatz	Zeitpunkt der letzten Meldung (UTC).

Client-Typen

Client-Typ	Anwendung	Gemeldete Version
Desktop	primedocs Desktop Client mit den Office-COM-Add-Ins	Installierte Anwendungsversion
Web	primedocs Web im Browser	Version der Web-App
OfficeAddin	Office Web Add-In in Word, Excel oder PowerPoint	Version des ausgerollten Add-In-Manifests
OutlookAddin	Outlook Web Add-In	Version des ausgerollten Add-In-Manifests
TeamsAddin	primedocs als Teams-App	Version des ausgerollten Teams-Manifests
SharePoint	primedocs über die SharePoint-Erweiterung (SPFx)	Version des ausgerollten Pakets (sppkg)

Erfassung

• Desktop Client: meldet beim Start der Synchronisierung seine Version und den Rechnernamen an den Sync-Dienst.
• primedocs Web und Web Add-Ins: melden bei authentifizierten Anfragen an den Server. Die Web Add-Ins übermitteln zusätzlich ihren Typ und die Version des Manifests, das sie gestartet hat. Die Manifest-Version steht zur Laufzeit weder über Office.js noch über das Teams SDK zur Verfügung und wird deshalb vom Manifest selbst mitgegeben.
• Eine Meldung wird höchstens einmal pro 24 Stunden je Benutzer, Client-Typ und Version verbucht.
• Die Erfassung ist unkritisch: Schlägt sie fehl, wird die Anfrage des Benutzers trotzdem normal verarbeitet und der Fehler lediglich protokolliert.

Manifest-Version «unknown»

Add-In- und SharePoint-Deployments, die vor der Einführung dieser Erfassung ausgerollt wurden, liefern keine Manifest-Version und erscheinen mit der Version unknown. Das ist ein verlässlicher Hinweis darauf, dass dort ein Update des Manifests bzw. des Pakets aussteht. Denselben Wert erhalten Meldungen, deren Versionsangabe leer ist oder ausschliesslich aus Zeichen besteht, die in keinem Versionsschema vorkommen.

Rechnername wird nicht nachgeführt

Ein Eintrag wird über Benutzer, Client-Typ und Version identifiziert. Der Rechnername gehört nicht dazu. Meldet derselbe Benutzer dieselbe Desktop-Version später von einem zweiten Rechner, bleibt der zuerst erfasste Rechnername stehen. Die Anzahl unterschiedlicher Rechner ist damit eine Untergrenze, keine Inventarliste.

Aufbewahrung

Ein Hintergrundjob löscht Einträge, deren letzter Einsatz länger zurückliegt als die Aufbewahrungsdauer. Standard sind 90 Tage. Ein anderer Wert wird über das Attribut userClientUsageRetentionDays am <syncBehavior>-Element der primedocs.config gesetzt:

<syncBehavior maxConcurrentClients="30" initialAverageSyncTimeInSeconds="10" timeoutInSeconds="120" userClientUsageRetentionDays="180" />

Ein Wert von 0 oder kleiner fällt auf die 90 Tage zurück.

Auswertung über den Health Monitor

Der Detail-Endpunkt des Health Monitors liefert unter userClientUsages je Datasource die Nutzung, gruppiert nach Client-Typ und Version und absteigend nach Anzahl sortiert:

GET {HealthMonitorUrl}/v1/status/detailed

Feld	Inhalt
type	Client-Typ
version	Version bzw. Manifest-Version
clientCount	Anzahl Benutzer mit dieser Kombination
lastSeenOnUtc	Jüngster Einsatz über alle Einträge dieser Kombination

Erster Einsatz und Rechnername sind hier nicht enthalten. Dafür dient die Admin API. Die Werte werden für die Dauer des Health-Monitor-Intervalls zwischengespeichert und sind entsprechend nicht tagesaktuell.

Auswertung über die Admin API

Die Admin API stellt dieselben Daten in zwei Ausprägungen bereit. Beide Endpunkte verlangen ein Token mit dem Scope pd_AdminWebApi und die Rolle SysAdmin oder Developer. Ein API-Client braucht dafür in der primedocs.config das Attribut roles="SysAdmin", siehe primedocs.config.

Zusammenfassung pro Typ und Version

GET .../api/v3/{datasourceId}/Admin/ClientUsages/Summary

Liefert unter clients einen Eintrag je Kombination aus Client-Typ und Version, sortiert nach Typ und Version:

Feld	Inhalt
type	Client-Typ (Unknown für einen Typ, den diese API-Version nicht kennt)
version	Version bzw. Manifest-Version
userCount	Anzahl unterschiedlicher Benutzer
machineCount	Anzahl unterschiedlicher Rechnernamen (0 für die webbasierten Clients)
firstSeenOnUtc	Frühester erster Einsatz dieser Kombination
lastSeenOnUtc	Jüngster letzter Einsatz dieser Kombination

Einzelne Einträge

GET .../api/v3/{datasourceId}/Admin/ClientUsages?query={suchbegriff}&page=1&pageSize=100

Liefert die einzelnen Einträge (je Benutzer, Client-Typ und Version einer), beginnend beim jüngsten Einsatz. Die Antwort folgt der allgemeinen Antwortstruktur und Paginierung.

Feld	Inhalt
userId	ID des Benutzers
userTitle	Anzeigename des Benutzers
type	Client-Typ
version	Version bzw. Manifest-Version
machineName	Rechnername (null für die webbasierten Clients)
firstSeenOnUtc	Erster Einsatz
lastSeenOnUtc	Letzter Einsatz

Der optionale Parameter query schränkt auf Einträge ein, deren Anzeigename, Version oder Rechnername den Suchbegriff enthält. Ob dabei Gross- und Kleinschreibung unterschieden wird, richtet sich nach der Collation der Datenbank.

# Zusammenfassung der Client-Nutzung abrufen
$apiRequestHeaders = @{ "Authorization" = "Bearer $accessToken" }
$apiUrl = "https://{instanz}/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