Execution Connector

Verwendung

Mit dem Execution Connector rufen Sie eine externe Anwendung innerhalb eines Workflows auf. Sie können jede Anwendung aufrufen, welche über die Kommandozeile gestartet werden kann.

Voraussetzungen

Linux

Stellen Sie sicher, dass bei paralleler Ausführung des Execution Connectors ausreichend physischer Speicher verfügbar ist. Pro ausgeführten INUBIT Prozess wird die zweifache Größe des maximalen Speichers des einzelnen INUBIT Prozesses benötigt.

Beispiele

Beispiel: Verzeichnis mit dem Execution Connector ausgeben

Mit der folgenden Konfiguration können Sie den Inhalt des Verzeichnisses /opt/data/archive auflisten und über die echo-Anweisungen in eine XML-Struktur schreiben:

module guide 1053 0

Beispiel: Datei mit dem Execution Connector kopieren

Mit der folgenden Konfiguration können Sie die Datei trace.log in das Verzeichnis /opt/data/tmp kopieren:

module guide 1054 0

Beispiel: Verzeichnis mit dem Execution Connector anlegen

In diesem Beispiel wird auf die Workflow-Variable var.dir zugegriffen. Wenn kein Verzeichnis mit dem Namen in var.dir existiert, wird es angelegt:

module guide 1055 0

Beispiel: Windows-Systemvariablen an Prozess übergeben

Verwendung

Beim Benutzen bestimmter Kommandos, Skripts etc. – z.B. der INUBIT-Kommandozeilenschnittstelle startcli – kann es erforderlich sein, Systemvariablen an den Prozess zu übergeben.

Das folgende Beispiel liefert die Zeitspanne zurück, die seit dem Starten der INUBIT Process Engine vergangen ist.

So gehen Sie vor

  1. Erstellen Sie einen neuen Workflow.

  2. Fügen Sie ein Execution Connector-Modul hinzu.

  3. Auf der Registerseite Execution Connector Eigenschaften, geben Sie die folgenden Werte in die zugehörigen Felder ein:

    • Befehl: startcli.bat

    • Parameter: -u <user> -p <password> --execCommand "uptime" https://<server>:<port>/ibis/servlet/IBISSoapServlet

    • Arbeitsverzeichnis: <inubit-installdir>/client/bin/

  4. Aktivieren Sie die Checkbox Systemvariablen an Prozess übergeben.

  5. Aktivieren Sie die Checkbox Ausgabenachricht verwenden, damit eine Ergebnisdatei generiert wird.

    module guide 1056 0

  6. Klicken Sie auf Fertig stellen, um die Änderungen zu speichern.

  7. Setzen Sie den Startpoint an das Execution Connector-Modul.

  8. Starten Sie den Test ohne Datei.

  9. Sobald der Workflow erfolgreich beendet ist, öffnen Sie die Ergebnisdatei.

Sie sollte wie folgt aussehen:

module guide 1056 1

Dialog Execution Connector Eigenschaften

In diesem Dialog konfigurieren Sie den Aufruf der externen Applikation.

Externer Befehl

  • Befehl

    Pfad und Name der aufzurufenden Applikation.

    Unter Windows müssen Sie einen Pfad in Anführungszeichen einschließen, wenn dieser ein oder mehrere Leerzeichen enthält.

    Beispiel: cmd.exe /C del "D:\PROD\ARCHIV\OBI\INVOICE OUT\OCR\AT\PDF\2019-10-24"

    Die aufzurufende Applikation muss auf demselben Rechner installiert sein wie der Tomcat-Applikationsserver. Der Pfad kann relativ zum Applikationsserver oder absolut angegeben werden.

    Nicht-terminierende Befehle gefährden die Stabilität der INUBIT Process Engine!

    Beispiel: cmd ohne /C zum Beenden des Befehls nach der Ausführung.

  • Parameter

    Parameter, mit denen die externe Applikation aufgerufen werden soll. Mehrere Argumente trennen Sie durch Leerzeichen.

    Schließen Sie Pfadangaben und Variablen, wenn diese Pfadangaben enthalten, in Anführungszeichen ein.

    Beispiel:

    {ScriptFile} "/home/ibis/test file/test"

    Wenn die Variable filePath eine Pfadangabe enthält, schließen Sie die in Anführungszeichen ein:

    {ScriptFile} "{Property:filePath}"

    Über den Button rechts neben dem Argumente-Feld können Sie folgende Platzhalter eingeben:

    • {File}

      Um die Eingangsnachricht als temporäre Datei an die aufgerufene Applikation zu übergeben. Nach ihrer Ausführung schreibt diese Applikation das Ergebnis in dieselbe Datei.

      Nutzen Sie {InputFile} und {OutputFile}, wenn zwei verschiedene Dateien verwendet werden sollen. {File} und {InputFile} schließen sich gegenseitig aus!

      Es ist nicht notwendig, {InputFile}, {OutputFile} oder Dateiparameter in Anführungszeichen zu setzen.

    • {XPath:Pfadangabe}

      Übergibt einen Knotenwert aus der XML-Eingangsnachricht an die aufgerufene Applikation. Ein Klick auf diesen Parameter öffnet den XPath-Assistenten, mit dem Sie XPath-Ausdrücke zum Auslesen des Knotenwertes erstellen können.

      Siehe XPath-Assistent

    • {Property:Propertyname}

      Übergibt eine Modulvariable oder eine Workflowvariable.

    • {ScriptFile}

      Übergibt den Inhalt aus dem Feld Skript.

    • {InputFile}

      Übergibt eine Eingangsnachricht an die aufgerufene Applikation, ohne diese nach der Ausführung wieder auszulesen, z.B.

      • Befehl: cmd.exe

      • Argumente: /C {ScriptFile.cmd} {InputFile}

      • Script: type "%1" > inputMessageDuplicated.dat

    • {OutputFile}

      Übergibt der aufgerufenen Applikation eine Datei, in welche die Applikation nach ihrer Ausführung das Ergebnis schreibt. Dieser Platzhalter wird meist zusammen mit {ScriptFile} genutzt, z.B.:

      • Befehl: cmd.exe

      • Argumente: /C {ScriptFile.cmd} {OutputFile}

      • Script: echo "This will be streamed into outputfile and provided to workflow" > "%1"

        Bei den Argumenten {File}, {ScriptFile}, {InputFile} und {OutputFile} können Sie eine der Dateiendung .cmd bzw. .bat angeben, z.B. {ScriptFile.bat}.

  • Arbeitsverzeichnis

    Für temporäre Dateien. Der Execution Connector und einige Applikationen benötigen ein solches Verzeichnis. Wenn Sie kein Verzeichnis angeben, wird das jeweilige Standard-Verzeichnis verwendet. Das Standard-Arbeitsverzeichnis ist <inubit-installdir>/inubit/bin.

    Wenn sich das Arbeitsverzeichnis und der Pfad zur Skriptdatei unterscheiden und der Pfad Leerzeichen enthält, schließen Sie den Pfad in Anführungszeichen ein.

    Wenn sich das Arbeitsverzeichnis und der Pfad zur Skriptdatei unterscheiden und die Kommandozeile einen Parameter enthält, fügen Sie am Ende der Kommandozeile ein zusätzliches Anführungszeichen ein, z.B.:

    Arbeitsverzeichnis: C:\temp
    Kommandozeile: cmd.exe, /C, "D:\te st\test.bat", "test", "test1"

Umgebungsvariablen

Umgebungsvariablen werden als Variablen/Wertepaare (getrennt durch ein = Zeichen) übergeben. Mehrere Umgebungsvariablen trennen Sie durch jeweils einen Zeilenumbruch.

Unter Windows müssen Sie bestimmte Zeichen wie Backslashes (\) und Anführungszeichen (") mit einem Backslash (\) entwerten, z.B.:

CATALINA_HOME=\"C:\\inubit 7\\server\\process_engine\"

Systemvariablen an Prozess übergeben

Wenn aktiviert, werden alle Systemvariablen des Systems mit der Process Engine an den Execution Connector-Prozess übergeben, damit die Befehle bzw. das Skript darauf zugreifen können.

Skript

Eingabefeld

Um ein Skript eingeben zu können, müssen Sie im Feld Parameter den Parameter {ScriptFile} einfügen. Um auf die Parameter zuzugreifen, die im Feld Parameter angegeben sind, verwenden Sie Variablen. Deren Syntax ist abhängig vom eingesetzten Betriebssystem:

  • Windows: %1

  • Linux: $1

Ein Skript kann auch via Variablen-Mapping am Execution-Connector übergeben werden. Dazu muss das Modulproperty Script überschrieben werden. Der Wert muss dabei base64-encodiert übergeben werden.

Prüfung des Rückgabewertes

Erwarteter Wert

Numerischer Wert:

  • Wenn der angegebene und der tatsächliche Rückgabewert gleich sind, dann wird die Workflow-Ausführung fortgesetzt.

  • Wenn ein anderer Wert als der angegebene zurückgegeben wird, dann wird der Fehlercode der aufgerufenen Applikation XML-formatiert (z.B. <ExitValue>0</ExitValue>) an den Workflow übergeben.

    Die formatierte Übergabe des Fehlercodes erfolgt nur, wenn die Checkbox Rückgabewert als XML zurückliefern aktiviert wurde. Ansonsten wirft das Modul einen Fehler.

  • Wenn kein erwarteter Wert angegeben ist, läuft der Workflow grundsätzlich weiter.

    Um sicherzustellen, dass fehlerhafte Ausführungen immer an den Workflow gemeldet werden, geben Sie 0 ein, denn Fehlercodes sind immer ungleich 0.

Verwendung der Ein- und Ausgangsnachrichten

  • Eingabenachricht verwenden

    (nur beim Medium/Output Connector)

    Wenn markiert, dann wird die Eingangsnachricht des Execution Connector-Moduls an die externe Applikation weitergeleitet.

  • Ausgabenachricht verwenden

    (nur beim Input/Medium Connector)

    Wenn markiert, dann wird die Ausgangsnachricht der externen Anwendung an den Execution Connector übergeben und von diesem an den Workflow weitergeleitet.

  • Fehlerausgang verwenden

    (nur beim Input/Medium Connector)

    Wenn markiert, dann wird die Fehler-Ausgabe der externen Anwendung an den Execution Connector und danach in den Workflow übergeben.

Ergänzende Einstellungen

  • Puffergröße für die Eingabenachricht

    Anzahl der Bytes für die Speicherreservierung.

    Wenn Sie keine Angabe machen, wird der Standard 4096 verwendet. Ein großer Wert verbraucht viel Speicher, der zum Aufrufzeitpunkt angefordert wird, und beschleunigt die Übergabe der Eingabenachricht an die aufrufende Applikation.

    Ein kleiner Wert verbraucht weniger Speicher. Die Übergabe der Eingangsnachrichten kann jedoch Zeit kosten, wenn diese viel größer als der Puffer sind und daher in Paketen mit der Größe des Puffers übermittelt werden müssen.

  • Rückgabewert als XML zurückliefern

    Nur sinnvoll in Kombination mit der Prüfung des Rückgabewertes (Return Code)!

    Der Rückgabewert wird in eine XML-Struktur eingebettet und zurückgeliefert.

Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen