SFTP integration

Introduction

If you don't find your HRIS in our list of integrations, you might still be able to automatically synchronize user data from your HRIS to Leapsome using the SFTP integration.

Some HRIS that are known to support SFTP export include SAP Success Factors, Ultimate Kronos Group (UKG), Paycom, Paylocity, Lucca and Ceridian, among others. Please inquire with your HRIS support specialist whether an SFTP integration is supported and how to set this up with your HRIS.

With the SFTP integration, user data is transmitted from your HRIS to Leapsome via a file that is kept up to date on an SFTP server. Once set up, Leapsome will check on a daily basis, whether changes have been made in your HRIS and automatically update your users in Leapsome. 

This guide explains how to complete the integration on the Leapsome side. As setting up the SFTP integration is a rather technical procedure, please request support from your organization's IT team or your HRIS provider, if needed.

What the integration does

Once activated, the integration will automatically:

• create a new Leapsome user account for every new employee that you list as 'active' in your file - we will automatically synchronize the user's name, email address, job title, department, and manager.
• send a Leapsome invitation to that user if the 'auto-invite' option is activated in Leapsome. Alternatively, you can manually invite users by re-sending open invites on your team admin page.
• create 'teams' on Leapsome for every new team you list in your file. Members of the team will automatically be assigned to the corresponding team on Leapsome.
• assign direct manager rights on Leapsome based on the data you provide in the 'Manager Email / Username' column - no need to re-establish your reporting lines.
• update all of the above daily or on-demand, based on the changes in your upload file. 

Setting up the integration

1. Prepare your User Data File

The way this integration works is similar to performing a regular Excel user upload. The difference is, that the user data file is generated and uploaded automatically by your HRIS. 

To be able to process the user data file, the formatting of this file needs to be identical to the the import template which you would also use for manually uploading users. 

You can find all details on how the User Data File needs to be formatted, which information needs to be added, and how to test your file in this article.

Adding Custom Attributes to the synchronization

You can also include custom attributes in the synchronization. For this, please first create the custom attributes in Leapsome, as outlined in this article. For the attribute to be updated easily via the integration, we recommend formatting it in a 'Text' format.

If you then export a new import template from the integrations menu in Leapsome, your custom attribute should be listed in the header column as well. You can now start updating values for your custom attribute using the SFTP integration.  

2. Generate openSSH 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 or 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 that should only be used by you (or very carefully within your own organization), and there's a public key that can safely be shared outside your organization. The integration uses the combination of the two keys to verify the security of the connection.

Please note, that the 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.

Check command line tools

First, check that you have a command line tool installed to your computer as you need this to generate the openSSH keys:

If you're using a Mac OS:

• Press 'command' + spacebar to start the Mac Search
• Type 'terminal' which opens the native command line tool called 
  

If you're using a Windows OS:

• Click on the Start button
• Type 'cmd' into search bar
• Select 'Command Prompt' from the list

Generate the key pair 

1. Enter the following command to your command line tool and confirm it by pressing Enter to generate a new key pair:

   ssh-keygen -t rsa

   If your computer can not accept this command, please install 'ssh-keygen' or 'puttygen', which are available for free online.
2. 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.
3. 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. Just press Enter, if you do not want to set a passphrase.
4. You can now navigate to the file in which your keys are saved, and:

• • Copy the public key to paste it to Leapsome's integration setup page in the next step.
  • Copy the private key to your HRIS or SFTP client setup side. Please contact your HRIS provider, if you're unsure where you can find that input screen.

Important: Please don't share your private SSH key with anyone. Multiple key pairs can be generated so you can choose to have a private key per person/SFTP connection.

3. Activate the integration in Leapsome

Open Leapsome as a (Super-) Admin and navigate to Settings > Integrations > SFTP and click 'Enable the integration'. Paste your SSH public key to the corresponding text field. Click 'Update & Synchronize'.

With the integration activated, you have additional options to customize the integration. For more information, check the infoboxes next to the settings.

4. Configure the integration in your HRIS

You are now ready to set up the integration in your HRIS. Please ask your HRIS' technical support for help, if required. You will need the following information:

• The hostname: sftp.leapsome.com
• The destination folder: /incoming
• A username: This is your Leapsome account ID, which can be found in 'Settings' > 'Company Settings' > 'Basic Settings' as well as on the SFTP integration page in Leapsome.
• The SSH private key file which you generated in step 2.

Leapsome will automatically process the most recently uploaded file once a day. You can also trigger manual parsing by clicking 'Update & synchronize' on the integrations page. All processed files will be moved to the 'processed' folder on your server.

Frequently Asked Questions and Troubleshooting

Commands

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 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, as the IP will change) on TCP Port 22. 

I set up the integration, but my user data does not seem to be updated - what can I do?

Please ensure, that the user data file you have set up is formatted exactly like the export file you can find in Leapsome. The column headers have to remain unchanged and all data has to be entered in the required format (e.g., dates follow the format DD-MM-YYYY). 

As Leapsome will process the latest file that has been pushed from your HRIS, the users may not be updated correctly if your HRIS sends any additional files, other than the user data file. Some HRIS, like Lucca, send a 'Summary Sheet' in addition to the user data file. Please make sure to switch this off in the settings of your HRIS and get in touch with your HRIS support specialist to find out how this can be done.

Can I sync multiple HRIS with our Leapsome Account by using SFTP?

Yes. If different business units within your organization use individual, SFTP-compatible HRIS, you can connect them all to your Leapsome account by using the SFTP integration. To do this, you need to use the same SSH Key in all HRIS accounts, as well as in Leapsome.

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.

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' and run the following command on the SSH2 file to convert it to openSSH:

ssh-keygen -i -f [FILENAME].pub > openssh.pub

Special characters are not showing correctly in Leapsome

In case you are using a CSV file to hold your user data, please consider changing this to a traditional XLS or XLSX file to make sure all special characters are saved correctly. In case your HRIS restricts you to use a CSV file, please make sure it is UTF-16 encoded file, or in case you are using a UTF-8 encoded one, to save it 'with encoding' or 'with BOM'. 

Team unassignments are not reflected properly

Since August 2023, you can customize whether the SFTP integration should only add new teams and not remove previous ones, or whether each SFTP upload should overwrite the previous team assignment so that only the currently assigned teams in your source system are reflected in Leapsome. If team unassignments are not reflected to Leapsome, you can activate the setting "Overwrite team assignment" in Settings > Integrations > SFTP and click "Update & Synchronize". 

Please note the following exceptions:

• Leapsome-generated auto-teams will not be overwritten (Manager (auto), Non-Manager (auto)).
• If the field in the source system is empty, the upload does not remove teams the user already has.

Is it possible to connect two or more source systems to Leapsome via SFTP?

Yes, it's possible. You can use the same SSH key in all source systems. Please make sure that the data that is being sent is consistent. Ideally, each user should only be present in one source system, to avoid conflicting data.

When will a file sent to the SFTP server be processed?

Leapsome processes the files dynamically based on when the file was uploaded. The SFTP sync is started around every 1-2 hours per account, meaning multiple files can be processed throughout the day. No specific processing time nor guarantee on the 1-2 hour window can be given as it might take 3-4 hours at certain times before a new file is processed.