FTP

Übersicht

Die Aktion FTP tauscht Dateien mit einem Server aus: Sie lädt Dateien von diesem PC hoch, lädt sie herunter, listet sie auf oder löscht sie. Sie beherrscht drei Protokolle:

Protokoll	Port	Verschlüsselung
`SFTP` (Standard)	22	SSH; Anmeldung mit Passwort und/oder Schlüsseldatei
`FTPS`	21 (`ImplicitTls`: 990)	TLS. Ein Server ohne TLS ist ein Fehler; RUNOS weicht nie auf unverschlüsseltes FTP aus.
`FTP`	21	keine: Passwort und Dateien gehen im Klartext

Damit Übertragungen zuverlässig sind, macht die Aktion Folgendes:

Jede Übertragung wird über die Größe geprüft. Nach dem Hochladen vergleicht RUNOS die Dateigröße auf dem Server mit der lokalen; beim Herunterladen muss die Datei mit der Größe ankommen, die der Server gemeldet hat. Weichen sie ab, zählt die Datei als Fehler. Einem Server, der keine Größe meldet, wird vertraut.
Heruntergeladene Dateien werden unter einem vorläufigen Namen geschrieben (name.part) und erst umbenannt, wenn sie vollständig und geprüft sind. Ein Datei-Trigger, der den Ordner überwacht, sieht nie eine halbe Datei.
Move löscht die Quelle erst nach der Prüfung. Lässt sich die Quelle nicht löschen, ist die Datei trotzdem angekommen: Das ist eine Warnung, kein Fehler, und die Datei wird beim nächsten Mal noch einmal übertragen.
Eine fehlerhafte Datei hält die anderen nicht auf. Am Ende schlägt die Aktion fehl, wenn eine Datei fehlgeschlagen ist oder Verbindung bzw. Anmeldung nicht geklappt haben. Wie bei jeder Aktion endet dann der Lauf oder die Fehlerbehandlung des Workflows greift (z. B. drei Wiederholungen mit RetryThenNotify).
Fehlende Ordner auf der Zielseite werden angelegt.

Im Workflow-Editor stellen Sie die Aktion in einem Formular zusammen und probieren sie mit Schritt testen aus.

Struktur

{
  "Type": "FTP",
  "Name": "RechnungSenden",
  "Parameters": {
    "Protocol": "SFTP",
    "Server": "sftp.partner.de",
    "User": "{{connector.Partner.Username}}",
    "Password": "{{connector.Partner.Password}}",
    "Fingerprint": "SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og",
    "Operation": "Upload",
    "Source": "{{FilePath}}",
    "Destination": "/eingang/rechnungen"
  }
}

Verbindung

Parameter	Standard	Bedeutung
`Protocol`	`SFTP`	`SFTP`, `FTPS` oder `FTP`. Ist er leer und `Server` eine URL, entscheidet deren Schema.
`Server`	–	Host (`sftp.example.com`), Host mit Port (`sftp.example.com:2222`) oder URL (`sftp://…`, `ftps://…`, `ftp://…`)
`Port`	`0`	`0` = der übliche Port des Protokolls (22, 21 bzw. 990 mit `ImplicitTls`). Geht einem Port in der URL vor.
`User`, `Password`	–	Anmeldung. FTP/FTPS ohne `User` meldet sich anonym an.
`PrivateKeyFile`, `PrivateKeyPassphrase`	–	SFTP: Schlüsseldatei (OpenSSH- oder PuTTY-Format) statt oder zusätzlich zum Passwort
`Fingerprint`	–	Nur diesen Server annehmen, siehe Fingerprint
`ImplicitTls`	`false`	FTPS: TLS ab dem ersten Byte (Port 990) statt `AUTH TLS` (Port 21)
`PassiveMode`	`true`	FTP/FTPS: passiver Modus. Nur `false`, wenn der Server aktiven Modus verlangt.
`IgnoreCertificateErrors`	`false`	FTPS: auch ein Zertifikat annehmen, dem Windows nicht vertraut (selbst signiert). Besser: `Fingerprint`.
`Timeout`	`60`	Sekunden für den Verbindungsaufbau und jede Antwort des Servers

Übertragung

Parameter	Standard	Bedeutung
`Operation`	`Upload`	`Upload`, `Download`, `List` oder `Delete`
`Source`	–	Was übertragen, aufgelistet oder gelöscht wird, siehe unten
`Destination`	–	`Upload`: Ordner auf dem Server (leer = Anmeldeordner). `Download`: Ordner auf diesem PC (Pflicht).
`Filter`	`*`	Ist `Source` ein Ordner: nur diese Dateien, z. B. `.pdf;.xml`
`Recursive`	`false`	Unterordner einbeziehen; ihre Struktur bleibt am Ziel erhalten
`IfExists`	`Overwrite`	Die Zieldatei gibt es schon: `Overwrite` (überschreiben), `Skip` (überspringen, zählt als `Skipped`) oder `Error` (zählt als Fehler)
`Move`	`false`	`Upload`/`Download`: Quelle nach geprüfter Übertragung löschen
`NewName`	–	`Upload`/`Download`: Name der Datei am Ziel. Kennt `%filename%`, `%filenamewithoutextension%`, `%extension%` (der jeweiligen Datei) sowie `%yyyy%`, `%MM%`, `%dd%`, `%HH%`, `%mm%`, `%ss%`.

Source ist je nach Operation:

Upload: ein oder mehrere Pfade auf diesem PC, getrennt durch ;: eine Datei ({{FilePath}}), ein Ordner (seine Dateien, die zu Filter passen) oder ein Muster wie C:\Export\*.xml. Eine Datei oder ein Ordner, den es nicht gibt, ist ein Fehler.
Download, List, Delete: ein Pfad auf dem Server: eine Datei (/ausgang/auftrag.xml), ein Ordner (/ausgang, seine Dateien, die zu Filter passen) oder ein Muster (/ausgang/*.xml). Eine Datei oder ein Ordner, den es nicht gibt, ist ein Fehler; ein Muster, zu dem nichts passt, nicht. Ein Pfad ohne führenden / beginnt im Anmeldeordner.

Delete löscht nur Dateien, nie Ordner, und braucht eine Source. List listet die Dateien auf (mit Recursive auch die der Unterordner).

Platzhalter in Pfaden: {{FilePath}}, {{InitialData…}}, Konnektoren und %yyyy%, %MM%, %dd% (z. B. /archiv/%yyyy%/%MM%) werden vor der Übertragung ersetzt.

Fingerprint

Ohne Fingerprint nimmt die Aktion jeden SFTP-Server an, der unter der Adresse antwortet, und jeden FTPS-Server, dessen Zertifikat Windows vertraut. Mit Fingerprint nimmt sie nur diesen einen Server an und lehnt jeden anderen vor der Anmeldung ab; das Passwort erreicht also nie einen falschen Server.

SFTP: der Host-Schlüssel, wie ssh, WinSCP oder FileZilla ihn zeigen: SHA256:ohD8VZ… (die ältere MD5-Form aa:bb:cc:… geht auch).
FTPS: der SHA-256- oder SHA-1-Hash des Zertifikats in Hex (mit oder ohne Doppelpunkte). Ein so festgelegtes Zertifikat wird auch angenommen, wenn es selbst signiert ist.

Den Fingerprint zeigt das Ergebnis: Jeder Lauf und jeder Test schreibt ihn nach Meta.Fingerprint. Testen Sie die Aktion also einmal ohne Fingerprint (Schritt testen in der Testansicht, z. B. mit dem Vorgang List) und tragen Sie den Wert aus der Ausgabe im Formular unter Fingerprint des Servers ein. Ändert sich der Schlüssel des Servers (neuer Server, neues Zertifikat), schlägt die Aktion mit einer entsprechenden Meldung fehl; tragen Sie dann den neuen Fingerprint ein.

Ergebnis

"Response": {
  "Results": [
    {
      "Source": "C:\\RUNOS\\Spooler\\…\\RE-2026-0001.xml",
      "Destination": "/eingang/rechnungen/RE-2026-0001.xml",
      "Size": 18342,
      "Status": "OK",
      "Message": ""
    }
  ],
  "SuccessCount": 1,
  "SkippedCount": 0,
  "ErrorCount": 0
},
"Meta": {
  "Host": "PC-01",
  "Protocol": "SFTP",
  "Server": "sftp.partner.de:22",
  "Fingerprint": "SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og"
}

Status ist OK, Skipped (gibt es schon, IfExists: Skip) oder Error mit dem Grund in Message. List liefert die Dateien stattdessen in Files, jede mit Name, Path, Size (Bytes, -1 wenn unbekannt) und Modified. Eine folgende Aktion liest sie als {{DateienAuflisten.Response.Files}}, z. B. in einem Loop.

Formular im Editor

Im Diagramm des Workflow-Editors hat die Aktion ein Formular (im Einstellungsfeld und in der mittleren Spalte der Testansicht):

Server: Protokoll SFTP, FTPS oder FTP; Server, Port (22, 21 bzw. 990), Benutzer und Passwort. Bei SFTP Datei mit privatem Schlüssel und Passphrase des Schlüssels; bei SFTP und FTPS Fingerprint des Servers (einmal ohne testen: das Ergebnis zeigt ihn unter Meta.Fingerprint, siehe Fingerprint); bei FTPS Implizites TLS (Port 990) und das Annehmen jedes Zertifikats; bei FTP und FTPS Passiver Modus (Standard an).
Dateien: Vorgang Upload, Download, List oder Delete; Quelle (beim Hochladen Lokale Dateien, sonst Pfad auf dem Server), Ziel (nur beim Hoch- und Herunterladen), Filter und Unterordner. Beim Hoch- und Herunterladen außerdem, was bei einer vorhandenen Datei passiert (Überschreiben, Überspringen, Fehler), Verschieben (Quelle löschen) (die Quelle wird erst nach der geprüften Übertragung gelöscht), ein neuer Name mit %filename% usw. und das Zeitlimit (Standard 60 Sekunden).

Jedes Feld nimmt auch {{…}}-Platzhalter und Werte, die Sie in der Testansicht aus der Spalte Eingabe hineinziehen; Auswahllisten, Schalter und Zahlenfelder werden mit einem {{…}} zu einem Textfeld. Parameter, die das Formular nicht kennt, stehen unter Weitere Parameter. Schritt testen führt die Aktion sofort einmal aus, mit den Daten der Schritte davor, und zeigt das Ergebnis mit Fehlern und Warnungen. Der Test überträgt bzw. löscht wirklich. Mit dem Vorgang List sehen Sie in der Ausgabe unter Response.Files, was auf dem Server liegt.

Beispiel

Jede Rechnung an den Partner senden. Ein Datei-Trigger nimmt jede XRechnung aus dem Exportordner und lädt sie auf den SFTP-Server des Partners, in einen Ordner pro Monat. Drei Wiederholungen bei Netzwerkproblemen:

{
  "Name": "Rechnungen an Partner",
  "Autostart": true,
  "Trigger": { "Type": "File", "Name": "Export", "Parameters": { "Pool": "C:\\Export\\XRechnung", "Filter": "*.xml" } },
  "Actions": [
    {
      "Type": "FTP",
      "Name": "Hochladen",
      "OnErrorPolicy": { "Strategy": "RetryThenNotify", "MaxRetries": 3, "InitialDelaySeconds": 10 },
      "Parameters": {
        "Server": "{{connector.Partner.BaseUrl}}",
        "User": "{{connector.Partner.Username}}",
        "Password": "{{connector.Partner.Password}}",
        "Fingerprint": "SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og",
        "Operation": "Upload",
        "Source": "{{FilePath}}",
        "Destination": "/eingang/%yyyy%-%MM%",
        "IfExists": "Error"
      }
    }
  ]
}

Alle 15 Minuten Aufträge abholen. Alle neuen XML-Dateien aus dem ausgang des Partners herunterladen und dort entfernen (Move), in einen Ordner, den ein anderer Workflow überwacht. Weil Downloads unter einem vorläufigen Namen ankommen, sieht dieser Workflow nur vollständige Dateien:

{
  "Name": "Aufträge abholen",
  "Autostart": true,
  "Trigger": { "Type": "Time", "Name": "Alle15Min", "Parameters": { "CronExpression": "0 0/15 * * * ?" } },
  "Actions": [
    {
      "Type": "FTP",
      "Name": "Abholen",
      "Parameters": {
        "Protocol": "FTPS",
        "Server": "ftp.partner.de",
        "User": "{{connector.PartnerFtp.Username}}",
        "Password": "{{connector.PartnerFtp.Password}}",
        "Operation": "Download",
        "Source": "/ausgang/*.xml",
        "Destination": "C:\\Import\\Auftraege",
        "Move": true
      }
    }
  ]
}