# 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](#eigener-server).

## Connection Details {#verbindungsdetails}

| | |
|---|---|
| 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 {#zugang}

1. [Create an SSH key pair](#erstellen-eines-ssh-key-pairs).
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](/en/docs/administration/users-and-roles.md)). The steps with screenshots are in [Step 1: Establish connection](/en/docs/implementation-guide/step-1-establish-connection.md#a2-oeffentlichen-schluessel-hinterlegen).
3. [Test the connection](#verbindung-testen).

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

## Directory Structure {#verzeichnisstruktur}

| 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 {#stammdaten}

- 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](/en/docs/master-data/master-data-hub.md) (see also [Transformer configuration](/en/docs/master-data/transformer-configuration.md)). 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](/en/docs/api-documentation/master-data-api.md#grenzen)).

## Pick up results {#ergebnisse}

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](/en/docs/channel-configuration/exported-documents.md).

### How Workist writes the files {#schreibweise}

- 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 {#eigener-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](/en/docs/api-documentation/master-data-api.md).

- **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 {#verbindung-testen}

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

```bash
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 {#erstellen-eines-ssh-key-pairs}

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

### Windows, Linux and Mac

```shell
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.