HRIS integration

Overview

HR information systems such as Workday, BambooHR and ADP can typically build a report of employees and deliver it to an SFTP server on a schedule. Pointing that delivery at Kesk keeps your enterprise's members in step with your HR records: people who join are invited, and people who leave lose access.

This page describes the setup in terms that apply to any HR system. Menu names and screens differ between products and change between releases, so follow your vendor's documentation for where each setting lives.

Benefits

  • Secure transfer. Files travel over SSH, and the connection authenticates with a key pair rather than a password.
  • Your schedule. Kesk processes each file when it arrives, so the sync runs as often as your HR system delivers.
  • Your selection. The report decides who has access. Filter it to the people who should be able to spend on the enterprise account.

Step-by-step setup

Before you start, enable SFTP for your enterprise.

1. Build the report

Create a report in your HR system with one row per employee and these columns:

Column headerRequiredSource
email
Yes
Work email address. It is the key Kesk matches people on
first_name
No
Given name
last_name
No
Family name
role
No
The exact name of a role in your Kesk enterprise
external_id
No
Employee number or worker id
  • Name the columns exactly as above, using your HR system's column-heading override if it has one. The full column list also lists the accepted alternative names.
  • The output must be CSV with a header row, UTF-8, comma-delimited.
  • Filter to active employees who should have access.
  • Run the report once and check the output before you schedule it. Look for empty emails, and for role names that do not match your Kesk roles exactly.

Decide what the report represents:

  • The complete list of people who should have access: deliver it to /to_kesk/employees/. Anyone missing from it is removed, so the filter has to be right. The safety threshold stops a file that would remove a large share of your roster at once.
  • Only joiners, or only leavers: deliver them to /to_kesk/employees/add/ or /to_kesk/employees/remove/. Neither folder has a threshold.

2. Generate and register an SSH key

Many HR systems generate the key pair themselves, in their credential or security settings. Otherwise generate one as shown in setup and load the private key into the HR system.

Export the public key in OpenSSH format. It is a single line that starts with the algorithm, for example ssh-ed25519 AAAA... or ssh-rsa AAAA.... Copy it as plain text; a key exported as a PEM block, a certificate or a PDF is rejected. Register it with addEnterpriseSftpKey, as described in setup.

Accepted algorithms are Ed25519, RSA, and ECDSA over NIST P-256, P-384 or P-521.

3. Configure SFTP delivery

In the HR system's outbound SFTP or file-delivery settings:

SettingValue
Host
sftp.kesk.app
Port
2222
Username
Your enterprise id (sftpUsername in Settings)
Authentication
The key pair from step 2
Directory
/to_kesk/employees/, /to_kesk/employees/add/ or /to_kesk/employees/remove/
File name
Anything ending in lowercase .csv, such as roster.csv
Format
CSV, with no further transformation

Some integrations accept these as a single URL, such as sftp://sftp.kesk.app:2222/to_kesk/employees/.

  • If the connector uploads under a temporary name and renames the file when it is done, that works: the rename to .csv starts processing.
  • If the connector sets file timestamps after upload, switch that off. The server does not support it, and the connector will report the step as an error.
  • Allow outbound connections to sftp.kesk.app on port 2222 through your firewall.

4. Schedule and monitor

Schedule the delivery at whatever frequency your HR changes need. Kesk imposes no schedule.

After each run, a report appears in /from_kesk/reports/. Check it, or have your integration fetch it:

  • completed: applied in full.
  • completed_with_errors: applied, except for the rows listed in errors.
  • rejected_excessive_churn: nothing was applied, because the file would have removed too many people. Check your HR report's filter before the next run.

No report means the file was not processed. Check that its name ends in lowercase .csv, that it went to one of the three folders, and that it has an email column. See Reports.

Testing the integration

There is no test folder: every file you upload is applied to your real roster. To test safely, start small.

  1. Deliver a file with a single row, for an address you control, to /to_kesk/employees/add/. Confirm the report shows added_count: 1 and the invitation email arrives.
  2. Deliver the same address to /to_kesk/employees/remove/ to revoke that invitation.
  3. Only then point the scheduled full-roster delivery at /to_kesk/employees/, and read the first report before the next run.

Reference

Generated reference — every type, field and argument of the Enterprise GraphQL API, built from the live schema. SFTP itself is not GraphQL and is documented in full in this section.

Built with