Overview

Organizational units can be created manually or automatically in primedocs. Organizational units can be synchronized with an external system via OrgSync.

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 data source 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.
          LookupKey must be set, otherwise the OrgSync will not find the target user. Valid fields are based on the Principal Connector:
          i.e. in the Action Directory: objectSid, sAMAccountName, but theoretically also other AD fields etc.
               in the Azure Active Directory: "id" - currently no other fields possible
	    -->
        <SecurityAccount LookupValue="local\username" LookupKey="sAMAccountName" />
      </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 data source, i.e. all desired Permissions must be present in primedocsOrgSync. Manually set permissions are overwritten.

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

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. The content from the InputFile (`-i`) is synchronized in the OU tree below the `SyncRoot`. If the `SyncRoot` itself is part of the import, it is also synchronized. 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 a `SyncRoot` using the import file: The top-level OU of the import file is searched for using the identifier in the DB. If there are several top-level OUs in the import file, the DB 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 be used to set the import to be created as a new root OU(s) as a sibling to the existing root.
-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.

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.

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

primedocs: technical documentation

Organization synchronization