Integrationen

Der Bereich Integrationen bündelt die Anbindung der Datasource an Verzeichnis, Benutzersynchronisation und Connect. Die Rubrik Benutzerdaten enthält Identitätsanbieter, Benutzersynchronisation und Verzeichniswechsel, die Rubrik Schnittstellen die Konnektoren und primedocs AI. Der Bereich ist für Systemadministratoren und Developer sichtbar, der Verzeichniswechsel nur für Systemadministratoren.

Identitätsanbieter

Die Seite zeigt den aktiven Verzeichnis-Konnektor (Active Directory, Microsoft Graph / Entra ID oder SCIM) und ob das Verzeichnis beim Laden der Seite erreichbar war. Welcher Konnektor gilt und wie sich Benutzer anmelden, legt die primedocs.config fest, nicht diese Seite.

Einstellbar sind die Angaben, mit denen der Konnektor Benutzer und Gruppen nachschlägt:

Konnektor	Einstellungen
Alle	Principal-Cache für Gruppenmitgliedschaften (nicht bei SCIM)
Active Directory	Domäne, Such-Wurzel, Benutzername und Passwort für den Verzeichniszugriff (leer = Dienstkonto), Gruppensuche für verschachtelte Gruppen, globaler Katalog für Umgebungen mit mehreren Domänen
Microsoft Graph / Entra ID	Schaltfläche «Zustimmung erteilen» für die Administrator-Zustimmung im Entra-ID-Mandanten. Sie erscheint, wenn die Serverkonfiguration eine Client-ID enthält.
SCIM	Anzeige des SCIM-Mandanten aus der Serverkonfiguration

Der Web-Admin zeigt das Passwort nicht an, sondern nur, ob eines hinterlegt ist. Ein leeres Passwortfeld lässt das gespeicherte Passwort unverändert. Ist unter Sicherheit & Compliance ein symmetrischer Schlüssel hinterlegt, wird das Passwort verschlüsselt gespeichert, sonst so wie eingegeben. Einen symmetrischen Schlüssel zu hinterlegen wird deshalb empfohlen. Das gespeicherte Passwort gilt nur für dieselbe Domäne, Such-Wurzel und denselben Benutzernamen. Nach einer Änderung einer dieser Angaben muss es neu eingegeben werden, sonst lässt sich nicht speichern.

Anzeigename

Die Karte Anzeigename legt fest, wie Benutzer in Suche, Freigaben und Dokumenten heissen. Der Anzeigename wird zur Bezeichnung des Benutzers in primedocs. Er stammt entweder direkt aus einem Attribut des Verzeichnisses oder wird mit einer Regel aus mehreren Attributen zusammengesetzt, etwa «Ada Lovelace (Research)».

Ohne Regel zeigt der Editor einen einzelnen Baustein mit dem Namensattribut. Zur Auswahl stehen bei Active Directory msDS-PrincipalName (Standard), sAMAccountName, userPrincipalName, displayName oder ein eigenes Attribut, bei Entra ID userPrincipalName (Standard) oder displayName und bei SCIM userName (Standard) oder displayName. Sobald weitere Bausteine, Text oder Ersatzwerte dazukommen, wird eine Regel gespeichert. Für die Regel gibt es zwei Bearbeitungsarten:

• Bausteine: Mit «Attribut hinzufügen» und «Text hinzufügen» werden Attribute und feste Texte aneinandergereiht und mit dem gewählten Trennzeichen verbunden. Pro Attribut lassen sich ein Ersatzattribut und ein Ersatztext für leere Werte sowie Text davor und danach festlegen. Text davor und danach erscheint nur, wenn das Attribut oder sein Ersatzwert ausgefüllt ist. Leere Bausteine fallen weg.
• JavaScript: Ein Ausdruck, der den Namen als Text liefert, oder Funktionen mit function main() { return …; }. $("attribut") liefert den Wert eines Verzeichnisattributs, $.firstNonEmpty(…) den ersten nicht leeren Text und $.joinNonEmpty(trennzeichen, …) verbindet die nicht leeren Texte. Geladen werden nur Attribute, die als fester Text in $("…") stehen. Beim Wechsel zu JavaScript übernimmt der Editor die Bausteine als Code. Der Weg zurück verwirft den Code.

$.joinNonEmpty(" ", $("givenName"), $("sn"))

Bei Active Directory lassen sich alle Attribute verwenden, auch extensionAttribute1 bis extensionAttribute15 und frei eingetippte Namen. Bei Entra ID stehen die Eigenschaften zur Verfügung, die auch die Benutzersynchronisation liest, ausser solchen, die Microsoft Graph nur für einzelne Benutzer liefert, bei SCIM die Attribute der SCIM-Synchronisation.

Ist das Ergebnis einer Regel für einen Benutzer leer, länger als 256 Zeichen oder schlägt die Regel fehl, gilt das Attribut unter «Wenn der Name leer bleibt oder die Regel fehlschlägt». Eine Anmeldung scheitert nie an der Regel.

Die Vorschau berechnet den Namen live aus dem Verzeichnis, ohne etwas zu speichern, standardmässig für das eigene Konto oder für einen gesuchten Benutzer. Mit «Leere Attribute testen» lässt sich prüfen, was bei fehlenden Werten herauskommt.

Gespeichert wird mit der Seite. Neue Benutzer und Treffer der Suche im Verzeichnis zeigen den neuen Namen nach etwa einer Minute. Die Bezeichnung bestehender Benutzer wird beim nächsten Lauf der Benutzersynchronisation angepasst. Lässt sich der Name dabei nicht ermitteln, bleibt die bisherige Bezeichnung und der Sync-Bericht enthält eine Warnung. Gruppen behalten ihren Namen aus dem Verzeichnis.

Benutzersynchronisation

Die Seite Benutzersynchronisation bearbeitet die Konfiguration der Benutzersynchronisation (UserSyncConfig). Mit dem Schalter Sync-Pipeline wird die Synchronisation ein- und ausgeschaltet. Die Seite zeigt auch den Zeitpunkt des letzten erfolgreichen Laufs.

Die Konfiguration lässt sich visuell oder im XML-Editor bearbeiten:

• Allgemein: Sync-Intervall, Timeout, Personen pro Durchlauf, gesperrte Felder überspringen und die automatische Bereinigung nicht mehr gefundener Personen.
• Quellen: Active Directory / LDAP, Entra ID (Microsoft Graph), SCIM, HTTP-Endpunkt, CSV-Datei, SQL-Abfrage und feste Werte, in der Reihenfolge der Pipeline. Pro Quelle die Verbindungsangaben und die Claims.
• Claims: Claim-Typ, Eigenschaft der Quelle, Sprache, Ersatzwert oder Weglassen bei leerem Wert sowie ein regulärer Ausdruck. Das Regex-Feld hat einen Testmodus, der Treffer und Gruppen an einem Beispieltext zeigt.

ResultMapping und Feld-Zuordnungen einer Quelle lassen sich nur im XML-Editor bearbeiten und bleiben beim visuellen Bearbeiten erhalten. Enthält die Konfiguration Elemente, die der visuelle Editor nicht kennt, öffnet sie im XML-Editor. «Beispiel einfügen» ersetzt den Inhalt durch eine Vorlage für Active Directory oder Entra ID, «Hilfe» beschreibt alle Elemente.

Visuelle Bearbeitung einer Active-Directory-Quelle mit Verbindungsangaben, zu ladenden Attributen und Claims.

Sync-Test

Der Sync-Test ist ein Probelauf ohne Schreibvorgang. Eine Person suchen oder ihre SID eingeben und «Testen» wählen. Das Ergebnis zeigt pro Quelle, ob die Person gefunden wurde und welche Eigenschaften gelesen wurden, dazu die Claims, die am Ende aller Quellen entstehen. Der Test verwendet die gespeicherte Konfiguration, offene Änderungen also vorher speichern.

Verzeichniswechsel

Wechselt eine Organisation das Verzeichnis, etwa von Active Directory zu Entra ID, erhalten Benutzer und Gruppen dort neue Kennungen. primedocs erkennt Konten aber an ihrer SID. Ohne Anpassung legt primedocs beim ersten Login über das neue Verzeichnis ein leeres neues Konto an, und Profile, Rollen und Feldwerte bleiben beim alten Konto. Die Seite Verzeichniswechsel verknüpft die bestehenden Konten mit ihrer neuen SID. Profile, Rollen, Gruppenzuordnungen und Felder bleiben erhalten. Die Seite ist Systemadministratoren vorbehalten.

Als SID gilt je nach Verzeichnis die objectSid (Active Directory), die Objekt-ID (Entra ID) oder die externalId (SCIM).

Vor der ersten Anmeldung über das neue Verzeichnis

Die Migration ausführen, bevor sich Benutzer über das neue Verzeichnis anmelden. Wer sich vorher anmeldet, erhält automatisch ein leeres Konto mit der neuen SID. Solche Konten erscheinen in der Vorschau als Konflikt.

Der Assistent führt in vier Schritten durch die Migration. Ein bereits freigegebener Schritt lässt sich direkt anklicken. Ein gesperrter Schritt nennt beim Darüberfahren oder Fokussieren den Grund.

1. Voraussetzung: Die Seite zeigt den aktiven Konnektor und ob das Verzeichnis erreichbar ist. Der Assistent stellt das Verzeichnis nicht um. Die Vorschau liest immer das aktuell konfigurierte Verzeichnis, der Konnektor muss also bereits auf das neue Verzeichnis zeigen. Bei einem Wechsel zwischen Active Directory, Entra ID und SCIM wird zuerst die primedocs.config angepasst.
2. Benutzer migrieren: Benutzer werden über ein gemeinsames Merkmal abgeglichen. Gewählt werden ein Benutzerfeld (Textfeld, vorbelegt mit dem E-Mail-Feld) und die Eigenschaft im Verzeichnis, standardmässig mail. Bei SCIM stehen userName, displayName und customAttribute1 bis customAttribute16 zur Verfügung. Verglichen wird der exakte Wert, ohne Unterscheidung der Gross- und Kleinschreibung.
3. Gruppen migrieren: Gruppen werden über ihren Namen abgeglichen, ohne Domänenpräfix. Eine Einstellung ist nicht nötig.
4. Abschluss: Die Zusammenfassung zeigt, was geändert wird. «Migration ausführen» schreibt zuerst die Benutzer, dann die Gruppen.

Die Vorschau ändert nichts. Bei grossen Verzeichnissen kann sie einige Minuten dauern. Jede Zeile hat einen Status:

Status	Bedeutung
Zu migrieren	Im Verzeichnis gefunden, mit einer anderen SID. Die neue SID wird vorgeschlagen und lässt sich in der Zeile ändern.
Bereits aktuell	Das Konto hat bereits die SID aus dem Verzeichnis.
Nicht gefunden	Kein Wert im gewählten Feld oder kein Treffer im Verzeichnis.
Konflikt	Die neue SID käme nach der Migration mehrfach vor.
Platzhalter	Das Konto hat aus einem früheren Lauf eine Platzhalter-SID. Benutzer mit Platzhalter sind vom Sync ausgeschlossen.

Vorausgewählt sind alle Zeilen mit dem Status «Zu migrieren» ohne Konflikt sowie Konflikte, für die primedocs einen Vorschlag macht. Nicht ausgewählte Zeilen werden nicht migriert.

Konflikte

Ein Konflikt entsteht, wenn mehrere Konten dieselbe neue SID erhalten würden oder ein anderes Konto sie bereits trägt, typischerweise ein Konto, das sich schon über das neue Verzeichnis angemeldet hat. Die Ansicht Konflikte zeigt pro umstrittener SID die beteiligten Konten mit letzter Anmeldung, letztem erfolgreichem Sync, Anzahl Profile und ob ein Profil mit Organisationseinheit besteht.

Bei Benutzern schlägt primedocs ein Konto vor, wenn es alle anderen klar übertrifft: zuerst eine mindestens 30 Tage neuere Anmeldung (oder als einziges überhaupt eine), sonst ein mindestens 30 Tage neuerer erfolgreicher Sync, sonst als einziges ein Profil mit Organisationseinheit. Die Anzahl Profile entscheidet nicht. Bei Gruppen gibt es keinen Vorschlag. Für jeden Konflikt lässt sich das Konto, das die SID erhält, mit «Wählen» bestimmen oder der Konflikt mit «Überspringen» auslassen. Gehört die SID einem Konto anderer Art, etwa einer Gruppe, ist der Konflikt blockiert und lässt sich hier nicht lösen.

Die übrigen Konten eines gelösten Konflikts erhalten eine Platzhalter-SID der Form [migration-conflict]-<alte SID>. Gelöscht wird nichts. Benutzer mit Platzhalter sind vom Sync ausgeschlossen und werden deshalb auch nicht automatisch offboardet.

Ausführen

Die Migration ändert nur die primedocs-Datenbank, nicht das Verzeichnis. Lässt sich ein Eintrag nicht übernehmen, etwa weil sich die SID seit der Vorschau geändert hat oder die neue SID inzwischen vergeben ist, wird er mit Begründung zurückgewiesen. Die übrigen Einträge werden geschrieben. Ändern sich während des Laufs Konten, etwa durch einen gleichzeitigen Sync, bricht die Migration ab. Die Änderungen des laufenden Teils (Benutzer oder Gruppen) werden zurückgenommen. Danach die Vorschau neu erstellen und die Migration wiederholen.

Die Migration lässt sich nicht automatisch rückgängig machen. Alte und neue SID stehen im Ergebnis und im Server-Log. Ein erneuter Lauf zeigt bereits migrierte Konten als «Bereits aktuell». Die Migration lässt sich auch über die Admin API ausführen.

Konnektoren

Die Seite Konnektoren enthält die Richtlinien für Connect und die angebundenen Dienste:

Einstellung	Wirkung
Prozessaufruf	Programme, die ein Connect-Befehl auf dem Client starten darf (Name und Pfad)
URL-Aufruf	Adressen, die ein Connect-Befehl öffnen darf, siehe InvokeUrl
Remote-Connect-Richtlinien	HTTP-Header für den Abruf von Connect-Dateien über eine URL
Richtlinien für Dokumentablagen	HTTP-Header für entfernte Ablageorte. «Access Token einfügen» setzt den Platzhalter für das Token eines Connected Service ein.

Zu weit gefasste Einträge öffnen den Client für unerwünschte Aufrufe. Einträge deshalb so eng wie möglich fassen.

Auf derselben Seite werden die Connected Services verwaltet: OAuth-Zugänge mit Name, Schlüssel, Beschreibung, Aktiv-Status, Authorize- und Token-URL, Client-ID, Client-Secret, Scope und URL-Mustern. Das Client-Secret wird mit dem symmetrischen Schlüssel der Datasource verschlüsselt abgelegt.

primedocs AI

Unter primedocs AI werden die Prompts gepflegt, die in primedocs Web in der KI-Funktion als Schaltflächen erscheinen: Titel (als Tooltip), Symbol (Flaggen-Code wie fi-gb, kurzer Text oder Emoji) und die Anweisung an das Sprachmodell. Prompts wirken erst, wenn auf dem Server ein OpenAI-Endpunkt konfiguriert ist. Andernfalls weist die Seite darauf hin.