Datenaustausch mittels SFTP Server

Workist stellt im Standard einen SFTP-Server bereit. Ihr System legt dort Stammdaten ab und holt die Ergebnisse der Dokumentverarbeitung ab. Der Server ist mit Public-Key-Authentifizierung gesichert: Sie erzeugen ein SSH-Schlüsselpaar und hinterlegen den öffentlichen Schlüssel in der Workbench.

Alternativ überträgt Workist die Ergebnisse auf Ihren eigenen SFTP-Server, siehe Eigener SFTP-Server.

Verbindungsdetails

Host	ftp.workist.com
Port	22
Benutzername	Kurzname Ihrer Organisation
Anmeldung	SSH-Schlüssel, kein Passwort
RSA-Fingerprint des Servers	LNe5eKZc2plvysmcr+1sZjfhjn63/K+L+0FtLbGjpXM (SHA256)
IP-Adressen des Servers	63.34.88.144, 54.220.170.13, 52.49.47.193

Dieselben Angaben mit Kopier-Symbol, einschließlich Ihres Benutzernamens, zeigt die Workbench oben auf der Seite Öffentliche SFTP-Schlüssel (Einstellungen → Integrationen → Öffentliche SFTP-Schlüssel). Maßgeblich sind die Angaben in der Workbench.

Beim ersten Verbinden zeigt Ihr SFTP-Client den Fingerprint des Servers an, z. B. als SHA256:LNe5eK…. Vergleichen Sie ihn mit dem Wert oben, bevor Sie die Verbindung bestätigen.

Zugang einrichten

1. SSH-Schlüsselpaar erzeugen.
2. Den öffentlichen Schlüssel in der Workbench unter Öffentliche SFTP-Schlüssel hinterlegen. Das dürfen Benutzer mit der Rolle IT oder Admin (siehe Benutzer und Rollen). Die Schritte mit Screenshots stehen in Schritt 1: Verbindung herstellen.
3. Verbindung testen.

Sie können mehrere Schlüssel hinterlegen, z. B. einen je System. Ein gelöschter Schlüssel funktioniert sofort nicht mehr.

Verzeichnisstruktur

Verzeichnis	Verwendungszweck
/export	Stammdaten, die Ihr System für Workist ablegt (aus dem ERP exportiert)
/incoming	Ergebnisse von Workist: Ausgabedatei (z. B. XML), Originaldokument und weitere Dateien
/archive	Für Ihre eigene Ablage. Workist nutzt den Ordner im Standard nicht.

Stammdaten ablegen

• Dateien, die Sie in /export oder einen Unterordner davon hochladen, importiert Workist sofort, wenn der Dateiname zu einem Dateinamenmuster einer Lookup-Definition passt. Die Muster legen Sie im Stammdaten-Hub fest (siehe auch Transformer-Konfiguration). Uploads in andere Ordner lösen keinen Import aus.
• Jeder Import ersetzt den gesamten Bestand der Lookup-Definition. Legen Sie immer die vollständige Liste ab.
• Workist ignoriert Dateien, deren Pfad .PART, .partfile, .filepart, .ffs_tmp oder /Testsystem/ enthält. Wenn Ihr Programm Dateien unter einem vorläufigen Namen hochlädt und danach umbenennt, verwenden Sie eine dieser Endungen. So liest Workist keine halb geschriebene Datei.
• Wurden für eine Lookup-Definition in der letzten Stunde mehr als 12 Importe angelegt, überspringt Workist weitere Uploads ohne Meldung (siehe Grenzen der Stammdaten-API).

Ergebnisse abholen

Wenn ein Kanal die Ergebnisse per SFTP überträgt, legt Workist für jedes abgeschlossene Dokument diese Dateien ab:

Datei	Dateiname	Wann
Ausgabedatei (z. B. XML)	<name>.<endung>	immer
Originaldokument	<name>.pdf, bei E-Rechnungen im XML-Format (XRechnung, CII) <name>.xml	wenn Originaldokument hochladen aktiv ist (Standard)
Original-E-Mail	<name>.eml	wenn Originale E-Mail hochladen aktiv ist und das Dokument per E-Mail kam
Zusätzliche Dateien	<name>_file_1.<endung>, <name>_file_2.<endung> …	wenn Zusätzliche Dateien aktiv ist (nur Bestellungen)

<name> ist der Name der Ausgabedatei ohne Endung. Dateien mit demselben <name> gehören zum selben Dokument. Das Originaldokument ist die PDF-Datei, die Workist aus dem Eingang erzeugt hat; Bilder und Office-Dateien kommen deshalb als .pdf an.

Ordner: Standard ist /incoming. In der Upload-Konfiguration des Kanals legen Sie eigene Ordner fest: Zielordner für generierte Dateien (Ausgabedatei), Zielordner für ausgehende Dokumente (Originaldokument und E-Mail) und Zielordner für zusätzliche Dateien (ohne Angabe: der Ordner für ausgehende Dokumente). Details: Exportierte verarbeitete Dokumente.

So schreibt Workist die Dateien

• Workist schreibt jede Datei zuerst als <dateiname>.PART und benennt sie nach vollständiger Übertragung um. Ignorieren Sie beim Abholen alle Dateien mit der Endung .PART.
• Reihenfolge: Originaldokument, Original-E-Mail, zusätzliche Dateien, zuletzt die Ausgabedatei. Wenn die Ausgabedatei da ist, sind alle Dateien des Dokuments vollständig. Lösen Sie Ihren Import deshalb über die Ausgabedatei aus.
• Liegt bereits eine Datei mit demselben Namen im Ordner, überschreibt Workist sie.
• Workist löscht abgeholte Dateien nicht. Verschieben oder löschen Sie sie selbst, z. B. nach /archive.
• Scheitert die Übertragung, zeigt das Dokument in der Workbench eine Fehlermeldung. Nach Behebung der Ursache wählen Sie im Menü der Dokumentzeile Nochmal probieren.

Eigener SFTP-Server

Statt auf den Workist-Server kann Workist die Ergebnisse auf Ihren SFTP-Server übertragen. Tragen Sie die Verbindung im Kanal unter Kanal verwalten → SFTP ein und wählen Sie unter Upload die Übertragungsart SFTP. Stammdaten legen Sie weiterhin auf dem Workist-Server ab oder übertragen sie per API.

• Host und Benutzername Ihres Servers.
• Port: Pflicht, auch wenn Ihr Server Port 22 verwendet.
• Hostkey: der öffentliche Schlüssel Ihres Servers im Format <typ> <base64>, ohne Hostnamen und ohne Kommentar, z. B. ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…. Unterstützt: ssh-rsa, ssh-ed25519, ecdsa-… und ssh-dss. ssh-keyscan -t ed25519 <host> gibt den Schlüssel mit vorangestelltem Hostnamen aus; übernehmen Sie nur die beiden letzten Teile. Ohne Hostkey prüft Workist die Identität Ihres Servers nicht.
• Passwort: Mit Passwort meldet sich Workist per Passwort an. Ohne Passwort meldet sich Workist mit einem eigenen RSA-Schlüssel an; den öffentlichen Schlüssel dafür erhalten Sie von Ihrer Ansprechperson bei Workist.
• Zielordner sind Pfade auf Ihrem Server, Standard /incoming. Die Ordner müssen existieren.

Workist schreibt auf Ihren Server genauso wie auf den eigenen: erst .PART, dann umbenennen, Ausgabedatei zuletzt.

Verbindung testen

Verwenden Sie sftp. Der Workist-Server spricht nur das SFTP-Protokoll, ältere scp-Versionen funktionieren deshalb nicht.

sftp -i ~/.ssh/workist_sftp <benutzername>@ftp.workist.com
sftp> put stammdaten.csv /export/stammdaten.csv
sftp> ls /incoming
sftp> get /incoming/<datei> .
sftp> bye

---

Erstellen eines SSH Key Pairs

Die Workbench erwartet einen RSA-Schlüssel im OpenSSH-Format. Der öffentliche Schlüssel beginnt mit ssh-rsa.

Windows, Linux und Mac

ssh-keygen -t rsa -b 4096 -C "ihre_email@beispiel.com" -f ~/.ssh/workist_sftp

Folgen Sie den Eingabeaufforderungen:

1. Optionale Passphrase eingeben.
2. Der Schlüssel wird erzeugt: ~/.ssh/workist_sftp (privat) und ~/.ssh/workist_sftp.pub (öffentlich).

Hinweis: ssh-keygen erfordert, dass OpenSSH installiert ist. Unter Windows 10 und 11 ist es in der Regel vorhanden.

PuTTY (Windows)

1. PuTTY von der offiziellen Website herunterladen.
2. PuTTY Key Generator öffnen.
3. RSA auswählen, 4096 Bits einstellen, auf „Generate" klicken und die Maus über den leeren Bereich bewegen.
4. Den öffentlichen Schlüssel aus dem Feld „Public key for pasting into OpenSSH authorized_keys file" kopieren.
5. Den privaten Schlüssel speichern: Conversions → Export OpenSSH Key.

Verwendung des Key Pairs

• Hinterlegen Sie den öffentlichen Schlüssel (Dateiendung .pub) in der Workbench unter Öffentliche SFTP-Schlüssel.
• Speichern Sie den privaten Schlüssel (ohne Dateiendung) auf dem System, das mit dem SFTP-Server kommuniziert. Geben Sie ihn nicht weiter, auch nicht an Workist.