Employees can be imported via a CSV file that gets uploaded via SFTP to the Honestly server. Based on the CSV file, new employees will be added, not existing employees will be removed and the information of already existing employees will be updated. This option is available to Enterprise or Global Player Customers.
To automatically synchronize your shared data with Honestly, you must first activate the SFTP integration.
This can be found at the top right under the "Menu" tab:
You then click on "Connect" in the box showing "CSV Employee Import".
After you have clicked on "Connect", another window opens which shows the most important information.
Here you will find the information "SFTP username" and "SFTP hostname", which are required on your side to establish the connection. You can also enter your SSH key here and then click on connect.
Once the connection has been established, the data can be transferred and stored in the upload folder. Directory: `~/upload/`
Data is automatically imported at 03:00 and 15:00.
The mechanism can also be triggered manually by clicking on import.
Please note: Depending on the size of the file, this process may take a few hours.
If the transfer was successful, you will also receive information on when this import was successfully completed.
If any errors occurred, you can click on the word "errors" to find out what they were:
Caution: If the import was not successful, all admins will receive an email with the employees or errors contained in the file.
Honestly Server
Hostname: "datafeed.honestly.com"
Directory: "~/upload/"
Authentication
Authentication works via passwordless authentication (ssh key authentication). That way, the related public key can be shared with Honestly over an unsecured channel like email.
The public key should be in ssh-rsa format.
In SAP SuccessFactors the integration module can be used to send the file. Follow this guide to generate the authentication key.
A rsa public key needs to be shared with Honestly to the email address import@honestly.com.
A username will be provided by Honestly that can then be used in combination with the private key of the public key to push the CSV file to the Honestly server.
CSV file
The file name needs to be "employees.csv".
The file needs to be encoded with UTF-8 character set without any BOM.
The data in the file itself needs to be separated by the comma character and surrounded by double-quotes.
The column names need to be included in the CSV file in the first line. The order of the column names is irrelevant. Column headers are case-sensitive.
Required columns
The following columns need to be present in the CSV file and also all dataset must contain values for them.
| Column Name |
Format
|
Description |
|---|---|---|
| ImportId | String | The unique identifier of an employee will be used to identify employees that have left the company. Furthermore, the identifier will match existing employee data with the data in the file even when the email address has changed. |
|
|
String | The E-Mail Address of the employee. |
| Firstname | String | The first name of the employee. |
| Lastname | String | The surname of the employee. |
The ImportId of an employee cannot be adjusted over the Upload file.
Optional language
It's recommended to also provide the language of the employee. If the language can not be provided, we can configure a default language.
| Language | ISO 639-1 | The primary language of the employee that will be used to select the questions and notification language of the employee. See here for more details. |
Optional additional employee groups
Based on the configuration of employee groups in the web application, additional employee data can be included to receive more detailed insights. Therefore, the CSV file needs to be extended with these additional columns in String data format.
On the web application, the user can select which employee data should actually show up as a filter on the dashboard.
Optional role & permission related columns
Employees have access to results based on their "reports to" relationship in addition to the permission on specific employee groups. ReportsToId or PermissionGroup and PermissionGroupValue can be blank.
| Column Name |
Format
|
Description |
|---|---|---|
| Role | String |
Value needs to be based on the table "Available roles". If no role is assigned (blank field) the employee will only be able to take part in surveys but will not be able to e.g. login to see results or create surveys. |
| ReportsToId | String | Contains the ID (ImportId) of the employee that this employee reports to. |
| PermissionGroup | String | Contains the name of the column header which drives the employee's permission. e.g. Country. |
| PermissionGroupValue | String |
Contains the specific employee group the user has access to e.g. Germany use `*` to give access to all users |
Possible roles
|
Name
|
Description
|
|---|---|
| Admin | Can do everything and has access to all account data, including all dashboards. Permission groups are not taken care of. |
| Manager | Can manage surveys & dashboards associated with the user groups specified in the permission groups and hierarchy. |
| Analyst | Has read-only access to specific dashboards associated with the user groups specified in the permission groups and hierarchy. |
| Report viewer | Has read-only access to specific dashboards associated with the user groups specified in the permission groups and hierarchy. Can not export any data. |
Example file with a department and location employee group
File name: employees.csv
Content:
|
"ImportId","Email","Firstname","Lastname","Language","Department","Location","ReportsToId","Role","PermissionGroup","PermissionGroupValue"
"1","john@norealmail.com","John","Smith","en","IT","Germany","","Admin","",""
"2","anna@norealmail.com","Anna","Peters","de","Sales","Switzerland","","Analyst","",""
"3","lucas@norealmail.com","Lucas","Jansen","nl","Customer Success","Germany","1","Manager","Location","Germany"
"4","afrodita@norealmail.com","Afrodita","Shehu","sq","Finance","UK","","Manager","Location","Germany"
"5","harun@norealmail.com","Harun","Divjak","bs","Marketing","UK","4","Manager","Location","UK"
|
Import mechanism
This file is imported twice a day (around 2-4 am and 2-4 pm). After a successful import, the import file is removed from the folder.
Warning: If you choose the automatic upload, any changes made manually will be overwritten every 12 hours.
If there is no file, no changes will be made.
- Employees which are already in the system will be updated.
-
- Employees cannot be created more than once in an account and will only be updated if they appear several times in a file.
- Employees which are not in the system will be created
- Employees which are not in the file and have an ImportId set by a previous upload will be deleted.
General Import Errors
-
Import cancelled because of errors while loading employees data from integration
-
Employee with email EMAIL already exists with import id IMPORT_ID, and cannot be imported with id NEW_IMPORT_ID.
-
Cannot create employee: EMAIL
This covers errors while creating an employee that are not covered by the “Employee with email … already exists” error -
Cannot update employee: EMAIL
This covers system errors while trying to update an employee -
Import: skip employee because email already exists EMAIL
-
Import cancelled:
There are 'COUNT_CURRENT_EMPLOYEES' employees in your account, and the update was going to delete 'COUNT_DELETE_EMPLOYEES' employees.
To prevent accidental deletion of too much data import is cancelled if it would delete more than MAX_ALLOWED_DELETED_PERCENTAGE 20% of employees.
In your account this means 'MAX_ALLOWED_DELETED_ABSOLUTE_COUNT' employees.
CSV Errors
-
Row number ROW_NUMBER in csv file is missing ImportId. Import is cancelled to prevent data corruption.
-
Cannot read employee from csv file row number ROW_NUMBER. Ignoring bad employee record ImportId: IMPORT_ID
-
Import file has bad/empty header
-
Bad CSV
-
No entries in file
-
CSV header is missing mandatory field: MANDATORY_FIELD
Integration Info:
Once the integration has been set up, employee data will be automatically imported every day at 03:15 and 15:15 respectively.