Directory Synchronization

Overview
The Directory Synchronization module provides an efficient way to synchronize WorkflowGen users and groups with one or more existing enterprise directories.
The following are some key points 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.

In the case of an account deletion, the user will either be archived or deactivated, depending on parameters specified. If archived, the username will then be renamed and the account disabled.
Recommendation for per-user license mode
It is 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 manually by the Administrator in the user/group lists, or automatically by using the self-activation feature.
General usage
Accessing the synchronization module
Only users with an Administrator profile can access the synchronization module.
Description of synchronization parameters
From the WorkflowGen Administration Module, you can list the directory synchronizations, consult synchronization parameters, or add new synchronizations.
When creating a new synchronization that is based on Active Directory, LDAP, or TEXT, the following fields will appear to define the method of synchronization.
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.
User synchronization query
For an LDAP query, an LDAP query must be specified to query user accounts.
Group synchronization query
For an LDAP query, 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 children of the targeted OU.
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.
Users 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 is processed by the connector.
Groups synchronization field
As with users, parameters can be set for the group synchronization field.
Prefix username by
To facilitate importing, and in certain cases to avoid double entries concerning user names, it is 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 to avoid, in certain cases, double entries concerning group names, it is possible to prefix the 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 modify also allows data for existing users to be updated, and Add, modify and delete has an additional function that enables archiving of WorkflowGen users who are not included in the Imported Directory.
Add only: During synchronization, any user that exists in the directory to be imported but does not 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 is not 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 modify: 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, modify and delete: You can delete users from a WorkflowGen directory through synchronization. In this mode, the user is deleted when they are 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 modify allows data for existing groups to be updated, and Add, modify and delete has an additional function that enables archiving of WorkflowGen groups that are not 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 a 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 logging into WorkflowGen for the first time. The ‘Inactive’ new user default status option must 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 processing is, in reality, not performed. Instead, it is 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 the 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:
1
LDAP://servername:port/OU=IT Department,OU=BusinessUnit2,DC=thecompany,DC=com
Copied!
The LDAP path does not 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.
Synchronization fields
User synchronization field and Group synchronization field 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 it is a unique identifier for each user and group object in Active Directory.
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
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
1
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
Copied!
Group
1
LDAP://servername:port/DC=thecompany,DC=com;(&(objectClass=group));adsPath,objectSid,sAMAccountName,Description;subtree
Copied!
To use a specific CN referencing two groups, the following query filters may be used:
User
1
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
Copied!
Group
1
LDAP://thecompany/dc=thcompany,dc=com;(&(objectClass=group)(|(sAMaccountName=Group1)(sAMaccountName=Group2)));adsPath,objectSid,sAMAccountName,Description;subtree
Copied!
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.
References
See the following web pages for additional samples of generic LDAP queries:
​http:/www.petri.co.il/ldap_search_samples_for_windows_2003_and_exchange.htm​
​http://msdn2.microsoft.com/en-us/library/aa746475.aspx​
​http://technet.microsoft.com/en-us/library/aa996205.aspx​
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
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 will need to have the importWorkflowGen_USER.txt file in this directory. If you want to perform group synchronization as well, you also need the importWorkflowGen_GROUP.txt and importWorkflowGen_USERGROUP.txt files. When setting the parameters for synchronization, once you have 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 is 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
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:
1
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"
Copied!
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
1
sn;givenName;sAMAccountName;mail;
2
"USER1-01";"Paul Smith";"psmith";"[email protected]";
3
"USER1-02";"John Doe";"jdoe";"[email protected]";
4
"USER1-03";"Jack Ryan";"jryan";"[email protected]";
5
"USER1-04";"Ted Graham";"tgraham";"[email protected]";
Copied!
Group file
1
sAMAccountName;Description
2
"HR";"GRP1-01"
3
"IT";"GRP1-02"
Copied!
User group file
1
GROUP_sAMAccountName;USER_sAMAccountName
2
"HR";"psmith"
3
"HR";"jdoe"
4
"IT";"jryan"
5
"IT";"tgraham"
Copied!
SCIM connector
The SCIM connector lets you define a new directory that will be used by Azure Active Directory to synchronize users and groups. For information on how to configure this, see the Azure Active Directory 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.
Delegations
Global Information
Last modified 1yr ago