This article explains how to import users into SMARTFENSE using a CSV file to create new users or bulk edit existing users. It details the file structure, the creation and update logic, case sensitivity handling, and optional fields.
The configuration is available under Users and Groups > Import and Synchronization > Manually from CSV File.
CSV File Structure
To get the example file:
- Go to Users and Groups > Import and Synchronization.
- Select Manually from CSV File.
- Click Save.
- Click the Download Example CSV button.
For bulk editing of existing users, you can also download the list from Users and Groups > Users. The structure is the same.
Example Row
user1,firstName1,lastName1,email1@domain.com,"group-A;group-B","functionalArea-A;functionalArea-B","hierarchyLevel-A;hierarchyLevel-B",Active,Administrator,en-us,Employee-ID,phone,UPN
Mandatory and Optional Columns
| Column | Mandatory | Notes |
|---|---|---|
| Username | No | If not specified, it is generated from the email. |
| First Name | Yes | Normalized with an initial capital letter. |
| Last Name | Yes | Normalized with an initial capital letter. |
| Yes | Without an email, the user cannot be imported. Always stored in lowercase. | |
| Groups | No | Multiple values separated by ; within the same field. |
| Functional Areas | No | Multiple values separated by ;. |
| Hierarchy Levels | No | Multiple values separated by ;. |
| Status | No | Accepts values in any supported language. If omitted, created as Active. |
| Role | No | If omitted, created as End User. |
| Language | No | If omitted, created with es-ar. |
| Employee ID | No | Optional. |
| Phone | No | Optional. |
| UPN | No | Optional. Preserves exact uppercase and lowercase letters. |
| Manager’s Email | No | Optional. |
Never remove mandatory columns from the CSV: the platform will not be able to interpret it correctly.
The system supports CSV files with only the 10 base columns. The columns Employee ID, Phone, UPN, and Manager’s Email are optional.
When a User Is Created or Edited
The platform follows this sequence to decide whether to create or update a record.
1. Search by Email
If the CSV email matches an existing user, that user is updated. Special case for username: if the CSV username differs from the existing one, the platform checks if it is available. If available, it updates it. If not, it shows a warning (highlighted in yellow).
2. Search by Username
If there is no match by email, it searches by username. If it matches, the user is updated. Special case for email: if it differs, the platform checks availability before updating it.
3. No Match
If there is no match by email or username, a new user is created.
Case Sensitivity Usage
Usernames
Uppercase letters are not considered when determining if a user exists, but they are preserved when creating a new user.
Groups
In groups, functional areas, and hierarchy levels, case sensitivity is distinguished. If an exact match is not found, a second search ignoring case is attempted.
Manually Created Groups
Groups that exist only because they were manually created in SMARTFENSE are not modified during import.
Example: if a user is assigned Group M (created manually) and Group A (imported previously), and the CSV only has Group C, the result will be Group M (retained) and Group C (added).
Status Behavior in the CSV
The Status field accepts values in any supported language. For example, Active in English is equivalent to Activo in Spanish. The comparison is case-insensitive. The same applies to Inactivo / Inactive values.
Empty Fields
| Field | Behavior if Left Empty |
|---|---|
| Language | Uses the language of the importing administrator or retains the existing user's current language. |
| Username | Generated from the first part of the email (before the @). |
| Without an email, the user cannot be imported. | |
| Status | Created as Active or the existing user retains the current status. |
| Role | Created as End User or the existing user retains the current role. |
| Phone, Employee ID, UPN | Remain empty. |
💡 Best Practices
- Always download the example CSV before creating your file to ensure the correct format.
- Verify emails and usernames before import to minimize warnings.
- Keep all mandatory columns, even if some values are empty.
- Maintain consistent group names to avoid duplicates due to case differences.
- Use Status values in any supported language and verify they are interpreted correctly.