Organization synchronization

Overview

In most installations, organizational units are maintained directly in primedocs. OrgSync is the optional alternative: it reconciles the organizational units with an external system and is worthwhile when that system owns the organizational structure and it changes regularly.

As organizational units are organized hierarchically, a 1:1 comparison as with users is not possible. An XML file is, therefore, used as the synchronization source, which must be filled in with the data from the external system.

The following data can be synchronized to primedocs:

• Title of the organizational unit
• Fields to be set for the organizational unit
• Permissions of the organizational unit
• Organizational unit hierarchy

The organizational unit is identified via a unique characteristic in primedocs, i.e., the external system specifies a "key/technical characteristic" and this characteristic is saved in primedocs when the organizational units are imported.

The generated file must then be imported into the primedocs Datasource via the JobHost, e.g. as a time-controlled task.

---

XML structure

The following XML structure is required:

<primedocsOrgSync>
  <OrganizationUnits>
    <OrganizationUnit>
      <!-- "Technical feature" - Must be unique and is our "identification feature" for the sync -->
      <Identifier></Identifier>
      <!-- Title of the OU -->
      <Title></Title>
      <!-- Fields that will be synced to primedocs -->
      <Fields>
        <!-- 
          Id="Org.Street": refers to a field definition (FieldId) in primedocs 
	      Value="Sample Street 123": Is the actual value that is saved for this organizational unit for this field.
        -->
        <Field Id="Org.Street" Value="Sample Street 123" />
        <!--
          The exact LCID is required for multilingualism. Without it, it is saved in the default language 
          Only specific LCIDs are permitted, i.e. "LCID 9" for "English" is not permitted, but must point exactly to "en-US" or "en-GB".
	      See: 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" />
        <!-- empty values are also supported -->
        <Field Id="Org.POBox" Value="" />       
      </Fields>
      <Permissions>
        <!-- 
          primedocs needs the SID and the type (user or group) and stores this information in the database.
	      To load this information, we do a "lookup" 

          The syntax allows us to search for SID, sAMAccountName or UPN in the Active Directory, for example
          The value searched for must correspond to exactly one object in the directory.
          Valid fields are based on the Principal Connector:
          in the Active Directory: objectSid, sAMAccountName, but theoretically also other AD fields etc.
          in Microsoft Entra ID: without LookupKey the object ID ("id"), otherwise one of the properties from the section "LookupKey with Microsoft Entra ID"
	    -->
        <SecurityAccount LookupValue="local\username" LookupKey="sAMAccountName" />
        <SecurityAccount LookupValue="jane.doe@contoso.com" LookupKey="userPrincipalName" />
      </Permissions>
      <OrganizationUnits>
        <!-- "Sub-OU", same schema -->
        <OrganizationUnit></OrganizationUnit>
      </OrganizationUnits>
    </OrganizationUnit>
  </OrganizationUnits>
</primedocsOrgSync>

---

Permission synchronization

Permissions, specified in this file are overwritten with the organizational unit found in the primedocs Datasource, i.e. all desired Permissions must be present in primedocsOrgSync. Manually set permissions are overwritten.

If the datasource is operated without application permissions, no account from the import can be resolved. The OrgSync then skips the permission synchronization and leaves the existing permissions unchanged. Titles, fields and hierarchy are still synchronized.

LookupKey with Microsoft Entra ID

With Microsoft Entra ID as the principal connector, LookupKey defines which property of the user or group primedocs uses to look up the LookupValue in Microsoft Graph. Without LookupKey, and with id or objectId (alias), primedocs loads the object directly by its object ID. Any other property is searched with a filter and must match exactly one object. A user is looked up first, a group only if no user matches.

LookupKey	Applies to	Note
empty, id, objectId	users and groups	Object ID from the Entra admin center. Default and always unique.
onPremisesSecurityIdentifier	users and groups	SID of the object synchronised from the on-premises Active Directory. This allows the objectSid values of an Active Directory configuration to be kept.
onPremisesSamAccountName	users and groups	sAMAccountName of the synchronised object.
mail, mailNickname, displayName	users and groups	Not necessarily unique within a tenant.
userPrincipalName	users only	Sign-in name (UPN).
employeeId	users only	Not necessarily unique.
onPremisesImmutableId, onPremisesDistinguishedName	users only	Values of the synchronised object.
onPremisesExtensionAttribute1 to onPremisesExtensionAttribute15	users only	Extension attributes from the on-premises Active Directory (extensionAttribute1 to extensionAttribute15).
extension_{appId}_{name}	users only	Directory extension of an application.
uniqueName	groups only	Unique name of the group.

Multi-valued properties such as proxyAddresses or otherMails and properties Microsoft Graph cannot filter (for example companyName or mobilePhone) are not allowed. objectSid is not a valid LookupKey in Entra ID, use onPremisesSecurityIdentifier for SIDs.

In the following cases the permission is not applied, and the JobHost log contains a warning of the Microsoft Graph connector:

• The LookupValue matches more than one object, for example two users with the same displayName. A group with the same value is not considered then.
• Microsoft Graph rejects the property because it does not exist for the object type or cannot be filtered. This also applies to user-only properties when no user matches and a group is therefore looked up.
• The LookupKey is not a valid property name. primedocs then does not call Microsoft Graph at all.

Set LookupKey to a unique property wherever possible, that is id, onPremisesSecurityIdentifier or userPrincipalName.

---

Field synchronization

Fields on the other hand, are merged with the existing fields in the organizational unit, i.e. unspecified fields are not emptied but left as they are.

No fields can be deleted via primedocsOrgSync either, in order for the inheritance mechanism of primedocs to take effect. This must be done manually.

---

Synchronization behaviour

All organizational units that exist below the SyncRoot but are not included in the import are deleted.

Profiles that are attached to the deleted organizational units are moved to the FallBackOu.

Organizational units that are outside the SyncRoot in the database but are specified as a child of the SyncRoot in the import are moved according to the import.

---

JobHost

As with UserSync, a DataSourceId can be specified for OrgSync. If this is not specified, OrgSync is executed on all databases. If no DataSourceId is specified, the minimum call is ...\primedocs.JobHost.exe OrgSync -i "P:\ath\To\InputFile.xml" with the path to the XML file as the only mandatory parameter.

Parameters

The following call parameters are available for OrgSync:

Short	Long	Required	Default	Description
-i	--InputFile	true	String.Empty	Path to import file
-d	--DataSourceId	false	null	GUID of the target database on the server. If omitted, the OrgSync is executed on all configured databases.
-r	--SyncRoot	false	String.Empty	Root OU for the sync process (see Determining the SyncRoot below).
-c	--CreateNewRootAsSibling	false	false	If true, the import is created as a sibling to the existing root. If false, the import is created as a child of the existing root. Only applies if the specified SyncRoot (-r) does not exist or no SyncRoot can be determined.
-f	--FallBackOu	false	String.Empty	OU to which profiles of deleted OUs are attached. If this is not specified, the existing root OU is used. If there are several existing root OUs in the database, the first one found is used.

Determining the SyncRoot

The SyncRoot (-r) determines the node below which the content from the InputFile (-i) is synchronized. The content is synchronized into the OU tree below the SyncRoot. If the SyncRoot itself is part of the import, it is synchronized as well. The value can be a GUID (primedocs-Id of the OU) or the identifier from the import file.

If no SyncRoot is specified, an attempt is made to determine one from the import file:

• The top-level OU of the import file is searched for using the identifier in the database.
• If there are several top-level OUs in the import file, the database is searched for an OU that has at least one of the top-level OUs from the import file as a child.

If no SyncRoot can be determined, the import is created by default as a child / as children of the existing root (if there are several existing root OUs in the database, the first one found is used). The -c option can instead be used to create the import as new root OU(s) as a sibling to the existing root.

---

Limitations

The purpose of OrgSync is to import a predefined organizational structure into primedocs and keep it synchronized.

If an organizational structure already exists in primedocs, there is currently no automatic way to synchronize it with an external system.
There is also no interface for setting or changing the Identifiers for synchronization.

note

If you have any questions, please contact our support team. We are happy to help you.