‘Domain users’ type data source

Applies to version 2016.1.x; Author: Damian Matuła

Every business process has a number of so-called “participants”:

  • Authors (aka. originators, e.g. an employee registering a business trip)
  • Approvers (e.g. superiors in a vacation process, accountants in an expense report workflow)
  • All other assignees, delegates and decision makers involved in a process directly or indirectly (e.g. employees who co-authored company policies and procedures)

WEBCON BPS offers a few methods for creating fields that store information about users:

  • Choice field, whose data source is a cached Active Directory (AD) table, or an external data source
  • Person or group form field
  • Choice field, whose data source is made up of domain users (directly from the AD)



In an article written quite some time ago – AD cache basics – we mentioned mapping Active Directory fields to the CacheOrganizationStructure table that is used by WEBCON BPS.

In this article, I will discuss a different way of obtaining data from the AD. This method should be easily applicable, even by those who do not use SQL.


Here are the main differences between a data source based on a CacheOrganizationStructure and one based on the AD:


Active Directory

Loading data Cyclically, at preset hours, the WEBCON BPS service will synchronize with the AD and save the data (update it) in the

CacheOrganizationStructure table of the database.

Dynamically, by executing the function which returns data according to the provided parameters.
Performance High, since it only reads data from a SQL table. Medium-low, the function for loading data must be executed every time the data source is needed. Noticeably slower.
Volume of data The number of columns is low compared to the number of fields in the AD. Contains the most commonly used types of data. To synchronize data from a field which has no column assigned to it by default, map the desired field to one of 30 available extra columns, i.e. COS_ExtensionAttribute [1-30] Data is loaded dynamically, therefore no data is stored in the database.


1 . Creating a data source from the AD

To create a data source containing users from the AD, go to the “Data sources” tab of WEBCON BPS Designer Studio. Find the “Domain users” group on the list and select it. To add a new data source of the selected type, either click the “New” button on the toolbar or use the CTRL+N keyboard shortcut. For this example, I will name the data source “Employees”


Fig. 1 – Configuration of the “Domain users” data source


2. Configuration

User story

I wish to build a process for project managers, where each PM will be able to choose assignees from amongst their subordinates and themselves. This will limit the number of displayed results in the Choice field and prevent mistakes.


To achieve the above goals, we can either use one of the pre-existing queries or create our own (Fig. 2). A guide on how to query the AD with LDAP can be found further down the article in chapter 4.


Fig. 2 – This section allows you to filter the rows returned by the query

To fit my scenario, I will use the “Current user – all subordinates (include user)” option.


Column section

To select which columns we want returned, mark the corresponding checkboxes.

It is possible to add columns with values from AD fields, to do this click the ‘+’ icon.



Fill out the name of the AD field we want mapped, descriptions are optional (Fig, 3).


Fig. 3 –  Selecting which columns will be returned by the query


In the sample configuration above, I added two additional fields: title (position/job type) and employeeid (used for storing ID’s from external ERP systems).

The additional columns will make it easier to find employees for task assignment.

In the configuration, I also selected columns which are not used in this sample workflow (e.g. department, description .etc.), even though I don’t have much use for them now, they might come in handy when using this data source for other processes.

Additional information on how to configure this type of data source can be found in the WEBCON BPS Designer Studio help manual (F1).


Certain AD fields that can be used when configuring this type of data source have been listed in chapter 5.


3. Use case

Once configured, such a “Domain users” data source can be employed in places like:

  • SharePoint picker choice field (with search box)
  • Choice field with autocomplete/suggestions function

For performance reasons, we do not recommend using a “Domain users” data source as a dictionary for a “Dropdown list” type choice field – displaying all rows of the AD on a single continuous list can be a bad idea.


Fig. 4 – Three different behavior modes for a choice field. When using “Domain users” as the choice field’s source, we recommend either “Popup (SharePoint picker)” or “Autocomplete” modes.


For this process to work as intended, I will add 3 additional text fields (Fig. 5 & 6):

Mail (containing an e-mail address)

ERP ID (employee’s ID in the ERP system)

Occupation (title or job description)

Additionally, I will create the aforementioned SharePoint Picker choice field named “Employee” which will use the “Employees” data source created earlier (Fig. 7).


Fig. 5 – Configuring a text field



Fig. 6 – Three new text fields on the form field tree



Fig. 7  –  Configuring a choice field


In the ”Advanced configuration” options of the “Employee” choice field, it is necessary to define a column containing a unique identifier of a user, as well as one containing their display name which will be displayed on the form.

As the unique identifier, we can use the employee’s domain login or ERP number (e.g. when a process is integrated with an external system, where it is identified only by the aforementioned number – a situation commonly found in vacation processes).


Fig. 8 – Advanced configuration of the “Employee” choice field. The “Mail”, “ERP ID” and “Occupation” fields have been configured to be automatically filled with data from the AD when an employee is selected from the picker.


Map values (Fig. 8) from the AD (”Source column”) to their corresponding form fields (“Target field”), this will ensure that values from the AD are automatically loaded into the form (Fig. 10).

The “Searching” configuration column is used to specify which of the AD columns will be searched for matches with the entered phrase in the SharePoint Picker (Fig. 9)

11Fig. 9 – The SharePoint Picker that pops up for the “Employee” choice field.



Fig. 10 – After choosing an employee from the picker, fields on the form are filled out automatically with data from the AD.


4. Extra part I – Filtering with LDAP queries

Filtering can be used if it is necessary to narrow down the returned data.

Query type should be set to “Custom”


Query construction:

Simple query ‘=’


e.g. (title=Manager)

Alternative ‘|’

(|(Argument1= Value1) (Argument2= Value2))

e.g. (|(title=Manager)(Division=Management))

Conjunction ‘&’
(&(Argument1= Value1) (Argument2= Value2))

e.g. (&(title=Manager)(Division=Management))

Negation ‘!’

(!Argument= Value)

e.g. (!title=Manager)

Wildcard (any value)  ‘*’

(Argument=*)  All non-empty values

(Argument=ab*) All values starting with ‘ab’

e.g. (&(l=*sk)(streetaddress=*)) will return all rows with cities that end with ‘sk’ and the full address.

Greater/lesser than ‘<’ ,’>’,’>=’,’<=’


e.g. (logoncount>50)  will return user accounts that were logged in more than 50 times.

Further information about LDAP basics on technet.microsoft.


5. Extra part II – List of AD fields

A list of sample fields found in the Active Directory.

Not all of the listed fields are obligatory, which means some of them might be left empty.


AD Field Description
Displayname Display name
Sn Last name/Surname
Name Full Name formatted as:

‘First name Last name’

Givenname Frist name
Company Organization/Business entity
Countrycode Country code
Title Position/occupation
Department Department/division
Info Info about AD account
Homedirectory User’s home directory path
Lastlogon Last log-in date
Lastlogontimestamp Last noted activity
Logoncount Number of registered log-ins
Whenchanged Last modification date
Whencreated Creation date
Comment Comment
Login Full login formatted as: DOMAIN\login
Description AD account description
samaccounttype* Account type
Mail E-mail
Mobile Mobile number
Homephone Home-phone number
Pager Pager
physicalDeliveryOfficeName Office address
Postalcode Postal code
Localeid Region code, e.g. country, city etc.
St Organization unit (state/county)
Streetaddress Street address number
Postofficebox P.O. box
telephonenumber Phone number
Wwwhomepage WWW homepage
Employeetype Type of work
employeeID Employee’s ID
l Location (e.g. city)

*COS_AD_samaccounttype – This field is useful for separating user accounts from other resources.

To return only records that are user accounts only, include: (Samaccounttype=805306368)

Leave a Reply

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