What can I learn from this page? | A technical guide on setting up SFTP |
Who is this guide for? | IT Specialists |
📌 Note: This article contains detailed technical instructions on setting up an SFTP integration, and is intended for your IT department or HRIS representative. If you're not sure if SFTP is right for, we recommend you first review the benefits of HRIS integrations and the native integrations we offer.
A Secure File Transfer Protocol (SFTP) integration is a great way to sync your Culture Amp employee data with the data in your HRIS. Culture Amp supports a secure, one-way connection that imports data files from HRIS tools that support SFTP or third party SFTP clients.
Depending on your HRIS, you may need to contact your HRIS representative for assistance. Our support team is happy to assist with any questions you might have. Just reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.
Setting up an SFTP Integration
You'll need to configure some integration settings in Culture Amp in order to set up your SFTP connection. To find these settings:
Navigate to the Account Admin Settings page
Click on Data integrations
Select your HR system from the options on the Data Integrations page. If you can't find it, use the search bar. If your HR system isn't listed, click on the Other Integration Options tile to get started.
Setting up 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 organisation), and there's a public key which can safely be shared outside your organisation. The integration uses the combination of the two keys to verify the security of the connection.
📌 Note: The Employee Data Integration only supports openSSH key pairs, not SSH2. If your HRIS or command line tool generates keys in SSH2 format, you can convert them to openSSH using the instructions in the troubleshooting guide below.
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:
Copy the public key to Culture Amp's Employee Data Integration setup page.
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.
Helpful Links
The following links provide examples that may vary slightly based on your specific environment, tools, or software versions.
Here's an example of how to generate SSH key pairs in a Mac environment:
Here's an example of how to generate SSH key pairs in a Windows environment:
There's specific information about how to correctly format and save SSH keys here.
The popular SFTP Client Filezilla has helpful documentation about how to set up keys here - https://wiki.filezilla-project.org/Howto
Uploading Employee Data Files Using the SFTP Connection
Using the Hostname and Username provided on the setup page, 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. Please note that CSV's should be with UTF-8 encoding and the separator a comma (,). Culture Amp will process the files using our partial import process.
Most SFTP clients will require the following information to set a connection:
Protocol: SFTP
Logon Type: Key File
Host/Hostname: [Found on the SFTP set up page]
Username: [Found on the SFTP set up page]
Make sure the hostname and username you use to set up your SFTP client are copied directly from the setup form in Culture Amp. Both are case-sensitive. You can find these on the Data integration setup page.
If required by your SFTP client, you may specify `/` as the upload directory
Here's a video example of how to connect to SFTP Using Filezilla. The steps provided in this video may vary slightly dependant on your specific environment, tools, or software versions.
Tips for Resolving Issues with the SFTP Connection
Commands
When interacting with our SFTP integration option, please note that we only allow the "PUT" command. We do not allow customers to interact with this type of integration in any other way such as "Write", "Delete" or "Get".
'Connection refused' Error
You may receive a 'connection refused' error when setting up an SFTP client. This could be because your organisation has an internal Firewall (either a local or network firewall) that's blocking the SFTP connection.
If this is the case, your firewall needs to be configured to allow outbound access via the hostname (NOT bound to a specific IP address: the IP will change) on TCP Port 22.
Make sure the hostname and username you use to set up your SFTP client are copied directly from the setup form in Culture Amp. Both are case-sensitive.
Converting SSH2 to SSH.
Make sure your HRIS supports both SFTP and SSH. Our SFTP only supports openSSH key pairs, not SSH2. If your HRIS or command line tool generates keys in SSH2 format, you can convert them to openSSH using the instructions in the guide below.
To convert an SSH2 public key into openSSH format:
Locate your public SSH key (named for example `ssh2.pub`). This is a file that, when you open it, contains this kind of information:
```
---- BEGIN SSH2 PUBLIC KEY ----
...
---- END SSH2 PUBLIC KEY ----
```
Ensure that the file has the file format `.pub`
Run this command on the SSH2 file: `ssh-keygen -i -f ssh2.pub > openssh.pub`
Switch to Use New Path for Existing Employee Data Integration
If you had a working Employee Data Integration but it fails, it could be because our hostname has changed. You can reset your integration to use the new hostname/target directory by:
Log in to Culture Amp and navigate to Account Admin > Integrations > Employee Data Integration
Copy your existing Public Key from the Public Key field to Notepad or Textedit temporarily.
Disable the integration by clicking ‘disable’ under the ‘Employee Data Integration’ button at the top of the screen
Re-enable the Employee Data Integration by clicking on the EDI button again. Supply the same public key and email as was used previously.
Now go to your SFTP client’s settings (depending which client you are using) to update the hostname there, using the hostname that appears in the newly-saved Employee Data Integration form (the hostname should start with "secure." and not "sftp.")
Also in your SFTP client’s settings, ensure that the target directory name (if it is required) is set to "/".
You've now reset your integration to point to the new server, using the target directory of "/".
If your SFTP client has an ability to test the connection, be sure to check that the updated settings are operational.
💬 Need help? Just reply with "Ask a Person" in a Support Conversation to speak with a Product Support Specialist.