Organisationssynchronisation

Überblick

Organisationseinheiten werden in den meisten Installationen direkt in primedocs gepflegt. Der OrgSync ist die optionale Alternative dazu: Er gleicht die Organisationseinheiten mit einem Fremdsystem ab und lohnt sich, wenn dieses System die Organisationsstruktur führt und sie sich regelmässig ändert.

Da Organisationseinheiten hierarchisch organisiert sind, ist ein 1:1-Abgleich wie bei den Benutzern nicht möglich. Als Synchronisationsquelle dient daher eine XML-Datei, welche mit den Daten vom Fremdsystem ausgefüllt werden muss.

Folgende Daten können hierbei zu primedocs synchronisiert werden:

• Titel der Organisationseinheit
• Zu setzende Felder der Organisationseinheit
• Berechtigungen der Organisationseinheit
• Organisationseinheitenhierachie

Die Organisationseinheit wird über ein eindeutiges Merkmal in primedocs erkannt, d.h. das Fremdsystem gibt einen "Schlüssel/Technisches Merkmal" vor und beim Import der Organisationseinheiten wird dieses Merkmal in primedocs gespeichert.

Die generierte Datei muss danach über den JobHost, z.B. als zeitgesteuerte Aufgabe, in die primedocs Datasource importiert werden.

---

XML Struktur

Folgende XML Struktur wird benötigt:

<primedocsOrgSync>
  <OrganizationUnits>
    <OrganizationUnit>
      <!-- "Technisches Merkmal" - muss eindeutig sein und dient als "Identifikationsmerkmal" für die Synchronisierung -->
      <Identifier></Identifier>
      <!-- Titel der Organisationseinheit -->
      <Title></Title>
      <!-- Felder, die zu primedocs synchronisiert werden -->
      <Fields>
        <!--
          Id="Org.Street": verweist auf eine Felddefinition (FieldId) in primedocs
          Value="Sample Street 123": der tatsächliche Wert, der für diese Organisationseinheit und dieses Feld gespeichert wird
        -->
        <Field Id="Org.Street" Value="Sample Street 123" />
        <!--
          Für die Mehrsprachigkeit ist die exakte LCID erforderlich. Ohne sie wird der Wert in der Standardsprache gespeichert.
          Es sind nur bestimmte LCIDs erlaubt, d. h. "LCID 9" für "Englisch" ist nicht zulässig, sondern muss exakt auf "en-US" oder "en-GB" zeigen.
          Siehe: https://docs.microsoft.com/en-us/openspecs/office_standards/ms-oe376/6c085406-a698-4e12-9d4d-c3b0ee3dbc4a
        -->
        <Field Id="Org.City" Value="München" />
        <Field Id="Org.City" Value="Munich" LCID="2057" />
        <!-- Leere Werte werden ebenfalls unterstützt -->
        <Field Id="Org.POBox" Value="" />
      </Fields>
      <Permissions>
        <!--
          primedocs benötigt die SID und den Typ (Benutzer oder Gruppe) und speichert diese Information in der Datenbank.
          Um diese Information zu laden, wird ein "Lookup" durchgeführt.

          Die Syntax erlaubt z. B. die Suche nach SID, sAMAccountName oder UPN im Active Directory.
          Der gesuchte Wert muss genau einem Objekt im Verzeichnis entsprechen.
          Die gültigen Felder richten sich nach dem Principal Connector:
          im Active Directory: objectSid, sAMAccountName, theoretisch aber auch weitere AD-Felder usw.
          in Microsoft Entra ID: ohne LookupKey die Object ID ("id"), sonst eine der Eigenschaften aus dem Abschnitt «LookupKey bei Microsoft Entra ID»
        -->
        <SecurityAccount LookupValue="local\username" LookupKey="sAMAccountName" />
        <SecurityAccount LookupValue="max.muster@contoso.ch" LookupKey="userPrincipalName" />
      </Permissions>
      <OrganizationUnits>
        <!-- "Unter-Organisationseinheit", gleiches Schema -->
        <OrganizationUnit></OrganizationUnit>
      </OrganizationUnits>
    </OrganizationUnit>
  </OrganizationUnits>
</primedocsOrgSync>

---

Berechtigungssynchronisation

Permissions, welche in dieser Datei angeben sind, überschreiben die Permissions der gefundenen Organisationseinheit in der primedocs Datasource, d.h. im primedocsOrgSync müssen alle gewünschten Permissions vorhanden sein. Manuell gesetzte Berechtigungen werden überschrieben.

Wird die Datasource ohne Application permissions betrieben, lässt sich kein Konto aus dem Import auflösen. Der OrgSync überspringt dann die Berechtigungssynchronisation und lässt die bestehenden Berechtigungen unverändert. Titel, Felder und Hierarchie werden weiterhin synchronisiert.

LookupKey bei Microsoft Entra ID

Mit Microsoft Entra ID als Principal Connector legt LookupKey fest, über welche Eigenschaft des Benutzers oder der Gruppe primedocs den LookupValue in Microsoft Graph sucht. Ohne LookupKey sowie mit id oder objectId (Alias) lädt primedocs das Objekt direkt über seine Object ID. Jede andere Eigenschaft wird mit einem Filter gesucht und muss genau ein Objekt treffen. Zuerst wird ein Benutzer gesucht, nur ohne Treffer danach eine Gruppe.

LookupKey	Gilt für	Hinweis
leer, id, objectId	Benutzer und Gruppen	Object ID aus dem Entra Admin Center. Standard und immer eindeutig.
onPremisesSecurityIdentifier	Benutzer und Gruppen	SID des aus dem lokalen Active Directory synchronisierten Objekts. Damit lassen sich die objectSid-Werte einer Active-Directory-Konfiguration weiterverwenden.
onPremisesSamAccountName	Benutzer und Gruppen	sAMAccountName des synchronisierten Objekts.
mail, mailNickname, displayName	Benutzer und Gruppen	In einem Mandanten nicht zwingend eindeutig.
userPrincipalName	nur Benutzer	Anmeldename (UPN).
employeeId	nur Benutzer	Nicht zwingend eindeutig.
onPremisesImmutableId, onPremisesDistinguishedName	nur Benutzer	Werte des synchronisierten Objekts.
onPremisesExtensionAttribute1 bis onPremisesExtensionAttribute15	nur Benutzer	Erweiterungsattribute aus dem lokalen Active Directory (extensionAttribute1 bis extensionAttribute15).
extension_{appId}_{name}	nur Benutzer	Verzeichniserweiterung (Directory Extension) einer Anwendung.
uniqueName	nur Gruppen	Eindeutiger Name der Gruppe.

Mehrwertige Eigenschaften wie proxyAddresses oder otherMails sowie Eigenschaften, die Microsoft Graph nicht filtern kann (etwa companyName oder mobilePhone), sind nicht zulässig. objectSid ist in Entra ID kein gültiger LookupKey, für SIDs onPremisesSecurityIdentifier verwenden.

In folgenden Fällen wird die Berechtigung nicht übernommen, und das Protokoll des JobHost enthält eine Warnung des Microsoft-Graph-Connectors:

• Der LookupValue trifft mehr als ein Objekt, etwa zwei Benutzer mit demselben displayName. Eine Gruppe mit demselben Wert wird dann nicht herangezogen.
• Microsoft Graph weist die Eigenschaft ab, weil sie für den Objekttyp nicht existiert oder nicht filterbar ist. Das gilt auch für reine Benutzereigenschaften, wenn kein Benutzer passt und deshalb eine Gruppe gesucht wird.
• Der LookupKey ist kein gültiger Eigenschaftsname. primedocs ruft Microsoft Graph dann gar nicht auf.

LookupKey möglichst auf eine eindeutige Eigenschaft setzen, also id, onPremisesSecurityIdentifier oder userPrincipalName.

---

Feldsynchronisation

Fields hingegen werden mit den bestehenden Feldern in der Organisationseinheit zusammengeführt, d.h. nicht angegebene Felder werden nicht geleert, sondern so belassen.

Über den primedocsOrgSync können auch keine Felder gelöscht werden, sodass der Vererbungsmechanismus von primedocs greift. Dies muss manuell geschehen.

---

Synchronisationsverhalten

Alle Organisationseinheiten, die unterhalb des SyncRoot existieren, aber nicht im Import enthalten sind, werden gelöscht.

Profile, die an den gelöschten Organisationseinheiten hängen, werden auf die FallBackOu umgehängt.

Organisationseinheiten, die in der Datenbank ausserhalb des SyncRoot sind aber im Import als Kind des SyncRoot angegeben sind, werden entsprechend dem Import verschoben.

---

JobHost

Analog dem UserSync kann beim OrgSync eine DataSourceId angegeben werden. Ist diese nicht angegeben, wird der OrgSync auf allen Datenbanken ausgeführt. Ohne angegebene DataSourceId ergibt sich der minimale Aufruf ...\primedocs.JobHost.exe OrgSync -i "P:\ath\To\InputFile.xml" mit dem Pfad zur XML-Datei als einzigen zwingenden Parameter.

Parameter

Für den OrgSync stehen die folgenden Aufrufparameter zur Verfügung:

Short	Long	Required	Default	Beschreibung
-i	--InputFile	true	String.Empty	Pfad zur Importdatei
-d	--DataSourceId	false	null	GUID der Zieldatenbank auf dem Server. Wenn weggelassen wird der OrgSync auf allen konfigurierten Datenbanken ausgeführt.
-r	--SyncRoot	false	String.Empty	Root-OE für den Syncprozess (siehe Ermittlung des SyncRoot unten).
-c	--CreateNewRootAsSibling	false	false	Wenn true, wird der Import als Geschwister zum bestehenden Root angelegt. Wenn false, wird der Import als Kind des bestehenden Root angelegt. Kommt nur zum Tragen, wenn der angegebene SyncRoot (-r) nicht existiert, oder kein SyncRoot ermittelt werden kann.
-f	--FallBackOu	false	String.Empty	OE, an welche Profile von gelöschten OEs angehängt werden. Wenn diese nicht angegeben ist, wird die bestehende Root-OE verwendet. Bei mehreren bestehenden Root-OEs in der Datenbank wird die erste gefundene verwendet.

Ermittlung des SyncRoot

Der SyncRoot (-r) bestimmt, unter welchen Knoten der Inhalt aus dem InputFile (-i) synchronisiert wird. Der Inhalt wird in den OE-Baum unterhalb des SyncRoot synchronisiert. Ist der SyncRoot selbst Teil des Imports, wird er ebenfalls synchronisiert. Als Wert kann eine GUID (primedocs-Id der OE) oder der Identifier aus dem Import-File angegeben werden.

Ist kein SyncRoot angegeben, wird anhand des Import-Files versucht, einen zu ermitteln:

• Die Top-Level-OE des Import-Files wird anhand des Identifiers in der Datenbank gesucht.
• Bei mehreren Top-Level-OEs im Import-File wird in der Datenbank nach einer OE gesucht, die mindestens eine der Top-Level-OEs aus dem Import-File als Kind hat.

Kann kein SyncRoot ermittelt werden, wird der Import standardmässig als Kind(er) des bestehenden Root angelegt (bei mehreren bestehenden Root-OEs in der Datenbank wird die erste gefundene verwendet). Mit der Option -c lässt sich stattdessen festlegen, dass der Import als neue Root-OE(s) als Geschwister zum bestehenden Root angelegt wird.

---

Einschränkungen

Der OrgSync hat das Ziel, eine vorgegebene Organisationsstruktur in primedocs zu importieren und synchron zu halten.

Ist bereits im primedocs eine Organisationsstruktur vorhanden, gibt es aktuell keine automatische Möglichkeit diese mit einem Fremdsystem zu synchronisieren.
Ebenfalls gibt es keine Oberfläche, um die Identifier für die Synchronisierung zu setzen oder zu ändern.

hinweis

Bei Fragen wenden Sie sich an unseren Support. Wir helfen Ihnen gern weiter.