Skip to main content

Our help center

Synchronize users via SFTP

This article is intended for administrators.

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 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.

☝️ Effects on Elevo features

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.

⚙️ Connecting to the Elevo SFTP server and dropping a file

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

KexAlgorithms diffie-hellman-group-exchange-sha256,curve25519-sha256@libssh.org,diffie-hellman-group16-sha512,diffie-hellman-group18-sha512
Ciphers diffie-hellman-group-exchange-sha256,curve25519-sha256@libssh.org,diffie-hellman-group16-sha512,diffie-hellman-group18-sha512
MACs hmac-sha2-256-etm@openssh.com,hmac-sha2-512-etm@openssh.com,umac-128-etm@openssh.com
HostKeyAlgorithms ssh-ed25519,ssh-ed25519-cert-v01@openssh.com,sk-ssh-ed25519@openssh.com,sk-ssh-ed25519-cert-v01@openssh.com,rsa-sha2-256,rsa-sha2-512,rsa-sha2-256-cert-v01@openssh.com,rsa-sha2-512-cert-v01@openssh.com

 

🧷 File format

You 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  

email

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.
Can only contain alphanumerical characters, as well as ".", "-" and "_"

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

Recommended

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

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.

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

 

➕ Custom additional fields and SFTP

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.

💾 Synchronization

1️⃣ 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.