Directory Synchronization

Overview

The Directory synchronization module provides an efficient way to synchronize WorkflowGen users and groups with one or more existing enterprise directories.

Here are some important things to know about synchronization:

  • The synchronization process can be manual or automatic.

  • The built-in WORKFLOWGEN directory cannot be synchronized.

  • A user’s username must be unique across all WorkflowGen directories.

  • You can synchronize multiple directories or multiple portions of a directory with different connectors.

  • When a user account is deleted, that user will either be archived or deactivated, depending on the parameters specified. If archived, the username will then be renamed and the account disabled.

Recommendation for per-user license mode

It's recommended that you synchronize a new user account with the New user default status option set to Inactive. These new accounts can later be activated either manually by the Administrator in the user/group lists or automatically by using the self-activation feature.

General usage

Accessing the synchronization settings

Only users with an Administrator profile can access the synchronization module.

To access a directory's synchronization settings, click its name in the Directories list, then scroll down to the Synchronization section.

When creating a new synchronization based on Active Directory, LDAP, or TEXT, the applicable fields listed below will appear based on the selected synchronization method.

Once saved, it's no longer possible to change the directory connector.

Separator

For the text connector, the column separation character in the text file can be a semicolon (;), a comma (,), or a Tab character.

File path

This field makes it possible to specify a path to access the files for the text connector. It takes as a value the path where the files are located, followed by the synchronization name.

The synchronization name is used to name the files.

LDAP path

For Active Directory, an LDAP path is required. Only a single LDAP path is supported per connector.

Data to synchronize

With WorkflowGen, groups and users can be synchronized. User synchronization is required, but group synchronization can be activated or deactivated.

With LDAP synchronization, a group query must be defined even if the group is not set to synchronize.

User synchronization field

In order to perform synchronization, the module uses a field to identify the users, and defines the additions, deletions, or updates. The default field is USERNAME, but you can choose any field from WorkflowGen (e.g. Ads_Path, EMPLOYEENUMBER, etc.) as long as it's processed by the connector.

Group synchronization field

As with users, parameters can be set for the group synchronization field.

User synchronization query

For an LDAP connector, an LDAP query must be specified to query user accounts.

Group synchronization query

For an LDAP connector, an LDAP query must be specified to query groups.

Directory login and password

For Active Directory or LDAP connectors, a login and password may be required to provide access to the directory server.

Deep search mode

For the Active Directory connector, define if the synchronization should include only the container of the targeted OU or include all the subtrees of the targeted OU.

User synchronization field & Group synchronization field

These are set to System identifier by default. If you have an existing WorkflowGen installation that uses an Active Directory connector for synchronization, we recommend switching the user and group synchronization fields to System identifier, since this is a unique identifier for each user and group object in Active Directory.

Prefix username by

To facilitate importing, and in certain cases to avoid double entries concerning usernames, it's possible to prefix usernames with a character string. 📌 Example: Domain\

The username prefix cannot contain the : (colon) character.

Prefix groupname by

To facilitate importing and in certain cases to avoid double entries concerning group names, it's possible to prefix group names with a character string. 📌 Example: Domain\

User synchronization type

There are three synchronization modes: Add only allows new users to be imported, Add and update also allows data for existing users to be updated, and Add, update and delete has an additional function that enables archiving of WorkflowGen users who aren't included in the imported directory.

  • Add only: During synchronization, any user that exists in the directory to be imported but doesn't exist in the WorkflowGen directory will be added to the latter. Data for existing users will not be modified. In order to be added, a user must at least have a user name (USERNAME) and a last name (LASTNAME). If this condition isn't satisfied, an error occurs and the add is cancelled. In case of a defect with one of these values (USERNAME and LASTNAME), an alert (WARNING) is generated.

  • Add and update: This type of synchronization functions the same as the preceding one with regards to additions. It also allows you to update data for users who are already present in the directory and are to be synchronized. In this way, data for a user present in the WorkflowGen directory and in the directory to be imported will be updated.

  • Add, update and delete: You can delete users from a WorkflowGen directory through synchronization. In this mode, the user is deleted when they're present in the WorkflowGen directory but not in the directory to be imported.

Group synchronization type

There are three synchronization modes: Add only allows only new groups to be imported, Add and update allows data for existing groups to be updated, and Add, update and delete has an additional function that enables archiving of WorkflowGen groups that aren't included in the imported directory.

New user default status

This option defines the default status of new user accounts that are created during the synchronization. Set the status to Active if you want a new user account to be activated by default. Set the status to Inactive if you want to manage new user account activation manually, or to enable the user self-activation feature. This is recommended for clients who are using the per-user license mode.

Self-activation

This option allows an inactive new user account to activate itself when the user logs in to WorkflowGen for the first time. The Inactive new user default status option must first be selected in order to use this option.

If a user is deleted

In order to provide proper user tracking in WorkflowGen, when a deletion request is generated, users that have performed actions are not actually deleted; you can either deactivate them or archive them. Once archived, the user will retain their unique internal ID, but their username will be renamed with an archive suffix and sequence number.

Launching mode

Triggering can occur manually (using the Synchronize button) or automatically.

  • Manual: Manual synchronization makes it possible to perform synchronization on an on-demand basis only. To do this, click the Synchronize button on the synchronization file concerned.

  • Test: This mode has the same running mode as manual synchronization, except that in reality, processing isn't performed. Instead, it's only simulated in order to anticipate if synchronization will take place correctly or not. To do this, click the Test button. A synchronization test is logged in the same way as a real synchronization.

  • Automatic: Data synchronization can take place automatically. In this case, a scheduled task analyzes the configuration of all the synchronizations on a daily basis, and subsequently runs the process.

Frequency

If synchronization is performed automatically, you can choose the frequency for synchronization. This can be every day, once a week, or once a month. For automatic synchronization, see the Configuration Panel section for instructions on how to set specific dates and times for the operation.

Active Directory connector

Overview

The purpose of this connector is to import users and groups from Active Directory into a WorkflowGen directory. The connector operates with the LDAP protocol using ADSI (Active Directory Service Interface). Access to Active Directory is read-only.

Requirements

  • Read-only LDAP access to Active Directory is required for an anonymous account or for an account that has access to the Active Directory server.

  • If the Active Directory server is located behind a firewall, the LDAP protocol must be open.

  • You can use the ADSVIEW utility tool provided in the setup package to check that your LDAP path refers to the correct container to retrieve the users and groups of your directory.

LDAP path

The connector needs an LDAP path in order to retrieve the data in Active Directory. This path consists of:

  • The protocol: LDAP://, in this case.

  • The name of the server or its IP address.

  • Optionally, the port separated from the name of the server with : (colon). Default: 389 ✏️ Note: If you’re using LDAP in SSL mode, you must use port 636; otherwise, you can omit the port number, or use the default one.

  • The path in the server's LDAP tree structure.

In order to run the query that is needed to synchronize the users, the Organization (O) and the Organizational Units (OU) must be specified starting from the bottom upwards, preceding them with DC= and separating them with , (comma).

📌 Example

An Active Directory structure is as follows:

  • Top level Domain (DC): thecompany.com

  • Organization unit (OU): group within the domain: BusinessUnit2

  • Sub-unit (OU): sub-group within the domain: IT Department

In order to access users and groups of IT Department, the LDAP path would be:

LDAP://servername:port/OU=IT Department,OU=BusinessUnit2,DC=thecompany,DC=com

The LDAP path doesn't support the . operator, but it does support spaces. Therefore, the .com is identified by the DC=com operator.

  • CN is also supported as a container type.

  • Only one branch of the directory can be associated with a given directory. If multiple OUs at the same level must be queried, then the parent of both OUs must be queried, or two directories created. For example, if the structure /Company/Department1 and /Company/Department2 and /Company/Department3 exists, and only departments 1 and 2 must be queried, then either the entire /Company OU should be specified (all three department OUs will be synchronized), or two separate synchronization directories should be created each with one OU specified.

  • LDAP query filters are not supported.

  • The group query is inherently the same as the user query.

  • Groups and users linked to them must exist within the same LDAP path, otherwise mismatched group/user combinations will be excluded from the synchronization and appear as errors in the synchronization log. This typically occurs when Active Directory groups are defined as CNs within an OU that point to users that are in fact defined in other OUs outside the scope in the LDAP path provided. For example, this situation will arise if the LDAP path is defined to link only to the /Company/Department1 OU, and within this OU the /Company/Department1/Team1 group points to users in /Company/Department2. In this case, it is recommended to either choose an LDAP path that includes all OUs that are involved in the groups, or to use the LDAP connector type instead to create more refined individual user/group queries and filters.

For more information, see LDAP connector.

Data to import

Synchronization is performed for users. However, it is also possible to synchronize groups, and consequently group user memberships. You can import data directly from the OU or the container that is the target path. You can retrieve data from the child containers by activating the Deep search mode.

For users to be synchronized, their sn and sAMAccountName attributes must be set in Active Directory. These map to Last name and Username, respectively.

The Active Directory connector does not take into account the Disabled property of AD user accounts; these accounts will therefore be synchronized as active users. If you don't want the synchronization to include inactive AD accounts, you'll need to use the LDAP connector instead, with the (!(userAccountControl:1.2.840.113556.1.4.803:=2)) filter added to the user synchronization query. As well, make sure to set the desired behavior for the If a user is archived option to either Archive (default) or Deactivate whenever an existing account becomes inactive in AD.

Retrieving Active Directory data

The information is retrieved in Active Directory using the LDAP path. As such, it provides an in-depth access to the data by targeting the OU from which the users and groups are to be retrieved.

The following tables list the mapping between the key-entry fields for a user and the field names with Active Directory. These mappings can't be edited, so if you want to edit them, you'll need to use the directory LDAP connector (see LDAP connector below).

Users

Field

Active Directory default mapping

Username

sAMAccountName

Password

userPassword

Name

sn

First name

givenName

Email

mail

Default time zone

(none)

Manager

manager

Phone

telephoneNumber

Mobile

mobile

Fax

facSimileNumber

Pager

pager

Office

physicalDeliveryOfficeName

Department

department

Company

company

Job title

title

Employee type

employeeType

Initials

initials

Title

personalTitle

Employee number

employeeID

Postal address

postalAddress

Zip code

postalCode

City

l

State/Area

st

Country

co

LDAP path

ADsPath

Display name

distinguishedName

Distinctive name

cn

Extended attribute 1

extensionAttribute1

Extended attribute 2

extensionAttribute2

Extended attribute 3

extensionAttribute3

Extended attribute 4

extensionAttribute4

Extended attribute 5

extensionAttribute5

System identifier

objectSid

Groups

Field

Active Directory default mapping

Name

sAMAccountName

Description

Description

Email

mail

Group code

groupCode

LDAP path

AdsPath

Display name

cn

Distinctive name

DistinguishedName

System identifier

objectSid

LDAP connector

Overview

The purpose of the LDAP connector is to import users and groups from a generic LDAP directory (e.g. AD, Sun ONE, ADAM, etc.) into a WorkflowGen directory. The connector operates with the LDAP protocol and the connection is performed as read-only.

Requirements

Read-only LDAP access is required for an anonymous account or for an account that has access to the LDAP server. If the LDAP server is located behind a firewall, the LDAP protocol must be open.

User and group synchronization queries

The connector needs an LDAP query in order to retrieve the data in the directory. This query consists of:

  • The protocol: LDAP://, in this case.

  • The name of the server or its IP address.

  • Optionally, the port separated from the name of the server with : (colon). The default port is 389.

  • The top level domain.

  • The LDAP query and/or filters.

📌 Examples

An LDAP structure is as follows:

  • Top level Domain (DC): thecompany.com

  • Organization unit (OU): Group within the domain: BusinessUnit2

  • Sub-unit (OU): Sub-group within the domain: IT Department

In order to access users and groups of IT Department, the LDAP queries would be (assuming an Active Directory LDAP structure):

User

LDAP://servername:port/DC=thecompany,DC=com;(&(objectCategory=person)(objectClass=user)(sn=*)(sAMAccountName=*)(memberOf=CN=TheSpecificCN,OU=LowestOU,OU=HigherOU,DC=thecompany,DC=com)(!(userAccountControl:1.2.840.113556.1.4.803:=2)));adsPath,objectSid,sAMAccountName,sn,GivenName,mail,telephoneNumber,mobile,pager,facSimileTelephoneNumber,department,company,EmployeeType,EmployeeId,title,initials,postalAddress,postalCode,physicalDeliveryOfficeName,st,L,co,manager;subtree

Group

LDAP://servername:port/DC=thecompany,DC=com;(&(objectClass=group));adsPath,objectSid,sAMAccountName,Description;subtree

To use a specific CN referencing two groups, the following query filters may be used:

User

LDAP://servername:port/DC=thecompany,DC=com;(&(objectCategory=person)(objectClass=user)(sn=*)(sAMAccountName=*) (memberOf=CN=TheSpecificCN,OU=LowestOU,OU=HigherOU,DC=thecompany,DC=com)(!(userAccountControl:1.2.840.113556.1.4.803:=2)));adsPath,objectSid,sAMAccountName,sn,GivenName,mail,telephoneNumber,mobile,pager,facSimileTelephoneNumber,department,company,EmployeeType,EmployeeId,title,initials,postalAddress,postalCode,physicalDeliveryOfficeName,st,L,co,manager;subtree

Group

LDAP://thecompany/dc=thcompany,dc=com;(&(objectClass=group)(|(sAMaccountName=Group1)(sAMaccountName=Group2)));adsPath,objectSid,sAMAccountName,Description;subtree

  • Only one user and group query can be associated with a given directory. If multiple OUs at the same level must be queried, then the parent of both OUs must be queried, two directories created, or a specific query filter devised that includes both OUs.

    For example, if the structure /Company/Department1 and /Company/Department2 and /Company/Department3 exists, and only departments 1 and 2 must be queried, then either the entire /Company OU should be specified (all the department OUs will be synchronized), or a specific filter must be devised that queries only those two OUs.

  • Groups and users linked to them must exist within the same LDAP path, otherwise mismatched group/user combinations will be excluded from the synchronization, and appear as errors in the synchronization log. This typically occurs when AD groups are defined as CNs within an OU that point to users that are in fact defined in other OUs outside the scope of the LDAP path provided.

    For example, if the LDAP path is defined to link only to the /Company/Department1 OU, and within this OU the /Company/Department1/Team1 group points to users in /Company/Department2, this situation will arise. In this case, it is suggested to choose a user query that includes all OUs that are involved in the groups.

See the Search Filter Syntax Microsoft article for additional samples of generic LDAP queries.

Data to import

Synchronization is performed for users. However, it is also possible to synchronize groups, and consequently, group user memberships.

For users to be synchronized, their sn and sAMAccountName attributes must be set in Active Directory. These map to Last name and Username, respectively.

You can import data directly from the OU or the container that is the target path. You can also retrieve data from the child containers by activating the Deep Search Mode.

Synchronization fields

The default synchronization fields are set as follows:

  • Users: System identifier

  • Groups: name (sn)

Retrieving LDAP data

The following tables list the mapping between the key-entry fields for a user and the field names with LDAP. These mappings can be edited by selecting the Edit mapping button on the directory editing page.

Make sure to save the field mapping whenever you add or modify an LDAP query.

Users

Field

LDAP default mapping

Username

sAMAccountName

Password

(none)

Name

sn

Firstname

givenName

Email

mail

Default time zone

(none)

Manager (must be a valid username)

manager

Phone

telephoneNumber

Mobile

mobile

Fax

facSimileNumber

Pager

pager

Office

physicalDeliveryOfficeName

Department

department

Company

company

Job title

title

Employee type

employeeType

Initials

initials

Title

personalTitle

Employee number

employeeID

Postal address

postalAddress

Zip code

postalCode

city

l

State/Area

st

Country

co

LDAP path

ADsPath

Display name

distinguishedName

Distinctive name

cn

Extended attribute 1

extensionAttribute1

Extended attribute 2

extensionAttribute2

Extended attribute 3

extensionAttribute3

Extended attribute 4

extensionAttribute4

Extended attribute 5

extensionAttribute5

System identifier

objectSid

Groups

Field

LDAP default mapping

Name

sAMAccountName

Description

Description

Email

mail

Group code

groupCode

LDAP path

AdsPath

Display name

cn

Distinctive name

DistinguishedName

System identifier

objectSid

Text connector

Overview

The purpose of the text connector is to import users and groups using text files into a WorkflowGen directory.

Requirements

The text connector requires three different text files:

  • User: One text file that contains the data related to the users to synchronize.

  • Group: One text file that contains the data related to the groups to synchronize.

  • Usergroup: One text file that contains the relationships between the users and the groups according to the selected synchronization fields.

Data to import

Synchronization takes place for the users, but it can also be activated for groups. To do this, check the corresponding box in the synchronization configuration sheet.

Selecting files

Since files to be imported have a standard suffix, use Filepath and key in the path followed by the part that is common to the names of the three files.

📌 Example

If you decide to name your import importWorkflowGen and you have saved it to the DRIVE:\Extract\ directory, you'll need to have the importWorkflowGen_USER.txt file in this directory. If you want to perform group synchronization as well, you'll also need the importWorkflowGen_GROUP.txt and importWorkflowGen_USERGROUP.txt files. When setting the parameters for synchronization, once you've chosen the Text connector, enter DRIVE:\Extract\importWorkflowGen in Filepath.

Text file names

Data import files must have suffixes as described in the following manner:

  • The user file must end with _USER.txt

  • The group file must end with _GROUP.txt

  • The group user member file must end with _USERGROUP.txt

The rest of the file name must be the same for the three files.

Text file structure

Text files begin with a line listing each of the property names separated with a character that is defined as a constant in the connector file. Each line then corresponds to a record, such as a user, with the values also separated by the delimiting character. If a property is empty, it must nevertheless be delimited by the separating character. The default delimiter is ; (semicolon).

The , (comma) separator cannot be used on a server that uses this character as a decimal separator, such as a French server.

The group user member file only has two fields: synchronization fields for groups and for users. These fields are chosen in the directory synchronization module. As well, it's possible to prefix the names of these fields in order to avoid cases where a field name for synchronizing users is the same as that for groups. These parameters are set in the Configuration Panel in the Administration Module when setting the Active Directory synchronization values.

For example, if the user synchronizing field is Username and the field for the groups is name, the file must contain the GROUP_sAMAccountName and USER_sAMAccountName fields.

ADS path

With text files exported from Active Directory, the connector needs the LDAP path in order to allow it to rebuild the ADSPATH property for the users.

List of properties

The following tables list the properties that are needed for synchronizing users, with their equivalents in WorkflowGen. These mappings define the column names in the text file and can be edited by selecting the Edit mapping button in the directory editing page.

Users

Field

Text default mapping

Username

sAMAccountName

Password

(none)

Name

sn

Firstname

givenName

Email

mail

Default time zone

(none)

Manager (must be a valid username)

manager

Phone

telephoneNumber

Mobile

mobile

Fax

facSimileNumber

Pager

pager

Office

physicalDeliveryOfficeName

Department

department

Company

company

Job title

title

Employee type

employeeType

Initials

initials

Title

personalTitle

Employee number

employeeID

Postal address

postalAddress

Zip code

postalCode

City

l

State/Area

st

Country

co

LDAP path

(none)

Display name

(none)

Distinctive name

(none)

Extended attribute 1

(none)

Extended attribute 2

(none)

Extended attribute 3

(none)

Extended attribute 4

(none)

Extended attribute 5

(none)

System identifier

(none)

Groups

Field

Text default mapping

Name

sAMAccountName

Description

Description

User groups

These are the required fields for the group user member file:

  • Synchronization field name for groups (e.g. GROUP_SAMAccountName)

  • Synchronization field name for users (e.g. USER_SAMAccountName)

Active Directory export text file

You can generate an export text file for user data by using the following command:

csvde –f file.csv –s SERVERNAME –d "OU=myOu,DC=mycompany,DC=com" –p subtree –r "(objectClass=OrganizationalPerson)" –l "ADsPath,cn,displayName,givenName,sn,sAMAccountName,mail, telephoneNumber,mobile,pager,facSimileTelephoneNumber,physicalDeliveryOfficeName,department,company, initials,title,employeeID,employeeType,postalAddress,postalCode,l,st,co,personalTitle"

In this case SERVERNAME is the name of the server hosting the directory, file.CSV is the name of the resulting text file, and OU=myOu,DC=mycompany,DC=com is the path to the container in which you want to put the list of users.

To execute this synchronization automatically, this data export process must be added to the task scheduler before the synchronization script is run. To add a task, see the administrator documentation for the Synchronization module. This method does not allow groups to be synchronized.

Examples of text files

User file

sn;givenName;sAMAccountName;mail;
"USER1-01";"Paul Smith";"psmith";"paul.smith@mycompany.com";
"USER1-02";"John Doe";"jdoe";"john.doe@mycompany.com";
"USER1-03";"Jack Ryan";"jryan";"jack.ryan@mycompany.com";
"USER1-04";"Ted Graham";"tgraham";"ted.graham@mycompany.com";

Group file

sAMAccountName;Description
"HR";"GRP1-01"
"IT";"GRP1-02"

User group file

GROUP_sAMAccountName;USER_sAMAccountName
"HR";"psmith"
"HR";"jdoe"
"IT";"jryan"
"IT";"tgraham"

SCIM connector

The SCIM connector lets you define a new directory that will be used by Microsoft Entra ID (formerly Azure Active Directory) to synchronize users and groups. For information on how to configure this, see the Microsoft Entra ID Synchronization section in the WorkflowGen for Azure guide.

Self-provisioning connector

The self-provisioning connector is a directory connector that automatically creates and synchronizes a user based on the user's session token claims that contain claims from the OpenID Connect provider ID token. For instructions on how to configure this, see the Auth0 user provisioning section in the WorkflowGen Technical Guide.

Synchronization logs

Overview

Synchronization logs are set up on the Directory synchronization tab in the Configuration Panel; see Directory synchronization in the Configuration Panel section.

Each synchronization, whether manual or automatic, is logged and available to be viewed by Administrators only, in the Synchronization logs option in the Directories menu.

By default, 31 days of logs are maintained. This parameter can be changed by an Administrator in the Configuration Panel.

Each log provides the details of each synchronization action performed, including listing all users and groups added, modified, or deleted (archived). This also includes warnings (such as a missing email) and errors (such as a missing last name). Log files can be viewed or deleted.

Location of log files

Log files can be found on the WorkflowGen server under the \wfgen application folder at the following location: \wfgen\App_Data\LogFiles\Dir\Synchro.

PreviousDelegationsNextGlobal Information