# 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](#eigener-server). ## Verbindungsdetails {#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 {#zugang} 1. [SSH-Schlüsselpaar erzeugen](#erstellen-eines-ssh-key-pairs). 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](/docs/administration/users-and-roles.md)). Die Schritte mit Screenshots stehen in [Schritt 1: Verbindung herstellen](/docs/implementation-guide/step-1-establish-connection.md#a2-oeffentlichen-schluessel-hinterlegen). 3. [Verbindung testen](#verbindung-testen). Sie können mehrere Schlüssel hinterlegen, z. B. einen je System. Ein gelöschter Schlüssel funktioniert sofort nicht mehr. ## Verzeichnisstruktur {#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 {#stammdaten} - 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](/docs/master-data/master-data-hub.md) fest (siehe auch [Transformer-Konfiguration](/docs/master-data/transformer-configuration.md)). 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](/docs/api-documentation/master-data-api.md#grenzen)). ## Ergebnisse abholen {#ergebnisse} 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) | `.` | immer | | Originaldokument | `.pdf`, bei E-Rechnungen im XML-Format (XRechnung, CII) `.xml` | wenn **Originaldokument hochladen** aktiv ist (Standard) | | Original-E-Mail | `.eml` | wenn **Originale E-Mail hochladen** aktiv ist und das Dokument per E-Mail kam | | Zusätzliche Dateien | `_file_1.`, `_file_2.` … | wenn **Zusätzliche Dateien** aktiv ist (nur Bestellungen) | `` ist der Name der Ausgabedatei ohne Endung. Dateien mit demselben `` 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](/docs/channel-configuration/exported-documents.md). ### So schreibt Workist die Dateien {#schreibweise} - Workist schreibt jede Datei zuerst als `.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 {#eigener-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](/docs/api-documentation/master-data-api.md). - **Host** und **Benutzername** Ihres Servers. - **Port**: Pflicht, auch wenn Ihr Server Port 22 verwendet. - **Hostkey**: der öffentliche Schlüssel Ihres Servers im Format ` `, ohne Hostnamen und ohne Kommentar, z. B. `ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…`. Unterstützt: `ssh-rsa`, `ssh-ed25519`, `ecdsa-…` und `ssh-dss`. `ssh-keyscan -t ed25519 ` 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 {#verbindung-testen} Verwenden Sie `sftp`. Der Workist-Server spricht nur das SFTP-Protokoll, ältere `scp`-Versionen funktionieren deshalb nicht. ```bash sftp -i ~/.ssh/workist_sftp @ftp.workist.com sftp> put stammdaten.csv /export/stammdaten.csv sftp> ls /incoming sftp> get /incoming/ . sftp> bye ``` --- ## Erstellen eines SSH Key Pairs {#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 ```shell 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.