BPS user list synchronization

Applies to version 2017.1.x; Author: Jacek Język


The BPS user list in the System settings is where the system stores all information about users.
The AD cache was replaced with the BPS user list, but the AD and AAD are still the preferred methods for managing user data. The BPS users list will now combine users synchronized from the AD or AAD with those from external authentication providers, into one universal cache of all users of the system. The BPS user list serves as the base for granting privileges to view and access the system. The BPS user list also contains data of the company structure.


The BPS Users list combines user and group information from separate sources: Active Directory, SharePoint and External Users. Its status has to be constantly updated to provide users with uninterrupted access. This is why a correct configuration of this system element and monitoring the synchronization are critical system tasks.



Access to the BPS Users list synchronization configuration is possible through WEBCON BPS Designer Studio in the following section: System settings -> Global Parameters -> BPS users list.

This tab allows to browse and search for currently synchronized users. It can verify if a specific user was synchronized and is available in the system.


Clicking on „Synchronization configuration” button allows defining the parameters of BPS users list synchronization.


Designating synchronized AD domains

„Settings” tab is used to choose a domain or a specific Organizational Unit from which user/group/organization structure data will be downloaded. It is possible to choose a couple of domains or OU’s which will be synchronized. Domain and OU list are available by clicking on “+” button.


The configuration of synchronized domains/OU’s is done also in the WEBCON BPS installer during system update from older versions to 2017.1. However in this case synchronization is not done by the installer, but by WEBCON WorkFlow Service in time set in the schedule after correct installation.

Users can work with the system (i.e. data access) as soon as the first successful synchronization is complete.


Data synchronization from Active Directory is carried out in the context of the user that is defined in the “Credentials” tab. So in the context of this user, the list of domain/OU’s possible to synchronization is loaded.


Available on the list by default, is a domain to which a server with WEBCON WorkFlow Service installed belongs. Also available are all domains from the same domain forest. If there are configured trust relationships with another domain/forest, then those also trusted domains/forests are also visible on the list.

An OU structure is displayed within the domains, which allows to narrow down the synchronization to a chosen entity.


During the synchronization, data is downloaded from selected OU’s. However if downloaded objects have a relation to the object from outside the synchronized entity (i.e. users’ superior belongs to other, not synchronized domain), then despite the lack of this domain in configuration, necessary data considering this object (i.e. superior’s) will be downloaded. Downloading data from outside the synchronized entities is a subject to additional conditions (i.e. proper privileges) – more details of the synchronization can be found in the further part of this article.

The range of data downloaded from the Active Directory during synchronization is included in Appendix A. However it is possible to download additional data about the synchronized item from AD and save it in the BPS database. 30 additional properties that were read from the AD are available to download, and their values will be saved on selected database columns.

Pointing to additional data for synchronization is not necessary.


Part of the users’ information can be independently stored both in Active Directory and SharePoint user profile. This information is:


  Attribute name in AD Attribute name in SP
E-mail address mail E-Mail
Displayed name displayname Name
Department department Department
Job title title Job Title


Synchronization configuration allows pointing from which data source (Active Directory or SharePoint) data will be downloaded. Checking the option “SharePoint user profile data overrides Active Directory data (email, display name, position)” downloads the data saved in SharePoint profile. Leaving it non-checked downloads the data from Active Directory.


Connection data setup

BPS user list synchronization with Active Directory is carried out by WEBCON WorkFlow Service in the context of the user defined in the synchronization configuration in “Credentials” tab. The user used in synchronization has to have appropriate privileges, that allows him to read data from specific domain/OU configurations.

Minimal privileges needed to execute a correct synchronization:

  • read account restrictions
  • read general information
  • read public information


The default user in the context of whom the synchronization is executed is the user on whom the WEBCON WorkFlow Service works.


Synchronization schedule

The schedule allows defining hours of synchronization execution. In order to ensure that WEBCON BPS has current data, synchronization should be carried out a couple of times a day.

Default configuration carries out the synchronization every 3 hours. In most cases, this configuration is enough to bring up to date even frequently changing data. The synchronization mechanism is additionally integrated with user management actions (“Active Directory” action groups and “SharePoint – privileges”). If such an action is executed, the system will start synchronization for users edited outside the schedule and an instantly update the BPS user list.

Synchronization schedule can be tailored to the specific needs of individual system implementations. When changing synchronization hours it is important to remember about: frequency of data changes by the AD and SharePoint or maintenance of the system (it requires to halt the synchronization in specified timeframe).


Synchronization schedule configuration is also available from the service configuration menu in “System settings”.


Synchronization types and diagnostic options

Synchronization can be carried out in two ways, as Incremental synchronization or Full synchronization.

The default mode is Incremental synchronization. While it is carried out, the user and group data are updated in a differential way which means only the data that changed since the last synchronization. Status of added/removed objects is also refreshed.

In Full synchronization, all the data is refreshed regardless if it was changed since the last synchronization or not.

For purely performance reasons, it is recommended to use Incremental synchronization in the vast majority of cases.

Full synchronization should be used only in certain cases, especially when Incremental synchronization doesn’t refresh the elements correctly. This can be indicated by wrong range of data displayed on the user form and reports, lack of user on BPS user list or errors of incremental synchronization.


BPS user list synchronization can be started manually. Clicking on “Incremental synchronization” or “Full synchronization” will initiate the synchronization accordingly to the current configuration. It is important to save the configuration before the manual start of the synchronization.

Options “Incremental synchronization – Debug” and “Full synchronization – Debug” allow starting synchronization with an expanded data logging. DEBUG mode allows for an accurate analysis of all synchronization steps and should only be used for diagnostic reasons.


Monitoring the synchronization

In order to ensure the uninterrupted work for WEBCON BPS users, synchronization has to be constantly monitored and all the abnormalities corrected.

Events which might occur during the synchronization are divided into two categories: errors and warnings. This division comes from the influence of a specific event on the work of the system.


Examples of events labeled as errors:

  • No access to the synchronized domain/OU
  • It is not possible to download users’ ID (login, User Principal Name) or group (SID).


Examples of events labeled as warnings:

  • It is not possible to download a part of user/group data
  • It is not possible to download superior’s data coming from an unsynchronized domain
  • It is not possible to download group data coming from an unsynchronized domain


Full information about the synchronization along with errors and warnings is saved in the synchronization log. It is accessible from WEBCON BPS Studio level or system Event Log.


In case of events qualified as errors, the information can be sent to a specified e-mail address as administrative notification. To configure such notification for users list synchronization choose “Users list synchronization” in the notification range.


Synchronization description

Rules of the synchronization will be described based on a handful of BPS and Active Directory configuration scenarios.


Full domain synchronization

A whole AD domain from which the data has to be synchronized is selected in BPS configuration.


This Active Directory exemplary structure has users as well as superiors and groups to which these users belong.

The user in the context of whom the synchronization is being carried out (tab „Credentials”) has proper privileges allowing to read data from AD.


During synchronization data of all the users, domain groups and users affiliations to groups will be downloaded. A superior-employee relationship will also be downloaded.

If any subordinate OUs exist, data from them will also be downloaded.

All the changes (adding/removing a group, user, affiliations) will be saved in the BPS database and have their reflection in BPS users list.


Synchronization of a chosen OU

In BPS configuration a specific OU was pointed from which the data is to be synchronized (Active Directory consists of a couple of Organizational Units).


Example of Active Directory’s structure in OU New York consists of employees, but their superior is a part of OU London. OU London contains also other user and group objects.

The user in the context of whom the synchronization is executed („Credentials” tab) has privileges allowing to read data both from OU New York and OU London.


During the synchronization data of all the users and groups of OU New York will be downloaded (User1, User2, User3 and Employees). For users whose superior belongs to OU London, regardless of the fact that synchronization is executed for OU New York, the superior’s data will be also downloaded. This also means that his data (the Manager), groups that he belongs to (Management) and his relationships with his superiors will be loaded.

Other users and groups from OU London will not be downloaded (UserA, UserB, UserC, and Users).

If there are subordinate OU’s in OU London, then this data will be downloaded as well.

All the changes (adding/removing a group, user, affiliations) will be saved in the BPS database and have their reflection in BPS users list.


Synchronization of specified OU without access to unsynchronized OU

In BPS configuration a specific OU was selected from which the data is going to be synchronized. (Active Directory contains a couple of OU’s).


This sample Active Directory structure in OU New York consists of employees, but their superior is a part of OU London. OU London contains also other user and group objects.

The user in the context of whom the synchronization is executed („Credentials” tab) has privileges allowing to read data from OU New York but doesn’t have access to OU London.


During the synchronization data of all the users and groups of the OU New York will be downloaded (User1, User2, User3, and Employees). For users whose superior belongs to OU London, the superior’s data will attempt to be read. However, the lack of privileges to this data will cause the reading to fail. In the synchronization log, a warning will appear informing about the lack of ability to read data for this “Manager” user.

If there are subordinate OU’s in OU London, then this data will be downloaded as well.

All the changes (adding/removing a group, user, affiliations) will be saved in the BPS database and will have their reflection in BPS users list.


Data synchronization with SharePoint

BPS user list synchronization is carried out through a few connected steps. Apart from data synchronization from Active Directory, one of the synchronization steps is SharePoint data synchronization.

Downloading group and SharePoint user data start with searching in SharePoint farm for all the Web Applications with active BPS feature. Next all the users, group users, and groups are downloaded for all SharePoint sites of this Web Applications.

Data from both sources (AD and SharePoint) is merged (i.e. additional information about user’s affiliation to SharePoint groups) and then saved in WEBCON BPS database. The diagram below shows the steps of the synchronization process.


Deleting users/groups marked as „not entirely updated”

The minimum range of data allowing to identify a specific user, is their login and UPN. For groups it is the SID. If those identifiers are read from Active Directory then the synchronized object is saved in BPS database. If the identifiers are not read, the information about user/group will not be saved in BPS database which means it won’t be available in BPS users list as well.

Identifiers themselves are not enough for correct system operation, especially when it comes to the functionalities based on privileges, group affiliation or organizing structure. This is why in case the full information about user/group was not downloaded, this object is marked as “not fully updated” with corresponding information in the synchronization log.


The administrator’s duty is identifying the reason for it (i.e. lack of specific read privileges) and fixing the configuration if needed, to ensure a full update. In some case,s it might be needed to use Full synchronization instead of Incremental synchronization.

If data marked as „not fully updated” is not fixed in 24 hours, then in the next synchronization after this time passes, the data will be completely removed fromthe database and the user’s work in the system will not be possible.


Appendix A – Range of data downloaded from AD during synchronization

Target database column

AD form field name

Mandatory attributes(*)

[COS_IsActive] useraccountcontrol (ADS_UF_ACCOUNTDISABLE)
[COS_AD_accountexpires] accountexpires
[COS_AD_countrycode] countrycode
[COS_AD_iscriticalsystemobject] iscriticalsystemobject
[COS_AD_localeid] localeid
[COS_AD_objectguid] objectguid
[COS_AD_objectsid] objectsid


[COS_AD_objectversion] objectversion
[COS_AD_primarygroupid] primarygroupid
[COS_AD_samaccounttype] samaccounttype


[COS_AD_securityidentifier] securityidentifier
[COS_AD_useraccountcontrol] useraccountcontrol
[COS_AD_whenchanged] whenchanged
[COS_AD_whencreated] whencreated
[COS_AD_company] company
[COS_AD_comment] comment
[COS_AD_department] department
[COS_AD_description] description
[COS_AD_displayname] displayname
[COS_AD_distinguishedname] distinguishedname


[COS_AD_givenname] givenname
[COS_AD_homedirectory] homedirectory
[COS_AD_homephone] homephone
[COS_AD_info] info
[COS_AD_ipphone] ipphone
[COS_AD_mail] mail
[COS_AD_manager] manager
[COS_AD_memberOf] memberOf
[COS_AD_mobile] mobile
[COS_AD_name] name
[COS_AD_objectcategory] objectcategory
[COS_AD_objectclass] objectclass
[COS_AD_ou] ou
[COS_AD_pager] pager
[COS_AD_postalcode] postalcode
[COS_AD_postofficebox] postofficebox
[COS_AD_samaccountname] samaccountname
[COS_AD_showinaddressbook] showinaddressbook
[COS_AD_sn] sn
[COS_AD_st] st
[COS_AD_streetaddress] streetaddress
[COS_AD_telephonenumber] telephonenumber
[COS_AD_title] title
[COS_AD_userparameters] userparameters
[COS_AD_userprincipalname] userprincipalname


[COS_AD_wwwhomepage] wwwhomepage
[COS_AD_physicalDeliveryOfficeName] physicalDeliveryOfficeName
[COS_AD_cn] cn
[COS_AD_proxyaddresses] proxyaddresses


(*) – mandatory attributes mean the minimal range of data downloaded during synchronization. The lack of access to them results in skipping the object (user or group) during synchronization. This object will not visible in the BPS users list.

2 thoughts to “BPS user list synchronization”

  1. Dzień dobry

    Czy można jakoś usprawnić proces synchronizacji uprawnień użytkownika pomiędzy AD a WEBCON ?
    Ewentualnie czy można „wymusić” ręcznie taką synchronizację jakimś poleceniem lub skryptem ?–

    Dziękuję i pozdrawiam

    1. Dzień dobry,
      Guzik “Synchronize now” inicjuje synchronizację poza wyznaczonym harmonogramem.

Leave a Reply

Your email address will not be published. Required fields are marked *