Synchronize users via SFTP
This article is intended for administrators.
- ☝️ Effects on Elevo features
- ⚙️ Connecting to the Elevo SFTP server and dropping a file
- 💪🏼 Supported algorithms
- 🧷 File format
- ➕ Custom additional fields and SFTP
- 💾 Synchronization
This automatic synchronization method is the most universal because it can be adapted to any user-based system.
Elevo can provide single, secure access for your company to the Elevo SFTP where you can upload export files in an automated manner. Elevo will automatically synchronize users without any intervention from you.
💡 Note: Most HRIS offers an automatic and regular export function of your user database with the file deposited on a secure remote server (SFTP). Ask your service provider for more information.
To set up this synchronization, contact our support@elevo.io with the following information:
- a technical contact,
- the name of your solution from which users will be synchronized,
- the IP address or a range of IP addresses you will use to connect to our gateway,
- an SSH public key (Minimum RSA size : 3072) that you will use to connect.
Elevo support will then provide you with:
- your login for our SFTP server,
- our public GPG key to cipher the files before upload (optional),
- confirmation that Elevo is ready to process files for synchronization.
Automatically synchronizing user changes some of Elevo's behavior and functionality:
- It is no longer possible to modify the attributes of synchronized users from Elevo,
- Users added to your HRIS will automatically be added to Elevo,
- Users deleted from your HRIS will be automatically suspended on Elevo.
The protocol used is SFTP (SSH File Transfer Protocol). Sessions must be established by you, whether it involves sending or receiving data. You will have a dedicated account, secured by an SSH key that you will have provided us. Elevo verifies that the login request originates from the company using an identification/authentication mechanism, which is performed using the encryption key. Additionally, a network whitelisting of the company outbound IPs is necessary.
The connection details to the SFTP server (domain name, port and username) will be provided by support@elevo.io. Once the connection is established, the files must be uploaded to the "/uploads/users" folder.
💪🏼 Supported algorithms
🧷 File formatYou will find on these links the file templates to complete: Excel, Google Sheet and CSV.
Constraints
- Respect the CSV format RFC 4180,
- The CSV standard defined via RFC 4180 explicitly forbids ending a row with a comma, otherwise it is interpreted as the existence of an additional column (section 2.4),
- Be encoded in UTF-8 format,
- The first row should define the column headers,
- Must contain all mandatory columns,
- May not contain optional columns,
- Unrecognized columns will be ignored,
- The columns can be in any order.
Name of the file
The file name does not affect processing. Elevo will process all incoming files that are dropped into the correct folder on the SFTP server.
Unique identifier for users
To make the matching of users between the CSV file and the users in the Elevo space more reliable, the file requires a uniq_identifier column. This column is mandatory.
For this column:
- constant: this field must remain constant from one synchronization to the next,
- strict uniqueness: each user must have a different value,
- value: can be the internal user ID used by the system providing the data, for example.
💡 Note : this uniq_identifier is a string and not a numeric field, meaning that values 1 and 001 are considered different values.
Columns in the CSV file
|
Column header |
Mandatory / Optional |
Restrictions |
Detail |
|
uniq_identifier |
Mandatory |
Must be unique across all users |
Unique identifier for a user |
|
|
Mandatory if the username is not filled |
Must be a valid and unique email among users |
User's email Info: The value is converted to lower case |
|
username |
Mandatory if the email is not filled |
Must be unique across all users. |
User’s username can be used by the user to login if they don’t have any email defined. It can also be used in case your SSO nameid is different from the email address. |
|
first_name |
Mandatory |
Character strings |
User's first name Info: The value is converted to Proper Case (Each word starts with a capital letter) |
|
last_name |
Mandatory |
Character strings |
User's last name Info: The value is converted to Proper Case (Each word starts with a capital letter) |
|
manager_uniq_identifier |
Mandatory, can be empty |
Must match another user's uniq_identifier |
Unique identifier for the user's manager |
|
manager_email |
Optional |
Must be a valid email or empty if no manager |
The manager's email This value is not used during synchronization, but it can be useful to debug synchronization Info: The value is converted to lower case |
|
registration_number |
Optional |
Character strings |
Identification number or number plate |
|
job_title |
Optional |
Character strings |
Name of the position |
|
work_start_date |
Optional |
In ISO 8601 format (ex: 2015-02-25) |
Date of hire |
|
team_name |
Optional |
Character strings |
User's team name |
|
department |
Optional |
Character strings |
The department |
|
region |
Optional |
Character strings |
The region, city, or office |
|
gender |
Optional |
Gender codes (f, F, female, Female, m, M, male, Male, other, Other) |
Gender of the user |
|
service |
Optional |
Character strings |
Name of the department, Business Unit, |
|
level |
Optional |
Character strings |
Employee level (executive, non-executive, Level 12, Coeff 3.3, etc...) |
|
locale |
Optional |
Language ISO code (en, fr, es, nl, de, it) |
Language of the employee on Elevo platform. If it is not sent, it will use your platform default language. |
|
working_time_ratio |
Optional |
0 ≤ Integer ≤ 100 (Integer less than or equal to 100, and greater than or equal to 0) |
Working time ratio (for example, 50 corresponds to 50%, i.e. half-time) |
|
use_sso |
Optional |
Boolean (empty field or "false" are the only authorized values) |
This will allow you to determine if a user should login via SSO or not. This column is useful only if the SSO is configured on your platform. If you want the user to login via SSO, leave the column empty. |
|
skip |
Optional |
Boolean |
If the value is set to "True", "Yes", "Oui" then the line in question will be completely excluded from the synchronization |
Elevo allows additional fields to be added to user profiles (find out more). These fields are fully compatible and synchronizable with SFTP.
To do so, you need to add a column to the dedicated file. The exact heading of the column (header) will be sent to you by our Support team when the field is created, as it depends on the heading you define.
💾 Synchronization1️⃣ Removal of ignored lines
If the skip column is set, then all rows for which skip is set to TRUE are removed.
2️⃣ User Uniqueness Validation
A first validation is done only on the uniq_identifier column. If this column contains duplicate values, the synchronization is canceled, and an error report is sent.
3️⃣ Reconciliation of file and user data Elevo
Elevo uses the uniqueness column from step 1 of the CSV file to compare it with the users on Elevo.
- Users present on Elevo but not present in the CSV file will be disabled on Elevo,
- Users in the CSV file but not on Elevo will be created on Elevo at the synchronization stage.
4️⃣ Synchronization
Synchronization is done line by line.
If a line is not valid (invalid data), this line will be ignored, and the synchronization will continue on the following lines. The user in question will be marked as "synchronization error" and no changes will be made for this user.
In case of an error, an error report is sent by email to the address provided.