Directory Synchronization
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
WORKFLOWGENdirectory 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.
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.
Only users with an Administrator profile can access the synchronization module.
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.
For the text connector, the column separation character in the text file can be a semicolon (
;), a comma (,), or a Tab character.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.
For Active Directory, an LDAP path is required. Only a single LDAP path is supported per connector.
For an LDAP query, an LDAP query must be specified to query user accounts.
For an LDAP query, an LDAP query must be specified to query groups.
For Active Directory or LDAP connectors, a login and password may be required to provide access to the directory server.
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.
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.
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.As with users, parameters can be set for the group synchronization field.
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.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\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 (USERNAMEandLASTNAME), 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.
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.
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.
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.
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.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.
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.
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.
- 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.
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).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 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/Department1and/Company/Department2and/Company/Department3exists, and only departments 1 and 2 must be queried, then either the entire/CompanyOU 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/Department1OU, and within this OU the/Company/Department1/Team1group 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 theLDAPconnector type instead to create more refined individual user/group queries and filters.
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.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.
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).
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 |
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 |
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.
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.
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 is389. - The top level domain.
- The LDAP query and/or filters.
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):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
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:
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
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/Department1and/Company/Department2and/Company/Department3exists, and only departments 1 and 2 must be queried, then either the entire/CompanyOU 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/Department1OU, and within this OU the/Company/Department1/Team1group 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 following web pages for additional samples of generic LDAP queries:
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.
The default synchronization fields are set as follows:
- Users: System identifier
- Groups: name (
sn)
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.
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 |
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 |
The purpose of the text connector is to import users and groups using text files into a WorkflowGen directory.
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.
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.
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.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.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 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.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.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.
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) |
Field | Text default mapping |
Name | sAMAccountName |
Description | Description |
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)
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.
sn;givenName;sAMAccountName;mail;
"USER1-01";"Paul Smith";"psmith";"[email protected]";
"USER1-02";"John Doe";"jdoe";"[email protected]";
"USER1-03";"Jack Ryan";"jryan";"[email protected]";
"USER1-04";"Ted Graham";"tgraham";"[email protected]";
sAMAccountName;Description
"HR";"GRP1-01"
"IT";"GRP1-02"
GROUP_sAMAccountName;USER_sAMAccountName
"HR";"psmith"
"HR";"jdoe"
"IT";"jryan"
"IT";"tgraham"
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.
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 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.
Log files can be found on the WorkflowGen server under the
\wfgen application folder at the following location: \wfgen\App_Data\LogFiles\Dir\Synchro.Last modified 27d ago