A Secure File Transfer Protocol (SFTP) integration is a great way to sync your employee data from your HRIS system to AllVoices. AllVoices supports a secure, one-way connection that imports data files from HRIS tools that support SFTP.
Basic Requirements
1. Create a file with user information in .csv (standard UTF-8 encoding) according to the file format requirements below
2. Schedule regular file exports to our SFTP server (we recommend daily, after work hours)
General CSV file format requirements
- All values must be either comma-separated or semicolon-separated (other characters are not supported)
- All values must be double-quoted (")
- In case a double-quote character appears as a value, it must be escaped with another double-quote
- The file must be UTF-8 encoded
- The first row in the CSV file must be a header row
Business-specific data format requirements
The below columns marked *Required must always appear in the CSV file and must contain answer values. The fields marked as *Optional are suggested fields and do not require answer values. If you would like to include any of the optional fields use the headers exactly as named below (the headers are case sensitive).
- EmployeeID: a unique identifier that clearly and uniquely identifies a person. This ID must never change for a given person, regardless of their current occupation, department, current name etc., nor should it ever be re-used for a different person. We will use this value to keep track of the same employee over time. (*Required)
- Name: A person's full name, starting with the birth name, following with any middle names, and ending with surnames (*Required)
- Email: A person's email address (*Required)
- Phone: A person’s phone number (*Optional)
- Location: Location at which the person works (*Optional)
- Department: The current department to which the person belongs (ie. "Human Resources", "Engineering", "Design" etc.) (*Optional)
- Occupation: A person’s current occupation (ie. “Project manager”, “developer” etc.) (*Optional)
- ManagerID: The unique identifier (EmployeeID) of this person’s manager (*Optional)
Include only active employees in the CSV file.
The CSV file may also contain other additional custom columns. We will assign this extra information to that person and it will be visible on the employee profile view and at the report/case level. These additional CSV column headers will be used on the employee profile view to describe the value - preferably the header names are spelled out, so instead of using costcenter, prefer Cost Center etc.
FAQS
Setting up your SFTP Integration
SSH Key Pairs
To set up an SFTP integration, you'll need to create an SSH Key Pair. This is to ensure that the SFTP connection via your client/HRIS is unique and secure.
An SSH key pair is a pair of unique keys that are generated by you and saved on your computer. There's a private key which should only be used by you (or very carefully within your own organization), and there's a public key which can safely be shared outside your organization. The integration uses the combination of the two keys to verify the security of the connection.
Step 1: Check command line tools
First, check that you have the command line tools you need to generate openSSH keys:
If you're using a Mac OS:
command + spacebar to search => type 'terminal' which opens the native command line tool
If you're using a Windows OS:
Select the Start button
Type 'cmd' into search bar
Select 'Command Prompt' from the list
What if I don't have a command line tool? There are free, opensource key generator apps available to download. A commonly-used tool for generating SSH Key Pairs for Windows is PuTTYgen.
Step 2: Generate the key pair
Run the command `ssh-keygen -t rsa` to generate a new key pair.
When prompted, enter a file path and filename to save the new key pair to, for example `users/firstname.lastname/department-key-pair/[filename]`. We recommend you create a new folder to save your key pair to so that you don't overwrite any existing key pairs you may have saved.
You may be asked for a passphrase. It's a good idea to set (and keep a record of) a passphrase if you want to, but it's not compulsory.
You can now navigate to the file in which your keys are saved, and:
Send the public key to your AllVoices Customer Service representative.
Copy the private key to your HRIS or SFTP client setup side.
What if my computer is not set up to accept this command? The `ssh-keygen` or `puttygen` apps can be downloaded for free with a search online.
NOTE: Be wary of sharing your private key. Don't send it anywhere via email, text or through any other insecure means. Multiple key pairs can be generated so you can choose to have a private key per person/SFTP connection.
Uploading Employee Data File using the SFTP integration:
Using the Hostname and Username provided below, along with your Private Key generated above, you’ll now be able to set the connection with your SFTP client, and upload employee data files in CSV/XLSX format via that connection.
SFTP clients will require the following information to set a connection:
Protocol = SFTP
Log on type = Key file
Host/Host Name = transfers.allvoices.co
Port = 22
User Name = {companyname}
Make sure the hostname and username you use to set up your SFTP client are copied directly from above. Both are case-sensitive.
If required by your SFTP client, you may specify `/` as the upload directory