SFTP Integration

Über die Integration

Falls Du das HRIS, welches in Deinem Unternehmen verwendet wird, nicht in der Liste unserer nativen Integrationspartner findet, erlaubt euch unsere SFTP Integration möglicherweise dennoch, eure Nutzerdaten mit Leapsome zu synchronisieren.

Zu den HRIS, welche einen SFTP-Export unterstützen zählen unter anderem SAP Success Factors, Ultimate Kronos Group (UKG), Paycom, Paylocity, Lucca und Ceridian. Bitte wende Dich an den Support deines HRIS um herauszufinden, ob dieses SFTP-Integrationen unterstützt und welche Einstellungen auf Seiten des HRIS vorgenommen werden müssen.

Mittels der SFTP Integration werden Daten aus deinem HRIS mittels eines SFTP Servers an Leapsome übermittelt. Dabei gleicht Leapsome täglich ab, ob sich in eurem HRIS Änderungen an den Nutzerdaten ergeben haben und aktualisiert diese dann automatisch in eurer Leapsome-Nutzerübersicht.

Dieser Artikel zeigt Dir, welche Schritte in Leapsome unternommen werden müssen, um eine solche Integration aufzusetzen. Da das Aufsetzen der SFTP integration technisch anspruchsvoll ist, ziehe bei Bedarf gern Unterstützung aus dem IT-Team Deiner Organisation bzw. von Seiten eures HRIS-Betreibers hinzu.

Funktionsumfang

Einmal aktiviert führt die Integration folgende Schritte aus: 

• Sie erstellt ein Leapsome Konto für jeden neuen Mitarbeiter, den Du in deiner Nutzerdatei als 'aktiv' hinzufügst. Die Plattform synchronisiert automatisch den Namen, die E-Mail-Adresse, die Position, das Team und den Manager des Benutzers.
• Sie versendet eine Einladung zu Leapsome an diesen Benutzer, wenn die Option 'Automatisch Einladungen zu Leapsome an alle synchronisierten Nutzer senden' aktiviert ist. Alternativ kannst Du neue Benutzer auch manuell einladen, indem Du noch offene Einladungen auf der 'Nutzer & Teams' Seite erneut versendest.
• Sie erstellt Teams in Leapsome für jedes neue Team, das in deiner Nutzerdatei gelistet ist.
• Basierend auf der Angabe in der Spalte 'Manager Email / Username' weist sie Managerberechtigungen in Leapsome zu. Dadurch musst Du die Berichtslinien nicht neu einrichten.
• Sie aktualisiert all diese Informationen täglich basierend auf Deinen Änderungen in der Nutzerdatei. 

Aufsetzen der Integration

1. Bereite deine Nutzerdaten-Datei vor

Die SFTP Integration funktioniert ähnlich wie ein manueller Excel-Upload. Der Unterschied ist, dass Dein HRIS das Erstellen, Aktualisieren und Hochladen der Datei für Dich übernimmt.

Damit Leapsome Deine Nutzerdaten-Datei richtig verarbeiten kann, ist es wichtig dass diese exakt wie die von uns vorgegebene Importdatei formatiert ist. Bitte stelle daher sicher, dass Deine Datei die folgenden Kriterien erfüllt: 

• Bitte nutze die Importvorlage, welche Du auch für einen manuellen Nutzerupload in Leapsome verwenden würdest. Hierbei müssen die Spaltenbeschriftungen unverändert bleiben, damit Leapsome die Datei lesen kann. Die Uploaddatei erhältst Du in den Leapsome SFTP-Einstellungen, indem Du auf 'Vorlage herunterladen' klickst. Bitte melde Dich, falls dein HRIS die Vorlage nicht unterstützt.
• Stelle sicher, dass jedes Datum in deiner Datei unserem Format (TT-MM-JJJJ) entspricht, damit es korrekt in Leapsome angezeigt werden kann
• Bitte konfiguriere die Nutzerdatei so, dass bei jedem Uplaod eine vollständige Liste mit allen existierenden und neuen Nutzern gesendet wird. So stellst du sicher, dass Managerwechsel und Nutzerdeaktivierungen korrekt erfasst werden.
  • Bitte stelle sicher, dass auch (kürzlich) gekündigte Personen weiterhin in der Datei gelistet bleiben und ihr Status als 'deactivated' ausgewiesen wird. Nur so kann Leapsome die entsprechenden Nutzerprofile automatisch deaktivieren. Wenn Du hingegen aktive Nutzer einfach aus der Datei entfernst, wird Leapsome ihre Profile unverändert als 'aktiv' belassen.
  • Bitte beachte, dass wenn Du einem Nutzer einen Manager oder eine zusätzliche Führungskraft zuweisen möchtest, dieser Manager auch als Nutzer in einer Zeile in dieser Upload-Datei aufgeführt werden muss. Andernfalls können die Änderungen nicht ordnungsgemäß übernommen werden.

Benutzerdefinierte Attribute in die Intergration mitaufnehmen

Du hast zusätzlich die Möglichkeit, auch benutzerdefinierte Attribute über die Intergation auf dem aktuellsten Stand zu halten. Hierfür musst du zunächst die entsprechenden Attribute in Leapsome erstellen. Diese Anleitung zeigt Dir, wie Du dafür vorgehen musst. Damit das Attribut in Zukunft reibungslos durch die Integration aktualisiert werden kann, empfehlen wir, es im Format 'Text' aufzusetzen.

Sobald das erledigt ist, kannst Du eine neue Version eurer Importdatei unter Einstellungen > Integrationen > HRIS Integrationen > SFTP herunterladen. Die zusätzlichen Attribute sollten nun auch in der ersten Zeile gelistet sein. Mithilfe dieser Vorlage kannst du nun auch dieses Attribut mittels der SFTP Integration synchronisieren.

2. Einrichten der openSSH Keys

Um die SFTP Integration einrichten zu können, musst Du zunächst ein SSH Key Pair erstellen. Diese Keys stellen sicher, dass die SFTP-Verbindung über Dein HRIS sicher ist.

Ein SSH Key Pair beinhaltet zwei einzigartige Schlüssel, die von Dir generiert und auf Deinem Computer gespeichert werden. Hierzu gehören ein sogenannter 'Private Key', welcher idealerweise nur von Dir (oder autorisierten Personen in deinem Unternehmen) genutzt wird, sowie ein 'Public Key', welcher auch außerhalb deiner Organisation sicher geteilt werden kann. Die Integration nutzt die Kombination beider Keys (= Pair), um die Sicherheit der Verbindung zu verifizieren.

Bitte beachte, dass die Integration nur 'openSSH' Key Pairs unterstützt, jedoch keine 'SSH2' Key Pairs. Sollte dein HRIS bzw. dein Command Tool lediglich SSH2 Key Pairs generieren, kannst Du diese manuell in openSSH konvertieren. Folge dazu der Anleitung im Bereich 'Häufig gestellte Fragen'.

Öffne dein Command Line Tool

Stelle sicher, dass Du auf deinem Computer über ein Command Line Tool verfügst, über welches Du die openSSH Keys erstellen kannst.

Falls Du ein Mac Betriebssystem benutzt:

• Drücke 'command' + Leerzeichen um die Mac Suche zu starten
• Tippe 'terminal' ein und öffne das dazugehörige Mac Command Line Tool namens 'Terminal'
  

Falls Du ein Windows Betriebssystem benutzt: 

• Klicke auf 'Start'
• Tippe 'cmd' in die Suchleiste ein
• Wähle die 'Eingabeaufforderung' aus der Liste

Erstelle das Key Pair

1. Gib den folgenden Befehl in das Terminal bzw. die Eingabeaufforderung ein und bestätige ihn mit Enter, um ein neues Key Pair zu erstellen:

   ssh-keygen -t rsa

   Falls dein Computer diesen Befehl nicht erkennt, musst Du zunächst die notwendeigen Apps installieren. Suche dafür im Internet nach 'ssh-keygen' oder 'puttygen'.
2. Tippe dann einen Dateipfad und Dateinamen ein, unter dem das Key Pair gespeichert werden soll. Das könnte wie folgt aussehen:

   users/firstname.lastname/department-key-pair/[filename]

   Wir empfehlen Dir, einen neuen Ordner für dein Key Pair anzulegen, damit mögliche bereits vorhandene Key Pairs auf deinem Computer nicht versehentlich überschrieben werden.
3. Definiere als nächstes eine Passphrase für dein Key Pair. Die Passphrase funktioniert dabei wie ein Passwort und hilft, dein Key Pair zu schützen. Dieser Schritt ist optional. Drücke Enter, wenn Du ihn überspringen willst.
4. Navigiere nun zur Datei, in welchem deine Keys gespeichert wurden und 
   • Kopiere den Public Key, um diesen im nächsten Schritt in Leapsome einzugeben.
   • Kopiere den Private Key und füge ihn an der entsprechenden Stelle in Deinem HRIS bzw. SFTP Client ein. Kontaktiere hier den Betreiber deines HRIS, falls Du unsicher bist, wo Du diese Eingabemaske findest. 

Wichtig: Bitte teile deinen Private Key mit niemandem. Stattdessen kannst Du bei Bedarf mehrere Key Pairs erstellen, sodass Du jeweils einen Private Key pro Person bzw. pro SFTP Verbindung verwendest.

2. Aktiviere die Integration

Öffne Leapsome als (Super-) Admin, navigiere zu den Admin-Einstellungen > Integrationen > SFTP und setze einen Haken bei der Option 'Integration aktivieren'. Füge den SSH Public Key in das entsprechende Feld ein und bestätige deine Eingaben mit einem Klick auf 'Speichern & Synchronisieren'.

3. Nutzerdaten hochladen

Nun kannst Du die Integration auf Seiten deines HRIS aufsetzen. Ziehe hierfür den Support deines HRIS-Betreibers heran, falls nötig. Du wirst folgende Daten benötigen: 

• Host Name: 'sftp.leapsome.com'
• Name des Zielordners: '/incoming'
• User Name: Das ist die Account ID eures Leapsome Accounts. Diese findest Du in den Einstellungen unter Admin-Einstellungen > Basis Einstellungen oder direkt in den Leapsome-Einstellungen für die SFTP Integration.
• Die SSH Private Key Datei, welche Du in Schritt 2 erstellt hast

Leapsome wird dann automatisch einmal pro Tag die zuletzt bearbeitete Datei abrufen. Alternativ kannst Du einen Datenabgleich auch manuell anstoßen, indem Du in Leapsome auf der SFTP-Integrationsseite auf 'Speichern & Synchronisieren' klickst. Alle verarbeiteten Dateien werden in den 'processed' Ordner auf Deinem Server verschoben.

Troubleshooting und häufig gestellte Fragen

Befehlstypen

Bitte beachte, dass wir nur die Verwendung des 'Put' Befehls erlauben. Jede andere Form der Interaktion mit dieser Art von Integration (z.B. 'Write', 'Delete', 'Get') ist nicht möglich.

'Connection refused' Fehler

Du kannst einen 'connection refused' Fehler beim Einrichten des SFTP Client erhalten. Ursache dafür kann z.B. eine interne Firewall in eurer Organisation sein, welche die SFTP Verbindung blockiert (lokale oder Netzwerk-Firewall). In diesem Fall muss die Firewall so konfiguriert werden, dass sie ausgehenden Zugriff ('outbound access') mittels des Hostnamen (nicht an eine spezifische IP Adresse gebunden, da sich diese verändern wird) auf TPC Port 22 erlaubt.

Ich habe die Integration aufgesetzt, aber die Nutzerdaten scheinen nicht aktualisiert zu werden - was kann ich tun?

Bitte stelle sicher, dass die Datei, die Deine Nutzerdaten beinhaltet, exakt so formatiert ist, wie die Vorlage, die Du in Leapsome findest. Insbesondere müssen die Spaltenbeschriftungen unverändert bleiben und die Zellinhalte korrekt formatiert sein (z.B. müssen Daten im Format TT-MM-JJJJ angegeben werden).

Da Leapsome immer die neueste Datei nutzt, die aus Deinem HRIS übertragen wurde, kann es sein, dass Nutzerdaten nicht korrekt aktualisiert werden, wenn Dein HRIS zusätzliche Dateien an Leapsome schickt, die keine Nutzerdaten beinhalten. Manche HRIS, wie z.B. Lucca, senden 'Summary Sheet' nachdem die Nutzerdatei verschickt wurde. Bitte stelle sicher, dass Dein HRIS keine derartigen Dateien an Leapsome schickt und wende Dich an deinen HRIS Support, falls Du hierbei Unterstützung benötigst. 

Kann ich mehrere HRIS über SFTP mit einem Leapsome Account synchronisieren?

Ja. Wenn beispielsweise verschiedene Organisationseinheiten oder Länder innerhalb Deines Unternehmens eigenständige, SFTP-kompatible HRIS benutzen, kannst du für sie alle die SFTP Integration zu eurem Leapsome Account aufsetzen. Hierfür muss in allen HRIS Accounts derselbe SSH Key verwendet werden, der auch in Leaspome verwendet wird. 

SSH2 zu SSH konvertieren

Stelle sicher, dass dein HRIS SFTP und SSH unterstützt. Bitte beachte, dass die Integration nur 'openSSH' Key Pairs unterstützt, jedoch keine 'SSH2' Key Pairs. Sollte dein HRIS bzw. dein Command Tool lediglich SSH2 Key Pairs generieren, kannst Du diese wie folgt manuell in openSSH konvertieren:

Suche die Datei, die den Public SSH Key beinhaltet. Das erkennst Du an der Dateiendung, z.B. 'ssh2.pub'. Wenn du diese Datei öffnest, solltest du Informationen ähnlich wie im folgenden Beispiel sehen:

---- BEGIN SSH2 PUBLIC KEY ----
...
---- END SSH2 PUBLIC KEY ----

Stelle sicher, dass die Datei die Endung '.pub' besitzt, und führe dann folgenden Befehl mittels Deines Command Tools für die Datei aus, um diese ins openSSH zu konvertieren: 

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

Sonderzeichen werden nicht korrekt in Leapsome angezeigt

Falls Eure Nutzerdaten im CSV-Format gespeichert sind, versuche dies auf XLS oder XLSX-Format umzustellen, um sicherzustellen, dass alle Sonderzeichen korrekt gespeichert werden. Falls du an das CSV-Format gebunden bist, nutze am Besten eine UTF-16-kodierte Datei, oder eine UTF-8-kodierte Datei mit 'BOM'. UTF-8 kodierte CSV-Dateien ohne BOM können leider zu Fehlern in der Darstellung von Sonderzeichen führen.

Entfernte Teams werden in Leapsome weiterhin angezeigt

Bis August 2023 galt, dass wenn ein Team in der Uploaddatei aus der Liste an Teams, denen ein Nutzer angehört, entfernt wird, wird dieses Team aktuell nicht auch aus dem Profil des Nutzers in Leapsome entfernt. Wenn hingegen ein neues Team in der Datei hinzugefügt wird, wird das Teammitglied diesem auch in Leaspome zugewiesen. 

Durch eine neue Einstellungsoption "Overwrite team assignment" (Teamzuweisung überschreiben) ist es nun möglich, die SFTP-Integration so zu konfigurieren, dass Leapsome stets den aktuellen Stand der Teams im HRIS reflektiert. Ist diese Funktion aktiviert, werden mit jeder Synchronisierung die vorherigen Teamzuweisungen entfernt, und mit den aktuell gültigen ersetzt. 

Hierbei gelten die folgenden Ausnahen:

• Von Leapsome erstellte Auto-teams (Manager (auto), Non-Manager (auto)) werden nicht entfernt.
• Wurden im Quellsystem alle Teams entfernt und die SFTP Datei enthält einen leeren Wert für das Teams Attribut, werden die bestehenden Teams nicht entfernt.

Ist es möglich, mehrere Systeme via SFTP an Leapsome anzubinden?

Ja. Du kannst in dem Falle einfach denselben SSH Key in allen Systemen verwenden, die du mit Leapsome verbinden möchtest. Bitte stelle sicher, dass die Daten in den verschiedenen Systemen konsistent sind. Beispielsweise sollte jeder Nutzer idealerweise nur in einem der Systeme vorhanden sein, um Fehler oder Konflikte in den Nutzerdaten zu vermeiden.