Data Exchange via SFTP Server

Workist provides an SFTP server by default. Your system places master data there and picks up the results of document processing. The server is secured with public key authentication: you create an SSH key pair and add the public key in the Workbench.

Alternatively, Workist transfers the results to your own SFTP server, see Your own SFTP server.

Connection Details

Host	ftp.workist.com
Port	22
User name	Short name of your organisation
Login	SSH key, no password
RSA fingerprint of the server	LNe5eKZc2plvysmcr+1sZjfhjn63/K+L+0FtLbGjpXM (SHA256)
IP addresses of the server	63.34.88.144, 54.220.170.13, 52.49.47.193

The Workbench shows the same details with a copy icon, including your user name, in the SFTP Server Information card at the top of the SFTP Public Keys page (Settings → Integrations → SFTP Public Keys). The details in the Workbench are authoritative.

When you connect for the first time, your SFTP client shows the server's fingerprint, e.g. as SHA256:LNe5eK…. Compare it with the value above before you confirm the connection.

Set up access

1. Create an SSH key pair.
2. Add the public key in the Workbench under SFTP Public Keys. Users with the IT or Admin role can do this (see Users and roles). The steps with screenshots are in Step 1: Establish connection.
3. Test the connection.

You can add several keys, e.g. one per system. A deleted key stops working immediately.

Directory Structure

Directory	Purpose
/export	Master data that your system places for Workist (exported from the ERP)
/incoming	Results from Workist: output file (e.g. XML), original document and further files
/archive	For your own storage. Workist doesn't use the folder by default.

Place master data

• Workist imports files that you upload to /export or one of its subfolders immediately if the file name matches a file name pattern of a lookup definition. You set the patterns in the Master Data Hub (see also Transformer configuration). Uploads to other folders don't trigger an import.
• Every import replaces the entire data set of the lookup definition. Always upload the complete list.
• Workist ignores files whose path contains .PART, .partfile, .filepart, .ffs_tmp or /Testsystem/. If your program uploads files under a temporary name and renames them afterwards, use one of these endings. That way Workist never reads a half-written file.
• If more than 12 imports were created for a lookup definition in the last hour, Workist skips further uploads without notice (see Limits of the Master Data API).

Pick up results

When a channel transfers its results via SFTP, Workist places these files for every finished document:

File	File name	When
Output file (e.g. XML)	<name>.<extension>	always
Original document	<name>.pdf, for e-invoices in XML format (XRechnung, CII) <name>.xml	if Upload original document is on (default)
Original email	<name>.eml	if Upload original e-mail is on and the document came by email
Additional files	<name>_file_1.<extension>, <name>_file_2.<extension> …	if Additional Files is on (orders only)

<name> is the name of the output file without its extension. Files with the same <name> belong to the same document. The original document is the PDF that Workist created from the input; images and Office files therefore arrive as .pdf.

Folders: the default is /incoming. In the channel's Upload configuration you set your own folders: Destination folder for generated files (output file), Destination folder for outgoing documents (original document and email) and Destination folder for additional files (if empty: the folder for outgoing documents). Details: Exported processed documents.

How Workist writes the files

• Workist first writes every file as <file name>.PART and renames it once the transfer is complete. Ignore all files ending in .PART when picking up.
• Order: original document, original email, additional files, and the output file last. Once the output file is there, all files of the document are complete. So trigger your import on the output file.
• If a file with the same name already exists in the folder, Workist overwrites it.
• Workist doesn't delete files that you have picked up. Move or delete them yourself, e.g. to /archive.
• If the transfer fails, the document shows an error message in the Workbench. After fixing the cause, choose Retry in the menu of the document row.

Your own SFTP server

Instead of the Workist server, Workist can transfer the results to your SFTP server. Enter the connection in the channel under Manage channel → SFTP and choose the delivery method SFTP under Upload. You still place master data on the Workist server or transfer it via the API.

• Host and Username of your server.
• Port: required, even if your server uses port 22.
• Hostkey: the public key of your server in the format <type> <base64>, without host name and without comment, e.g. ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…. Supported: ssh-rsa, ssh-ed25519, ecdsa-… and ssh-dss. ssh-keyscan -t ed25519 <host> prints the key with the host name in front; only copy the last two parts. Without a host key, Workist doesn't verify your server's identity.
• Password: With a password, Workist logs in with the password. Without a password, Workist logs in with its own RSA key; your Workist contact provides the public key for it.
• Destination folders are paths on your server, default /incoming. The folders must exist.

Workist writes to your server the same way as to its own: first .PART, then rename, output file last.

Testing the Connection

Use sftp. The Workist server only speaks the SFTP protocol, so older scp versions don't work.

sftp -i ~/.ssh/workist_sftp <user name>@ftp.workist.com
sftp> put masterdata.csv /export/masterdata.csv
sftp> ls /incoming
sftp> get /incoming/<file> .
sftp> bye

---

Creating an SSH Key Pair

The Workbench expects an RSA key in OpenSSH format. The public key starts with ssh-rsa.

Windows, Linux and Mac

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

Follow the prompts:

1. Enter an optional passphrase.
2. The key is generated: ~/.ssh/workist_sftp (private) and ~/.ssh/workist_sftp.pub (public).

Note: ssh-keygen requires OpenSSH to be installed. On Windows 10 and 11 it is usually present.

PuTTY (Windows)

1. Download PuTTY from the official website.
2. Open PuTTY Key Generator.
3. Select RSA, set 4096 bits, click "Generate" and move the mouse over the empty area.
4. Copy the public key from the field "Public key for pasting into OpenSSH authorized_keys file".
5. Save the private key: Conversions → Export OpenSSH Key.

Using the Key Pair

• Add the public key (file extension .pub) in the Workbench under SFTP Public Keys.
• Store the private key (without file extension) on the system that communicates with the SFTP server. Don't share it, not even with Workist.