Altova FlowForce Server 2024 Advanced Edition

Hinzufügen von Error Handlern zu einem Auftrag

Zur Startseite Zurück Nach oben Weiter

In diesem Beispiel wird gezeigt, wie Sie Fehlerbehandlung zu einem Auftrag hinzufügen. Im Auftrag in diesem Beispiel wird der Inhalt eines Verzeichnisses aufgelistet und über den Browser als Webservice aufgerufen. Sie lernen, wie Sie FlowForce Server konfigurieren, damit das Ergebnis des Auftrags folgendermaßen behandelt wird:

 

Wenn der Auftrag erfolgreich ausgeführt werden konnte, soll die Ausgabe des Auftrag im Browser angezeigt werden.

Wenn der Auftrag aus irgendeinem Grund nicht ausgeführt werden konnte, soll eine E-Mail-Benachrichtigung an einen bestimmten Empfänger gesendet werden.

Schreibe immer, wenn der Auftrag - unabhängig vom Ausführungsstatus - fertig ausgeführt wurde, die interne Auftrags-ID in eine Datei im lokalen System.

 

In FlowForce Server erstellen Sie einen so genannten geschützten Block mit zwei Error Handler-Bedingungen: "Bei Fehler" und "Immer" (jede dieser Bedingungen behandelt eines der obigen Szenarien).

 

Voraussetzungen

Benötigte Lizenzen: FlowForce Server

Der FlowForce Web Server- und der FlowForce Server-Dienst werden an der konfigurierten Netzwerkadresse und am konfigurierten Port ausgeführt und sind dort empfangsbereit.

Die FlowForce Server Mail-Einstellungen müssen konfiguriert werden, siehe Definieren der Mail-Parameter.

Sie benötigen ein FlowForce Server-Benutzerkonto mit Berechtigungen für einen der Container (standardmäßig hat jeder authentifizierte Benutzer Zugriff auf den in diesem Beispiel verwendeten Container /public).

Mit dem in diesem Beispiel erstellten Auftrag wird eine Ausgabe auf ein Speichermedium geschrieben. Sie benötigen daher auf dem Betriebssystem, auf dem FlowForce Server installiert ist, Lese- und Schreibrechte für das entsprechende Verzeichnis. In diesem Beispiel wird C:\FlowForceExamples\ErrorHandling verwendet.

 

Tipps

In diesem Beispiel werden zwar Windows-Pfade und Befehle verwendet, Sie können es aber auch auf anderen Betriebssystemen testen, wenn Sie die Pfade und Befehle entsprechend anpassen.

 

Erstellen des Auftrags

1.Erstellen Sie auf dem Rechner, auf dem FlowForce Server ausgeführt wird, ein Verzeichnis, das das Arbeitsverzeichnis des Auftrags bildet. In diesem Beispiel wird C:\FlowForceExamples\ErrorHandling verwendet.

2.Melden Sie sich bei der FlowForce Server Web-Verwaltungsschnittstelle an und gehen Sie zum Container /public/Examples. Der Container public/Examples sollte bereits vorhanden sein, wenn Sie das vorherige Beispiel durchgearbeitet haben; erstellen Sie ihn andernfalls mit dem Befehl Erstellen | Container erstellen.

3.Klicken Sie auf Auftrag erstellen und geben Sie einen Namen für den Auftrag ein, z.B. "ListDirectory". Die Auftragsbeschreibung ist optional.

4.Klicken Sie unter "Auftrags-Input-Parameter" auf die Schaltfläche add und fügen Sie einen Parameter vom Typ "String" hinzu. Zur Laufzeit des Auftrags liefert der Parameter den Pfad des aufzulistenden Verzeichnisses. Der Name des Parameters lautet in diesem Beispiel "inputDir" und wird in den nachfolgenden Schritten verwendet.

5.Klicken Sie unter "Ausführungsschritte" auf Neuer Error/Success Handler-Schritt.

6.Klicken Sie unter "Ausführen mit Error/Success Handler" auf die add-Schaltfläche und fügen Sie einen neuen Ausführungsschritt mit den folgenden Einstellungen hinzu:

 

Funktion ausführen

Navigieren Sie zur Funktion /system/shell/commandline.

Befehl

Geben Sie den folgenden Shell-Befehl ein:

 

dir {inputDir}

 

inputDir ist hier der Name des zuvor erstellten Parameters. Der Name steht innerhalb von geschweiften Klammern, da der Inhalt zur Laufzeit des Auftrags dynamisch durch den Parameterwert ersetzt wird. Nähere Informationen dazu finden Sie unter Einbetten von Ausdrücken in String-Felder.

Bei Fehler abbrechen

Lassen Sie diese Option unverändert. Nähere Informationen dazu finden Sie unter der Beschreibung der Funktion /system/shell/commandline.

Arbeitsverzeichnis

Geben Sie den Pfad zum zuvor erstellen Arbeitsverzeichnis ein, z.B. C:\FlowForceExamples\ErrorHandling.

7.Klicken Sie unter der Bedingung "Bei Fehler" auf die add-Schaltfläche und fügen Sie einen neuen Ausführungsschritt mit den folgenden Einstellungen hinzu:

 

Funktion ausführen

Navigieren Sie zur Funktion /system/mail/send.

Von

Geben Sie die E-Mail-Adresse des Absenders, z.B. flowforce@localhost, ein. Lassen Sie das Feld leer, wenn Sie die Mail-Einstellungen über die Seite "Verwaltung" konfiguriert haben.

An

Geben Sie Ihre E-Mail-Adresse ein.

Betreff

Geben Sie den folgenden Betreff für die Benachrichtigungs-E-Mail ein:

 

Auftrag {instance-id()} ist fehlgeschlagen.

 

Der Teil zwischen den geschweiften Klammern ist ein FlowForce-Ausdruck, der die Funktion instance-id aufruft, um die eindeutige ID der aktuellen (fehlgeschlagenen) Auftragsinstanz abzurufen.

Nachrichtentext

Geben Sie Folgendes ein:

 

Exit Code: {string(exitcode(failed-step()))}

Standard Error: {content(stderr(failed-step()))}

Error message: {error-message(failed-step())}

 

Die Teile zwischen den geschweiften Klammern sind zwei FlowForce-Ausdrücke. Diese Ausdrücke rufen die fehlerhafte Ausgabe auf und konvertieren sie in einen String, der den Text der E-Mail bildet:

 

Die Funktion failed-step gibt das Ergebnis result des fehlerhaften Schritts zurück. Es handelt sich hierbei um einen abstrakten FlowForce-Typ, der am besten als Argument an die Funktionen exitcode, stderr oder error-message bereitgestellt wird, siehe unten.

Die Funktion exitcode ruft den Exit-Code des Fehlers aus result als Zahl ab, vorausgesetzt es gibt einen Exit-Code.

Die Funktion stderr ruft die Standardfehlerausgabe des Fehlers aus result als Stream ab, vorausgesetzt es gibt eine Standardfehlerausgabe.

Die Funktion error-message ruft den Text der FlowForce-Fehlermeldung, so wie sie im Log aufscheint, ab. Eventuell gibt sie einen leeren String zurück, wenn es keinen Fehler gibt oder wenn der Fehlertext aus technischen Gründen nicht abgerufen werden kann.

Die Funktion string konvertiert den Exit-Zahlencode in einen String (da der Text der E-Mail vom Typ string ist).

Die Funktion content konvertiert die Fehlerausgabe von einem Stream in einen String.

 

Die Funktionen exitcode und stderr geben nur dann einen Wert zurück, wenn bei der Ausführung ein Exit-Code bzw. eine Fehlerausgabe erzeugt wird. Dies ist normalerweise bei Fehlern wie solchen, die von der Befehlszeile erzeugt werden, der Fall. Die Funktion error-message dient nur zu Informationszwecken. Es gibt keine Garantie dafür, dass dadurch der Fehlertext für jede mögliche Auftragskonfiguration und Fehlerbedingung zurückgegeben wird.

 

8.Klicken Sie auf Neuer Error/Success Handler und wählen Sie Immer.

9.Klicken Sie unter der Bedingung "Immer" auf die Schaltfläche add und fügen Sie einen neuen Ausführungsschritt mit den folgenden Einstellungen hinzu:

 

Funktion ausführen

Navigieren Sie zur Funktionbuiltin_function/system/shell/commandline.

Befehl

Geben Sie den folgenden Shell-Befehl ein:

 

echo {instance-id()} >> JobLog.txt

 

Auf Windows-Systemen schreibt dieser Befehl die Auftrags-ID in eine Datei namens JobLog.txt. Wenn die Datei Daten enthält, wird der neue Text hinter den vorhandenen Daten hinzugefügt.

Arbeitsverzeichnis

Geben Sie den Pfad zum zuvor erstellen Verzeichnis ein (C:\FlowForceExamples\ErrorHandling).

 

Anhand dieses Verzeichnisses wird der Pfad zur Datei JobLog.txt aufgelöst.

 

Der Auftrag sollte zu diesem Zeitpunkt folgendermaßen aussehen (vorausgesetzt, Sie haben keine anderen Pfade oder Shell-Befehle verwendet).

fs_error_handling_01

10.Um den Auftrag in einen Webservice umzuwandeln, aktivieren Sie das Kontrollkästchen Diesen Auftrag über HTTP unter URL zur Verfügung stellen und geben Sie den Namen des Webservice ein, zum Beispiel:

fs_error_handling_02

Notieren Sie sich den Namen des Diensts; Sie benötigen diesen, um den Webservice aufzurufen.

 

11.Wählen Sie unter "Anmeldeinformationen" einen vorhandenen Eintrag aus oder definieren Sie lokale Anmeldeinformationen.

12.Klicken Sie auf Speichern.

 

Ausführung des Auftrags

Sie haben die Auftragskonfiguration nun abgeschlossen. Da dieser Auftrag als Webservice bereitgestellt wird, können Sie ihn auf jede der folgenden Arten ausführen:

 

Gehen Sie zur Startseite und klicken Sie anschließend auf Alle aktiven Trigger und Dienste anzeigen. Klicken Sie anschließend auf die in der Spalte "Info" angezeigte URL des Auftrags.

Geben Sie in die Adressleiste des Browsers http://127.0.0.1:4646/service/ListDirectoryService ein. Beachten Sie, dass diese URL nur funktioniert, wenn der FlowForce Server-Dienst an der Standard-Host-Adresse und am Standard-Port-Namen empfangsbereit ist. Wenn Sie auf der Konfigurationsseite andere Host- und Port-Einstellungen definiert haben, dann ändern Sie die Adresse entsprechend.

Wenn Sie das optionale Feld Host-Name von FlowForce Server über die Setup-Seite definieren, können Sie den Webservice-Aufruf direkt über die Auftragskonfigurationsseite ausführen, indem Sie neben dem Kontrollkästchen Diesen Auftrag über HTTP...zur Verfügung stellen auf die Schaltfläche fs_ic_call_ws klicken. Andernfalls wird diese Schaltfläche nicht angezeigt.

 

Wenn Sie aufgefordert werden, beim Aufrufen des Web-Diensts Anmeldeinformationen anzugeben, so geben Sie dieselben Anmeldeinformationen ein, mit denen Sie sich auch bei FlowForce Server angemeldet haben.

 

Für die HTTP-Authentifizierung sollten Sie Ihre FlowForce Server-Anmeldeinformationen nur zu Testzwecken eingeben. Für Produktionszwecke wird empfohlen, einen neuen FlowForce-Benutzer zu erstellen, diesem Benutzer im Container, in dem sich der Auftrag befindet, die Berechtigung Dienst - Verwenden einzuräumen und den Web-Dienst anschließend über das entsprechende Benutzerkonto aufzurufen. Um die HTTP-Authentifizierung zu deaktivieren, und den Web-Dienst öffentlich zugänglich zu machen, weisen Sie dem Benutzer Anonymous die Berechtigung Dienst - Verwenden zu, siehe Funktionsweise von Berechtigungen.

 

Da dieser Auftrag Parameter hat, werden Sie aufgefordert, einen Parameterwert anzugeben, wenn Sie den Webservice in einem Browser aufrufen.

fs_error_handling_03

Wenn Sie einen gültigen Verzeichnispfad wie z.B. C:\ eingeben, wird der Auftrag ausgeführt und das Ergebnis wird im Browser angezeigt.

 

Außerdem wird, gemäß der zuvor konfigurierten "Immer"-Bedingung, jedes Mal, wenn Sie den Auftrag ausführen, die ID der Auftragsinstanz an den Inhalt der JobLog.txt-Datei angehängt.

 

Um die Bedingung "Bei Fehler" zu testen, ändern Sie den Parameter "inputDir" absichtlich in einen falschen Wert um (z.B. einen nicht vorhandenen Pfad). In diesem Fall wird im Browser ein Fehler angezeigt und FlowForce Server sendet eine E-Mail an die im Handler "Bei Fehler" im Feld "Empfänger" definierte Adresse. Die E-Mail könnte z.B. folgendermaßen aussehen:

fs_error_handling_04

Wie bereits erwähnt, besteht keine Garantie, dass die in diesem Beispiel verwendeten Fehlerfunktionen für jede mögliche Auftragskonfiguration einen Wert zurückgeben. Der Detailliertheitsgrad der E-Mail hängt daher von Ihrer Auftragskonfiguration und der Art des aufgetretenen Fehlers ab. Es steht nicht zu erwarten, dass die E-Mail-Felder Exit-Code, Standardfehler und Fehlermeldung immer Text enthalten. Am verlässlichsten wird die Ursache des Fehlers im FlowForce Server Log angegeben.

© 2017-2023 Altova GmbH