Skip to main content

Articles in this section

See more
Print

Text file | Update AD Users rule

  • Updated

Text file | Update AD Users rule

Rule description

This rule queries a text file data source in a comma-separated variable format (CSV) and updates user accounts according to the Action section settings. You can also update user virtual attributes. For more details, see the Virtual Attributes article.

NOTE: The CSV file should be in the UTF-8 format if you are using diacritics or accents (e.g., á, ä, é, í, ö, ü, etc.)

When to use this rule

Use this rule when you need to perform a bulk AD user account update using an HR/ERP/SIS system export. This rule requires a source text file in the comma-separated variable format (CSV). You can use the template CSV file provided with the rule or create a file in Microsoft Excel and export it as CSV.

Refer to the steps to use a template CSV file:

  1. In the Query section, click the ... button next to the Select data source setting.

  2. In the Templates folder, select the Update AD Users − Template CSV file and click Open.

The Query's source text file requires the following CSV (comma-separated value) format:

FirstName,LastName,Description,EmailAddress
Joe,Smith,test user,joe@domain.com
Kelly,Jones,test user,kelly@domain.com

Rule settings

Query section

Setting name Description

Select data source

Specify the text file to be imported.

The […] (three dots) button allows the user to browse for the file and the Create/Edit button allows the creation or editing of the existing file in the built-in Data Source editor.

Limit scope to this domain or OU

This setting defines the search query scope. To improve query performance, limit the scope to a specific OU.

IMPORTANT: To test the rule configuration, limit the rule scope to an OU that contains test accounts or objects and use the Preview feature.

Data source anchor attribute

Define a column in the data source used to identify and map the user account. The value is compared to the Active Directory anchor attribute.

User names are likely to have duplicates; it is recommended to use another unique attribute to identify and map a user.
CSV file delimiter Specify a character to separate data values in the CSV file.

Active Directory anchor attribute

Define an AD attribute to compare the data source anchor attribute to.

NOTE: If the Active Directory attribute you would like to use is missing, you can enter the LDAP name of the attribute in the field. The attribute must be flagged as searchable (https://msdn.microsoft.com/en-us/library/ms679765(v=vs.85).aspx) within Active Directory. To determine if the attribute is flagged as searchable, you can use ADSI Edit to view the Schema Objects container and examine the attribute searchFlags property.

Maximum number of users Specify the maximum number of users to modify in the selected scope.

More options

Filter CSV data

This setting specifies the filter that can remove data rows from the imported text file that satisfies the specific condition.

Properties to display

Define object properties to display in the output file.

Filter

Set the filtering conditions to hide unwanted data based on criteria not supported in the Query criteria setting.

Example: filter by the found object Distinguished Name.

TIP: For optimal performance, use the Query criteria setting above to filter objects whenever possible.

Empty field in data source

Define the behavior in case of an empty value in the CSV file column:

  • Ignore

  • Clear property value

TIP: Use the Clear property value setting with the Replace action in Operation for multi-valued attributes to clear the attribute values.

Action section

Setting name Description
Update method

Specify the method to update AD user properties:

  • Always update.

  • Only update empty values.

  • Only update on value difference.
Simplified output

When set to 'Yes', the output shows user attribute values as they were queried.

When set to 'No', values are requested and verified after the update to display true end values in the output. This affects rule performance for large datasets. 
Account

FirstName (GivenName)

Define the FirstName data column in the data source. If the data source contains a field named FirstName, ignore this setting. Otherwise, use the selector. 

Initials

Define the Initials data column in the data source. If the data source contains a field named Initials, ignore this setting. Otherwise, use the selector. 

Last/Surname (sn)

Define the LastName data column in the data source. If the data source contains a field named LastName, you can ignore this setting. Otherwise, use the Selector button to choose a field from the Data Source. 

Display name

Define the displayName format. The default format uses the cn value. You can use predefined options, use the expression builder to select a field from the data source, or contact Cayosoft for support.

Description

Define the description data column in the data source. If the data source contains a field name Description, you can ignore this setting. Otherwise, manually enter a static text value or use the selector button to choose a field from the data source. 

Settings

Default password

Define a password for accounts:

  • Static text

  • A custom data column in the CSV file

  • A random password

NOTE: Static passwords and passwords from the data source must meet the Active Directory Password complexity policy of the target container; alternatively, the account is created in a disabled state. Randomly generated passwords are generated to match both the Active Directory password complexity policy and additional complexity requirements defined in the Cayosoft Administrator password complexity policy.

  • Must change password at next logon

  • Account enabled

  • User cannot change password

  • Password never expires

Define the settings to control default Active Directory user object settings. Select one of the available options:

  • Skip (to keep the original value)

  • True

  • False

Account expiration date

Define the account expiration attribute for Active Directory. You can populate this field using a data source column or a static text string entered manually in the MM/DD/YYYY or YYYY-MM-DD format.

Organization

  • Office

  • Job title (Title)

  • Department

  • Company

  • Employee number

  • EmployeeID

  • Division

Define the values for the default organization attributes in Active Directory or skip the attribute. Otherwise, manually enter a static text value or use the selector button to choose a field from the data source.

Manager identifier

Use the selector button to choose a field from the data source that is a unique identifier for the manager. Typically, the identifier used is the EmployeeNumber or EmployeeID value.

AD attribute for manager lookup

Define an Active Directory attribute used to link the manager and the Manager identifier value.

Contact info

Country

If the Data Source contains a field name Country, ignore this setting. Otherwise, manually enter a static text value or use the Selector button to choose a field from the Data Source.

The country/region should be represented as a 2-character code based on ISO-3166.

For example, to set Germany use code DE.

  • Country

  • Office phone (telephoneNumber)

  • Mobile phone (mobile)

  • Street address

  • City (l)

  • State

  • Postal code

Define the values for the default contact info attributes in Active Directory. If the data source contains the field names, you can ignore this setting. Otherwise, manually enter a static text value or use the selector button to choose a field from the data source.

IMPORTANT: The country/region should be represented by a 2-character code based on ISO-3166. For example, use code DE to define Germany.

Multi-valued attributes

Multi-valued attribute support

Enable or disable the support for multi-valued attributes in AD users.
Multi-valued attribute delimiter Define a character to separate multiple data values in the CSV file.
List of multi-valued attributes

Define a list of multi-valued attributes using the selector.

IMPORTANT: Link source data attributes to matched attributes in Other properties to assign multiple values to corresponding attributes. Otherwise, the values won't be assigned.
Operation for multi-valued attributes

Define the action when you update multi-valued attributes from a CSV file:

  • Add. Collect values from the CSV file, compare them to the existing attribute values, and add new values to the attribute.

  • Replace. Collect values from the CSV file and replace the existing attribute values with the CSV file values.

  • Remove. Collect values from the CSV file, compare them to the existing attribute values and remove the values from the attribute. Keep non-matching values only.

NOTE: The logic extends to the Empty field in data source setting; when you set the setting value to Clear, only the Replace action is affected. The existing values in a multi-valued attribute are replaced with the CSV file values (i.e., empty value).

Other properties

Other properties

Map data source columns and target user properties using the picker.

Other properties script

Data mapping also can be set by the script.

If you want every provisioned user to have extension attribute 1 populated with some string value then use this

Copy
:{@{'extensionAttribute1'='YourString'}}

If you want every provisioned user to have extension attribute 2 populated with the corresponding value from the column in your data source file, then use this:

Copy
{@{'extensionAttribute2'=$_.EXT2}}

since EXT2 is the name of the column from your data source.

NOTE: If you set mapping for the same properties both in Other properties and Other properties script, attribute values will be updated by the script.

Output section

This section defines the output format of this rule.

To get more information about this section, please see the Rule Output section article.

Enforce/Schedule section

This section defines the schedule for how often to run the rule.

To get more information about this section, please see the Rule Enforce/Schedule section article.

Change history

Version Notes
13.1 The Multi-valued attributes section has been added.

© Copyright 2013-2026 Cayosoft Inc. All rights reserved.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Return to top

Related articles

Comments

0 comments

Please sign in to leave a comment.