Group Synchronization

Group synchronization (GroupSync) reconciles the directory groups of a datasource with the directory. Directory groups are groups from Active Directory, Entra ID or SCIM that have been onboarded in primedocs. Afterwards, the name of a group follows the directory, and its sync status shows whether the directory still knows it. Groups that are no longer found can optionally be deleted automatically, in the same stages as the offboarding of users. primedocs app groups are never affected.

Group synchronization is independent of user synchronization: it has its own switch, its own time of the last run and its own configuration (GroupSyncConfig). The UserSyncConfig has no effect on groups.

Prerequisites

• A directory connector is configured for the datasource (Active Directory, Microsoft Graph / Entra ID or SCIM), see Identity provider. Without a connector, group synchronization is skipped.
• The datasource is not operated without application permissions. In that mode primedocs does not query Microsoft Graph, group synchronization is skipped, and groups are neither marked nor deleted.
• The JobHost runs regularly, for example as a scheduled task, see Configure background jobs. Group synchronization only runs in the JobHost.

Enabling

Group synchronization is switched off by default. It is switched on with the GroupSyncActivated setting. If the setting is missing, it stays off, even when user synchronization is active. It is switched on in one of these places:

• Web Admin: under Integrations › User data › Group synchronization, turn on the Enabled switch in the Sync pipeline card and save.
• Admin API: PUT .../Admin/Settings/GroupSync with activated and the existing configuration in xml, because a missing xml removes the configuration, see Admin API.

After a complete run, primedocs stores the time in GroupSyncLastRun. The Web Admin shows it as the last run.

Configuration

The configuration is stored in the XML of the GroupSyncConfig setting. In the Web Admin it is edited visually or as XML in the Group-sync XML card. Without a configuration the defaults apply, and groups that are no longer found are only marked as «Error» but never deleted.

<GroupSyncConfig batchSize="10" syncTimeoutInSeconds="60">
  <AutomaticGroupDeletion mode="enabledWithoutAutomaticDeletion">
    <StatusChangesAfterUnavailabilityDuration>
      <SetToPendingDeletion days="30" />
      <SetToFlaggedForDeletion days="60" />
    </StatusChangesAfterUnavailabilityDuration>
  </AutomaticGroupDeletion>
</GroupSyncConfig>

Attribute / element	Default	Description
batchSize	10	Number of groups the job processes in one batch. 1 to 100 are allowed, other values fall back to the default.
syncTimeoutInSeconds	60	Time after which a group stuck in the «Syncing» status is set to «Sync timeout» and reconciled again. 10 to 3600 are allowed, other values fall back to the default.
AutomaticGroupDeletion	—	Automatic deletion of groups that are no longer found. Without this element nothing is deleted.
mode	disabled	disabled: no automatic deletion. enabledWithoutAutomaticDeletion: groups are only marked. enabled: groups are marked and then deleted.
SetToPendingDeletion days	30	Days without being found in the directory until the «Pending deletion» status
SetToFlaggedForDeletion days	60	Days without being found in the directory until the «Flagged for deletion» status

Days below 1 fall back to the defaults of 30 and 60. Only the three names listed are valid for mode. The Web Admin and the Admin API do not save a configuration with invalid XML or an unknown mode. If an unreadable configuration is present nevertheless, the job uses the defaults for batch size and timeout, and the automatic deletion stays off. The job writes a warning to the log.

Process

A run reconciles all directory groups that are not excluded from the sync. Unlike user synchronization, there is no interval.

1. The job checks whether the directory connector is reachable. If it is not, the job writes nothing and the run counts as failed. The SCIM connector has no such check.
2. Groups that have been in the «Syncing» status for longer than syncTimeoutInSeconds are set to «Sync timeout» and reconciled again in the same run.
3. The groups are reconciled in batches of batchSize, the ones not synchronized for the longest time first. For each group the job queries the connector by its SID, without the principal cache.
4. Once all groups are reconciled, the job stores GroupSyncLastRun and starts the automatic group deletion.

If another process changes the same groups at the same time, the run stops. It then counts as incomplete: GroupSyncLastRun stays unchanged, and no deletion follows. The JobHost repeats the run, see JobHost.

Result per group

Case	Sync result	Effect
Group found in the directory	OK	The name from the directory is taken over, the time of the last successful sync is updated. A pending automatic deletion is cancelled.
Not found, or the SID does not belong to a group in the directory	Error	The name and the time of the last successful sync are kept. Only such groups are covered by the automatic deletion.
Query failed, for example because of a connection or permission error or ambiguous matches	Warning	Name, time and deletion status stay unchanged. The reason is in the sync report. The automatic deletion does not cover the group.
Well-known system SID (Everyone, Authenticated Users) or the internal SID for anonymous Connect	—	The group is set to «Excluded from sync» without a query and is never deleted.

After the first run, the name from the directory is authoritative. The next run overwrites a rename made in primedocs. Groups that received a placeholder SID during a directory switch are also excluded from the sync.

Sync status and report

The state of each group is shown in:

• Web Admin: the Sync status column with a filter in the group list. For «Error» a tooltip states when the group was last found, and while a deletion is under way «Pending deletion» and «Flagged for deletion» appear. The detail page of a directory group shows sync status, sync result, last sync, last successful sync, the status of the automatic deletion and the sync report in the Synchronization section. If a group is flagged for deletion and its last result is «Error», a warning appears.
• Admin API: the fields syncStatus, syncResult, syncTimeUtc, syncLastSucceededOnUtc and syncAutomaticDeletionStatus on the UserGroups, and additionally syncReport in the detail view.

The sync report has the same JSON format as in user synchronization and contains one entry with the source PrincipalConnector.Group. As long as a group has no completed reconciliation, the Admin API returns no sync result (null).

Automatic group deletion

The automatic group deletion works in the same stages as the automatic user deletion. It counts from the last successful sync of the group or, if it never had one, from its creation in primedocs:

1. After SetToPendingDeletion days without being found, the group gets the «Pending deletion» status (PendingDeletion).
2. After SetToFlaggedForDeletion days, it gets the «Flagged for deletion» status (FlaggedForDeletion).
3. In enabled mode, a flagged group is deleted in a later run. In enabledWithoutAutomaticDeletion mode, it stays flagged.

Deletion works like a manual delete: the group is removed from primedocs together with its permissions, roles and memberships. It remains in the directory and can be onboarded again. The removed permissions and roles then have to be granted again.

Safeguards

• The deletion only runs directly after a fully completed group synchronization run. If the directory connector was not reachable, the run stopped or group synchronization is switched off, nothing is marked or deleted.
• Only groups whose last completed reconciliation had the result «Error» are covered. Groups with «Warning», groups excluded from the sync, never synchronized and currently syncing groups are never affected, and neither are app groups. A group that is already flagged is not deleted if the last reconciliation only resulted in a warning.
• A group is only deleted in a run after it was flagged. The «Flagged for deletion» status is therefore visible for at least one run.
• If a group is found again, group synchronization resets its deletion status.

Directory switch

When switching directories, for example from Active Directory to Entra ID, the groups get new SIDs. Without migrating the SIDs first, the connector no longer finds the groups, they get the result «Error» and, with deletion active, are deleted together with their permissions once the periods have elapsed. Before the switch, therefore run the directory switch in the Web Admin or set the mode to enabledWithoutAutomaticDeletion.

tip

Run a new configuration with enabledWithoutAutomaticDeletion first and check the flagged groups before switching to enabled. The visual editor in the Web Admin starts with this mode when the cleanup is switched on.

JobHost

A JobHost run without parameters executes group synchronization directly after user synchronization. To run it on its own, use the GroupSync verb:

...\primedocs.JobHost.exe GroupSync

Short	Long	Required	Default	Description
-d	--DataSourceId	false	null	GUID of the target database on the server. If omitted, GroupSync is executed on all configured databases.

If the directory connector is not reachable or the run stops, the JobHost repeats it according to its retry configuration. If the last attempt fails as well, the JobHost ends with exit code 1, and further datasources are not reconciled in this run. primedocs.JobHost.exe help GroupSync shows the parameters.