What can I learn from this page? | How to effectively troubleshoot common SFTP integration issues |
Who is this guide for? | Account Admins, IT |
Quick links:
Investigating and resolving any data issues
The first step when investigating SFTP data issues is to check the import summary for your most recent import. This will provide specific information about the erroring data in your report so that you can address these in your HRIS.
To find the Import Summary for your last import, please navigate to this page via Account Admin > Import History and select your most recent SFTP import at the top of the page.
The Import Summary option you click into will display the errors that were included in your last import which will need to be adjusted or the page will prompt you to run a manual upload if this is required.
Handling of inactive employees
If an employee has a Termination Date (End Date) and is included in your report, they will be made inactive in Culture Amp (upon the term date)
*Employees with a Termination Date (End Date) who are not included in your transfer file will remain active in Culture Amp account
Any updates to inactive employees, such as a changed End Date or any other update to demographic information, will be applied during the import
Sync blocked due to swapped employee IDs
Your sync might be blocked if Culture Amp suspects that one of your employees may have had their details mixed up with another.
If a combination of an employee's Name, Date of Birth, Email, or Employee ID is changed, the sync will be blocked. This is to prevent an employee from accidentally getting access to another employee's private information, such as performance reviews.
If you've intentionally changed the employee's details, you can complete a manual import to bypass this block.
Destination folder
The upload to Culture Amp is to the root directory of our SFTP server, so the destination folder should be left blank. Some SFTP clients / HRIS ask for a value, if so it can be listed as "/".
Common Errors
"Access Denied"
Expected if:
You try to put the file in an actual folder, or even the ‘failed’ folder. The upload is to the root directory of our SFTP server, so the destination folder should be left blank. If a value is required, then it can just be listed as “/“.
You try to complete any other action besides the PUT (post) request to send the complete file. That includes any MOVE, RENAME, READ, DELETE or GET.
For example, if you’re sending the file in parts and then renaming it to one complete file. We would not accept the 'RENAME' request and additionally also reject the .filepart file type as this is not accepted by our server.
We’ve seen this with the SFTP client called WinSCP that splits the file into two separate files. Adjusting the preferences should allow the file to be sent as 1 complete file, rather than in parts.
Time-stamping is another example, which has been noted with WinSCP. The final action as part of a file transfer is sometimes set to add a time-stamp. Again, as we don't support any additional actions, it's likely you may see an error message. In some cases, the file may have been successfully transferred, so the error can be disregarded, but to avoid the error, the recommendation would be to turn off setting permissions or preserving timestamp. Alternatively you could turn on ‘Ignore permission errors’ option.
You are trying to send through files with the same name. Ensure that there is a differentiating factor such as adding time stamps to the file name to make each file name different.
"Connection refused"
You may receive a 'connection refused' error when setting up an SFTP client. This could be because your organization 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.
"Unexpected server shutdown"
Expected if attempting to negotiate a connection with an unsupported SFTP protocol version (0, 1, or 2). We support 4, 5, and 6.
Other / unknown errors
Some SFTP clients have an Event log where you can access a Payload. In the event of an error, this can often help identify the root cause. Example:
Event log:
HTTP Error response code 422 with response state text: Unprocessable Entity; Click text to download payload for further details
Payload:
{"errors":[{"field":"email","errorCodes":["duplicate-email"]}]}
Multiple uploads in quick succession
Our SFTP integration is designed to process one mass employee file at a time, and between each file, we wait for approx 10 mins before checking if there are further files to process. Although multiple files (with unique file names) can be sent in quick succession, it’s likely to take a while for all of the files to be imported.
Multiple transmissions of the same-named file, within a 10 to 15-minute window, will result in the failure of the second file. The second file would need to have a new name in order for the second transmission to be successful.
Failed imports
Import attempt not showing in Culture Amp
The import file may be missing one of our mandatory columns, such as Employee Id or Email, or there could be a data issue, such as a duplicate email address error or similar.
Incorrect format
The file is not in one of our expected formats (CSV UTF-8 (comma separator) or XLSX) or data may contain unsupported (special) characters.
In general, different CSV format options don't handle special characters the same way, which can sometimes change the data formatting resulting in import failures. You will need to ensure that you are using CSV (UFT-8 encoded) format to ensure special characters are formatted so we can read the information correctly.
SSH key pairs
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.