Thema Technische Benutzerdokumentation - WBFileExchanger Workbooster File Exchanger Command Line Tool Letzte Anpassung 18. Januar 2014 Status / Version Finale Version - V 1.1 Summary Erstellung Diese technische Dokumentation erklärt die Bedienung der Workbooster File Exchanger Software für den automatisierten Austausch von Dateien (z.b. von einem FTP Server auf ein lokales Laufwerk). Roger Guillet Workbooster GmbH roger.guillet@workbooster.ch +41 (0)44 515 48 87 Inhalt Grundlagen... 2 Unterstützte Quell-/Zielsysteme... 2 Aufruf... 2 Verarbeiten mehrerer Verzeichnisse... 2 Steuerung... 2 Konfiguration... 3 Verbindungsinformationen (Connections)... 3 Parameter... 4 Protokollierung... 5 Meldungen... 5 Ausgabe... 5 Log-Files... 6 Technische Benutzerdokumentation - WBFileExchanger.docx Seite 1 von 6
Grundlagen Beim WBFileExchnager handelt es sich um eine Applikation, welche über die Windows Kommandozeile ausgeführt wird. Sie ermöglicht es den Transfer von Dateien von einer Datenquelle zu einem Datenempfänger zu automatisieren (z.b. mit dem Windows Task Scheduler). Unterstützte Quell-/Zielsysteme Zur Zeit werden die folgenden Systeme unterstützt: Lokales Filesystem Datenträger und Netzwerk-Shares des Systems auf dem WBFileExchanger ausgeführt wird. FTP Upload und Download über das File Transfer Protocol. Aufruf Bei einem Aufruf der Applikation über die Konsole werden Dateien von einem Quellsystem zu einem Zielsystem kopiert. Mittels Parameter kann eingestellt werden, von wo die Dateien abgeholt und wohin diese kopiert werden sollen. Beispiel für ein Aufruf mit lange Parameternamen: WBFileExchanger.exe --sourceconnection "DistributorFTP" --sourcerelativepath "subdirectory/1/" --destinationconnection "DriveC" --destinationrelativepath "temp\data\" --fileextensionfilter "csv" --deletesourcefiles --logfilepath "C:\temp\log" --logfileseveritylevel "Debug" Beispiel für einen Aufruf mit kurzen Parameternamen: WBFileExchanger.exe -s " DistributorFTP" -x "subdirectory/1/" -d "DriveC" -y "temp\data\" -e "csv" -o -l "C:\temp\log" -f "Debug" Das Beispiel zeigt, wie der Aufruf von WBFileExchanger aussehen könnte, wenn Dateien von einem FTP Server abgeholt und in ein lokales Verzeichnis kopiert werden sollen. Die einzelnen Parameter, sowie die «Connections» («sourceconnection» und «destinactionconnection») werden weiter unten noch detailliert erklärt. Verarbeiten mehrerer Verzeichnisse Der WBFileExchanger arbeitet pro Aufruf nur mit einer Quelle und einem Ziel. Sollen mehrere Verzeichnisse verarbeitet werden, so muss der WBFileExchanger mehrmals aufgerufen werden. Steuerung Die Applikation läuft ausschliesslich als Konsolenapplikation. Es gibt keine grafische Benutzeroberfläche (GUI). Die Steuerung geschieht mittels Parametern, welche beim Aufruf der Applikation über die Konsole mitgegeben werden. Allgemeine Einstellungen zum Verhalten der Applikation, Technische Benutzerdokumentation - WBFileExchanger.docx Seite 2 von 6
sowie Verbindungsinformationen (Connection) zu den Quell-/Zielsystemen müssen in dem Config-File der Applikation hinterlegt werden können. Konfiguration Das Config-File heisst «WBFileExchanger.exe.config» und liegt in demselben Verzeichnis wie die Applikation selbst. Nachfolgend ein Beispiel, wie das Config-File in etwa aussehen könnte: <?xml version="1.0"?> <configuration>... <WBFileExchanger> <connections> <add name="drivec" provider="filesystem" path="c:\" /> <add name="distributorftp" provider="ftp" path="someserver.com" user="usr" password="mypassword" /> </connections>... </WBFileExchanger>... </configuration> Für die Steuerung ist vor allem der Abschnitt unter «WBFileExchanger» «connections» wichtig. Verbindungsinformationen (Connections) Die Verbindungsinformationen der Quell- und Zielsysteme («Connection») werden im Config-File der Applikation gespeichert. Diese können anschliessend mit ihrem Namen beim Aufruf des WBFileExchanger als «sourceconnection» oder als «destinationconnection» angebene werden. Folgende Informationen können erfasst werden: Name Type Muss Beschreibung name string Ja Eindeutige Bezeichnung der Verbindung (Unique). Beispiel: «DistributorFTP» provider string Ja Verbindungstyp. Zur Auswahl stehen: «filesystem», «ftp» path string Ja Adresse des Servers. Beispiele: «ftp://someserver.com/» oder «\\networkshare\» oder «C:\» user string Nein Benutzername für Login password string Nein Passwort für Login Technische Benutzerdokumentation - WBFileExchanger.docx Seite 3 von 6
parameters string Nein Eine durch Semikolon «;» getrennte Liste mit zusätzlichen Verbindungsparameter spezifisch für den entsprechenden Provider. Beispiel: «apikey=xxyyzz;requestmethod=post» Parameter Folgende Parameter können beim Ausführen des «WBFileExchanger.exe» mitgegeben werden: Parameter Type Muss Beschreibung --help - Nein Zeigt einen Hilfe-Text mit der Beschreibung der Parameter an. -s --sourceconnection -x --sourcerelativepath -d --destinationconnection -y --destinationrelativepath -e --fileextensionfilter -o --deletesourcefiles string Ja Bezeichnung der Verbindung, die als Quellsystem verwendet werden soll. Beispiel: «DistributorFTP» string Nein Relativer Pfad unterhalb des Basis-Pfad der Quellsystem-Verbindung. Beispiel: Basis-Pfad = «ftp://someserver.com/» Relative Path = «subdirectory/1/» Ergibt folglich den Pfad: «ftp://someserver.com/subdirectory/1/» string Ja Bezeichnung der Verbdingung, die als Zielsystem verwendet werden soll. Beispiel: «DriveC» string Nein Relativer Pfad unterhalb des Basis-Pfad der Quellsystem-Verbindung. Beispiel: Basis-Pfad = «C:\» Relative Path = «temp\data\» Ergibt folglich den Pfad: «C:\temp\data\» string Nein Eine Komma «,» getrennte Liste mit Dateitypen, welche übertragen werden sollen. Beispiel: «xml,csv,txt» Es werden nur Dateien mit einer dieser Endungen übertragen. bool Nein Sollen die Dateien auf dem Quellsystem nach dem Übertragen gelöscht werden? Wenn ja muss dieser Parameter angegeben werden. Default=true -l string Nein Absoluter Pfad Verzeichnis in dem die Log-Files abgelegt werden sollen. Technische Benutzerdokumentation - WBFileExchanger.docx Seite 4 von 6
--logfilepath -f --logfileseveritylevel Beispiel: «C:\Temp\log\» string Nein Ab welchem Schweregrad sollen die Log- Meldungen in das Log File geschrieben werden? Mögliche Werte: Debug, Info, Warning, Error Default=Info Protokollierung Der Erfolg oder der Misserfolg eines Transfers kann anhand der Protokollierung nachvollzogen werden. Meldungen Die Applikation loggt alle Vorgänge, damit im Nachhinein nachvollzogen werden kann, welche Aktionen ausgeführt wurden und wo unter Umständen Fehler aufgetreten sind. Für Log-Meldungen gibt es unterschiedliche Schweregrade: Debug Meldungen mit denen technisch detailliert nachvollzogen werden kann, welche Programm-Schritte ausgeführt und welche Daten dabei verwendet wurden. (z.b. die Ausgabe der Parameter und Konfigurationseinträge welche beim Aufruf der Applikation verwendet wurden) Info Informationen für den Endbenutzer was ausgeführt wurde. (z.b. wie viele Dateien übertragen wurden.) Warning Meldungen zu Umständen, die evtl. ein Problem werden könnten. (z.b. wenn Dateien zwar übertragen wurden, aber nicht gelöscht werden konnten.) Error Es ist ein Fehler aufgetreten, welcher den korrekten Programmablauf verhindert. (z.b. zwingend benötigte Konfigurationseinträge fehlen oder ein Server ist nicht erreichbar) Ausgabe Die Log-Meldungen werden dem Benutzer zur Laufzeit ab dem Schweregrad «Info» in der Konsole ausgegeben. Ausserdem können die Meldungen in einem Log-File gespeichert werden, sofern ein entsprechender Parameter beim Aufruf der Applikation angegeben wurde. Die Ausgabe in der Konsole sieht bei einem Erfolg in etwa so aus: INFO: Start Exchange INFO: <- FTP File: bitze.li:21/tst01.gaggibissi.ch/test/uninstall.csv INFO: <- FTP File: bitze.li:21/tst01.gaggibissi.ch/test/test.csv INFO: Write Files to destination Filesystem: C:\temp\\ INFO: -> File: C:\temp\\test.csv INFO: -> File: C:\temp\\uninstall.csv INFO: Exchange finished Technische Benutzerdokumentation - WBFileExchanger.docx Seite 5 von 6
Log-Files Wurde beim Aufruf der Parameter «logfilepath» mitgeben, so wird ein Log-File in das angegebene Verzeichnis geschrieben. Der Dateinamen eines Log-Files enthält das Datum und die Uhrzeit der Ausführung. Beispiel: 2013-12-10_09-17-02.txt Format: «Jahr»-«Monat»-«Tag»_«Stunde»-«Minute»-«Sekunde».txt Technische Benutzerdokumentation - WBFileExchanger.docx Seite 6 von 6