Handbuch FTAPI® Starter / Professional Edition Version
Werbung
Handbuch FTAPI® Starter / Professional Edition Version 1.1.4 Q3 / 2011 FTAPI® Software UG (haftungsbeschränkt) Heßstraße 89 80797 München Ticketing‐System: http://support.ftapi.com E‐Mail: [email protected] Tel.: +49 (0)89 / 1265 3105 Webseite: www.ftapi.com Handbuch FTAPI 1.1.4 Inhaltsverzeichnis 1. FTAPI Handbuch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.1.1 Apache Tomcat als Windows Dienst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Konfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.1 SMTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.2 DNS-Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.3 Datenablage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.3.1 Metadaten (Datenbank) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.3.2 Binärdaten (Storage) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.4 Staging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.5 Pfade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.6 Rollen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.7 Applet Konfigurationsmöglichkeiten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.8 HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2.8.1 Redirect HTTP zu HTTPS einrichten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 Web-Interface (WebUI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.4 LDAP und Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.5 SubmitBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.6 Download Disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.7 Web-Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.8 E-Mail Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.9 Benutzer importieren . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.10 FTAPI Client - BETA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.11 Action Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.12 Serverseitiges Scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.13 FTAPI REST Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.14 Tools und Erweiterungen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.14.1 FTAPI Ant Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.15 ChangeLog 1.1.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.16 FAQ (1.1.4) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 4 5 6 8 10 10 13 15 16 16 17 21 24 25 30 37 38 39 39 40 40 43 43 46 63 63 68 69 FTAPI Handbuch Diese Dokumentation bezieht sich auf die Versionen FTAPI Starter, Professional und Enterprise 1.1.4 und ist vor allem für Administratoren und Integratoren des Systems bestimmt. Falls bestimmte Bereiche nicht für alle drei genannten Versionen gültig sind, ist dies zu deren Beginn vermerkt! Installation Nachfolgend erfahren Sie, wie Sie in wenigen Schritten FTAPI für einen ersten Testlauf installieren und konfigurieren können. Voraussetzungen Um den FTAPI Server betreiben zu können, benötigen Sie einen entsprechend leistungsfähigen Rechner. Unsere minimale Empfehlung liegt bei mind. 2 Ghz Prozessor, mind. 2 GB freier RAM und mind. 50 GB freier Festplattenspeicher, sowie einer ausreichend schnellen Netzwerkanbindung. Darüber hinaus müssen Sie sicherstellen, dass auf dem Server die Java Version 1.6 oder höher (JRE ist ausreichend) installiert haben. Diese Information können Sie durch Eingabe des folgenden Befehls in Ihre Konsole/Terminal ermitteln: java -version Anschließend sollten Sie eine Ausgabe ähnlich der folgenden erhalten: java version "1.6.0_21" Java(TM) SE Runtime Environment (build 1.6.0_21-b07) Java HotSpot(TM) Client VM (build 17.0-b17, mixed mode, sharing) Sollte Sie eine Java Version kleiner als 1.6 installiert haben oder der Befehl nicht gefunden werden, dann installieren Sie bitte eine aktuelle Java-Version auf ihrem System. Diese können Sie kostenlos unter folgender URL beziehen: JRE unter http://www.java.com oder http://java.sun.com/j2se Java JDK unter http://www.oracle.com/technetwork/java/javase OpenJDK Die Java-Variante OpenJDK reicht für den Betrieb von FTAPI nicht aus! Proxy-Server Der Betrieb mit einem Proxy-Server ist nicht empfohlen; richten Sie bitte für Ihre FTAPI URL eine Proxy-Ausnahme ein. Hinterlegen Sie hierzu eine Ausnahme für ftapi.ihre-domain.com* in Ihren Gruppenrichtlinien. Details entnehmen Sie unseren FAQs. Schritt 1 - Entpacken und installieren Nachdem Sie das FTAPI-Software-Paket heruntergeladen haben, entpacken Sie dieses bitte zunächst in ein Verzeichnis Ihrer Wahl. Nun sollten Sie im entpackten FTAPI Software Paket unter anderem das Verzeichnis "ftapi-server" vorfinden. Schritt 2 - Server starten Wechseln Sie in das Verzeichnis "ftapi-server". In diesem Verzeichnis befindet sich eine gebündelte Version von FTAPI mit dem Servlet-Container Apache Tomcat. Starten Sie nun direkt FTAPI, indem sie einfach das Skript ftapi-start.bat (unter Windows) bzw. ftapi-start.sh (unter Linux) ausführen. © FTAPI Software UG (2011), Seite 2 FTAPI-Server auf Linux ausführen Im Terminal/Konsole die Berechtigungen der folgenden Dateien und Ordner mit chmod +x auf "ausführbar" setzen /ftapi-server/ftapi-start.sh und ftapi-stop.sh /ftapi-server/bin/*.sh Eine spezielle Anleitung zum Einrichten unter Linux mittels einer grafischen Oberfläche finden Sie in unseren FAQs! FTAPI-Server Neustart Für einen Server-Neustart müssen Sie diesen zuvor über die Datei ftapi-stop.bat (unter Windows) bzw. ftapi-stop.sh (unter Linux/Mac) herunterfahren, oder das Tomcat-Eingabeaufforderungsfenster (unter Windows) einfach schließen. Erst nachdem der Server vollständig gestoppt wurde, kann dieser (wie zu Beginn von Schritt 2 erläutert) neu gestartet werden. FTAPI ohne Tomcat FTAPI wird zwar mit dem Servlet-Container Apache Tomcat ausgeliefert, allerdings können Sie FTAPI auch in einem anderen Servlet-Container betreiben. Kopieren Sie hierfür einfach die Datei ftapi-server/webapps/ftapi-server.war in Ihren gewünschten Servlet-Container. FTAPI wurde derzeitig nur auf Apache Tomcat ausführlich getestet. Für die Lauffähigkeit auf anderen Servlet-Containern kann keine Garantie übernommen werden. Schritt 3 - Browser starten Nachdem der Server erfolgreich gestartet wurde, öffnen Sie Ihren Web-Browser und geben Sie die Adresse http://localhost:8080/ftapi-server ein und folgen Sie den dortigen Anweisungen: SMTP-Sever konfigurieren Öffnen Sie die Datei .ftapi/config/server-production.properties und suchen Sie darin nach folgendem Eintrag: ftapi.email.charset=ISO-8859-1 ftapi.email.from.address=notify@localhost ftapi.email.from.name=notify@localhost ftapi.email.smtp.host= ftapi.email.smtp.port=25 ftapi.email.smtp.username= ftapi.email.smtp.password= ftapi.email.smtp.useSSL=false ftapi.email.smtp.useTLS=false Geben Sie hier bitte die Einstellungen zu Ihrem E-Mail-Server ein und speichern Sie anschließend die Datei. Versteckte Ordner unter Linux Der Ordner .ftapi wird in Linuxumgebungen als versteckter Ordner behandelt. Die Anzeige versteckter Ordner kann im Dateibrowser in den Einstellungen aktiviert werden.Mehr hierzu in der speziellen Anleitung zum Einrichten unter Linux finden Sie in unseren FAQs! Basis-URL konfigurieren (optional) Sollte Sie FTAPI nur lokal testen wollen, so müssen Sie diese Einstellung nicht durchführen. Möchten Sie allerdings mit FTAPI auch an andere Empfänger Pakete versenden und diesen den Zugriff auf das FTAPI-System ermöglichen, so müssen Sie zusätzlich noch die Basis-URL einstellen, welche Sie ebenfalls in der Konfigurationsdatei server-production.properties vorfinden: ftapi.base.url=http://localhost:8080/ftapi-server Ändern Sie diese URL auf diejenige URL ab, unter welcher Ihr FTAPI-Server "von außen" erreichbar ist. Beispiel: http://www.ihre-domain.com:8080/ftapi-server. © FTAPI Software UG (2011), Seite 3 Wie Ihre Basis-URL lautet, hängt davon ab, wie Sie FTAPI in Ihr Netzwerk eingebunden haben. Darüber hinaus kann es auch notwendig werden, den Port 8080 entsprechend anzupassen. Diese Einstellungen können Sie in der Datei ftapi-server/conf/server.xml vornehmen. Für tiefergehende Informationen zu dieser Konfigurationsdatei werfen Sie bitte einen Blick in die offizielle Apache Tomcat Dokumentation: http://tomcat.apache.org/tomcat-6.0-doc/index.html Beachten Sie, dass Sie Ihre Firewall ggfs. für einen anderen Port einstellen müssen, damit dieser von extern erreichbar ist! Storage-Größe konfigurieren (optional) Im Auslieferungszustand ist FTAPI in der Konfigurationsdatei server-production.properties auf 10GB maximales Speichervolumen eingestellt. Sie können diesen Wert- je nach Ihren Gegebenheiten - beliebig anpassen oder mit "-1" auf unendlich setzen: # The max size of all files together in this storage Default: 10240000000 (10GB), For no quota at all set to: \-1 ftapi.storage.quota=10240000000 Merh Details hierzu erfahren Sie im Bereich der Konfiguration unter Binärdaten (Storage)! Lizenzdatei aktivieren und -bedingungen zustimmen Wählen Sie im Dialog die Lizenzdatei aus, welche Sie vom FTAPI Vertrieb erhalten haben und aktivieren Sie diese, indem Sie auf den Button "Lizenzdatei laden" drücken. Nach dem Laden Ihrer Lizenzdatei werden Sie im nächsten Schritt aufgefordert, die angezeigten Lizenzbedingungen (Disclaimer) zu akzeptieren, um das FTAPI System verwenden zu dürfen. Schritt 4 - Erstmaliger Login Starten Sie zum Einlesen der E-Mail Konfiguration den FTAPI Server neu (siehe Schritt 2. - Server starten) Nach der Konfiguration Ihres SMTP-Servers und dem Aktivieren Ihrer vom FTAPI Vertrieb zugesandten Lizenzdatei, stehen Sie auf der FTAPI Login-Seite. Für Ihren erstmaligen Login verwenden Sie bitte die folgenden Daten: Benutzername: admin Passwort: admin Bitte ändern Sie im Anschluß direkt das Administratorpasswort über die Benutzereinstellungen (Zahnradsymbol rechts oben oder über Benutzer-Tab)! Apache Tomcat als Windows Dienst Apache Tomcat als Windows Dienst betreiben Die wichtigsten Vorteile von Tomcat als Windows Dienst sind Reduziertes Risiko eines Versehentlichen Schließens der FTAPI Tomcat Instanz; wenn Sie Tomcat manuell starten, öffnet sich ein Konsolenfenster welches dauerhaft offen bleibt. Das Risiko, dass jemand dieses Fenster und damit FTAPI komplett aus Versehen schließt, ist hierbei recht hoch. Automatisiertes Hochfahren (Recovery) des Tomcat FTAPI Dienstes nach einem Serverneustart. Verbesserte Problembehandlung aufgrund von zusätzlichen Logausgaben des Servers in Dateiformat. ApacheTomcat als Windows-Dienst für FTAPI einrichten Um den Apache Tomcat6 Dienst zu installieren, werden folgende zwei Dateien auf Ihrem FTAPI System benötigt: ftapi-service-install.bat ftapi-service-uninstall.bat Alle Dateien befinden sich im Verzeichnis \ftapi-server; falls diese bei Ihnen nicht vorhanden sein sollten, wenden Sie sich bitte an den FTAPI Support. Führen Sie über die Eingabeaufforderung (muss mit Administratorrechten geöffnet sein) im ftapi-server Verzeichnis die folgende Datei aus: ftapi-service-install.bat Es sollten in der Eingabeaufforderung folgende Zeilen (mit Ihren entsprechenden Pfadangaben) erscheinen: © FTAPI Software UG (2011), Seite 4 Installing the service 'Tomcat6' ... Using CATALINA_HOME: "C:\FTAPI\ftapi-server" Using CATALINA_BASE: "C:\FTAPI\ftapi-server" Using JAVA_HOME: "C:\Program Files\Java\jdk1.6.0_18" Using JVM: "C:\Program Files\Java\jdk1.6.0_18\jre\bin\server\jvm.dll" The service 'Tomcat6' has been installed. Weitere Info http://tomcat.apache.org/tomcat-6.0-doc/windows-service-howto.html#Installing_services In LINUX-Umgebungen als Hintergrundprozess einrichten: http://tomcat.apache.org/tomcat-6.0-doc/setup.html#Unix_daemon Apache Tomcat Windows-Dienst deinstallieren Nachfolgend wird kurz erläutert, wie Sie den Apache Tomcat6 Dienst deinstallieren. Es wird hierbei NUR der Windows-Dienst entfernt - keine sonstigen Dateien! Führen Sie in der Eingabeaufforderung (muss mit Administratorrechten geöffnet sein!) aus Ihrem ftapi-server Verzeichnis heraus folgenden Aufruf aus: ftapi-service-uninstall.bat Der Apache Tomcat6 Dienst wird zuvor automatisch gestoppt und dann vollständig deinstalliert. Bei erfolgreicher Deinstallation des Dienstes wird in der Eingabeaufforderung folgende Zeile ausgegeben: The service 'Tomcat6' has been removed. Apache Tomcat Windows-Dienst Einstellungen ändern Wenn Sie an Ihrem ApacheTomcat6 Dienst Änderungen vornehmen möchten (z.B. unter einem anderen Benutzer ausführen, Pfade anpassen, o.ä.), gehen Sie wie folgt vor: Änderung des Dienst-Starttyps: In den Dienst-Eigenschaften (mit Admin-Rechten) kann der Starttyp (manuell, automatisch, usw.) jederzeit angepasst und geändert werden. Änderung des Anmelde-Kontos: Direkt in den Windows-Diensten (Aufruf über services.msc) den Apache Tomcat6 Dienst bearbeiten und die Anmeldeinformationen eines bestimmten Benutzers, unter dem dieser Dienst für FTAPI ausgeführt werden soll (i.d.R. Administrator), eintragen. Pfadangabe des Tomcat-Verzeichnisses ändern: Der Pfad kann nicht direkt im Dienst angepasst werden - es wird empfohlen, den Dienst zuvor komplett zu deinstallieren und beim Neueinrichten die CATALINA_HOME Variable in der Datei install_ftapi_service.bat entsprechend dem neuen/geänderten Pfad anzugeben. Standardmäßig ist der Pfad zum Tomcat BIN-Verzeichnis so gesetzt, dass dieser sich direkt unterhalb von \ftapi-server\ befindet. Der Standardpfad lautet set CATALINA_HOME=%cd% - dies setzt CATALINA_HOME auf den Beispielordner C:\FTAPI\ftapi-server\ Pfadangabe des .ftapi-Verzeichnisses ändern: Der Pfad kann nicht direkt im Dienst angepasst werden - es wird empfohlen, den Dienst zuvor komplett zu deinstallieren und beim Neueinrichten die FTAPI_HOME Variable in der Datei install_ftapi_service.bat entsprechend dem neuen/geänderten Pfad anzugeben. Standardmäßig ist der Pfad zum .ftapi-Verzeichnis so gesetzt, dass der Order \.ftapi\ auf der gleichen (Hierarchie-)Ebene wie auch \ftapi-server\ angesiedelt ist. Der Standardpfad lautet set FTAPI_HOME=%CATALINA_HOME%/../.ftapi - dies setzt FTAPI_HOME auf den Beispielordner C:\FTAPI\.ftapi Konfiguration FTAPI besitzt einen äußerst flexiblen Konfigurationsmechanismus, der sich in verschiedene Bereiche unterteilt, die nachfolgend näher erläutert werden. Durch diese Flexibilität lässt sich FTAPI optimal an Ihre Bedürfnisse anpassen. Konfigurationsdatei (Properties-Datei) Die zentrale Konfigurationsdatei von FTAPI (als Properties-Datei bezeichnet) befindet sich standardmäßig im Verzeichnis /.ftapi/config. Beim erstmaligen Start des Serversystems wird dieses Verzeichnis neu angelegt. Der Name der Konfigurationsdatei ist standardmäßig © FTAPI Software UG (2011), Seite 5 server-production.properties. Zusätzlich lassen sich je nach Betriebsmodus (Stage) auch unterschiedliche Konfigurationsdateien laden (server-development.properties oder server-assembly.properties). Dies ist aber nur relevant, wenn Sie für FTAPI verschiedene Betriebsmodi vorsehen. Mehr hierzu erfahren Sie im Kapitel Staging. Überschreiben von Konfigurationswerten FTAPI unterstützt das sogenannte "Shadowing" oder auf deutsch, das Überschreiben von bestehenden Konfigurationswerten. Dabei werden die Konfigurationswerte in drei Stufen gesetzt, wobei die nachfolgende Stufe die Konfigurationswerte der vorhergehenden Stufe überschreibt (z.B. 2. überschreibt 1.). Diese Stufen lauten: 1. Standardwerte (vom System vorgegeben und können vom Anwender nicht direkt verändert werden) 2. Die Datei server-production.properties im Verzeichnis /.ftapi/config (diese kann verändert werden) 3. Java-System-Properties, die z.B. beim Systemstart in der Form -D<name>=<wert> gesetzt werden können. Ein Beispiel: Angenommen, Sie möchten das Property ftapi.base.url anpassen. Nachfolgend ist dargestellt, wie dies geschehen könnte: 1. Standardmäßig ist dieses Property vom System folgendermaßen gesetzt: ftapi.base.url=http://localhost:8080/ftapi 2. Wenn Sie nun in der Datei server-production.properties folgenden Eintrag machen ftapi.base.url= http://localhost, so lautet die URL nun http://localhost und der Standardwert http://localhost:8080/ftapi ist damit überschrieben. 3. Möchten Sie aber nun beispielsweise nur kurzzeitig diese URL ändern, ohne die Property-Datei bearbeiten zu müssen, können Sie beim Start des Servlet-Containers dem Parameter -Dftapi.base.url=http://localhost:8181 mitgeben. In diesem Fall wird der Wert aus der Property-Datei http://localhost mit diesem http://localhost:8181 überschrieben. Bitte beachten Sie, dass bei Änderungen an den Konfigurationswerten das Serversystem stets neu gestartet werden muss. SMTP FTAPI versendet in den verschiedensten Situationen E-Mail-Nachrichten. Z.B. an den Empfänger, wenn ein neues Datenpaket für Ihn bereitgestellt wurde (das sogenannte "Download-Ticket"). Hierfür ist es notwendig, einen SMTP-Server zu konfigurieren, der als Gateway für den E-Mail-Versand zwischen Ihrem FTAPI-System und dem jeweiligen Anwender dient. Bitte beachten Sie, dass ohne Konfiguration eines SMTP-Servers kein korrekter Betrieb von FTAPI möglich ist. Konfigurationseinstellungen ftapi.email.charset ftapi.email.from.address ftapi.email.from.name ftapi.email.smtp.host ftapi.email.smtp.port ftapi.email.smtp.username ftapi.email.smtp.password ftapi.email.smtp.useSSL ftapi.email.smtp.useTLS E-Mail-Benachrichtigungen Neues Datenpaket bzw. neuer Submit Submit-Ticket Aktivierung Fehlermeldungen und Verbesserungsvorschläge Konfigurationseinstellungen Die Einstellungen zum SMTP-Server werden in der Datei /.ftapi/config/server-production.properties im folgenden Abschnitt gemacht: © FTAPI Software UG (2011), Seite 6 #-------------------------------------------------------------------# Email settings #-------------------------------------------------------------------ftapi.email.charset=ISO-8859-1 [email protected] ftapi.email.from.name=FTAPI System ftapi.email.smtp.host= ftapi.email.smtp.port=25 ftapi.email.smtp.username= ftapi.email.smtp.password= ftapi.email.smtp.useSSL=false ftapi.email.smtp.useTLS=false Nachfolgend werden die einzelnen Konfigurationsoptionen näher erläutert. Bitte beachten Sie, dass keinerlei Leerzeichen am Ende eines Eintrags verbleiben! ftapi.email.charset Das Encoding, welches verwendet werden soll (z.B. ISO-8859-1 oder UTF-8). ftapi.email.from.address Die Absenderadresse, welche bei Systembenachrichtigungen in der E-Mail erscheinen soll. Diese muss nicht mit dem smtp.username übereinstimmen oder überhaupt existieren. ftapi.email.from.name Der Name des Absenders, welcher bei Systembenachrichtigungen in der E-Mail erscheinen soll. Dies kann ein beliebiger Name sein, der nicht mit dem smtp.username übereinstimmen muss. ftapi.email.smtp.host Der Hostname des SMTP-Servers. ftapi.email.smtp.port Der Port des SMTP-Servers. ftapi.email.smtp.username Der Benutzername des SMTP-Accounts, falls eine Authentifizierung erforderlich ist. ftapi.email.smtp.password Das Passwort des SMTP-Accounts, falls eine Authentifizierung erforderlich ist. ftapi.email.smtp.useSSL Gibt an, ob eine sichere Verbindung über SSL verwendet werden soll (true) oder nicht (false). ftapi.email.smtp.useTLS Gibt an, ob eine sichere Verbindung über TLS verwendet werden soll (true) oder nicht (false). E-Mail-Benachrichtigungen Nachfolgend werden kurz die jeweiligen E-Mail-Benachrichtigungen beschrieben, die FTAPI als E-Mail versendet. Das Format einer E-Mail-Benachrichtung wird durch ein sogenanntes E-Mail-Template festgelegt. Alle E-Mail-Templates befinden sich im Verzeichnis WEB-INF\classes\com\ftapi\notification Ihrer FTAPI-Server-Installation. Bitte beachten Sie, dass Änderungen an den E-Mail-Templates nur durch den FTAPI-Support durchgeführt werden sollten. Falls Sie dennoch diese E-Mail-Templates selbst anpassen möchten, kann FTAPI hierfür keine Haftung übernehmen. Falls dadurch Probleme im Betrieb von FTAPI entstehen, sind Sie hierfür selbst verantwortlich. Neues Datenpaket bzw. neuer Submit © FTAPI Software UG (2011), Seite 7 Nachdem ein Benutzer ein Datenpaket an einen beliebigen Empfänger versendet hat bzw. über die SubmitBox eingereicht hat, erhält dieser eine E-Mail mit einem eingebetten Download-Link. Diese E-Mail hat folgendes Format: ${delivery.message.body} --Bitte klicken Sie hier, um den Download zu starten: $config.get("ftapi.base.url")/download/${delivery.uuid} Die Variable ${delivery.message.body} entspricht dabei dem Text, welchen der Versender eingetragen hat. Die Variablen $\config.get("ftapi.base.url")/download/${delivery.uuid} wird durch den Download-Link ersetzt. Submit-Ticket Aktivierung Nachdem ein Benutzer über die SubmitBox seine E-Mail-Adresse eingegeben und auf "Submit-Ticket anfordern" geklickt hat, erhält er eine Aktivierungs-E-Mail mit einem eingebetten Link, dem so genannten "Submit-Ticket". Darüber kann er das Einreichen der Daten durchführen. Diese E-Mail hat standardmäßig folgendes Format: Guten Tag ${createdBy.displayLabel}, es wurde ein Submit-Ticket für Sie bereitgestellt. Bitte klicken Sie auf diesen Link, um direkt mit dem sicheren Upload Ihrer Daten zu beginnen: $config.get("ftapi.base.url")/submit/submitPortal.html?submitTicketUuid=${ticket.uuid} Vielen Dank, dass Sie FTAPI für den Versand Ihrer Daten verwenden. Ihr FTAPI Team Fehlermeldungen und Verbesserungsvorschläge Der Benutzer hat die Möglichkeit, auf einfache Art und Weise direkt an den FTAPI-Support eine E-Mail zu versenden. Z.B., wenn ein Fehler aufgetreten ist oder wenn Verbesserungsvorschläge kommuniziert werden sollen. Das Format dieser E-Mail sieht folgendermaßen aus: Der FTAPI-Benutzer ${issue.reporterEmail} hat ein Problem an einer FTAPI-Installation festgestellt. ------------ Beginn allgemeine Informationen -----------User: ${issue.reporterEmail} Server: ${issue.ftapiServer} Version: ${issue.ftapiVersion}-${issue.buildNumber} Customer: ${issue.customerName} #if($issue.evaluationLicense) License: ${issue.licenseInfo} [Evaluation] Evalutaion end date: ${issue.evaluationEndDate} #else License: ${issue.licenseInfo} #end Ticket-ID: ${issue.ticketId} Subject: ${issue.subject} ------------ Beginn Fehlermeldung ----------------------${issue.message} DNS-Server Grundsätzlich sollte Ihr FTAPI-Server über eine einheitliche URL sowohl von Extern (Lieferanten und sonstige Firmen) wie auch von Intern (Mitarbeiter und Partner im gleichen Netzwerk) erreichbar sein. Um dies zu ermöglichen, muss für die internen Clients ein spezieller Eintrag in Ihrem DNS-Server vorgenommen werden. Es wird empfohlen, sich für FTAPI eine eigene Subdomain, wie z.B. ftapi.ihre-domain.com, als feste URL einzurichten. © FTAPI Software UG (2011), Seite 8 Einstellungen am DNS-Server 1. Im ersten Schritt im DNS-Server eine neue Forward-Lookupzone einrichten. FTAPI Base URL Die Forward-Lookupzone muss genau dem Eintrag zur ftapi.base.url in der Datei .ftapi/config/server-production.properties entsprechen! Wenn Ihre FTAPI URL beispielsweise http://ftapi.ihre-domain.com lautet, dann muss die Forward-Lookupzone hierfür ftapi.ihre-domain.com lauten. 2. Im zweiten Schritt dann dort einen Host (A)-Eintrag einrichten, der auf den FTAPI-Server verweist (in den nachfolgenden Screenshots verweist ihre-domain-ftapi.de auf den Server mit de festen IP-Adresse 192.168.89.100). Die Einstellungen sehen dann wie folgt aus: Diese Einstellungen führen dann zu dem gewünschten Ergebnis, dass alle Clients im internen Netz das FTAPI-System direkt auch von intern ansprechen. Überprüfen der Einstellungen Die Korrektheit der Zuordnungen und Weiterleitungen kann auf einem internen Client über die Eingabeaufforderung mit den folgenden Befehlen überprüft und validiert werden: ping ftapi.ihre-domain.de Diese Zieladresse sollte grundsätzlich erreichbar sein nslookup ftapi.ihre-domain.de Es sollte die zuvor eingestellte IP-Adresse (im obigen Beispiel 192.168.89.100) und der dazugehörige interne Servername angezeigt werden Testen der Erreichbarkeit Grundsätzlich sollte die Erreichbarkeit des FTAPI-Servers von folgenden Orten aus getestet werden: vom (FTAPI) Server direkt, von einem internen Client und von einem externen Client. Es wird empfohlen, von allen Aufruforten aus zu prüfen, ob © FTAPI Software UG (2011), Seite 9 nach Aufruf der FTAPI URL (standardmäßig http://ftapi.ihre-domain.com:8080/ftapi-server) der FTAPI Loginscreen erscheint, man sich erfolgreich (als Admin oder Benutzer) am FTAPI System anmelden kann, das Java Applet ("Neue Sendung" Button) vollständig geladen wird und man eine Sendung erfolgreich verschicken kann. Proxy-Server Beim Betrieb eines Proxy-Servers ist es in der Regel notwendig, bei allen Clients (bestenfalls in Gruppenrichtlinien am Server) folgenden Eintrag in den Proxy-Ausnahmen zu ergänzen (s. hierzu auch FAQs): ftapi.ihre-domain.com* Datenablage FTAPI unterscheidet stets zwischen zwei verschiedenen Datenarten: Metadaten Binärdaten Metadaten sind die beschreibenden Daten. D.h., diese beschreiben sowohl den Übertragungsprozess (z.B. welcher Versender, Empfängeradresse, usw.) wie auch die Binärdaten selbst (z.B. Dateiname, Dateigröße, letzte Änderung, usw.). FTAPI speichert diese Dateien in einer Datenbank. Binärdaten sind diejenigen Daten, die vom Versender an den Empfänger übermittelt werden, wie z.B. ein Word-Dokument, Bilder oder andere Dokumente. Diese Daten können durchaus mehrere hundert Gigabyte groß sein. FTAPI speichert diese Daten an einem separaten Ort, dem sogenannten Storage. FTAPI ist so konstruiert, dass standardmäßig sowohl der Storage als auch die Datenbank in das FTAPI-System "eingebettet" sind. D.h., es ist standardmäßig keine Konfiguration dieser Speicherorte notwendig. FTAPI verwendet von Haus aus den Ort ~/.ftapi/db für die Ablage der Metadaten und ~/.ftapi/storage für die Ablage der Binärdaten. Allerdings ist dieser eingebettete Betrieb nicht für den Produktivbetrieb empfohlen. Bei einem Produktivbetrieb wird dringend empfohlen, die Metadaten und die Binärdaten auf separate Systeme zu verteilen! Dies hat drei einfache Gründe: Sicherheit: Erst durch die Trennung von Meta- und Binärdaten kann eine höhere Sicherheit gewährleistet werden. Datenstabilität und Backup: Die Metdaten werden durch die interne HSQLDB-Datenbank verwaltet. Diese ist jedoch nicht für hohe Anfragelasten ausgelegt. Zudem läuft diese Datenbank in einem sogenannten Single-User-Mode. D.h. die Daten können nur begrenzt gesichert werden. Performance: Die Aufgaben und somit die Anfragelast werden auf verschiedene Systeme verteilt Die eingebettete Datenbank ist nur für kleine Anfragelasten geeignet. Falls Sie eine hohe Anfragelast erwarten, wird empfohlen, eine extrerne Datenbank, wie z.B. MySQL, Oracle oder PostgreSQL anzubinden, um nur einige Beispiele zu nennen. Andere Datenbank Hier erfahren Sie, wie Sie eine alternative, externe Datenbank an FTAPI anbinden können: Speicherung der Metadaten (Datenbank) Anderer Storage Hier erfahren Sie, wie Sie den Speicherort für den Storage ändern können: Binärdaten (Storage). Metadaten (Datenbank) Metadaten sind beschreibende Daten. D.h., mit den Metadaten von FTAPI wird z.B. beschrieben, welcher Versender welche Daten an welchen Empfänger sendet. Mögliche konkrete Werte könnten beispielsweise die Empfänger-E-Mail, die Dateinamen oder die Dateigrößen sein, um nur einige zu nennen. FTAPI speichert die Metadaten in einer Datenbank. Dies ermögicht es Ihnen später, umfangreiche Auswertungen auf Basis von SQL durchzuführen. Standardmäßig wird eine eingebettete Datenbank (HSQLDB) verwendet. Allerdings ist diese nicht für den Produktivbetrieb empfohlen. Stattdessen sollte eine externe Datenbank, wie z.B. MySQL verwendet werden. Nachfolgend erfahren Sie, wie Sie eine alternative Datenbank anbinden können. Konfiguration ftapi.jdbc.url © FTAPI Software UG (2011), Seite 10 ftapi.jdbc.driver ftapi.jdbc.username ftapi.jdbc.password ftapi.hibernate.dialect ftapi.hibernate.hbm2ddl.auto ftapi.hibernate.show_sql MySQL anbinden Schritt 1: JDBC-Treiber besorgen und installieren Schritt 2: Datenbank und Benutzer anlegen Schritt 3: Datenbankanbindung konfigurieren Bitte beachten Sie, dass im massiven produktiven Betrieb von der Verwendung einer Embedded-Datenbank wie z.B. H2 oder HSQLDB abgeraten wird. Stattdessen sollten Sie z.B. MySQL verwenden. Konfiguration Öffnen Sie die Datei server-production.properties und suchen Sie nach folgendem Eintrag: # HSQLDB FileSystem # NOTE: Backward slashes \ are not allowed! Use forward slashes / instead! ftapi.jdbc.url=jdbc:hsqldb:file:#{ftapi.home}/db/ftapi ftapi.jdbc.driver=org.hsqldb.jdbcDriver ftapi.jdbc.username=sa ftapi.jdbc.password= ftapi.hibernate.dialect=org.hibernate.dialect.HSQLDialect ftapi.hibernate.hbm2ddl.auto=update ftapi.hibernate.show_sql=false Nachfolgend werden die einzelnen Konfigurationsparameter genauer erläutert. ftapi.jdbc.url Die JDBC-URL zum verwendeten Datenbanksystem. Wie diese URL lautet, ist vom so genannten JDBC-Treiber des Datenbanksystems abhängig und kann in dessen Dokumentation nachgelesen werden. Sehen Sie hierzu auch das Beispiel zu MySQL weiter unten. Die Standardeinstellung jdbc:hsqldb:file:~/.ftapi/db/ftapi steht dafür, dass die interne HSQLDB-Datenbank alle Daten im Heimatverzeichnis des Benutzers (bzw. dem Pfad, der als ftapi.home gesetzt ist) ablegt, unter dem das System aktuell betrieben wird. ftapi.jdbc.driver Mit diesem Wert wird der Klassenpfad des JDBC-Treibers bestimmt. Wie dieser Klassenpfad lautet, entnehmen Sie bitte der Dokumentation des verwendeten JDBC-Datenbantreibers. Standardmäßig wird der Treiber für die eingebettete HSQLDB-Datenbank verwendet. ftapi.jdbc.username Der Benutzername des Datenbank-Accounts, falls notwendig, um sich mit der Datenbank verbinden zu können. ftapi.jdbc.password Das Passwort des Datenbank-Accounts, falls notwendig, um sich mit der Datenbank verbinden zu können. ftapi.hibernate.dialect Je nachdem, welche Datenbank Sie verwenden, muss der so genannte "Dialect" ebenfalls entsprechend angepasst werden. In der nachfolgenden Tabelle finden Sie die Zuordnung des Dialects zum verwendeten Datenbanksystem: Datenbanksystem Dialect DB2 org.hibernate.dialect.DB2Dialect DB2 AS/400 org.hibernate.dialect.DB2400Dialect DB2 OS390 org.hibernate.dialect.DB2390Dialect H2 org.hibernate.dialect.H2Dialect PostgreSQL org.hibernate.dialect.PostgreSQLDialect MySQL org.hibernate.dialect.MySQLDialect © FTAPI Software UG (2011), Seite 11 MySQL with InnoDB org.hibernate.dialect.MySQLInnoDBDialect MySQL with MyISAM org.hibernate.dialect.MySQLMyISAMDialect MySQL 5 org.hibernate.dialect.MySQL5Dialect Oracle (any version) org.hibernate.dialect.OracleDialect Oracle 9i org.hibernate.dialect.Oracle9iDialect Oracle 10g org.hibernate.dialect.Oracle10gDialect Sybase org.hibernate.dialect.SybaseDialect Sybase Anywhere org.hibernate.dialect.SybaseAnywhereDialect Microsoft SQL Server org.hibernate.dialect.SQLServerDialect SAP DB org.hibernate.dialect.SAPDBDialect Informix org.hibernate.dialect.InformixDialect HypersonicSQL org.hibernate.dialect.HSQLDialect Ingres org.hibernate.dialect.IngresDialect Progress org.hibernate.dialect.ProgressDialect Mckoi SQL org.hibernate.dialect.MckoiDialect Interbase org.hibernate.dialect.InterbaseDialect Pointbase org.hibernate.dialect.PointbaseDialect FrontBase org.hibernate.dialect.FrontbaseDialect Firebird org.hibernate.dialect.FirebirdDialect ftapi.hibernate.hbm2ddl.auto Mit diesem Wert wird die Schemagenerierung konfiguriert. Er entspricht dem Hibernate-Property hibernate.hbm2ddl.auto. Bitte ändern Sie diesen Wert nur, wenn Sie wirklich wissen, was Sie tun. ftapi.hibernate.show_sql Mit diesem Wert kann bestimmt werden, ob die SQL-Statements angezeigt werden (true) oder nicht (false). Der Standardwert ist false und sollte auch nur in Ausnahmefällen verändert werden. MySQL anbinden In diesem Abschnitt wird die Anbindung einer MySQL-Datenbank schrittweise erklärt. Schritt 1: JDBC-Treiber besorgen und installieren Als ersten Schritt müssen Sie den JDBC-Treiber für MySQL besorgen und installieren. Dieser ist auf folgender Website kostenlos als Download erhältlich: http://dev.mysql.com/downloads/connector/j Laden Sie sich die Datei herunter und entpacken Sie diese. Im entpackten Verzeichnis sollten Sie eine Datei mit der Endung .jar vorfinden (z.B. mysql-connector-java-5.1.12.jar). Kopieren Sie diese Datei anschließend nach <FTAPI-Context>/WEB-INF/lib, wobei <FTAPI-Context> für die FTAPI-Applikation in Ihrem Servlet-Container steht. Unter Tomcat wäre dies beispielsweise / webapps/ftapi-server. Schritt 2: Datenbank und Benutzer anlegen Erstellen Sie in Ihrem MySQL-System eine neue Datenbank (Kollation utf8_general_ci) mit dem Namen ftapi, sowie einen Benutzer, der Zugriff auf diese Datenbank besitzt. Dieser Benutzer muss zudem die Erlaubnis besitzen, die Datenbankstruktur verändern zu dürfen (DDL-Permission). Schritt 3: Datenbankanbindung konfigurieren Als letzten Schritt müssen Sie nur noch die Datenbank entsprechend in der Datei server-production.properties (.ftapi/config/server-production.properties) konfigurieren. Öffnen Sie diese Datei und passen Sie die Parameter entsprechend den folgenden Angaben - diese sind auskommentiert bereits vorhanden - an: © FTAPI Software UG (2011), Seite 12 ftapi.jdbc.url=jdbc:mysql://localhost:3306/ftapi?characterEncoding=UTF-8 ftapi.jdbc.driver=com.mysql.jdbc.Driver ftapi.jdbc.username=<username> ftapi.jdbc.password=<password> ftapi.hibernate.dialect=org.hibernate.dialect.MySQL5Dialect Natürlich müssen Sie die Parameter ftapi.jdbc.url, ftapi.jdbc.username und ftapi.jdbc.password entsprechend Ihres MySQL-Systems anpassen. Bitte vergessen Sie nicht, bei der Umstellung auf eine andere Datenbank die standardmäßig hinterlegten HSQLDB-Einträge vollständig mittels einer # am Zeilenanfang auszudokumentieren! Erfolgt eine Datenbank-Umstellung während des Betriebs, gehen alle bisherigen Informationen (in der alten Datenbank enthaltenen Metadaten) wie z.B. bereits versendete Dateien oder hinterlegte Benutzer usw. verloren. Falls Sie eine Umstellung planen, kontaktieren Sie bitte das FTAPI Support-Team. Binärdaten (Storage) Die Binärdaten, also diejenigen Daten, die mit dem FTAPI-System übertragen werden, werden im sogenannten Storage abgelegt. Ein Storage ist ein beliebiger Ort, an dem Binärdaten abgespeichert und wieder geladen werden können. Dies kann beispielsweise eine lokale Festplatte, ein NAS (Fileserver) in ihrem Unternehmensnetzwerk oder ein Speicherplatz im Internet (z.B. Cloud-Storage) sein. Wo genau die Binärdaten abgelegt werden, wird durch das Storage-Modul bestimmt. Es stellt die Kommunikation zwischen dem FTAPI-System und dem Zielort (z.B. Festplatte) sicher. DiskStorage ftapi.storage.home Binärdaten verschieben ftapi.storage.quota S3Storage Weitere Parameter Automatischer Storage-Cleanup ftapi.storage.cleanup.enabled ftapi.storage.cleanup.interval ftapi.storage.cleanup.max.age DiskStorage Standardmäßig ist in FTAPI das DiskStorage-Modul aktiviert. Dieses Modul erlaubt die Ablage der Daten auf jedem beliebigen, lokal verfügbaren Medium, wie z.B. eine gemountete Festplatte. Die Werkseinstellungen dieses Moduls legen fest, dass die Binärdaten im Verzeichnis ~/.ftapi/storage abgelegt werden. Wenn dieses Verzeichnis nicht existiert, wird es angelegt. Sie können diesen Pfad und andere Einstellungen aber natürlich Ihren Bedürfnissen anpassen. Öffnen Sie hierfür die globale Konfigurationsdatei server-production.properties und suchen Sie den folgenden Eintrag: #-------------------------------------------------------------------# Storage settings #-------------------------------------------------------------------# The location where to store the parts on local disk ftapi.storage.home=~/.ftapi/storage # The max size of all files together in this storage # Default: 10240000000 (10GB), For no quota at all set to: -1 ftapi.storage.quota=10240000000 # The max size of a tmp file in bytes # Default: 10240000 (10MB) ftapi.storage.tmp.max=10240000 Nachfolgend erhalten Sie eine kurze Beschreibung der jeweiligen Parameter. ftapi.storage.home Mit diesem Parameter können sie den Pfad zu einem beliebigen Verzeichnis auf ihrem lokalen System angeben, in welches die Storage-Daten abgelegt werden sollen. Wenn dieses Verzeichnis nicht existiert, wird es angelegt (auch alle darüber liegenden Verzeichnisse). © FTAPI Software UG (2011), Seite 13 Bitte stellen Sie sicher, dass FTAPI entsprechende/ausreichende Schreibrechte im angegebenen Verzeichnis besitzt. Um die Daten beispielsweise in ein Verzeichnis storage der Festplatte D: unter Windows abzulegen, könnten Sie folgende Konfiguration verwenden: ftapi.storage.home=D:/storage Bitte beachten Sie, dass auch unter Windows "Forward-Slashes" / anstelle von "Backward-Slashes" \ für Pfadangaben verwendet werden können. Eine Tilde ~ zu Beginn einer Pfadangabe wird zudem als das Heimatverzeichnis des Benutzers interpretiert, unter dem das FTAPI-System ausgeführt wird. Binärdaten verschieben Um die Binärdaten an einen anderen Ort zu verschieben, sollten Sie folgendermaßen vorgehen: 1. 2. 3. 4. Den FTAPI Server herunterfahren, um keine inkonsistenten Daten zu erhalten. Die Binärdaten an den neuen Zielort kopieren. Den Pfad zum neuen Zielordner anpassen. Den FTAPI Server wieder starten. ftapi.storage.quota Durch diesen Parameter können Sie die Maximalgröße des Storage in Bytes festlegen. FTAPI überprüft vor dem Upload die Größe des Datenpakets und berechnet, ob bei dessen Annahme das fest gelegte Storage-Quota überschritten werden würde. In diesem Fall würde FTAPI das Datenpaket mit einer Meldung zurückweisen. Damit können Sie sicher stellen, dass das konfigurierte Speichermedium niemals mit Daten über die festgelegte Maximalgrenze hinaus beschrieben wird. Andernfalls könnte es unter manchen Betriebssystemen durchaus vorkommen, dass durch einen "Überlauf" des Storage-Mediums nicht mehr genügen Speicherplatz für andere Anwendungen, wie z.B. das Betriebssystem selbst zur Vefügung stehen und dieses im schlimmsten Fall abstürzt. Solche Szenarien kommen bei anderen Systemen, wie z.B. FTP durchaus vor. Um z.B. das Quota auf 10GB festzulegen, müssen Sie folgende Angabe machen: ftapi.storage.quota=1024000000 S3Storage In FTAPI Professional wird ein spezieller Storage Manager mitgeliefert, der es ermöglicht, Segmente auch auf dem Cloud Storage System Amazon Simple Storage Service (S3) auszulagern. Bitte beachten Sie, dass der S3Storage Manager derzeitig noch BETA ist. Der Einsatz erfolgt daher vollständig auf eigene Gefahr hin. Um den S3Storage Manager zu aktivieren, öffnen Sie bitte die Datei ftapi-server/webapps/ftapi-server/WEB-INF/classes/sc-core.xml und unkommentieren Sie anschließend folgenden Eintrag: <bean id="storageManager" parent="storageManagerBase"> <property name="awsAccessKey" value="YOUR_ACCESS_KEY"/> <property name="awsSecretKey" value="YOUR_SECRET_KEY"/> </bean> Ersetzen Sie die Werte YOUR_ACCESS_KEY und YOUR_SECRET_KEY entsprechend durch den AccessKey und SecretKey, den Sie über Ihren Amazon S3 Online Account erfragen können. Deaktivieren Sie anschließend den standardmäßig aktivierten DiskStorageManager, indem Sie folgenden Eintrag in derselben Datei suchen und diesen auskommentieren, wie nachfolgend gezeigt: <!-- <bean id="storageManager" parent="storageManagerBase"/> --> Starten Sie anschließend den FTAPI Server neu. © FTAPI Software UG (2011), Seite 14 Weitere Parameter Der S3Storage kann zusätzlich mit denselben Parametern konfiguriert werden, wie der DiskStorage, wobei ftapi-server.storage.home hier für die lokale Zwischenspeicherung der Segmente verwendet wird und ftapi-server.storage.quota sich auf den verwendeten Speicherplatz auf dem Amazon S3 Server bezieht. Automatischer Storage-Cleanup Viele Administratoren von Datentransfer-Systemen, die sich mit z.B. E-Mail oder FTP beschäftigen müssen, haben das große Problem, dass die Dateien auch nach der erfolgreichen Zustellung an den Empfänger auf dem Übertragungssystem erhalten bleiben und damit nicht nur ein erhöhtes Sicherheitsrisiko darstellen, sondern nach und nach das entsprechende System "zumüllen". Die Administratoren haben beispielsweise erheblichen Aufwand, die entsprechenden Systeme "sauber" zu halten und regelmäßig aufzuräumen. Vielleicht kennen Sie ja auch die berühmte E-Mail "Server voll, bitte jeder aufräumen" oder so ähnlich ;) Mit FTAPI kann dies nicht passieren, da es so konfiguriert ist, dass erfolgreich und vollständig zugestellte Datenpakete automatisch vom System entfernt werden. Dies kann den System-Administrator deutlich entlasten. Natürlich kann dieses Verhalten an die eigenen Bedürfnisse angepasst oder komplett abgestellt werden. Die Einstellungen hierzu finden Sie in der der Datei server-production.properties, in folgendem Abschnitt: #-------------------------------------------------------------------# Storage cleanup settings #-------------------------------------------------------------------# Switch on/off the cleanup job # Default: true ftapi.storage.cleanup.enabled=true # The interval then the cleanup task should run regularily. # Default: 0 0 3 * * ? (every day at 3:00 AM) ftapi.storage.cleanup.interval=0 0 3 * * ? # The max age of a deliverable until its binary data will be deleted from storage. # The format is <integer>{m|h|d}, whereas m = minutes, h = hours and d = days. # Examples: 90d (= 90 days), 2h (= 2 hours), 30m (= 30 minutes) ftapi.storage.cleanup.max.age=1m Nachfolgend werden die einzelnen Parameter genauer beschrieben. ftapi.storage.cleanup.enabled Mit diesem Wert lässt sich die AutoClean-Funktion generell aktivieren (true) oder deaktivieren (false). ftapi.storage.cleanup.interval Dieser Parameter bestimmt, mit welcher Häufigkeit der Storage regelmäßig überprüft und gegebenenfalls zutreffende Dateien gelöscht werden. Hierzu wird eine sogenannte "Cron-Expression" festgelegt, mit welcher bis auf die Sekunde genau bestimmt werden kann, in welchen Abständen eine Überprüfung stattfinden soll. Die Cron-Expression 0 0 3 * * ? bedeutet beispielweise, dass die Überprüfung jeden Tag um 3:00 Uhr morgens stattfinden soll, oder 0 59 * * * ? bedeutet, dass die Überprüfung jede Stunde zur 59. Minute durchgeführt wird. Weitere Informationen zum Thema Cron-Expressions erhalten Sie z.B. hier : http://www.quartz-scheduler.org/DOCS11/tutorials/crontrigger.html. Je nachdem wie hoch Ihr FTAPI-System frequentiert ist, kann es sinnvoll sein, das Check-Intervall anzupassen. Da die Überprüfung der Einträge relativ aufwändig ist, empfiehlt es sich, die Überprüfung auf ein Minimum zu reduzieren. Als guter Wert hat sich die tägliche Überprüfung um 3:00 Uhr Morgens herausgestellt, da zu diesem Zeitpunkt erfahrungemäß nur wenige Transfer-Aktionen stattfinden und somit das System nicht genutzte Leistung für den Check verwenden kann. ftapi.storage.cleanup.max.age Dieser Wert bestimmt, wie alt eine Datei sein muss, bevor sie gelöscht werden darf. Mit jeder neuen Zustellung eines Deliveries wird das Alter (age) wieder auf 0 zurückgesetzt und beginnt von neuem hochzuzählen. Sie haben hier die Möglichkeit, die Angabe in Minuten, Stunden oder Tagen zu machen, indem sie die Endung m, h oder d verwenden. Im nachfolgenden Beispiel sind 90 Tage eingestellt: ftapi.storage.cleanup.max.age=90d Staging FTAPI unterstützt einen sogenannten "Staging-Prozess". Dies ist vor allem dann extrem hilfreich, wenn Sie selbst regelmäßig Erweiterungen © FTAPI Software UG (2011), Seite 15 in FTAPI integrieren oder eine neue Konfiguration testen möchten, bevor Sie diese Konfiguration in das Produktivsystem übernehmen. Hierfür können Sie FTAPI beim Start den Parameter "-Dftapi.stage=<stage>" mitgeben, wodurch jeweils eine unterschiedliche Konfiguration geladen wird. Wird dieser Parameter nicht angegeben, so wird automatisch die Produktiv-Konfiguration geladen. Um ein bestimmtes Stage zu aktivieren, müssen Sie in den Startup-Skripten (ftapi-start.bat bzw. ftapi.sh im Ordner /ftapi-server/) den Parameter "-Dftapi.stage=<stage>" inklusive einem vorangestellten Leerzeichen entsprechend ergänzen. Ein Beispiel für die Datei ftapi-start.bat: set JAVA_OPTS="-Dftapi.home=%CATALINA_HOME%/../.ftapi" "-Dftapi.stage=assembly" Falls Sie einen anderen als den standardmäßig mit ausgelieferten Tomcat Servlet-Container verwenden, sehen Sie bitte in der zugehörigen Dokumentation nach, wo genau Sie den Parameter hierfür angeben müssen. Nachfolgend sehen Sie die verfügbaren Staging-Werte und die zugehörigen Konfigurationen, die entsprechend geladen werden: Stage Konfiguration Beschreibung production ~/.ftapi/conf/server-production.properties Diese Stage wird standardmäßig verwendet, wenn kein Parameter -Dftapi.stage angegeben wurde und umfasst alle Einstellungen, die für den Produktivbetrieb notwendig sind. Alternativ kann der Aufurf auch exlpizit über -Dftapi.stage=production gesetzt werden. assembly ~/.ftapi/conf/server-assembly.properties In dieser Stage kann z.B. der Integration-Test durchgeführt werden. In der Regel enthält die Konfiguration bereits genau die Einstellungen, die auch später im Produktivsystem verwendet werden sollen. Die einzige Ausnahme stellen die Referenzen zu externen Systemen, wie z.B. Datenbanken oder dem Storage dar. development ~/.ftapi/conf/server-development.properties Dieser Stage ist vor allem während der Entwicklung sehr hilfreich. In der zugehörigen Datei können z.B. eine Test-Datenbank referenziert werden oder Dummy-Werte platziert werden. Sie sind in der Regel nur für den Entwickler und dem Testing relevant. Pfade Je nachdem, über welche URL FTAPI über das Internet erreichbar ist, kann es notwendig werden, diesen Pfad in der Konfiguration anzupassen, um sicher zu stellen, dass diese URL z.B. auch in E-Mail-Benachrichtigungen und Reports korrekt wieder gegeben wird. Konfiguration Die Einstellungen für die externen Pfade finden Sie in der Datei server-production.properties. Ein Auszug der Standardeinstellung: ftapi.base.url=http://localhost:8080/ftapi-server Nachfolgend werden diese Parameter näher erläutert. ftapi.base.url Dies ist die Basis-URL, die z.B. in E-Mail-Benachrichtigungen verwendet wird. Sie muss über das Internet erreichbar sein (siehe hierzu auch DNS-Server), falls Sie mit FTAPI auch Daten mit Partnern und Kunden austauschen möchten und dies über das Internet geschehen soll. Rollen FTAPI besitzt ein Rollen-Konzept mit dem die Berechtigungen von FTAPI-Accounts gezielt gesetzt werden können. Die Rollen können nur durch einen Benutzer mit Administrator-Rechten (ROLE_ADMIN) geändert werden. Nachfolgend sind die verschiedenen Rollen und deren Bedeutung aufgelistet und erläutert: ROLE_ADMIN Ist ein Benutzer dieser Rolle zugeordnet, so hat er uneingeschränkte Berechtigungen. Unter anderem darf er Benutzer anlegen und löschen. Wenn einem Benutzer diese Rolle zugeordnet wird, so werden beim Speichern automatisch auch alle anderen Rollen an diesen Benutzer zugewiesen. © FTAPI Software UG (2011), Seite 16 ROLE_ANONYMOUS Dieser Rolle ist automatisch jeder Benutzer zugeordnet. Die Zuordnung kann nicht gelöscht werden. Dabei ist es unerheblich, ob dieser Benutzer eingeloggt ist oder nicht. Dies ist vor allem für spätere Reports sinnvoll, da hier jeder Benutzer mindestens einer konkreten Rolle zugeordnet werden kann und es keine leeren Einträge gibt (NULL-Referenzen auf Rollen). ROLE_RECEIVER Benutzer, die dieser Rolle zugeordnet sind, haben die Berechtigung Daten zu empfangen (sofern dies nur auf registrierte Benutzer beschränkt ist). Dies ist vor allem in Verbindung mit dem qualifizierten Download im Download Applet vorgesehen. ROLE_SENDER Jeder Benutzer, welcher dieser Rolle hinzugefügt ist, hat die Berechtigung Daten zu versenden (z.B. über das Upload Applet). ROLE_SUBMITTER Diese Rolle ermöglicht es dem jeweiligen Besitzer, Daten über eine SubmitBox zu versenden. Standardmäßig wird diese Rolle dynamisch gesetzt, sobald ein Benutzer ein Submit-Ticket anfordert. ROLE_UI_USER Alle Benutzer, die sich in die WEB-UI einloggen möchten, müssen dieser Rolle zugeordnet sein. Applet Konfigurationsmöglichkeiten Notwendigkeit für Empfänger-Account voreinstellen Empfänger-Account erzwingen Empfänger-Account vollständig unterbinden Request-Parameter Drag-Support: Applet auf den Desktop "ziehen" FTAPI in Windows-Kontextmenü integrieren Das FTAPI-Applet lässt sich flexibel an die eigenen Bedürfnisse anpassen. In diesem Abschnitt erfahren Sie, welche Konfigurationsmöglichkeiten zur Verfügung stehen. Notwendigkeit für Empfänger-Account voreinstellen Standardmäßig kann der Versender einstellen, ob der Empfänger einen FTAPI-Account besitzen muss oder nicht. Eine Zustellung wird hierdurch zusätzlich abgesichert, da sich jeder Empfänger vor einem Download authentifizieren muss. In einigen Fällen kann es sinnvoll sein, dass z.B. durch den Administrator diese Einstellung unveränderbar vorgegeben ist und z.B. ein solcher Empfänger-Account aus Sicherheitsgründen immer zwingend ist (siehe Empfänger-Account erzwingen). Im umgekehrten Fall kann eingestellt werden, dass dieser niemals angefordert werden darf. (siehe Empfänger-Account vollständig unterbinden) Beide Fälle lassen sich in der FTAPI-Konfiguration entsprechend voreinstellen: Empfänger-Account erzwingen © FTAPI Software UG (2011), Seite 17 Hierzu muss in der FTAPI-Konfiguration server-production.properties der Wert ftapi.force.recipient.account=ALWAYS gesetzt werden. Dies führt zu folgender Voreinstellung im Applet: Die Checkbox ist aktiviert und kann durch den Benutzer nicht mehr verändert werden. Empfänger-Account vollständig unterbinden Hierzu muss in der FTAPI-Konfiguration server-production.properties der Wert ftapi.force.recipient.account=NEVER gesetzt werden. Dies führt zu folgender Voreinstellung im Applet: Es wird überhaupt keine Checkbox angezeigt, da ein Empfänger-Account in keinem Falle notwendig ist bzw. angefordert werden kann. Request-Parameter Das Applet erlaubt die Vorbelegung seiner Felder durch Request-Parameter. Die belegbaren Felder und zugehörigen Request-Parameter lauten wie folgt: Applet-Feld Request-Parameter Beschreibung E-Mail recipients Eine durch Semikolons ; getrennte Liste von E-Mail-Adressen, die als Empfänger der Zustellung eingetragen werden sollen. Betreff subject Der Betreff der Nachricht. Nachricht message Der Text der Nachricht. Dateien files Eine durch Semikolons ; getrennte Liste aller Dateipfade und -namen, die der Zustellung hinzugefügt werden sollen. © FTAPI Software UG (2011), Seite 18 Request-Beispiel Ein Aufruf der Form http://localhost/ftapi-server/upload/[email protected]&subject=Test&message=Test&files=D:\document.pdf führt zu folgendem bereits vorausgefülltem Applet: Drag-Support: Applet auf den Desktop "ziehen" Das FTAPI Applet kann aus dem Browser heraus auch auf den Desktop gezogen werden, um dort als eigenständige Applikation solange weiter zu laufen, bis eine Übertragung abgeschlossen ist. Der Web-Browser kann in der Zwischenzeit sogar geschlossen werden. Halten sie hierzu lediglich die Taste ALT gedrückt und verschieben Sie gleichzeitig das Applet mit der Maus auf den Desktop. © FTAPI Software UG (2011), Seite 19 Der "Drag-Support" ist nur mit einer Java-Version ab 1.6 verfügbar. Um den Drag-Support zu aktivieren, müssen Sie in der FTAPI-Konfiguration server-production.properties folgenden Wert setzen: ftapi.webui.applets.draggable=true Dieser Wert ist standardmäßig auf false gesetzt. FTAPI in Windows-Kontextmenü integrieren Mit wenigen Handgriffen ist es möglich, dass FTAPI in das Windows-Kontextmenü integriert wird. So kann mit einem rechten Mausklick auf eine Datei diese direkt mit FTAPI verschickt werden. Und das ohne die Notwendigkeit, eine zusätzliche Software installieren zu müssen! Für Änderungen an der Windows-Registry und allen daraus resultierenden Folgen übernimmt FTAPI keine Haftung. Die nachfolgend beschriebenen Einstellungen erfolgen vollständig auf eigene Gefahr hin. Darüber hinaus gibt FTAPI hierfür keinerlei Support. Um FTAPI in das Windows-Kontextmenü zu integrieren, gehen Sie folgendermaßen vor: 1. Geben Sie in der Windows-Eingabeaufforderung regedit ein. Es öffnet sich der Registrierungs-Editor. 2. Navigieren Sie zum Ordner HKEY_CLASSES_ROOT/*/shell 3. Klicken Sie mit der rechten Maustaste auf den Ordner shell und erstellen Sie einen neuen Schlüssel mit dem Namen Send with FTAPI SecuTransfer 4. Klicken Sie mit der rechten Maustaste auf den soeben neu erstellten Schlüssel und erstellen Sie einen neuen, weiteren Schlüssel © FTAPI Software UG (2011), Seite 20 4. mit dem Namen command 5. Markieren Sie mit der linken Maustaste den soeben neu erstellten Schlüssel 6. Klicken Sie nun auf den Eintrag Standardwert rechts doppelt und geben Sie bei Wert "C:\Program Files\Internet Explorer\iexplore.exe" http://localhost:8080/ftapi-server/upload/createDelivery.html?files=%1 ein, wobei der Pfad zu Ihrem FTAPI Server natürlich entsprechend angepasst werden muss. Falls der Internet-Explorer in Ihrem System an einem anderen Ort installiert ist, müssen Sie auch diesen Pfad entsprechend anpassen. 7. Fertig. Ab sofort können Sie Dateien direkt aus Ihrem Desktop heraus mit FTAPI versenden, ohne dass Sie zusätzliche Software installieren müssen. HTTPS In order to secure all FTAPI transfers by using HTTPS, preconditions are a few settings and a (self) signed certificate. The procedure is described step by step below. Background By default FTAPI delivers a self-signed certificate for testing and evaluation purposes. You should get a "real" CA signed certificate if you plan on using FTAPI in a productive environment. In order to get such a CA signed certificate just follow the next steps: 1. Creating your Keystore 2. Certificate Signing Request 2.1. Generate .CSR (Certificate Signing Request) file in console 2.2. Open .CSR file and copy the text 3. Install signed certificate to keystore 4. Enabling SSL in the Tomcat server.xml File 5. Configure FTAPI config file An easy certificate for demo- and test cases can easily be ordered and dwonloaded at RapidSSL Free 30 day. 1. Creating your Keystore First of all you need to create a Keystore and a key pair. You will be using the keytool command to create and manage your new Keystore file. You may need to add your (for example) c:\program files\Java\jdk1.6.0_18\bin directory to your system variable PATH before the keytool command is recognized. Or you execute keytool.exe in your console directly from your Java folder (e.g. C:\Program Files\Java\jdk1.6.0_18\bin ) . When you are ready to create your keystore go to the directory where you plan to manage your Keystore and certificates - standard is folder \.ftapisecurity. Enter the following command: keytool.exe -genkey -alias ftapi-server -keyalg RSA -keysize 2048 -keystore your_site_name.jks Typing keytool.exe - help will show you all available commands. First you will be prompted to choose a password for your keystore. Afterwards you will then be prompted to enter your Organization information: Abbreviation Long term Example © FTAPI Software UG (2011), Seite 21 Question in console & other More info on the web CN Common Name ftapi.your-site-name.de Wie lautet Ihr Vorn- und Nachame? What is your first and last name? This one MUST match your URL (e.g. ftapi.your-site-name.com !) OU Organisation Unit - Wie lautet der Name Ihrer organisatorischen Einheit? What is the name of your organizational unit? O Organisation Ihr Firmenname Wie lautet der Name Ihrer Organisation? What is the name of your organization? L Locality Ihre Stadt Wie lautet der Name Ihrer Stadt oder Gemeinde? What is the name of your City or Locality? ST State Bundesland Wie lautet der Name Ihres Bundeslandes oder Provinz? What is the name of your State or Province? C Country DE Wie lautet der Landescode für diese Einheit? What is the two-letter country code for this unit? http://www.digicert.com/csr-creation.htm This is the Common Name (Fully Qualified Domain Name - FQDN) http://www.digicert.com/ssl-certificate-country-codes.htm Common Name From a technical point of view the only important value is "Common Name". This one must exactly match with your DNS hostname, which one is used for your FTAPI server. For example does the Common Name (CN) ftapi.your-site-name.com secure the URL https://ftapi.your-site-name.com/ When it asks for first and last name, this is NOT your first and last name, but rather it is your Fully Qualified Domain Name for the site you are securing (example: www.yourdomain.com). If you are ordering a Wildcard Certificate this must begin with the * character. (example: *.yourdomain.com) After you have completed the required information confirm that the information is correct by entering 'j' or 'ja' (if in english use 'y' or 'yes') when prompted. Next you will be asked for your password to confirm. Make sure to remember the password you choose. With Enter you can choose to use the same password as for your keystore (which is recommended) .JKS file Your keystore file named your_site_name.jks is now created in your current working directory (e.g. \Java\jdk1.6.0_18\bin OR \.ftapi\security). Find more details at http://www.digicert.com/ssl-certificate-installation.htm. If you do not order your certificate at www.digicert.com, the procedure can be different from the one desribed here! 2. Certificate Signing Request The certification process consists of two steps (http://www.digicert.com/csr-creation-tomcat.htm): 2.1. Generate .CSR (Certificate Signing Request) file in console keytool.exe -certreq -alias ftapi-server -file csr.txt -keystore your_site_name.jks Use the keystore password that you chose earlier and hit Enter. 2.2. Open .CSR file and copy the text © FTAPI Software UG (2011), Seite 22 Your CSR file named csr.txt is now created in your current directory. Open the CSR with a text editor, and copy the text below (including the BEGIN and END tags). -----BEGIN NEW CERTIFICATE REQUEST----MIIBuTCCASICAQAweTELMAkGA1UEBhMCREUxDzANBgNVBAgTBkJheWVybjERMA8GA1UEBxMITXVl bmNoZW4xGjAYBgNVBAoTEUZUQVBJIFNvZnR3YXJlIFVHMRAwDgYDVQQLEwdVbmtub3duMRgwFgYD VQQDEw9mdGFwaS5mdGFwaS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAJtE4P4mbXhF f8q4pzkm5AChn0E0n16rUjus+zSwSxrYKmmqE5NyJ1KnkhBhB0qNnFxFVpzAw4b9r14D/FfE/R9Y cOZEt3U+0HZZBbdU5YNIxs/JFzxDdJmSpXBtlnNol4ga025E3OGtcduZgli6nDmZ8hZhgJYeZtur 673nPf8LAgMBAAGgADANsdfsFSDFS230BAQUFAAOBgQCNKh2zvm6sB867PKbh/LbvFsbvyHiOrlZW sk7Q8763CAxXO2XvxF8bSXZHulTrEdvTFajQxORQKkfR7NuZ1i+m4Y9DE38Hxq0sFnD1JRv61uu\+ 60OnKZr4vqDZbdk/vnZ/ZtrRqE4ejp6Ez6aC5Etqta0vLX7AIZf9iBQsUMSAEg== -----END NEW CERTIFICATE REQUEST----- The full text has to be send to a Certificate Authority (CA). Be careful to save the keystore file (your_site_name.jks). Your certificates will be installed to it in the following step. 3. Install signed certificate to keystore This step explains, how a (CA) signed certificate has to be installed into your keystore. Download your signed SSL certificate (e.g. your-domain-name.p7b) to the directory where your keystore was saved during the CSR creation process! (the keystore is called your_site_name.jks - see 2.1). Your SSL certificate must be installed to the same keystore that was used to generate your CSR. If you try to install it to a different keystore it won't work! In order to install your certificate into your keystore, type the following command to install the certificate file to your keystore: keytool.exe -import -trustcacerts -alias ftapi-server -file your_domain_name.p7b -keystore your_site_name.jks You should get a confirmation stating that the "Certificate reply was installed in keystore" If it asks if you want to trust the certificate. Choose y or yes. Your keystore file (your_site_name.jks) is now ready to use on your Tomcat Server and you just need to configure your server to use it. 4. Enabling SSL in the Tomcat server.xml File In the final step you have to adjust the SSL connectors to you certificate. This is done at the Apache Tomcat Server for your FTAPI system. Tomcat needs a configured SSL connector in order to provide secure communication and transfers: 1. Open the Tomcat server.xml file with a text editor - the file should be found in the folder ...\ftapi-server\conf\server.xml or in your Tomcat home folder. 2. Deactivate (uncomment) the current connector by adding start and end comment lines "<!--" before and "-->" after the following section of code - afterwards this one should look like this: <!-<Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" /> --> 3. Specify the correct keystore filename and password in your connector configuration. Activate this section of code by removing the start and end comment lines ("<!--" before and "-->" after). When you are done your connector should look something like this: <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="../.ftapi/security/your_site_name.jks" keyAlias="ftapi-server" keypass="your_keystore_password" /> 4. (optional) Set the redirect port on the HTTP connector: If a request comes in for a secure ressource on the HTTP port, a redirect will be made automatically to the HTTPS port. In order to enable this, make sure the attribute redirectPort="8443" is set at your HTTP connector (see 2. above), whereas 8443 is the port number of your HTTPS connector. Example: © FTAPI Software UG (2011), Seite 23 <Connector port="8080" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="8443" /> 5. Save your changes to the server.xml file. 6. Restart Tomcat. By default the FTAPI Tomcat will look for your Keystore with the file name .keystore in your home directory with the default password "changeit". (The home directory is generally /home/user_name/ on Unix and Linux systems, and C:\Documents and Settings\user_name\ on Microsoft Windows systems.) 5. Configure FTAPI config file In order for your FTAPI server to be accessed using https you need to change the config file "server-production.properties" (usually this file is located at \.ftapi\config ) Configure the following setting with your domain or iIP address # Misc settings # ------------------------------------------------ftapi.base.url=https://localhost:8443/ftapi-server Finally restart your Tomcat server and browse to your ftapi.base.url in this example https://localhost:8443/ftapi-server If your HTTPS connector uses port 443, you don't need to set the port at ftapi.base.url, since all browsers automatically use this port as default, if the https:// protocol is requested. You could then set something like: https://localhost/ftapi-server. Redirect HTTP zu HTTPS einrichten Folgende Einstellungen sind notwendig, damit alle URL-Aufrufe - sowohl HTTP wie auch HTTPS - immer über die SSL gesicherte FTAPI-URL aufgerufen werden. Im folgenden Beispiel erfolgt die gesicherte Kommunikation immer über den Port 443, da dieser ein Standard-Port ist, der auch in einer URL nicht explizit angegeben werden muss. Es müssen insgesamt die drei folgenden Dateien angepasst werden, damit der Tomcat-Redirect von ungesicherten http Aufrufen auf https funktioniert. server.xml web.xml server-production.properties server.xml In der Datei server.xml - befindet sich im Ordner /ftapi-version/ftapi-server/conf/ - muss folgendes stehen: <Connector port="80" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort="443" /> UND <Connector port="443" protocol="HTTP/1.1" SSLEnabled="true" maxThreads="150" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" keystoreFile="../.ftapi/security/ftapi.com.jks" keyAlias="ftapi-server" keypass="changeit" /> Dies bewirkt, dass alle Webanwendungen unter %CATALINA_HOME%\webapps nur noch verschlüsselt erreicht werden können! (ein Aufruf auf http://localhost:80 oder http://localhost wird automatisch immer zu https://localhost:443 weitergeleitet) web.xml © FTAPI Software UG (2011), Seite 24 In der Datei web.xml - ebenfalls im Ordner /ftapi-version/ftapi-server/conf/ - ist der folgende Text ab und inklusive der Zeile <security-constraint> nach den zuvor hier genannten Einträgen zu ergänzen: <web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http:/java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5"> <security-constraint> <web-resource-collection> <web-resource-name>Secure Apps</web-resource-name> <url-pattern>/*</url-pattern> </web-resource-collection> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint> Im FTAPI Server Verzeichnis befinden sich insgesamt zwei web.xml Dateien! Die oben genannten Anpassungen sind alle in der Datei /ftapi-server/conf/web.xml durchzuführen bzw. werden bereits so ausgeliefert. Die zweite und NICHT zu ändernde Datei befindet sich unter /ftapi-server/webapps/ftapi-server/WEB-INF/web.xml! server-production.properties Abschließend noch überprüfen bzw. einstellen, dass die FTAPI-Base-URL ebenfalls als HTTPS und mit dem gleichen Port (hier 443) angegeben ist: \#----------------------------------------------\ \# Misc settings \#----------------------------------------------\ ftapi.base.url=https://localhost:443/ftapi-server Nachdem der FTAPI Server nun neugestartet wurde, sollte nun auch beim Aufruf von http://localhost:80 eine Weiterleitung direkt zu https://localhost:443 erfolgen. Web-Interface (WebUI) Der FTAPI-Server bietet Ihnen die Möglichkeit, große und/oder sensible Daten über die nachfolgend erläuterte Weboberfläche zu übermitteln, ohne dass Sie spezielle Software installieren müssen. Nachfolgend werden die wichtigsten Masken und Oberflächen, sowei ein grundlegender Durchlauf kurz erläutert. Aufruf und Log-In Ihr FTAPI-Server ist über die URL http://<host> erreichbar, wobei <host> für den Hostnamen Ihres FTAPI-Servers steht. Wenn Sie die FTAPI-LDAP (oder AD) Anbindung eingerichtet haben, können Sie Ihre gewohnten Zugangsdaten für den Login ins FTAPI-System nutzen. Falls dies bei Ihnen nicht der Fall ist, erhalten Sie Ihre speziellen FTAPI-Zugangsdaten von Ihrem Administrator. Übersicht - Dashboard © FTAPI Software UG (2011), Seite 25 Nach erfolgreichem Login erscheint Ihre benutzerspezifische Übersichtsseite. Hier erfahren Sie alle wichtigen Informationen zu Ihrem Benutzer-Account wie u.a. die Anzahl Ihrer erhaltenen und versendeten Sendungen die Anzahl der noch nicht abgeholten Zustellungen das Datum Ihres letzten Logins Ihre im System hinterlegte E-Mailadresse die URL Ihrer persönlichen SubmitBox Durch einen Klick auf die Spalten "Eingang/ Ausgang" können Sie direkt in den jeweiligen Bereich springen! Nähere Informationen über die versendeten bzw. noch nicht abgeholten Tickets erhalten Sie durch Anklicken des jeweiligen Bereiches. Versenden - neue Sendung Über den -Button (rechts oben) öffnet sich ein neues Fenster bzw. Reiter für eine komplett neue Zustellung. © FTAPI Software UG (2011), Seite 26 Zertifikat akzeptieren Bitte Akzeptieren Sie beim ersten Laden der Versendeseite das Zertifikat (für das Java Applet) dauerhaft, um FTAPI für Ihren Datentransfer nutzen zu können. Um die hohe Sicherheit des Datentransfers mit FTAPI gewährleisten zu können, wird dieses Zertifikat benötigt. Das Akzeptieren hat keine weiteren Auswirkungen auf Ihren Browser. Bei der nachfolgend dargestellten Sicherheitsmeldung bitte den Haken setzen und mit Ausführen bestätigen! Der Versendedialog ist wie ein gängiges E-Mailprogramm aufgebaut. 1. Geben Sie zuerst die E-Mailadresse des Empfängers Ihres Datenpakets ein. Mehrere E-Mailempfänger können durch ein Semikolon ; ohne weitere Leerzeichen davor oder danach eingegeben werden. © FTAPI Software UG (2011), Seite 27 2. Das Feld Betreff und den anschließenden Text für den oder die Empfänger füllen Sie wie bei einer normalen E-Mail aus. 3. Im unteren Bereich fügen Sie die zu versendenden Daten hinzu. Dies können Sie auf mehrere Weisen tun: - Klick auf das Symbol mit dem Ordner und der Box - Drag & Drop (Browserfenster nicht maximiert oder zweiter Bildschirm) - Klick auf das grüne Plus-Symbol (links unten) - Doppelklick auf den gesamten Bereich Im Datei- und Ordnerauswahldialog können Sie durch das Drücken der Strg-Taste einzelne Dateien UND Ordner direkt auswählen. Ordnerstrukturen werden von FTAPI automatisch rekursiv (also inklusive allen Unterordnern und den darin enthaltenen Dateien) hinzugefügt. ! 4. Starten Sie den Versand über den blauen Knopf rechts unten. Dieser Knopf ist erst dann aktiv, wenn Sie mindestens eine Datei hinzugefügt haben! Empfängerverifizierung bei Zustellung Wenn Sie einen Haken bei "Empfänger muss FTAPI Account besitzen" setzen, kann sichergestellt werden, dass genau und nur dieser die Zustellung erhält ein Download ist somit immer an eine bestimmte E-Mailadresse gebunden und kann deshalb auch nicht an Dritte weitergeleitet werden. Benutzereinstellungen - MySettings © FTAPI Software UG (2011), Seite 28 Jeder Benutzer kann über das Zahnradsymbol rechts oben seine persönlichen Einstellungen einsehen und bearbeiten. Zusätzlich kann hier die eigene SubmitBox und der eigene RSS-Feed de-/aktiviert oder umbenannt werden! Logout Der Logout erfolgt über das Tür-Symbol !FTAPI Logoutsymbol.jpg! rechts oben. Bitte loggen Sie sich für einen optimalen Schutz Ihres Benutzer-Accounts immer komplett hierüber aus. FTAPI führt zu Erhöhung der Systemsicherheit automatisch einen Logout nach einiger Zeit der Nichtaktivität durch! Feedback an FTAPI senden Probleme, generell Vorschläge oder Feedback können auf jeder Seite der FTAPI Weboberfläche über den Link unten links (Problem aufgetreten oder Vorschlag versenden?) direkt an das FTAPI-Team versandt werden. Bitte notieren Sie sich nach dem Senden Ihre angezeigte Ticket-ID für Rückfragen. © FTAPI Software UG (2011), Seite 29 LDAP und Active Directory FTAPI besitzt eine eigene, leistungsfähige Benutzerverwaltung. In manchen Situationen ist es jedoch sinnvoll, bereits bestehende Benutzer-Accounts aus einem LDAP- oder Active-Directory-System zu verwenden, um eine doppelte Verwaltung dieser Konten zu vermeiden. In diesem Kapitel erfahren Sie, wie Sie FTAPI so konfigurieren können, dass es Benutzer-Konten aus einem LDAP- oder Active-Directory-System akzeptiert. Bevor Sie mit der Konfiguration in FTAPI beginnen, stellen Sie bitte sicher, dass Ihr LDAP-System über das Netzwerk erreichbar ist und Sie sich erfolgreich per LDAP verbinden können. Dies können Sie beispielweise überprüfen, indem Sie sich mit einem der zahlreichen kostenloses LDAP-Clients, wie z.B. dem LDAP Browser von Softerra auf Ihren LDAP-Server verbinden. Im folgenden Abschnitt wird der Begriff LDAP-Server als Synonym für ein LDAP- wie auch ein Active-Directory-System verwendet. Konfiguration anpassen Verbindungsparameter ftapi.ldap.enabled ftapi.ldap.url ftapi.ldap.manager.dn ftapi.ldap.manager.password Parameter für das Attribut-Mapping ftapi.ldap.attr.firstName ftapi.ldap.attr.lastName ftapi.ldap.attr.email ftapi.ldap.attr.fingerprint Parameter für die LDAP-Suche ftapi.search.base ftapi.ldap.search.filter ftapi.ldap.search.subtree Parameter für den Cleanup ftapi.ldap.cleanup.enabled ftapi.ldap.cleanup.interval Mapping von LDAP-Gruppen zu FTAPI-Rollen Single Mapping Multi Mapping Konfiguration anpassen Öffnen Sie die Datei ~/.ftapi/config/server-production.properties und suchen Sie den Eintrag, der in etwa folgendes Aussehen besitzt: #-------------------------------------------------------------------# LDAP settings #-------------------------------------------------------------------# Server settings ftapi.ldap.enabled=false ftapi.ldap.url=ldap://localhost ftapi.ldap.manager.dn= ftapi.ldap.manager.password= # Context attribute mappings ftapi.ldap.attr.firstName=givenName ftapi.ldap.attr.lastName=sn ftapi.ldap.attr.email=mail ftapi.ldap.attr.fingerprint=objectGUID # User search settings ftapi.ldap.search.base= ftapi.ldap.search.filter=(&(sAMAccountName={0})(objectclass=user)) ftapi.ldap.search.subtree=true Ändern Sie diese Parameter entsprechend Ihren Bedürfnissen und speichern Sie anschließend die Datei wieder ab. Anschließend müssen Sie den FTAPI-Server neu starten, damit diese Änderungen aktiv werden. Nachfolgend werden die einzelnen Konfigurationsparameter ausführlich beschrieben. © FTAPI Software UG (2011), Seite 30 Verbindungsparameter Die folgenden Parameter werden für die Aktivierung der Verbindung zu einem LDAP-System benötigt. ftapi.ldap.enabled Mit diesem Parameter können Sie LDAP generell aktivieren (true) oder deaktivieren (false).Wird kein Wert angegeben, so wir der Standardwert false verwendet. Wenn die LDAP-Anbindung aktiviert und funktionsfähig ist, so führt FTAPI die Benutzerauthentifizierung stets in folgenden Schritten durch: 1. Es wird zuerst im LDAP-System nach dem entsprechenden Benutzer gesucht und bei einem Fund, dessen Login-Daten für die Authentifizierung verwendet. 2. Konnte im LDAP-System kein Benutzer mit dem angegebenen Benutzernamen gefunden werden, so wird die FTAPI eigene Benutzerverwaltung überprüft und falls sich hier der gewünschte Benutzer befindet, dessen Daten für die Authentifizierung verwendet. 3. Konnten weder im LDAP-System noch in der FTAPI-Benutzerverwaltung der Benutzer gefunden werden, so wird der Login mit einem "Login Failed" zurückgewiesen. Wenn sich ein LDAP-Benutzer erstmalig bei FTAPI anmeldet, so werden alle notwendigen und nicht-sensiblen Daten von dessen LDAP-Account in die FTAPI-Benutzerverwaltung übernommen. Dies ist notwendig, um weitere Einstellungen an diesem FTAPI-Account vornehmen zu können (z.B. Rollen zuordnen/entfernen), ohne den LDAP-Account ändern zu müssen. Einige Felder, wie z.B. das Passwort oder der Benutzername selbst, können dann nicht über die Oberfläche der FTAPI-Benutzerverwaltung verändert werden. Dies muss im LDAP-System selbst vorgenommen werden. Gleichnamige Benutzer-Accounts Bitte beachten Sie, dass es aus Sicherheitsgründen nicht erlaubt ist, dass ein manuell angelegter FTAPI-Account und ein LDAP-Account mit demselben Benutzernamen existieren. In diesem Fall wird beim Login eine Fehlermeldung angezeigt. Um dieses Problem zu umgehen, loggen Sie sich bitte als Administrator ein und geben Sie dem FTAPI-Account einen anderen Benutzernamen. ftapi.ldap.url Dieser Parameter ist Pflicht und gibt die URL zu Ihrem LDAP-Server im Format ldap://<host>:<port> an. Über diese URL muss der LDAP-Server vom FTAPI-System aus erreichbar sein. Ein Beispiel: ldap://ad-server:389 ftapi.ldap.manager.dn Mit diesem Parameter wird der sogenannte DN (Benutzername) des LDAP-Managers angegeben, über den die Verbindung zum LDAP-System aufgebaut werden soll. Diese Angabe ist Pflicht. Ein Beispiel: [email protected] ftapi.ldap.manager.password Das Passwort des LDAP-Managers. Diese Angabe ist optional, je nach dem ob der LDAP-Manager ein Passwort besitzt oder nicht. Parameter für das Attribut-Mapping Mit den nachfolgend beschriebenen Parametern können Sie bestimmen, welche Felder aus einem LDAP-Account verwendet werden, um dessen Werte in den FTAPI-Account zu übernehmen. Im Regelfall ist keine Änderung dieser Parameter notwendig. ftapi.ldap.attr.firstName Bestimmt den Namen des LDAP-Context-Felds, dessen Wert als Vorname in den lokalen FTAPI-Account übernommen werden soll. ftapi.ldap.attr.lastName © FTAPI Software UG (2011), Seite 31 Bestimmt den Namen des LDAP-Context-Felds, dessen Wert als Nachname in den lokalen FTAPI-Account übernommen werden soll. ftapi.ldap.attr.email Bestimmt den Namen des LDAP-Context-Felds, dessen Wert als E-Mail in den lokalen FTAPI-Account übernommen werden soll. ftapi.ldap.attr.fingerprint Bestimmt den Namen des LDAP-Context-Felds, dessen Wert als eindeutiger Fingerabdruck in den lokalen FTAPI-Account übernommen werden soll. Dies ist aus Sicherheitsgründen notwendig, um sicher zu stellen, dass der LDAP-Context nicht durch einen anderen "ausgetauscht" wird und kann jedes beliebige Feld sein, welches einen eindeutigen Wert besitzt. Parameter für die LDAP-Suche Nachdem mit dem LDAP-System eine Verbindung hergestellt wurde, wird in einem ganz bestimmten Bereich im "LDAP-Baum" nach dem Login-Benutzer gesucht. Welcher Bereich dies ist und wie diese Suche durchgeführt werden soll, wird durch die nachfolgenden Parameter bestimmt. ftapi.search.base Dieser Parameter bestimmt den Basis-Knoten im LDAP-Baum, ab dem mit der Suche begonnen werden soll. Ein solcher Pfad könnte beispielsweise für einen Active-Directory-Server auf einem Microsoft Small Business Server folgendermaßen aussehen: ou=SBSUsers,ou=Users,ou=MyBusiness,dc=ftapi,dc=local Im Active Directory Browser würde sich dieser Pfad dann durch folgende Baustruktur wiederspiegeln: Weitergehende Informationen, wie LDAP-Pfade aufgebaut sein können, entnehmen Sie bitte der Dokumentation zu Ihrem LDAP-Serversystem. ftapi.ldap.search.filter Mit diesem Parameter werden die Context-Typen bestimmt, die für eine Überprüfung heran gezogen werden sollen. Es stellt somit einen Filter dar. Unter einem Active-Directory-Server sollte diese Angabe stets folgendermaßen belassen werden: (&(sAMAccountName={0})(objectclass=user)) ftapi.ldap.search.subtree © FTAPI Software UG (2011), Seite 32 Dieser Parameter bestimmt, ob rekursiv gesucht werden soll (true) oder nicht (false). D.h., ob auch in den Kinderknoten nach dem Login-Benutzer gesucht werden soll. Der Standardwert ist (false). Vor allem bei großen LDAP-Baumen ist es häufig sinnvoll, diesen Wert auf false zu setzen, um die Systemlast zu vermindern. Allerdings muss dann der Parameter ftapi.search.base direkt auf die korrekte Ebene zeigen. Parameter für den Cleanup FTAPI besitzt einen Mechanismus um FTAPI Accounts, die zwar über LDAP angelegt wurden aber im LDAP System nicht mehr existieren, auch aus der FTAPI Benutzerdatenbank wieder zu entfernen. Dies stellt vor allem bei großen Benutzerdatenbanken eine deutliche Erleichterung für den LDAP-Administrator dar. ftapi.ldap.cleanup.enabled Dieser Parameter gibt an, ob die LDAP Cleanup-Funktion aktiv sein soll oder nicht. Der Standardwert ist false. ftapi.ldap.cleanup.interval Dieser Parameter ist ein Cron, der angibt, in welchen Intervallen ein Abgeleich der FTAPI Benutzeraccounts mit dem LDAP-System erfolgen soll. Im nachfolgenden Beispiel erfolgt eine solche Überprüfung täglich um 4:00 Uhr Morgens. Dies ist auch die Standardeinstellung. ftapi.ldap.cleanup.interval=0 0 4 * * ? Mapping von LDAP-Gruppen zu FTAPI-Rollen Standardmäßig kann sich jeder Benutzer, der einen gültigen Account im LDAP-System besitzt, in FTAPI einloggen. Er erhält in diesem Fall automatisch alle Rollen zugeordnet, die durch ftapi.ldap.default.roles spezifiziert wurden. Vor alle in größeren Umgebungen ist es jedoch oft gewollt, dass nur eine bestimme, privilegierte Gruppe von LDAP-Benutzern Zugang zum FTAPI-System erhält. FTAPI bietet Ihnen hierfür zwei verschiedene Möglichkeiten an, wie eine Zuordnung von LDAP-Gruppen zu FTAPI-Rollen erfolgen kann. Single Mapping & Multi Mapping Diese werden nachfolgend näher erklärt. Single Mapping Dies ist die einfachere Variante von beiden, um von LDAP zu FTAPI Rollen zu mappen und wird deshalb vor allem dann empfohlen, falls Sie keine feingranulare Zuordnung je Benutzer zu FTAPI-Rollen benötigen. Hier muss nur eine einzige Gruppe in LDAP angelegt werden (z.B. mit dem Namen FTAPI). Alle LDAP-Benutzer, die dieser Gruppe angehören, erhalten beim Login dann automatisch die FTAPI-Rollen zugeordnet, die durch das Property ftapi.ldap.default.roles definiert wurden. © FTAPI Software UG (2011), Seite 33 Im Active Directory Browser wäre hierfür beispielsweise folgende Struktur sinnvoll: Innerhalb der Organisationseinheit SBSUsers wurde hier die Gruppe FTAPI angelegt, welcher die für FTAPI privilegierten Benutzer hinzugefügt werden. Um Single Mapping zu aktivieren, müssen Sie in der FTAPI Konfigurationsdatei folgende Einstellungen vornehmen: © FTAPI Software UG (2011), Seite 34 #-------------------------------------------------------------------# LDAP to FTAPI role mapping settings #-------------------------------------------------------------------# Enables the LDAP to FTAPI role mapping # Default: false ftapi.ldap.role.mapping.enabled=true # The base path to start with the role search # Default: ou=FTAPIRoles,ou=SBSUsers,ou=Users,ou=MyBusiness,dc=ftapi,dc=local ftapi.ldap.role.mapping.search.base=ou=SBSUsers,ou=Users,ou=MyBusiness,dc=ftapi,dc=local # Should only one LDAP group used for mapping? # Default: true ftapi.ldap.role.mapping.single=true # The name of the single group # Default: FTAPI ftapi.ldap.role.mapping.single.group=FTAPI # Should a recursive search should be done starting at the role search base? # Default: false ftapi.ldap.role.mapping.search.subtree=false # The attribute where the name of the role can be found # Default: cn ftapi.ldap.role.mapping.attribute=cn # Should the name of the role always be converted to upper case? # Default: true ftapi.ldap.role.mapping.touppercase=true Die wichtigsten Einstellungen zu den obigen Properties sind nachfolgend noch einmal zusammengefasst: ftapi.ldap.role.mapping.enabled=true aktiviert das generelle Mapping von LDAP-Gruppen zu FTAPI-Rollen ftapi.ldap.role.mapping.search.base Angabe des LDAP-Pfades zum Verzeichnis, in welchem sich die LDAP-Gruppe befindet ftapi.ldap.role.mapping.single=true aktiviert das Single Mapping ftapi.ldap.role.mapping.single.group=FTAPI Name der LDAP-Gruppe, welcher alle LDAP-Benutzer zugeordnet sein müssen, um FTAPI verwenden zu können. Diese Gruppe muss sich innerhalb des Pfads befinden, der durch ftapi.ldap.role.mapping.search.base angegeben wurde ftapi.ldap.default.roles Stellen Sie sicher, dass hier all diejenigen FTAPI-Rollen eingestellt sind, die ein Benutzer der der LDAP-Gruppe FTAPI zugeordnet ist, standardmäßig erhält. Nachfolgend als Beispiel die Standard-Zuordnungen: # Any user which was authenticated thru LDAP, will have assigned these FTAPI roles by default. # Example: ROLE_SENDER,ROLE_UI_USER,ROLE_RECEIVER # Default: (empty) ftapi.ldap.default.roles=ROLE_SENDER,ROLE_UI_USER,ROLE_RECEIVER Multi Mapping Im Gegensatz zum Single Mapping, bietet das Multi Mapping die Möglichkeit der 1-zu-1-Zuordnung von LDAP-Gruppen zu FTAPI-Rollen. Legen Sie hierfür in LDAP einfach eine Gruppe an, die denselben Namen wie die zugehörige FTAPI-Rolle (z.B. ROLE_SENDER) besitzt und fügen Sie dieser die entsprechenden LDAP-Benutzer hinzu. Sobald sich diese LDAP-Benutzer in FTAPI einloggen, werden sie automatisch der gleichnamigen FTAPI-Rolle (z.B. ROLE_SENDER) zugeordnet. Dies können Sie für alle anderen FTAPI-Rollen gleichermaßen durchführen. © FTAPI Software UG (2011), Seite 35 Im Active Directory Browser ist hierfür beispielsweise folgende Struktur sinnvoll: Innerhalb der Organisationseinheit SBSUsers wurde eine weitere Organisationseinheit FTAPIRoles erstellt, in welcher sich die eigentlichen Rollen befinden. Um Multi Mapping zu aktivieren, müssen Sie in der FTAPI Konfigurationsdatei folgende Einstellungen vornehmen: © FTAPI Software UG (2011), Seite 36 #-------------------------------------------------------------------# LDAP to FTAPI role mapping settings #-------------------------------------------------------------------# Enables the LDAP to FTAPI role mapping # Default: false ftapi.ldap.role.mapping.enabled=true # The base path to start with the role search # Default: ou=FTAPIRoles,ou=SBSUsers,ou=Users,ou=MyBusiness,dc=ftapi,dc=local ftapi.ldap.role.mapping.search.base=ou=FTAPIRoles,ou=SBSUsers,ou=Users,ou=MyBusiness,dc=ftapi,dc=local# Should only one LDAP group used for mapping? # Default: true ftapi.ldap.role.mapping.single=false # The name of the single group # Default: FTAPI ftapi.ldap.role.mapping.single.group=FTAPI # Should a recursive search should be done starting at the role search base? # Default: false ftapi.ldap.role.mapping.search.subtree=false # The attribute where the name of the role can be found # Default: cn ftapi.ldap.role.mapping.attribute=cn # Should the name of the role always be converted to upper case? # Default: true ftapi.ldap.role.mapping.touppercase=true Beim Mulit Mapping ist lediglich das folgende Property - im Vergleich zum Single Mapping (s. oben) - anders einzustellen. ftapi.ldap.role.mapping.single=false deaktiviert das Single Mapping und aktiviert das Multi Mapping Zusätzlich müssen Sie sicherstellen, dass im Property ftapi.ldap.default.roles kein Wert gesetzt ist, damit keine Zuordnung zu den Standard-FTAPI-Rollen erfolgt (außer Sie wünschen dies explizit): # Any user which was authenticated thru LDAP, will have assigned these FTAPI roles by default. # Example: ROLE_SENDER,ROLE_UI_USER,ROLE_RECEIVER # Default: (empty) ftapi.ldap.default.roles= Bitte beachten Sie, dass die Rolle ROLE_ADMIN dem zugeordneten Benutzer zwar das Recht zum Bearbeiten von anderen Benutzern und Einstellungen zuweist, allerdings nicht andere Rechte, wie z.B. den Login in die Web-UI oder das Versenden. Hierfür muss der Benutzer auch zusätzlich den anderen Rollen, wie z.B. ROLE_UI_USER oder ROLE_SENDER zugeordnet werden. SubmitBox Eine SubmitBox bietet Ihren Kunden und Partnern die Möglichkeit, Ihnen große und/oder sensible Daten über eine einfache Website zu übermitteln, ohne dass diese spezielle Software installieren oder sich Zugangsdaten merken müssen. Hier zum Beispiel die SubmitBox (Einreicheportal) von Herrn Mustermann: © FTAPI Software UG (2011), Seite 37 SubmitBox aufrufen Jeder FTAPI-Benutzer erhält automatisch eine eigene SubmitBox. Dies ist über die URL http://<host>/submit/<username> erreichbar, wobei <host> für den Hostnamen Ihres FTAPI-Servers und <username> für den entsprechenden Benutzernamen steht. Ein Beispiel http://localhost:8080/submit/MaxMustermann Die SubmitBox-URL ist ähnlich einer E-Mail oder Telefonnummer: Sie können diese über Ihre Website oder E-Mail-Signatur an Ihre Kunden und Partner publizieren mit dem Hinweis, dass sie große und/oder sensible Dateien direkt über diese URL an Sie zustellen können. Beispiel: Um große oder sensible Daten an mich zu übermitteln, verwenden Sie bitte folgenden Link: http://server/submit/MaxMustermann SubmitBox aktivieren bzw. deaktivieren Standardmäßig ist die SubmitBox des jeweiligen Benutzers bei dessen Neuanlage aktiviert. Es kann in den Benutzereinstellungen des entsprechenden Benutzers nachträglich deaktiviert werden. Ist die SubmitBox deaktiviert, so wird bei dessen Aufruf eine entsprechende Meldung angezeigt. Externe Partner und Kunden können dann keine Daten über das SubmitBox einreichen. Download Disclaimer In FTAPI haben Sie die Möglichkeit, sich vom Empfänger einer Zustellung zuvor eine Zustimmung zu festgelegten Bedingungen einzuholen, bevor dieser den Download starten kann. Erst wenn der Empfänger den angezeigten Bedingungen durch Anklicken der Checkbox "Ich stimme zu" zustimmt, kann er den Download starten. Hierdurch können Sie auf einfache Art und Weise eine rechtliche Sicherheit herstellen. Sowohl der Zeitpunkt der Zustimmung als auch der Fingerprint des entsprechenden Disclaimer-Textes werden festgehalten und können für spätere Zwecke wieder geladen werden. Aktivieren und konfigurieren Um diese Funktion zu aktivieren, müssen Sie in der Konfigurationsdatei den Wert ftapi.download.disclaimer.enabled auf true setzen. Über den Parameter ftapi.download.disclaimer.path geben Sie den Pfad zur Disclaimer Text-Datei an, welche den Disclaimer-Text beinhaltet, der dem Empfänger vor dem Herunterladen einer Zustellung angezeigt werden soll. Standardmäßig ist dies #{ftapi.home}/templates/download-disclaimer.txt. Eigenen Disclaimer-Text ergänzen In der Regel ist keine Anpassung dieses Pfades, jedoch die Ergänzung Ihres eigenen Disclaimer-Textes in der zuvor genannten Datei, notwendig. Präfix-Regeln © FTAPI Software UG (2011), Seite 38 Wenn Sie den Wert ftapi.download.disclaimer.enabled auf true setzen, wird zunächst ausnahmslos für jede Zustellung dem Empfänger der Download-Disclaimer angezeigt. Dies ist allerdings nicht immer gewollt, da Sie z.B. nur für bestimmte Zustellungen einen Disclaimer anfordern möchten und für andere wiederum keinen benötigen. Hierfür können Sie den Parameter ftapi.download.disclaimer.subject.prefixes verwenden, welcher standardmäßig zunächst leer ist. Falls Sie hier mindestens ein sogenanntes Präfix angeben, wird mit jeder Zustellung dessen Betreff mit diesem Präfix abgeglichen und der Download-Disclaimer nur dann angezeigt, falls der Betreff (genau) mit diesem Präfix beginnt. Sie können auch mehrere Präfixes definieren, indem Sie diese durch ein Komma trennen. In diesem Fall wird der Disclaimer nur dann angezeigt, wenn der Betreff mit einem dieser Präfixe beginnt. Ein Beispiel: Angenommen, Ihre Präfix-Einstellung lautet wie folgt: ftapi.download.disclaimer.subject.prefixes=[RELEASE],[UPDATE] So würden folgende Betreffzeilen dazu führen, dass beim Download der Download Disclaimer angezeigt wird: [UPDATE] Ihr Software 1.1 Update [RELEASE] Ihr Software 2.0 Release Hingegen würden die folgenden Betreffzeilen dazu führen, dass beim Download der Download Disclaimer nicht angezeigt wird: Ihr Software 1.1 Update Ihr Software 2.0 Release Web-Templates FTAPI verwendet eine einheitliche Weboberfläche zur Darstellung der Benutzermasken. Eine Anpassung (Customizing) an Ihr Corporate Design ist grundsätzlich mit Kenntnissen in CSS und HTML möglich. Für eine Funktionsgarantie lassen Sie sich bitte für Anpassungen vom FTAPI Support unterstützen. Das Aussehen der von FTAPI ausgelieferten Web-UI ist hier dokumentiert und dargestellt. Web-Templates Das Aussehen der FTAPI Weboberflächenwird durch mehrere sogenannte Web-Templates festgelegt. Alle Templates und Bilder befinden sich im Verzeichnis _\ftapi-server\webapps\ftapi-server\webui\themes\default_ \resources und \templates Ihrer FTAPI-Server-Installation. Bitte beachten Sie, dass Änderungen an den Web-Templates nur durch den FTAPI-Support durchgeführt werden sollten. Falls Sie dennoch diese Web-Templates selbst anpassen möchten, kann FTAPI hierfür keine Haftung übernhemen. Falls dadurch Probleme im Betrieb von FTAPI entstehen, sind Sie hierfür selbst verantwortlich. E-Mail Templates In FTAPI werden für verschiedene Vorgänge automatisch generierte E-Mails versendet. Das Format dieser E-Mails wird jeweils durch ein E-Mail-Template festgelegt. Die E-Mail-Templates werden beim ersten Start des FTAPI-Servers in das Verzeichnis ~/.ftapi/templates/notification kopiert. Dort können Sie anschließend Anpassungen an den jeweiligen Templates vornehmen. Standardmäßig kommt die Template-Engine Velocity zum Einsatz. Für nähere Hinweise werfen Sie bitte einen Blick in die Dokumentation zu dieser Template-Engine (http://velocity.apache.org/). In welchen Situationen die einzelnen Templates verwendet werden, ist immer direkt im jeweiligen Template beschrieben. Folgende Templates werden derzeit verwendet: DownloadCommittedNotification.txt.vtl © FTAPI Software UG (2011), Seite 39 Vorlage für E-Mail, wenn ein "Downloadbestätigung an den Versender" versandt wird IssueNotification.txt.vtl Vorlage für "Vorschlag oder Problem versenden" SubmitConfirmationNotification.txt.vtl Vorlage für "Einreichebestätigung an (externen) Submitter" SubmitTicketCreatedNotification.txt.vtl Vorlage für "Submit Ticket wurde für Sie bereit gestellt" - Mail an externen Submitter NewDeliveryNotification.txt.vtl Vorlage für Text, der an jeder E-Mail mit "Downloadlink am Ende" angehängt wird Innerhalb eines Templates werden häufig implizite Objekte zur Verfügung gestellt. Welche Objekte dies sind, wird ebenfalls im jeweiligen Template beschrieben. Benutzer importieren Sie haben in FTAPI die Möglichkeit, mehrere Benutzer auf einmal in das System zu importieren. Wechseln Sie hierfür in das Verzeichnis .ftapi/import und öffnen Sie die Datei default-users.csv. Hierbei handelt es sich um eine sogenannte CSV-Datei, welche nachfolgend beispielhaft dargestellt ist: # Username; Password; Enabled; Email; FirstName; LastName; Roles; # ----------------------------------------------------------------------------------------------------BugsBunny; {MD5}acbd; true; [email protected]; Bugs; Bunny; ROLE_ADMIN, ROLE_UI_USER, ROLE_SENDER; Jeder Benutzer, der in das System eingetragen werden soll, muss in einer eigenen Zeile definiert werden, wobei die einzelnen Spalten durch ein Semikolon ; voneinander getrennt sein müssen. Existiert ein Benutzer mit dem angegebenen Username bereits, so wird er nicht erneut eingetragen. Auch ein Update dieser Benutzerdaten erfolgt nicht. Mehrere Rollen müssen durch ein Komma , voneinander getrennt sein. Nachdem Sie die Eintragungen durchgeführt haben, starten Sie den FTAPI Server neu. Die aufgelisteten Benutzer werden anschließend sofort in Ihr FTAPI-System importiert. Kurze Beschreibung der einzelnen Spalten: Username (erforderlich): Der eindeutige Name des Benutzers. Existiert bereits ein Benutzer mit demselben Namen, wird der Import für diesen Benutzer übersprungen. Password (erforderlich): Das Passwort, welches für den Login verwendet werden soll. Aus Sicherheitsgründen sollten Sie hier ausschließlich codierte Passwörter angeben. Unterstützt werden die beiden Hash-Verfahren MD5 und SHA. Welcher Hash-Algorithmus verwendet wurde, muss durch das Präfix {MD5} bzw {SHA} vor dem Passwort angegeben werden. Wird kein solches Präfix gesetzt, so wird davon ausgegangen, dass das Passwort im Klartext vorliegt (nicht empfohlen). Enabled (optional): Gibt an, ob der angegebene Benutzer aktiviert (true) oder deaktiviert (false) sein soll. Wird hier kein Wert angegeben, so wird der Wert true angenommen. Email (erforderlich): Die eindeutige E-Mail-Adresse des Benutzers. FirstName (optional): Der Vorname des Benutzers. LastName (optional): Der Nachname des Benutzers. Roles (erforderlich): Eine kommaseparierte Liste an Rollen, die dem Benutzer zugewiesen werden sollen. Hier finden Sie eine Beschreibung aller in FTAPI verfügbaren Rollen! FTAPI Client - BETA Der FTAPI Client ist als BETA Version Bestandteil dieser Auslieferung. Bitte beachten Sie, dass aufgrund des Beta-Stadiums der Support für diesen FTAPI nicht Bestandteil eines Support- und Wartungsvertrages ist. Eine Garantie für die vollständige Funktionsfähigkeit ist hierfür nicht gegeben. Einrichtung des Clients © FTAPI Software UG (2011), Seite 40 Der FTAPI Client liegt jeder Auslieferung im Ordner \ftapi-client bei. Der Client kann entweder in Form einer Weitergabe des Ordners ftapi-client an alle Mitarbeiter verteilt werden, oder durch die Aktivierung der Downloadoption (s. weiter unten!) direkt von jedem Benutzer nach erfolgreichem Login selbst heruntergeladen werden Bedienung des Clients Es wird empfohlen, eine Desktopverknüpfung für den Client anzulegen. Für Windows verknüpfen Sie die Datei ftapi-client.exe, bei Mac oder Linux die Datei ftapi-client.bat. Folgende Werte müssen für einen erfolgreichen Login angegeben werden: Im Gegensatz zum Login über einen Web-Browser muss am Ende der Server-URL noch /services/rest ergänzt werden. Der Benutzer-Login kann gespeichert werden, so dass beim nächsten Aufruf des Clients der dargestellte Login-Screen nicht mehr erscheint. Der Client an sich entspricht dem Bereich "Neue Sendung" auf der Web-Oberfläche: © FTAPI Software UG (2011), Seite 41 Auch hier wird vor dem Upload-Beginn überprüft, ob mind. eine gültige E-Mailadresse, ein Betrefftext und mind. eine Datei vorhanden sind! Aktivierung in WebUI Wenn Sie möchten, dass der Client allen Benutzern von FTAPI zum Download zur Verfügung steht, dann können Sie dies in der Datei .ftapi/config/server-production.properties aktivieren (= auf true setzen). #-------------------------------------------------------------------# WebUI settings #-------------------------------------------------------------------# Allows to download the FTAPI Client for the users by # simply clickinig a download link on the dashboard. # NOTE: This feature is BETA. Enable it at your own risk # and without any support from FTAPI Support Team. ftapi.webui.clientdownload.enabled=true Jeder Benutzer, der die Berechtigung hat, sich in der FTAPI WebOberfläche anzumelden, sieht anschließend auf seiner Übersichtsseite UND bei jeder neuen Sendung den folgenden Hinweis: © FTAPI Software UG (2011), Seite 42 Es wird empfohlen, sich einen Ordner ftapi-client anzulegen, die Dateien darin zu entpacken und dann eine Desktopverknüpfung auf ftapi-client.exe (Windows) oder .bat (Mac/Linux) zu erstellen. Zurücksetzen des Clients Um den Client auf den Auslieferungszustand zurückzusetzen, muss das entsprechende Verzeichnis gelöscht werden. Anschließend können alle Server- und Logindaten neu eingegeben werden. Standardmäßig werden die Einstellungen im Heimatverzeichnis des gerade angemeldeten Benutzers abgespeichert. In Windows wäre dies c:\users\Username\.ftapi\client Wenn Sie bei einem Benutzer den Ordner \client komplett löschen, dann ist dieser FTAPI Client auf den Auslieferungszustand zurückgesetzt und alle Daten für einen Login können erneut eingegeben werden. Action Logs Zahlreiche Aktionen, die in FTAPI durchgeführt werden, werden protokolliert. Somit ist es ein Leichtes, später Auswertungen durchzuführen und z.B. verantwortliche Personen zu ermitteln. Die letzten 1000 Aktionen können direkt über die Administrations-Oberfläche im Menüpunkt Logs -> Aktionen eingesehen werden. Beispiel: Benötigen Sie hingegen alle Aktionen, so finden Sie diese in der verwendeten SQL-Datenbank in der Tabelle ActionLog. Serverseitiges Scripting Bitte beachten Sie, dass sich dieses Kapitel auf Funktionen bezieht, die nur in den FTAPI Professional und Enterprise Editionen vorhanden sind. FTAPI bietet Ihnen eine elegante und zugleich mächtige Möglichkeit, serverseitige Skripte einzubinden und auszuführen. Dies kann sinnvoll sein, um z.B. auf eingehende Dateien mit einer entsprechenden Aktion zu reagieren (z.B. große Bilder in kleine Thumbnails rendern) oder um per Remote bestimmte Aktionen auf dem Server anzustoßen. Unterstützt werden nahezu alle wichtigen Script-Arten, wie z.B. serverseitiges JavaScript, Groovy, Python, Ruby, um nur einige wenige zu nennen. Grundsätzlich werden alle Script-Arten unterstützt, die auf https://scripting.dev.java.net/ genannt sind und auch von Java unterstützt werden. Standardmäßig ist die JavaScript-Engine Mozilla Rhino bereits aktiviert. D.h., Sie können ohne großen Aufwand sofort serverseitige JavaScript-Skripte erstellen und ausführen. Möchten Sie hingegen eine andere Script-Engine verwenden, so müssen Sie diese zuvor aktivieren - dies wird am Ende dieses Kapitels beschrieben. © FTAPI Software UG (2011), Seite 43 Falls Sie umfangreiche Aufgaben mit der FTAPI Scripting Engine durchführen möchten, sollten Sie zumindest grundlegende Kenntnisse nicht nur in der entsprechenden Scriptsprache, sondern auch Java haben, da Sie von jedem Script aus auch auf die FTAPI-Objekte zugreifen können, die in Java dokumentiert sind. In diesem Kapitel basieren die Beispiele zwar allesamt auf der Skriptsprache JavaScript, können aber mit der Syntax der jeweiligen anderen Skriptsprache ebenfalls durchgeführt werden. Eine gute Einführung in die Verwendung von Java innerhalb von JavaScript bietet die Website von Rhino: https://developer.mozilla.org/en/Scripting_Java Skript-Home-Verzeichnis Skript erstellen Implizite Objekte springContext configRepo Skript ausführen Skript per Remote ausführen Per URL-Aufruf Per FTAPI-Command Skript beim Starten des Servers ausführen Skript zeitgesteuert ausführen Skript ereignisgesteuert ausführen Andere Script-Engine aktivieren Groovy einbinden Skript-Home-Verzeichnis Bevor Sie mit dem Erstellen von Skripten beginnen, sollten Sie sicher stellen, dass die Konfigurationsvariable ${ftapi.script.home} in Ihrer Konfigurationsdatei server-production.properties korrekt gesetzt ist. Sie muss auf das Verzeichnis zeigen, in dem sich später alle ausführbaren Skripte befinden werden. Standardmäßig ist dies ${ftapi.home}/scripts. Sie können diesen Pfad aber natürlich Ihren Bedürfnissen entsprechend anpassen. Skript erstellen Um ein Skript ausführen zu können, müssen Sie hierfür zunächst eine Datei im Verzeichnis ${ftapi.script.home} erstellen. Die Datei kann einen beliebigen Namen besitzen und muss mit einem Suffix enden, welches der zu verwendenden Script-Engine zugeordnet ist. Für JavaScript lautet dieses Suffix standardmäßig .js. D.h., dass eine Datei helloworld.js also immer mit der JavaScript Engine ausgeführt werden würde. Die wichtigsten Suffix-Engine-Mappings lauten: .js = JavaScript engine .groovy = Groovy engine .rb = Ruby engine .py = Python engine Implizite Objekte Innerhalb eines Skripts haben Sie Zugriff auf verschiedene implizite Objekte, ohne dass Sie diese selbst instanziieren müssen. Diese Objekte werden nachfolgend näher beschrieben. springContext Unter dem Namen springContext wird Ihnen der gesamte (so genannte) Application Context zur Verfügung gestellt. Über dieses Objekt erhalten Sie Zugriff zu allen Manager-Objekten des FTAPI-Systems. Um beispielsweise das Config-Repository zu laden, könnten Sie in JavaScript folgendermaßen vorgehen: var config = springContext.getBean("configRepository"); Das Objekt springContext ist eine Instanz von http://static.springsource.org/spring/DOCS11/3.0.3.RELEASE/javadoc-api/org/springframework/web/context/WebApplicationContext.html; Um mit dem Application Context zu arbeiten, ist ein umfassendes Wissen über das FTAPI System und das verwendete Framework Spring notwendig. configRepo © FTAPI Software UG (2011), Seite 44 Das Config-Repository können Sie entweder über das implizite Objekt springContext laden oder direkt das implizit zur Verfügung gestellte Objekt configRepo verwenden. Über dieses Objekt erhalten Sie vollen Zugriff auf alle Konfigurationseinstellungen des FTAPI Systems. Um beispielsweise den Wert für ftapi.script.home auszulesen, können Sie in JavaScript folgendermaßen vorgehen: var scriptHome = configRepo.getValue("ftapi.script.home"); Das Objekt configRepo ist eine Instanz von der FTAPI Klasse ConfigRepository. Skript ausführen Nachdem Sie ein Skript im Verzeichnis ${ftapi.script.home} mit einem entsprechenden Suffix erstellt haben, können Sie dieses sofort ausführen. Hierfür stehen Ihnen drei verschiedene Möglichkeiten zur Verfügung: Remote per FTAPI Kommando Zeitgesteuert per Cron-Job Eventgesteuert per FTAPI Server Event Beim Starten des Servers Skript per Remote ausführen Per URL-Aufruf Sie können ein Skript per Remote von jedem Ort der Welt aus ausführen, indem Sie einfach die URL http://ihr-server/services/rest/script/ExecuteScript?scriptName=example.js aufrufen, wobei Sie natürlich "ihr-server" durch die Addresse Ihres Servers und "example.js" durch den Namen des auszuführenden Skripts ersetzen müssen. Darüber hinaus müssen Sie gegenüber dem FTAPI Server natürlich entsprechend authentifiziert sein, um die Ausführung durchführen zu dürfen, indem Sie sich zuvor eingeloggt haben oder anderweitig per HTTP authentifiziert haben. Per FTAPI-Command Eine weitere Möglichkeit hierfür bietet das FTAPI Kommando CmdExecuteScript, welches die gesamte Authentifizierungs-Prozedur für Sie übernimmt und in Kombination mit dem FTAPI Command Ant Task zusammen mit anderen Kommands ausgeführt werden kann. Sehen Sie sich hierzu das Kapitel Commands an, um weitere Informationen zur Ausführung von FTAPI Commands zu erhalten. Skript beim Starten des Servers ausführen In manchen Situationen kann es sinnvoll sein, ein oder mehere Skripte unmittelbar beim Starten des Servers auszuführen, um z.B. bestimmte Initialisierungen oder Benachrichtigungen durchzuführen. Hierfür muss das Skript lediglich unter dem Konfigurations-Property ftapi.script.startup in der Konfigurationsdatei server-production.properties eingetragen werden. Mehrere Skripte können angegeben werden, indem diese durch Kommata voneinander getrennt werden. Die Reihenfolge in der die Skripte ausgeführt werden entspricht der Reihenfolge der Definition. Das nachfolgende Beispiel führt beim Server-Startup die Skripte boot.js und example.js nacheinander aus: ftapi.script.startup=boot.js, example.js Standardmäßig ist das Skript init.js bereits als Startup-Skript registriert. Falls Ihnen ein einzelnes Startup-Skript ausreicht, müssen Sie keine Anpassungen an der Konfiguration vornehmen, sondern können Ihre Startup-Definitionen direkt im Skript init.js platzieren. Skript zeitgesteuert ausführen Sie können Skripte zeitgesteuert ausführen, indem Sie diese programmatisch über ein weiteres Skript registrieren. Das nachfolgende Beispiel zeigt den Inhalt des Skripts init.js, welches wiederum das Skript helloworld.js für eine zeitgesteuerte Ausführung alle 59 Sekunden registriert: var scriptManager = springContext.getBean("scriptManager"); scriptManager.registerCronScript("helloworld.js", "59 * * * * ?"); Die Syntax für die Cron-Definition wird durch Quartz festgelegt. Mehr Informationen hierzu erhalten Sie auf der Website des Quartz Projekts. Mehr Informationen zur Verwendung des Script-Managers erhalten Sie in der Javadoc zur Klasse ScriptManager. © FTAPI Software UG (2011), Seite 45 Bitte beachten Sie, dass die programmatische Registrierung des Skripts transient ist. D.h., dass die Registrierung bei einem Neustart des Servers verloren geht. Um eine persistente Registrierung durchzuführen, müssen Sie dasjenige Skript, welche die Registrierung durchführt, in den Startup-Prozess einbinden, wie im Abschnitt ?weiter oben beschrieben. Skript ereignisgesteuert ausführen Skripte können auch immer dann automatisiert ausgeführt werden, wenn bestimmte Ereignisse auf dem Server auftreten. Hierzu ist das jeweilige Skript unter dem entsprechenden Ereignis zu registrieren. Dies erfolgt ebenfalls programmatisch aus einem Skript init.js heraus, wie nachfolgendes Beispiel zeigt: var scriptManager = springCOntext.getBean("scriptManager"); scriptManager.registerEventScript("hello-event.js", com.ftapi.server.event.ServerEventEntityPropertyChanged); Dieses Beispiel-Skript registriert das Skript hello-event.js unter dem Event ServerEventEntityPropertyChanged. D.h., es wird zukünftig immer dann ausgeführt, wenn sich irgendein persistiertes Property ändert. In der Javadoc im Package com.ftapi.server.event erhalten Sie eine Auflistung aller verfügbaren Server-Events, die Sie in Ihrem Skript verwenden können. Bitte beachten Sie, dass der zweite Parameter von registerEventScript() eine Java-Event-Klasse sein muss, welche durch ihren voll qualifizierenden Pfad angegeben ist. Innerhalb eines Event-Skripts wird Ihnen automatisch die implizite Variable serverEvent zur Verfügung gestellt, welche vom Typ der angegebenen Event-Klasse ist, wie nachfolgendenes Beispiel von hello-event.js zeigt: println("Property changed event fired. Property name: " + serverEvent.getPropertyName()); Bitte beachten Sie, dass die programmatische Registrierung des Skripts transient ist. D.h., dass die Registrierung bei einem Neustart des Servers verloren geht. Um eine persistente Registrierung durchzuführen, müssen Sie dasjenige Skript, welche die Registrierung durchführt, in den Startup-Prozess einbinden, wie im Abschnitt weiter oben beschrieben. Andere Script-Engine aktivieren Neben der standardmäßig aktivierten JavaScript-Engine können Sie auch zahlreiche andere Script-Engines in FTAPI einbinden. Die einzige Bedingung für die zu verwendende Script-Engine besteht darin, dass sie eine ScriptEngine-Implementierung besitzt, die mit dem Java-Standard JSR-223 kompatibel ist. Eine Liste solcher Engines erhalten Sie auf der Website von java.net: https://scripting.dev.java.net/ Groovy einbinden Eine Script-Engine, welche mit JSR-223 kompatibel ist, ist Groovy. Anhand dieser Script-Engine soll beispielhaft erklärt werden, wie eine solche Script-Engine eingebunden werden kann. Im ersten Schritt laden Sie sich Groovy herunter und kopieren Sie die Jar-Datei, welche die Groovy-Engine enthält, nach ${FTAPI_SERVER}/WEB-INF/lib, wobei ${FTAPI_SERVER} für den Pfad steht, in dem Ihr FTAPI Server installiert ist. Im zweiten und letzten Schritt müssen Sie nur noch ein Mapping zwischen der neuen Groovy Engine und der Skript-Endung ".groovy" erstellen, damit FTAPI weiß, dass Skripte mit dieser Endung mit der Grooy-Engine auszuführen sind. Öffnen Sie hierzu die Datei ${FTAPI_SERVER}/WEB-INF/classes/sc-core.xml und fügen Sie folgenden Eintrag innerhalb von <property name="engineExtensionMapping"> hinzu: <entry key=".groovy" value="groovy"/> Damit wird ein Mapping zwischen der Endung .groovy und der Script-Engine unter dem offiziellen Namen groovy erzeugt. Wie dieser offizielle Name für Ihre Script-Engine lautet, entnehmen Sie bitte der Dokumentation der jeweiligen Engine. FTAPI REST Commands © FTAPI Software UG (2011), Seite 46 Bitte beachten Sie, dass sich dieses Kapitel auf Funktionen bezieht, die nur in den FTAPI Professional und Enterprise Editionen vorhanden sind. DRAFT Bitte beachten Sie, dass dieses Kapitel noch nicht final ist, d.h., es ist noch nicht vollständig bzw. Inhalte können sich noch ändern. Einführung Übersicht über FTAPI Commands AddDeliverablesOnUploadTicket CreateSubmitTicket CreateUploadTicket DeleteUser Deliver Echo ExecuteScript FindAllRoles FindAllUsers FindDefaultSubmitPortal FindDeliverableCollectionByUuid FindDeliveriesByTemplate FindDeliveryByUuid FindNextUploadSegment FindNumberOfDownloadTickets FindRoleByName FindSubmitPortalByName FindSubmitPortalByUuid FindSubmitTicketByUuid FindUploadTicketByUuid FindUserByEmail FindUserById FindUserByUsername FindUserExists GetLog GetServerInfo RegisterDeliverable RegisterDeliverableCollection RegisterDeliveryTemplate RegisterRecipient RegisterUploadTicket SaveUser SendDeliveries SendDeliveries SendIssue SetConfigProperty Submit Upload UploadDeliverable Einführung FTAPI Commands bieten die Möglichkeit, den FTAPI Server per Remote durch den Aufruf einfacher HTTP-Befehle (Kommandos) zu steuern. Dabei wird als Basis der so genannte Representational State Transfer (REST) verwendet und somit eine äußert einfache, aber zugleich mächtige Möglichkeit geboten, per WebService auf den FTAPI Server zugreifen zu können. REST wird unter anderem von Firmen wie Google oder Amazon für Ihre Cloud-Services intensiv eingesetzt und gilt als einfachere und flexiblere Alternative zu SOAP. Grundsätzlich ist es möglich, alle FTAPI Commands z.B. direkt über einen Web-Browser aufzurufen, indem die Kommando-URL direkt in die Adresszeile des Browsers eingegeben wird.z.B.: http://localhost/ftapi-server/services/rest/GetServerInfo Allerdings wird dies spätestens bei POST-Anfragen und mehreren Anfragen, die unmittelbar nacheinander ablaufen sollen, mühsam und unübersichtlich. Stattdessen bietet es sich an, die FTAPI Commands z.B. durch eigene Bash-Skripte oder mit Hilfe von Ajax auszuführen. Die Möglichkeiten - wie die FTAPI Commands aufgerufen werden - sind groß, da grundsätzlich keine Bindung an eine spezielle Programmiersprache besteht. Jede Umgebung, die das HTTP-Protokoll versteht, kann theoretisch auch FTAPI Commandos ausführen. Als Austauschformat zwischen Client und FTAPI Server kommen zwei Varianten in Frage, die durch den HTTP-Header "Content-Type" © FTAPI Software UG (2011), Seite 47 entsprechend gesetzt werden können, wie durch REST definiert: Serialisierte Java-Objekte JSON-Dokumente Während ersteres nur dann sinnvoll ist, wenn der Client ebenfalls in Java geschrieben ist, wird die zweite Variante vor allem in Nicht-Java-Umgebungen sinnvoll. JSON ist ein Format - ähnlich wie XML - welches aber deutlich kompakter ist und vor allem im Web-Umfeld (AJAX) sowie bei NoSQL-Datenbanken immer häufiger Verwendung findet. Damit wird es möglich, die FTAPI Commands z.B. direkt von einer Website aus per Javascript aufzurufen und z.B. Download-Statistiken oder Datenpakete in eine Web-Präsenz nahtlos und interaktiv einzubinden und den FTAPI Server beispielsweise zu einem zentralen Download-Server zu machen. Wird kein Content-Type definiert, so wird standardmäßig JSON als Austauschformat verwendet. Übersicht über FTAPI Commands Nachfolgend erhalten Sie eine Übersicht über alle - in den zu Beginn dieses Kapitels genannten Editionen - verfügbaren Kommandos, in englischer Sprache. In dieser Version der Commands-Übersicht werden nur die Java-Datentypen als Argumente bzw. Rückgabewerte verwendet. JSON-Dokumente können jedoch einfach daraus abgeleitet werden, indem die Regeln von http://wiki.fasterxml.com/JacksonDataBinding angewandt werden. Die Dokumentation zu den JSON-Dokumenten wird im nächsten Release nachgereicht. AddDeliverablesOnUploadTicket Add the deliverables from deliverable collection with given uuid on the upload ticket with given uuid. Note: This is only possible as long as the upload of data has not been started for the given upload ticket so far. Currently its only possible to call this command once per upload ticket. Make it possible to call this command more than once. See also the upload tickets setDeliverables() for this. Java definition com.ftapi.cmd.def.upload.CmdAddDeliverablesOnUploadTicket Path /upload/AddDeliverablesOnUploadTicket/uploadTicketUuid/deliverableCollectionUuid Return void Parameters uploadTicketUuid: java.lang.String deliverableCollectionUuid: java.lang.String Return void Parameters uploadTicketUuid: java.lang.String files: java.io.File[] CreateSubmitTicket Creates a new submit ticket at server side. © FTAPI Software UG (2011), Seite 48 Java definition com.ftapi.cmd.def.submit.CmdCreateSubmitTicket Path /submit/CreateSubmitTicket/submitPortalUuid/email/createUser/sendNotify Return com.ftapi.cmd.dto.SubmitTicketDTO Parameters submitPortalUuid: java.lang.String email: java.lang.String createUser: boolean sendNotify: boolean CreateUploadTicket Creates, registers and returns a new upload ticket. Java definition com.ftapi.cmd.def.upload.CmdCreateUploadTicket Path /upload/CreateUploadTicket Return com.ftapi.cmd.dto.UploadTicketDTO Parameters DeleteUser Deletes the given user from the system. This also deletes any packages and deliveries associated with that user. Java definition com.ftapi.cmd.def.security.CmdDeleteUser Path /security/DeleteUser/userId Return void © FTAPI Software UG (2011), Seite 49 Parameters userId: long Deliver Delivers a given package to the given recipients. Java definition com.ftapi.cmd.def.deliver.CmdDeliver Path Return java.util.Set Parameters deliverableCollectionUuid: java.lang.String subject: java.lang.String message: java.lang.String recipients: java.lang.String[] Echo Prints the given text onto the console. Java definition com.ftapi.cmd.def.local.CmdEcho Path Return void Parameters text: java.lang.String inti: int ExecuteScript Executes the script with given name at server side. Note there must exist a script with exactly that name in the script home folder of the FTAPI server. Java definition com.ftapi.cmd.def.script.CmdExecuteScript Path /script/ExecuteScript © FTAPI Software UG (2011), Seite 50 Return void Parameters scriptName: java.lang.String FindAllRoles Returns all roles, registered in the system. Java definition com.ftapi.cmd.def.security.CmdFindAllRoles Path /security/FindAllRoles Return java.util.List Parameters FindAllUsers Finds all users, registered in the system. Java definition com.ftapi.cmd.def.security.CmdFindAllUsers Path /security/FindAllUsers Return java.util.List Parameters FindDefaultSubmitPortal Returns the uuid of the default submit portal of the given user id. Java definition com.ftapi.cmd.def.submit.CmdFindDefaultSubmitPortal Path © FTAPI Software UG (2011), Seite 51 /submit/FindDefaultSubmitPortal/userId Return java.lang.String Parameters userId: java.lang.Long FindDeliverableCollectionByUuid Finds a deliverable collection with given uuid. Java definition com.ftapi.cmd.def.deliver.CmdFindDeliverableCollectionByUuid Path /deliver/FindDeliverableCollectionByUuid/deliverableCollectionUuid Return com.ftapi.cmd.dto.DeliverableCollectionDTO Parameters uuid: java.lang.String FindDeliveriesByTemplate Finds all deliveries created using the given delivery template. Java definition com.ftapi.cmd.def.deliver.CmdFindDeliveriesByTemplate Path /deliver/FindDeliveriesByTemplate/deliveryTemplateUuid Return java.util.List Parameters deliveryTemplateUuid: java.lang.String FindDeliveryByUuid Finds the delivery with given uuid. © FTAPI Software UG (2011), Seite 52 Java definition com.ftapi.cmd.def.deliver.CmdFindDeliveryByUuid Path /deliver/FindDeliveryByUuid/deliveryUuid Return com.ftapi.cmd.dto.DeliveryDTO Parameters deliveryUuid: java.lang.String FindNextUploadSegment Finds the next upload segement for a given upload process of the given upload ticket uuid. Java definition com.ftapi.cmd.def.upload.CmdFindNextUploadSegment Path /upload/FindNextUploadSegment/ultUuid Return com.ftapi.cmd.dto.SegmentDTO Parameters ultUuid: java.lang.String FindNumberOfDownloadTickets Counts the number of existing download tickets at server side, assigned to the given user and in given state. Java definition com.ftapi.cmd.def.management.CmdFindNumberOfDownloadTickets Path /management/FindNumberOfDownloadTickets/userId/state Return java.lang.Long Parameters © FTAPI Software UG (2011), Seite 53 userId: long state: int FindRoleByName Finds a role with given name. Java definition com.ftapi.cmd.def.security.CmdFindRoleByName Path /security/FindRolebyName/roleName Return com.ftapi.cmd.dto.RoleDTO Parameters roleName: java.lang.String FindSubmitPortalByName Searches for a SubmitBox with given name and if found, returns it. If no SubmitBox with given name exists, also checks whether a portal's uuid corresponds to the given portalName. Java definition com.ftapi.cmd.def.submit.CmdFindSubmitPortalByName Path /submit/FindSubmitPortalByName/submitPortalName Return com.ftapi.cmd.dto.SubmitPortalDTO Parameters portalName: java.lang.String FindSubmitPortalByUuid Finds the SubmitBox by its uuid. Java definition com.ftapi.cmd.def.submit.CmdFindSubmitPortalByUuid Path /submit/FindSubmitPortalByUuid/submitPortalUuid © FTAPI Software UG (2011), Seite 54 Return com.ftapi.cmd.dto.SubmitPortalDTO Parameters submitPortalUuid: java.lang.String FindSubmitTicketByUuid Finds the submit ticket by its uuid. Java definition com.ftapi.cmd.def.submit.CmdFindSubmitTicketByUuid Path /submit/FindSubmitTicket/submitTicketUuid Return com.ftapi.cmd.dto.SubmitTicketDTO Parameters submitTicketUuid: java.lang.String FindUploadTicketByUuid Finds the upload ticket with given uuid and returns it. Java definition com.ftapi.cmd.def.upload.CmdFindUploadTicketByUuid Path /upload/FindUploadTicketByUuid/ultUuid Return com.ftapi.cmd.dto.UploadTicketDTO Parameters ultUuid: java.lang.String FindUserByEmail Finds a user by its email address. Since every user must have a unique email address in the system, this is possible. Java definition © FTAPI Software UG (2011), Seite 55 com.ftapi.cmd.def.security.CmdFindUserByEmail Path /security/FindUserByEmail/email Return com.ftapi.cmd.dto.UserDTO Parameters email: java.lang.String FindUserById Finds a user by its user id. Java definition com.ftapi.cmd.def.security.CmdFindUserById Path /security/FindUserById/userId Return com.ftapi.cmd.dto.UserDTO Parameters userId: long FindUserByUsername Finds a user by its unique username. Java definition com.ftapi.cmd.def.security.CmdFindUserByUsername Path /security/FindUserByUsername/username Return com.ftapi.cmd.dto.UserDTO Parameters username: java.lang.String © FTAPI Software UG (2011), Seite 56 FindUserExists Checks, whether a user with given is exists in the system. Java definition com.ftapi.cmd.def.security.CmdFindUserExists Path /security/FindUserExists/userId Return java.lang.Boolean Parameters userId: long GetLog Returns the log of given type. Java definition com.ftapi.cmd.def.management.CmdGetLog Path /management/GetLog/logType Return com.ftapi.content.ContentReference Parameters logType: java.lang.String GetServerInfo Returns information about the current state of the server as ServerInfoDTO. Java definition com.ftapi.cmd.def.management.CmdGetServerInfo Path /management/GetServerInfo Return © FTAPI Software UG (2011), Seite 57 com.ftapi.cmd.dto.ServerInfoDTO Parameters RegisterDeliverable A deliverable must be registered at server side before it can be send to the server. Doing it this way the server can decide whether it is willing to accept the deliverable beforehand and can make some presets like the segment size or the uuid. Java definition com.ftapi.cmd.def.upload.CmdRegisterDeliverable Path /upload/RegisterDeliverable Return com.ftapi.cmd.dto.FileDeliverableDTO Parameters deliverable: com.ftapi.cmd.dto.FileDeliverableDTO RegisterDeliverableCollection Registers the deliverable collection at server side. Note: All deliverables within the collection must be registered at server side beforehand. Java definition com.ftapi.cmd.def.upload.CmdRegisterDeliverableCollection Path /upload/RegisterDeliverableCollection Return com.ftapi.cmd.dto.DeliverableCollectionDTO Parameters collection: com.ftapi.cmd.dto.DeliverableCollectionDTO RegisterDeliveryTemplate Registers a new delivery template at server side. Java definition com.ftapi.cmd.def.deliver.CmdRegisterDeliveryTemplate © FTAPI Software UG (2011), Seite 58 Path /deliver/RegisterDeliveryTemplate Return java.lang.String Parameters deliveryTemplateDTO: com.ftapi.cmd.dto.DeliveryTemplateDTO RegisterRecipient Registers a new recipient. If such a recipient already exists, nothing happens. Java definition com.ftapi.cmd.def.deliver.CmdRegisterRecipient Path /deliver/RegisterRecipient Return com.ftapi.cmd.dto.RecipientDTO Parameters recipient: com.ftapi.cmd.dto.RecipientDTO RegisterUploadTicket Registers the given upload ticket and all of its containing FileDeliverableDTO at server side. Java definition com.ftapi.cmd.def.upload.CmdRegisterUploadTicket Path /upload/RegisterUploadTicket Return com.ftapi.cmd.dto.UploadTicketDTO Parameters ult: com.ftapi.cmd.dto.UploadTicketDTO SaveUser © FTAPI Software UG (2011), Seite 59 Saves the given user object at server side. Java definition com.ftapi.cmd.def.security.CmdSaveUser Path /security/SaveUser Return com.ftapi.cmd.dto.UserDTO Parameters user: com.ftapi.cmd.dto.UserDTO SendDeliveries Causes the server to create the delivery and send it to the registered recipients. Java definition com.ftapi.cmd.def.upload.CmdSendDeliveries Path Return void Parameters deliveryTemplate: com.ftapi.cmd.dto.DeliveryTemplateDTO SendDeliveries Creates deliveries from the given delivery template and sends them to the recipients. Java definition com.ftapi.cmd.def.deliver.CmdSendDeliveries Path /deliver/SendDeliveries Return java.util.Set Parameters deliveryTemplateUuid: java.lang.String © FTAPI Software UG (2011), Seite 60 SendIssue Sends a new issue to the FTAPI support. Java definition com.ftapi.cmd.def.management.CmdSendIssue Path /management/SendIssue Return void Parameters issue: com.ftapi.cmd.dto.IssueDTO SetConfigProperty This Command sets a property in the server config, or overwrites an existing one. The changes are made temporarily in memory, but will not be written to disk. Java definition com.ftapi.cmd.def.management.CmdSetConfigProperty Path /management/SetConfigProperty Return java.lang.String Parameters key: java.lang.String value: java.lang.String Submit Sends the given submit. Java definition com.ftapi.cmd.def.submit.CmdSubmit Path /submit/submit © FTAPI Software UG (2011), Seite 61 Return void Parameters submit: com.ftapi.cmd.dto.SubmitDTO Upload A macro command which has no real counterpart implementation at server side. It takes a bunch of files or an upload ticket and sends the defined files to the server using other commands. The implementation of this interface must react upon the following events: <ul> ClientEventUploadPauseRequested </ul> The implementation must send the following events when required: <ul> ClientEventUploadStarted ClientEventUploadFileStarted ClientEventUploadBytesSent ClientEventUploadFileFinished ClientEventUploadFinished ClientEventUploadPaused ClientEventUploadResumed </ul> Java definition com.ftapi.cmd.def.upload.CmdUpload Path Return com.ftapi.cmd.dto.UploadTicketDTO Parameters file: java.io.File Return com.ftapi.cmd.dto.UploadTicketDTO Parameters files: java.io.File[] Return com.ftapi.cmd.dto.UploadTicketDTO © FTAPI Software UG (2011), Seite 62 Parameters uploadTicketUuid: java.lang.String UploadDeliverable Once a deliverable was registered using RegisterDeliverable, it can be send to the server using this command. If the deliverable was not registered beforehand, an exception will be thrown. Java definition com.ftapi.cmd.def.upload.CmdUploadDeliverable Path Return void Parameters ultUuid: java.lang.String fileDTO: com.ftapi.cmd.dto.FileDeliverableDTO Tools und Erweiterungen FTAPI bietet verschiedene Tools und Erweiterungen für die reibungslose Integration in Ihre Unternehmens-IT an. Diese Tools werden in diesem Kapitel ausführlich beschrieben. Bitte beachten Sie bei jedem Tool und jeder Erweiterung die Versionsangaben, in denen diese verfügbar sind. FTAPI Ant Task Bitte beachten Sie, dass FTAPI Ant Task nur in den FTAPI Professional und Enterprise Editionen vorhanden ist. Warum gibt es FTAPI Ant Task? Was ist Apache Ant? Was ist ein FTAPI REST Command? Was ist der FTAPI Ant Task? Installation Apache Ant FTAPI Ant Task Verwendung Tutorial 1: Upload und Deliver Schritt 1 - Ant Skript als build.xml erstellen Schritt 2 - Dateien vorbereiten Schritt 3 - FTAPI REST Commands verwenden Schritt 4 - Server-Daten festlegen Festlegen eines Properties im Skript Auslagern eines Properties in eine externe Konfigurationsdatei Festlegen eines Properties bei Aufruf Schritt 5 - Skript ausführen Der FTAPI Ant Task - kurz FAT - ist eine Erweiterung des bekannten Build-Tools Ant (http://ant.apache.org) und ermöglicht die bequeme Ausführung nahezu aller FTAPI REST Commands über die Kommandozeile oder eingebettet in andere Aufgaben. Um dieses Tool verwenden zu können, sollten Sie Kenntnisse über folgende Themen besitzen: Apache Ant (http://ant.apache.org) FTAPI Commands (FTAPI Commands (REST API) ) © FTAPI Software UG (2011), Seite 63 Warum gibt es FTAPI Ant Task? Dieses Tool ist vor allem dann extrem hilfreich, wenn es darum geht FTAPI Commands automatisiert auszuführen. Eines der am häufigsten auftretenden Einsatzszenarien besteht z.B. darin, dass ein gegebenes Verzeichnis in regelmäßigen Abständen auf neue Dateien hin überprüft wird. Falls sich darin neue Dateien befinden werden diese automatisch an eine vorkonfigurierte Liste an Empfängern versendet. Was ist Apache Ant? Apache Ant (http://ant.apache.org) ist eines der am weitesten verbreiteten "Build-Tools" der Welt. Es bietet eine Vielzahl sogenannter Tasks an. Jeder Task ist eine Komponente die eine ganz konkrete Aufgabe ausführt (z.B. Datei kopieren, zippen, u.vm.). Es können beliebige Tasks wie Bausteine kombiniert und nacheinander ausgeführt werden (z.B. zuerst kompilieren, dann kopieren, dann zippen usw.). Dabei ist Ant nicht alleine auf die Software-Entwicklung beschränkt, sondern kann auch für viele weitere Aufgaben eingesetzt werden, wie die Fülle der verfügbaren Ant-Tasks auf der offiziellen Dokumentationsseite http://ant.apache.org/manual/index.html zeigt. Wie die einzelnen Tasks parametrisiert und ausgeführt werden, wird in der Ant-Konfigurationsdatei - die standardmäßig den Namen build.xml besitzt - festgelegt. Das Format dieser Datei ist XML, wodurch eine niedrige Lernkurve gewährleistet wird. Nachfolgend ist ein einfaches Beispiel einer solchen Datei gezeigt, welche lediglich den Text "Hello World" mit Hilfe des Echo-Tasks auf der Konsole ausgibt: <project name="MyHelloWorld" default="sayHello" basedir="."> <target name="sayHello> <echo message="Hello world!"/> </target> </project> Weitergehende Informationen zu diesem Dateiformat erhalten Sie im offiziellen Users Manual von Ant: http://ant.apache.org/manual/index.html. Was ist ein FTAPI REST Command? Ein FTAPI Server kann durch zahlreiche Befehle per Remote "gesteuert" werden. Ein solcher Befehl wird FTAPI Rest Command oder einfach nur Command genannt. Die Ausführung dieser Befehle erfolgt - vereinfacht gesagt - durch den Aufruf der zugehörigen URLs mit entsprechenden Parametern. Der Aufruf von solchen URLs kann auf verschiedene Arten erfolgen, unter anderem mit dem FTAPI Ant Task, welcher hier näher beschrieben wird. Was ist der FTAPI Ant Task? FTAPI Commands können grundsätzlich mit jedem HTTP Client ausgeführt werden, unabhängig von der Programmiersprache oder Umgebung. Eine noch einfachere Möglichkeit, FTAPI Commands auszuführen, besteht in der Verwendung des FTAPI Ant Task. Damit lassen sich FTAPI Commands in einem XML-Dokument wie Bausteine zusammenstellen, welche anschließend mit dem Tool Apache Ant ausgeführt werden. Ein großer Vorteil besteht, neben der übersichtlichen Darstellung und Flexibilität, darin, dass die FTAPI Commands mit anderen Ant-Tasks beliebig kombiniert werden können und damit ein mächtiges Werkzeug zur Verfügung steht. Eine umfangreiche Dokumentation über die verfügbaren Ant Tasks ist auf der Website Apache Ant zu finden: http://ant.apache.org/manual/ Voraussetzung Um den FTAPI Commands Ant Task verwenden zu können, wird eine installierte Java VM ab der Version 1.5 benötigt. Darüber hinaus müssen Sie zuvor Apache Ant, sowie den FTAPI Commands Ant Task selbst installieren. Dies kann in nur wenigen einfachen Schritten geschehen, wie nachfolgend beschrieben. Installation Apache Ant Um Apache Ant zu installieren, müssen zwei einfache Schritte erledigt werden: 1. Laden Sie sich die aktuelle Version von http://ant.apache.org/bindownload.cgi herunter und entpacken Sie diese in ein Verzeichnis Ihrer Wahl dieses Verzeichnis wird nachfolgend als $ANT_HOME bezeichnet. 2. Setzen Sie die Path-Variable Ihres Betriebssystems (System-Umgebungsvariable) auf das bin Verzeichnis innerhalb Ihres entpackten Ant-Verzeichnisses. (z.B. Wert der Variable: D:\apache-ant-1.8.1\bin) Tiefergehende Informationen zur Installation von ApacheAnt erhalten Sie direkt auf der Projektwebsite unter http://ant.apache.org/manual/install.html © FTAPI Software UG (2011), Seite 64 FTAPI Ant Task Um den FTAPI Commands Ant Task zu aktivieren, müssen Sie noch zwei weitere Schritte durchführen: 1. Kopieren Sie die Datei ftapi-client-ant-xxx.jar, welche sich in Ihrer FTAPI Version im Verzeichnis tools befindet, nach $ANT_HOME/libs. 2. Kopieren Sie anschließend alle Dateien aus dem Verzeichnis tools/dependencies ebenfalls in das eben verwendete $ANT_HOME/libs. Nun können Sie die FTAPI Commands Ant Tasks in jedem Ihrer Ant-Skripte verwenden. Wie dies praktisch aussehen kann, wird nachfolgend erläutert. Falls Ihre FTAPI-Version kein Verzeichnis tools enthält, so ist für Ihre Version diese Erweiterung nicht vorgesehen. Sie können das entsprechende Tool jedoch nachträglich erwerben, indem Sie sich direkt an unseren Vertrieb wenden kontaktieren Sie hierzu Ihren Kundenbetreuer oder schreiben Sie ein E-Mail an [email protected]. Verwendung Um ein optimales Ergebnis beim Einsatz des FTAPI Commands Ant Tasks zu erhalten, sollten Sie sich mindestens grundlegende Kenntnisse des Ant Buildfile Formats aneignen: http://ant.apache.org/manual/using.html#buildfile Jeder FTAPI Command wird im Ant Buildfile (Skript) durch jeweils ein Element <ftapi:command> repräsentiert. Durch das Attribut name wird dabei immer der Name des Commands angegeben, welches ausgeführt werden soll. Und zwar exakt so, wie dieser in der Dokumentation definiert ist (z.B. Upload). Alle weiteren Attribute entsprechen 1 zu 1 den Parametern, wie in der Dokumentation zum jeweiligen Command angegeben sind. Die Dokumentation der FTAPI REST Commands finden Sie hier. Sehen Sie hierzu das nachfolgende Beispiel eines minimalen Skripts: <project name="MyFTAPICommands" xmlns:ftapi="antlib:com.ftapi.client.ant.task"> <property name="ftapi.host" value="http://localhost"/> <property name="ftapi.username" value="demoUser"/> <property name="ftapi.password" value=""/> <target name="uploadAndDeliver"> <ftapi:command name="Upload" file="/home/user/uploads"/> <ftapi:command name="Deliver" recipients="[email protected]; [email protected]" subject="Demo subject" message="This is a demo message"/> </target> </project> In der ersten Zeile des Skripts sehen Sie, dass dem Skript ein freier Name MyFTAPICommands durch das Attribut name gegeben wurde. Entscheidend ist die darauf folgende Deklaration xmlns:example="antlib:com.ftapi.commands.ant", welche die FTAPI Commands in das Skript einbindet. Anschließend werden in diesem Skript die Verbindungsdaten für den FTAPI Server festgelegt. Mit Ausnahme von "ftapi.password" wurden alle Parameter direkt im Skript angegeben. Alternativ können diese Werte auch in eine eigene Konfigurationsdatei ausgelagert oder beim Aufruf über die Kommandozeile eingegeben werden. Letzteres wird später für die Angabe des Passwortes verwendet. Im nächsten Bereich wird ein sogenanntes Target mit dem frei gewählten Namen uploadAndDeliver festgelegt, welches eine Folge von FTAPI Commands, jeweils mit einem Element <ftapi:command> enthält. Das Kommando Upload überträgt zunächst alle Daten, die es im Verzeichnis /home/user/uploads findet, an den FTAPI Server. Anschließend wird der FTAPI Server mit dem Kommando Deliver angewiesen, das soeben erfolgreich hoch geladene Datenpaket an alle Empfänger zu versenden, deren Email-Adresse mit dem Attribut recipients angegeben wurden. Mit den zusätzlich notwendigen Attributen subject und message wird der Betreff und die Nachricht angegeben, die die Empfänger erhalten. Um dieses Skript auszuführen, ist nichts weiter zu tun, als folgenden Aufruf auf der Kommandozeile im selben Verzeichnis zu machen, in dem sich das Skript befindet: ant -Dftapi.password=1234 uploadAndDeliver Man sieht, dass sowohl das Passwort, als auch das Target, welches ausgeführt werden soll, angegeben werden. © FTAPI Software UG (2011), Seite 65 Sie können in Ihrem Ant-Skript beliebig viele Targets definieren und gezielt das gewünschte Target aufrufen. Darüber hinaus lassen sich Targets auch gruppieren und wiederverwenden. Sehen Sie hierzu bitte in der Ant-Dokumentation nach, um einen Einblick in die zahlreichen Möglichkeiten zu erhalten. Tutorial 1: Upload und Deliver In diesem Tutorial wird noch einmal Schritt für Schritt erläutert, wie Dateien aus einem Verzeichnis per FTAPI Ant Task an bestimmte Empfänger zugestellt werden können. Voraussetzung hierfür ist, dass Sie Apache Ant und den FTAPI Ant Task erfolgreich installiert haben, wie zuvor in diesem Kapitel beschrieben. Schritt 1 - Ant Skript als build.xml erstellen Erzeugen Sie in einem Verzeichnis Ihrer Wahl eine Datei mit dem Namen build.xml. Öffnen Sie diese im Anschluß und fügen Sie folgende Zeilen hinzu: <project name="Tutorial01" xmlns:ftapi="antlib:com.ftapi.client.ant.task"> </project> In der Datei build.xml haben Sie somit bereits das Grundgerüst eines Ant-Builds festgelegt und zudem den FTAPI Ant Task eingebunden. Durch das Attribut name wird der frei gewählte Name Tutorial01 für dieses Build-Projekt festgelegt. Mit xmlns:ftapi wird eine Bindung zwischen dem Präfix ftapi und dem Namensraum antlib:com.ftapi.commands.ant erzeugt, wodurch Ant mitgeteilt wird, dass es sich zukünftig bei XML-Elementen mit diesem Präfix immer um Elemente handelt, die vom FTAPI Ant Task ausgewertet werden. Alle FTAPI Ant Task Elemente müssen deshalb immer mit dem Präfix ftapi: beginnen, wie Sie nachfolgend noch sehen werden. Schritt 2 - Dateien vorbereiten Im nächsten Schritt wollen wir einige Dateien vorbereiten, die später per FTAPI versendet werden sollen. Erstellen Sie hierzu ein neues Verzeichnis (z.B. C:/data) und kopieren Sie die Dateien Ihrer Wahl hier hinein. Es sollten sich hierbei um 2-5 Dateien mit einer Gesamtgröße um die 5-10 MB handeln. Für die nächsten Schritte wird angenommen, dass der Pfad zu diesem Verzeichnis C:/data lautet. Falls der von Ihnen erstellte Verzeichnispfad hiervon abweicht, müssen Sie diesen natürlich entsprechend durch den von Ihnen erstellten ersetzen. Schritt 3 - FTAPI REST Commands verwenden In dieserm Schritt werden nun die beiden Commands Upload und Deliver dazu verwendet, um im ersten Schritt die Dateien aus dem Verzeichnis C:/data auf den FTAPI Server zu laden und anschließend im zweiten Schritt diese Dateien an die beiden Empfänger [email protected] und [email protected] zu versenden. Auch hier müssen Sie für eine erfolgreiche Zustellung diese E-Mail-Adressen durch Ihre eigenen E-Mail-Adressen ersetzen. Fügen Sie hierfür als nächstes folgende Zeilen in der Datei build.xml (s. Schritt 1) zwischen <project> und </project> ein: <target name="uploadAndDeliver"> <ftapi:command name="Upload" file="C:/data"/> <ftapi:command name="Deliver" recipients="[email protected]; [email protected]" subject="FTAPI Ant Task Demo" message="This is a demo message"/> </target> Die Ant-Tasks werden stets innerhalb eines Elements <target/> definiert. Dem Attribut name wurde der frei gewählte Name uploadAndDeliver zugewiesen, wodurch ein Target stets eindeutig referenziert werden kann. In unserem Beispiel wurden die beiden FTAPI REST Commands Upload und Deliver nacheinander innerhlab von <target/> angegeben. Der erste Command versendet alle Dateien aus dem Verzeichnis C:/data an den FTAPI Server und der zweite Command Deliver erzeugt Zustellungen für die beiden E-Mail-Adressen [email protected] und [email protected] mit dem Betreff "FTAPI Ant Task Demo" und der Nachricht "This is a demo message". Ihre Datei build.xml sollte nun wie folgt aussehen - bitte speichern Sie diese nun ab: <project name="Tutorial01" xmlns:ftapi="antlib:com.ftapi.client.ant.task"> <target name="uploadAndDeliver"> <ftapi:command name="Upload" file="C:/data"/> <ftapi:command name="Deliver" recipients="[email protected]; [email protected]" subject="FTAPI Ant Task Demo" message="This is a demo message"/> </target> </project> © FTAPI Software UG (2011), Seite 66 Schritt 4 - Server-Daten festlegen Im Grunde ist Ihr Ant-Skript fast vollständig. Allerdings fehlt noch die Information, welcher FTAPI Server für die Übertragung verwendet werden soll und zusätzlich die entsprechenden Zugangsdaten. Der FTAPI Ant Task erwartet hierfür folgende System-Properties: ftapi.host = Der Hostname des FTAPI-Servers. ftapi.username = Der Benutzer, mit dessen Rechten die Kommunikation mit dem FTAPI-Server stattfinden soll. ftapi.password = Das Passwort des Benutzers. Um die Werte für diese Properties entsprechend zu setzen, haben Sie drei Möglichkeiten: Definition direkt im Skript Einlesen einer Konfigurationsdatei, in der die Werte festgelegt sind Angabe beim Aufruf des Skripts über die Kommandozeile Wir werden im Folgenden zur besseren Verständlichkeit alle drei Möglichkeiten verwenden, indem wir ftapi.host direkt im Skript definieren, ftapi.username in eine Konfigurationsdatei mit dem Namen settings.properties auslagern und ftapi.password beim Aufruf des Skripts über die Konsole angeben. Festlegen eines Properties im Skript Um den Wert für das Property ftapi.host direkt im Skript festzulegen, fügen Sie direkt unterhalb von <project> folgende Zeile ein: <property name="ftapi.host" value="http://localhost:8080/ftapi-server"/> Natürlich müssen Sie den value entsprechend Ihrer Host-Einstellungen anpassen. Auslagern eines Properties in eine externe Konfigurationsdatei Um den Wert für das Property ftapi.username aus einer externen Konfigurationsdatei mit dem Namen settings.properties im selben Verzeichnis einzulesen, müssen Sie folgende Zeile direkt unterhalb von <project> in Ihr Build-Skript einfügen: <property file="settings.properties"/> Das Attribut name gibt hier den Namen der Property-Datei an. Erstellen Sie diese Datei in dem Ordner, in dem sich auch die build.xml befindet. Die Properties-Datei selbst enthält nur eine Zeile: ftapi.username=admin Durch dieses Vorgehen können Sie Ihr Build-Skript parametrisieren, ohne dass Sie das Skript (Datei build.xml) selbst öffnen und bearbeiten müssen. Festlegen eines Properties bei Aufruf Sie können jedes Property auch beim Aufruf des Build-Skripts über die Kommandozeile mit Hilfe des "-D" Präfixes angeben. Um z.B. das Passwort-Property ftapi.password auf diese Art und Weise festzulegen, müssen Sie zunächst das Property innerhalb des Skripts definieren, aber ohne Angabe eines Werts wie das nachfolgende Beispiel zeigt: <property name="ftapi.password" value=""/> Anschließend können Sie den Parameter -Dftapi.password=password beim Aufruf mitgeben und dadurch den Wert im Nachhinein festlegen. Dies wird nachfolgend in Schritt 5 im Detail gezeigt, wenn es darum geht, das Skript auszuführen. Schritt 5 - Skript ausführen Nachdem Sie nun alle Schritte bis hierher durchgeführt haben, geht es nun darum, das erstellte Build-Skript auszuführen. Das Skript sollte jetzt folgenden Inhalt besitzen: © FTAPI Software UG (2011), Seite 67 <project name="Tutorial01" xmlns:ftapi="antlib:com.ftapi.client.ant.task"> <property name="ftapi.host" value="http://localhost:8080/ftapi-server"/> <property file="settings.properties"/> <property name="ftapi.password" value=""/> <target name="uploadAndDeliver"> <ftapi:command name="Upload" file="C:/data"/> <ftapi:command name="Deliver" recipients="[email protected]; [email protected]" subject="FTAPI Ant Task Demo" message="This is a demo message"/> </target> </project> Um dieses Skript auszuführen, öffnen Sie Ihre Kommandozeile und wechseln Sie in das Verzeichnis, in welchem sich die Datei build.xml befindet. Geben Sie anschließend folgendes Kommando ein: ant -Dftapi.password=admin uploadAndDeliver Durch ant wird das Ant-Tool gestartet. Dieses sucht im aktuellen Verzeichnis nach einer Datei build.xml und führt darin das Target uploadAndDeliver aus. Durch den zusätzlichen Parameter -Dftapi.password=admin wird das Passwort für die Kommunikation mit dem Server festgelegt. Nachdem das Skript erfolgreich ausgeführt wurde, sollte an alle angegebenen E-Mail-Adressen jeweils eine Benachrichtigung, dass ein neues Datenpaket für den Download bereit steht, versandt worden sein. Dieses Datenpaket beinhaltet alle Dateien, die sich im Verzeichnis C:/data befinden. ChangeLog 1.1.4 In den FTAPI Versionen sind ab Version 1.1.4 folgende Verbesserungen, Neuerungen und Überarbeitungen enthalten: Kompatibilität mit IE9 sichergestellt und optimiert FTAPI Applet Funktionalität erweitert Empfänger-Feld-Funktionalitäten erweitert (z.B. mit ENTF können nun Einträge wieder entfernt werden) Applet-Kopfzeile lässt sich nun über die Konfiguration bei Bedarf dauerhaft ausblenden Automatische Proxy-Konfiguration in die Applets integriert Draggable-Support für Applet Das Applet kann nun per Drag&Drop auf den Desktop gezogen werden und dort ohne Web-Browser verwendet werden Notwendigkeit eines Empfänger-Accounts einstellbar Dies ist nun durch den Admin global einstellbar (immer, niemals, benutzerdefiniert) Request Parameter für Applet eingeführt Die Felder E-Mail, Betreff, Text und Dateien sind nun per Request parametrisierbar Integration in Windows Kontextmenü möglich Im Windows-Kontextmenü ist es nun möglich, per Registry Eintrag einen neuen Punkt "Send with FTAPI SecuTransfer" einzufügen und Dateien somit noch einfacher und schneller per rechte Maustaste zu verschicken Pausieren und Fortsetzen-Feature Vollständig implementiert für Uploads inkl. voller Integration auf FTAPI-Weboberfläche. Mapping LDAP-zu FTAPI-Gruppen integriert In LDAP-Systemen können eine oder mehrere FTAPI Zugriffsgruppen mit unterschiedlichen Rechten hinterlegt werden Empfängerverifizierung bei Zustellung Jeder Versender kann bei einer Zustellung einstellen, ob der Empfänger einen FTAPI-Account besitzen muss oder nicht - somit kann sichergestellt werden, dass genau und nur dieser die Zustellung erhält; eine Zustellung ist somit immer an eine bestimmte E-Mailadresse gebunden und kann deshalb auch nicht an Dritte weitergeleitet werden Posteingang und -Ausgang von Zustellungen Direkt über die FTAPI-Weboberfläche können alle versendeten wie auch erhaltenen Zustellungen angesehen werden Unbegrenzt viele gleichzeitige Uploads Ein Benutzer kann nun beliebig viele parallele/gleichzeitige Up- und Downloads durchführen FTAPI Client (Beta) integriert Nutzen Sie unseren lokalen Client, um Ihre Prozesse weiter zu beschleunigen - die Downloadoption für Benutzer kann deaktiviert werden E-Mailadressverwaltung im Applet verbessert Alle bereits genutzten E-Mail-Adressen werden automatisch vorgeschlagen und können per Tastatur oder Maus direkt ausgewählt werden Erweiterte Infos beim Up- und Download Die Statsuinformationen bzgl. Geschwindigkeit, Restdauer und Progress wurden bei allen Up- und Downloads erweitert Zustellungen nochmal versenden Benachrichtung zu einer bestehenden Zustellung können direkt per Klick nochmal versandt werden Benutzeroberfläche in neuem FTAPI Design Umstellung auf neues FTAPI Corporate Design in grünem Layout RSS-Feed © FTAPI Software UG (2011), Seite 68 Jeder Benutzer kann seinen eigenen RSS-Feed de-/aktivieren - dort werden alle Zustellungen als RSS-Feed zur Verfügung gestellt Verbesserte Exception Behandlung und Darstellung So wird z.B. beim Versuch eines Uploads von Daten die das Quota überschreiten würden, eine entsprechende benutzerfreundliche Meldung angezeigt Zertifiziertes FTAPI Applet integriert Alle FTAPI-Applets wurden mittels eines Code-Signing-Zertifikats von einer unabhängigen, dritten Stelle (Thawte) zertifiziert und die Herkunft von der Firma FTAPI bestätigt Standard-Benutzer-Import Bei jedem FTAPI-Serverstart können Standard-Benutzer in Form einer Excelliste importiert/abgeglichen werden Zustellungen löschen Bestehende Zustellungen können - als Admin - nun komplett gelöscht werden Als Windows Dienst integrierbar der FTAPI-Server kann somit als eigener Dienst, wie auch unter einem bestimmten Benutzer betrieben werden kleine (Schönheits-)Fehler beim LDAP-Mapping beseitigt Probleme mit dem SLF4JLogger beim Serverstart bereinigt Performance Verbesserungen und Optimierungen Etliche Bugfixes FAQ (1.1.4) Ich möchte den Ort, an dem die Binärdaten abgelegt werden ändern. Was ist zu tun? Ich möchte eine externe Datenbank (z.B. MySQL) für die Metadaten anbinden. Was ist zu tun? Ich möchte den FTAPI-Server in einer grafischen Linuxumgebung starten. Was ist zu tun? Der Port 8080 ist bei mir bereits belegt. Wie kann ich FTAPI auf einem anderen betreiben? Meine Base-URL soll nicht mit /ftapi-server aufhören. Wie kann ich das einstellen? Ich möchte den Ort für das .ftapi Verzeichnis fest definieren. Was ist zu tun? Ich bekomme in der Konsole die Meldung, dass weder eine JAVA_HOME noch JRE_HOME Variable definiert ist. Wie mache ich das? Wie finde ich die Version meines eingesetzten Apache Tomcat heraus? Ich habe einen Proxy-Server in Betrieb. Kann ich FTAPI damit effektiv ausführen? In meinem Internet Explorer 8 öffnen sich immer neue Fenster. Wie kann ich das auf Registerkarten umstellen? Ich möchte den Ort, an dem die Binärdaten abgelegt werden ändern. Was ist zu tun? Bei Verwendung des LocalDiskStorage (Standardfall) werden die Binärdaten im Verzeichnis ~/.ftapi/storage abgelegt. Um diesen Speicherort zu ändern, sind folgende Schritte notwendig: 1. Den FTAPI-Server stoppen 2. In der Konfigurationsdatei ${ftapi.home}/config/server-production.properties den Eintrag ftapi.storage.home=${ftapi.home} /storage suchen und entsprechend dem neuen Verzeichnis anpassen (z.B. ftapi.storage.home=/data) 3. Den Inhalt von ${ftapi.home}/storage in das neue Verzeichnis (z.B. /data) verschieben 4. Den FTAPI-Server starten Binärdaten verschieben Beachten Sie hierzu auch die Informationen unter [Binärdaten (Storage)]! Ich möchte eine externe Datenbank (z.B. MySQL) für die Metadaten anbinden. Was ist zu tun? Externe MySQL Datenbank anbinden Beachten Sie hierzu bitte die Informationen unter [Metadaten (Datenbank)]! Ich möchte den FTAPI-Server in einer grafischen Linuxumgebung starten. Was ist zu tun? Für die Installation und Einrichtung unter einem Linux-System werden nachfolgend die Schritte und Befehle beschrieben, die man per Terminal und/oder Oberfläche benötigt; diese Punkte sind als Unterschritte - speziell für Linux-Umgebungen - zum Punkt 2. bei Installation zu verstehen: 1. Terminal/Konsole öffnen und in das entpackte FTAPI Verzeichnis wechseln 2. Dort die Berechtigungen der folgenden Dateien und Ordner mit chmod -R +x ftapi-server auf ausführbar setzen /ftapi-server/ftapi-start.sh und ftapi-stop.sh /ftapi-server/bin/*.sh (Alternativ kann dies in einigen Linuxumgebungen auch über die grafische Oberfläche geschehen, indem man in den entsprechenden Dateieigenschaften den Haken beim Zugriffsrecht "Datei als Programm ausführen" setzt!) 3. Anschließend die Datei /ftapi-server/ftapi-start.sh ausführen (Befehl in Konsole lautet ./ftapi-start.sh) 4. Das Terminalfenster offen lassen, da der Server nochmal gestoppt und neu gestartet werden muss - dann weiter mit Schritt 3. in der Installation Anzeige versteckter Ordner und Dateien in grafischer Linux-Oberfläche Um den .ftapi Ordner im Userverzeichnis angezeigt zu bekommen folgende Hinweise: © FTAPI Software UG (2011), Seite 69 (Open) Suse KDE: Dolphin (Dateiexplorer) unter Ansicht/Versteckte Dateien anklicken Ubuntu: Dateibrowser (bzw. File Browser) unter Bearbeiten/Einstellungen "Show hidden and backup files" Der Port 8080 ist bei mir bereits belegt. Wie kann ich FTAPI auf einem anderen betreiben? Falls der (standardmäßig voreingestellte) Port 8080 bereits belegt/andersweitig verwendet wird, kann dieser auf einen beliebigen freien Port für den Betrieb von FTAPI umgestellt werden, 1. Den FTAPI-Server stoppen 2. In der Konfigurationsdatei ${ftapi.home}/config/server-production.properties den Eintrag *ftapi.base.url=http://localhost:8080/ftapi-server* suchen und entsprechend dem neuen Port anpassen (z.B. statt 8080 den nächst höheren Port 8282 eintragen - muss größer 1024 sein!) 3. Damit auch der Tomcatserver den gleichen Port nutzt, muss noch die Datei /ftapi-server/conf/server.xml angepasst werden. Darin den folgenden Eintrag mit port="8080" suchen und auf den neuen Port (z.B. 8282) anpassen: <Connector port="8282" protocol="HTTP/1.1" connectionTimeout="20000" redirectPort= "8443" /> 4. Den FTAPI-Server starten 5. Optional: Diesen Port (8282) in Ihrer Firewall für Zugriffe von extern freischalten Meine Base-URL soll nicht mit /ftapi-server aufhören. Wie kann ich das einstellen? Wenn Sie möchten, dass IhreBase-URL nicht mit /ftapi-server endet, können Sie die FTAPI war-Datei entsprechend umbenennen. 1. Den FTAPI-Server stoppen 2. In der Konfigurationsdatei ${ftapi.home}/config/server-production.properties den Eintrag *ftapi.base.url=http://localhost:8080/ftapi-server* suchen und am Ende einfach das /ftapi-server entfernen (Alternativ können Sie auch einen andere Bezeichnung einfügen - Fragen Sie hierzu bitte Ihren FTAPI-Support) 3. Benennen Sie in Ihrem FTAPI-Server-Verzeichnis /ftapi-server/webapps die ausgelieferte Datei ftapi-server.war in ROOT.war um. Löschen Sie im gleichen Verzeichnis noch den kompletten Ordner ftapi-server - nur falls bereits vorhanden. 4. Den FTAPI-Server starten Bitte bedenken Sie, dass Sie bei Updates diese Umbenennung ebenfalls immer durchführen müssen! Ich möchte den Ort für das .ftapi Verzeichnis fest definieren. Was ist zu tun? Standardmäßig wird der .ftapi-Ordner im Home-Verzeichnis des gerade angemeldeten Benutzers angelegt. Man kann diesen Pfad auch fix an einem anderen Ort angeben. In Windows-Umgebungen ist die folgende Zeile in der Datei /ftapi-server/ftapi-start.bat zu ergänzen: set JAVA_OPTS="-Dftapi.home=../.ftapi" Damit wird der .ftapi-Ordner innerhalb Ihres ftapi-server Verzeichnisses angelegt und genutzt. Ich bekomme in der Konsole die Meldung, dass weder eine JAVA_HOME noch JRE_HOME Variable definiert ist. Wie mache ich das? Wenn Sie beim Starten von FTAPI über die Konsole die folgende Meldung bekommen, dann ist keine der beiden genannten Umgebungsvariablen in Ihrem System angegeben. "Neither the JAVA_HOME nor the JRE_HOME environment variable is defined At least one of these environment variable is needed to run this program" Legen Sie hierzu in Ihren Systemeinstellungen eine passende Umgebungsvariable an. Bei einer Java JRE (Runtime Environment) eine JRE_HOME (empfohlen); falls Sie das Java JDK installiert haben, eine JAVA_HOME. Als Variablen-Wert verwenden Sie die Pfadangabe zur jeweiligen Java-Installation. Z.B. für JRE_HOME: C:\Programme\Java\jre6 Konsole erneut öffnen Nach dem Anlegen einer neuen Umgebungsvariable müssen Sie die - eventuell noch offene Konsole/Eingeabeaufforderung erneut öffnen. Wie finde ich die Version meines eingesetzten Apache Tomcat heraus? Entweder Sie öffnen die Logdatei /ftapi-server/logs/catalina.DATUM.log. Hier sollten Sie eine Ziel ähnlich dem folgenden vorfinden: © FTAPI Software UG (2011), Seite 70 INFO: Starting Servlet Engine: Apache Tomcat/6.0.29 Eine andere Möglichkeit besteht darin, die Jar-Datei ftapi-server/lib/catalina.jar mit einem üblichen Zip-Programm (z.B. WinZip, 7-zip, unzip) zu entpacken und dort dann die darin befindliche Datei org/apache/catalina/util/ServerInfo.properties zu öffnen. Hier sollten Sie eine Zeile ähnlich der folgenden vorfinden: server.info=Apache Tomcat/6.0.29 Ich habe einen Proxy-Server in Betrieb. Kann ich FTAPI damit effektiv ausführen? Falls Sie einen Proxy-Server bertreiben, empfehlen wir Ihnen, sich für Ihre FTAPI URL eine Ausnahme in Form von ftapi.ihre-domain.com* in Ihren Proxy-Gruppenrichtlinien einzutragen. Aufgrund der segmentierten Datenübertragung von FTAPI ist ein Proxy eher kontraproduktiv, wenn es u.a. um das Cachen von häufig angefragten Daten geht. Eine Authentifizierung gegenüber Proxy-Servern wird aus diesem Grund von FTAPI derzeit nicht unterstützt. Grundsätzlich ist FTAPI auch mit dazwischengeschaltetem Proxy voll einsatzfähig, jedoch ist die Performance teilweise beinträchtigt. Dies hängt primär auch vom Zugriffsort (Server direkt, Intranet oder Internet) auf den FTAPI-Server ab. In meinem Internet Explorer 8 öffnen sich immer neue Fenster. Wie kann ich das auf Registerkarten umstellen? Damit bei Links auf der FTAPI-Weboberfläche neue Registerkarten anstelle von neuen Fenstern aufgehen, müssen Sie hierzu eine Standard-Einstellung im IE8 verändern. Im IE-Menü den Punkt Extras - Internetoptionen öffnen; dort dann im Bereich Registerkarten die Einstellungen öffnen und den Radiobutton "beim Auftreten von Popups" auf "Internet Explorer entscheiden lassen ..." setzen. Wir freuen uns über Ihr Feedback! © FTAPI Software UG (2011), Seite 71 © FTAPI Software UG (2011), Seite 72
