IPluginWorkflowNode

Modified on Mon, 16 Jan, 2023 at 10:58 PM

Schnittstelle IPluginWorkflowNode

Diese Schnittstelle ermöglicht es, eine eigenen Node-Typ zum Workflow hinzuzufügen. Eine Node ist hierbei ein Knoten im Syntaxbaum einer Workflow-Verarbeitungskette. Der Wurzelknoten jedes solchen Syntaxbaums hat den Node-Typ "Sequenz". Ein Beispiel für solch einen Syntaxbaum ist etwa:

Sequenz
- Aktion "E-Mail versenden"
- Bedingung
  - Sequenz (If)
    - Aktion "Textdatei erzeugen"
    - Aktion "PDF befüllen"
  - Sequenz (Else)
    - Aktion "HTTP-Request"
    - Aktion "Word befüllen"
- Aktion "Externe Resource herunterladen"
- Switch (Wert [%tf1%])
  - Default-Case
    - Sequenz
      - Aktion "Textdatei erzeugen"
  - Switch-Case (wenn Wert gleich 1)
    - Sequenz
      - Aktion "Textdatei erzeugen"
  - Switch-Case (wenn Wert gleich 2)
    - Sequenz
      - Aktion "Textdatei erzeugen"
- Aktion "Abschlussseite"
- Experiment
  - Sequenz
    - Aktion "HTTP-Request ausführen"
  - Sequenz
    - Aktion "E-Mail an Administrator senden"

Dabei ist

die Sequenz ist ein Knoten, welche seine Kinderknoten der Reihe nach ausführt
die Bedingung ein Knoten, welcher eine Bedingung überprüft und je nach Resultat einen der beiden Kinderknoten ausführt (If-Zweig und Else-Zweig)
der Switch ein Knoten, welcher einen Wert gegen den Wert der Kinderknoten (Default-Case und Switch-Case) vergleicht und dann alle Kinderknoten ausführt, die einen passenden Wert haben
das Experiment (Try-Catch) ein Knoten, welcher versucht, den ersten Kinderknoten (Try-Block) auszuführen. Schlägt dies mit einer unbehandelten Ausnahme fehl, wird der zweite Kinderknoten (Catch-Block) ausgeführt.
die Aktion ein Knoten, der keine Kinderknoten hat und lediglich in Java definierte Logik ausführt

Mit diesem Interface können somit nicht nur Aktionen, sondern auch andere Knoten implementiert werden, die den Kontrollfluss beeinflussen.

Methodensignaturen

Die vollständige Dokumentation findet sich in der JavaDoc zu diesem Interface. Im Folgenden einige der wichtigsten Methoden:

public INodeHandler<?> getNodeHandler() Diese Methode muss die Implementierung von INodeHandler zurückliefern, welche durch das Plugin bekannt gemacht werden soll. INodeHandler enthält alle Methoden, um die Workflow-Node konfigurieren zu können.

Schnittstelle IPluginActionNodeHandler / APluginActionNodeHandler

Das Ergebnis des Demo-Workflow-Element-Plugins. Zeigt die im Workflow-Designer eingebundene Aktion.

Dieses Schnittstelle enthält viele Default-Implementierungen für reine abarbeitende Aktionen, die den Kontrollfluss nicht beeinflussen und lediglich in Java implementierte Logik ausführen. Es ist damit einfach möglich, eigene Workflow-Aktionen in das bestehende System hinzuzufügen.

Wir empfehlen, die abstrakte Klasse APluginActionNodeHandler zu verwenden. Falls das Plugin eine andere Superklasse haben soll, kann stattdessen das Mixin-Interface IPluginActionNodeHandler genutzt werden.

Eine Implementierung einer Workflow-Aktion besteht dabei üblicherweise aus mehreren Komponenten:

Implementierung einer Modelklasse zur Datenhaltung der Eigenschaften einer Workflow-Aktion (diese Klasse muss von BaseActionProps erben)
eine Enum-Implementierung zur Definition möglicher Fehlercodes, welche durch die Workflow-Aktion zurück geliefert werden können.
Implementierung der IPluginActionNodeHandler Schnittstelle unter Einbeziehung der definierten Modelklasse
eine XHTML-Seite zur Konfiguration und Anzeige der Eigenschaften der Workflow-Aktion
optional eine Managed-Bean-Implementierung (basierend auf der Schnittstelle INodePropertyPluginBean), um die XHTML-Seite (View) mit den Daten und der Geschäftslogik zu verknüpfen. Diese ist optional und nur erforderlich, wenn die XHTML-Seite spezielle Logik enthalten soll, wie etwa ein Button zum Prüfen Testen eines Webservices.

Methodensignaturen

Die vollständige Dokumentation findet sich in der JavaDoc zu diesem Interface. Im Folgenden einige der wichtigsten Methoden:

Erforderlich sind neben getName noch folgende zwei Methoden:

public INormalCompletionResult execute(INodeExecutionParams<TData> params) throws AbstractAbruptCompletionException

Hier erfolgt die Implementierung der Business-Logik des Plugins. Über params.getWorkflowContext() kann auf die Modelklasse mit der Konfiguration zugegriffen werden. Über params.getWorkflowContext() stehen viele Hilfsmethoden bereit, die verwendet werden sollten, anstellte Funktionen selber zu implementieren. Beispielsweise kann via params.getWorkflowContext().http().requestResponseRedirect(URI) eine Weiterleitung nach Ausführung des Workflows angestoßen werden. Alle Werte, welche die Aktion im Erfolgsfall zurück geben soll, müssen dem Datentyp entsprechen, welcher durch die Methode getSuccessValueDescriptor(IValueDescriptorFactory) definiert wird. Wenn diese Methode nicht implementiert ist, wird durch die Aktion kein Wert zurück gegeben.

public String getPropertiesViewXhtmlName()

Liefert den Namen (ohne Pfad-Angabe) zur XHTML-Seite, welche zur Konfiguration und Anzeige der Eigenschaften der Workflow-Aktion dient. Die XHTML-Seite muss in der Plugin-JAR im Ordner WEB-INF/ui liegen. Soll ein anderer Ordner genutzt werden, muss getPropertiesViewXhtmlPath überschrieben werden. Eine Implementierung ist erforderlich.

Wird das Mixin-Interface IPluginActionNodeHandler verwendet, muss noch getPluginInitializeData implementiert werden, welche nur den Wert zurückgibt, der in der initialize-Methode übergeben wurde.

Alle weiteren Methoden können optional bei Bedarf überschrieben werden. Auszugsweise hier einige Methoden:

public IElementCategory getMainCategory(IGetElementPrototypesParams params)

Definiert die Haupt-Kategorie, in der die Workflow-Aktion innerhalb des Workflow-Designers zur Auswahl angezeigt wird (links-seitige Auswahl). Die Implementierung dieser Methode ist optional. Erfolgt keine Implementierung, so wird die Workflow-Aktion standardmäßig unter der Rubrik "Aktionen" eingeordnet.

public IElementCategory getSubCategory(IGetElementPrototypesParams params)

Definiert die Unter-Kategorie, in der die Workflow-Aktion innerhalb des Workflow-Designers zur Auswahl angezeigt wird (links-seitige Auswahl). Die Implementierung dieser Methode ist optional. Erfolgt keine Implementierung, so wird die Workflow-Aktion standardmäßig unter der Rubrik "Allgemein" eingeordnet.

public IValueDescriptor<?, ? extends IValueBuilder<?>> getSuccessValueDescriptor(IValueDescriptorFactory factory)

Wenn Sie Werte in der Workflow-Aktion zurückgeben (und über Variablen/Platzhalter für andere Aktionen verfügbar machen möchten), muss diese Methode implementiert werden. Weiterhin muss sichergestellt werden, dass in der Methode execute(INodeExecutionParams) bei der Ausführung die entsprechenden Werte in der definierten Rückgabestruktur gesetzt werden. Falls die execute-Methode Werte zurückliefert, welche nicht in dieser Methode definiert sind, werden diese Werte ignoriert. Die Implementierung dieser Methode ist optional, wenn die Workflow-Aktion keine Werte zurück geben soll.

public IUnionValueDescriptor<String> getErrorValueDescriptor(IValueDescriptorFactory factory)

Diese Methode definiert dabei alle möglichen Ausprägungen von Fehlercodes, die in der Workflow-Aktion auftreten können. Jeder Fehlercode kann dabei unterschiedliche zusätzliche Informationen zurück liefern. Welche dies genau sind, ist am jeweiligen Fehlercodes zu definieren.Wenn in der {{code}}execute{{/code}} eine nicht behandelter Fehler auftritt, so wird standardmäßig der allgemeine Fehlercode {{code}}ERROR_CODE_GENERAL{{/code}} zurück geliefert.Diese Methode ist zu implementieren, wenn die Aktion benutzerdefinierte Fehlercodes zurück geben soll und diese über zusätzliche Informationen verfügen müssen. Wenn "nur" eine Unterscheidung nach Fehlercodes genügt, so muss nur die Methode {{code}}getErrorCodeClass{{\code}} implementiert werden und auf die entsprechende Enum-Klasse mit den Fehlercodes verweisen.

public Class<? extends Enum<?>> getErrorCodeClass()

Gibt den Typ der Enumeration zurück, welcher die Fehlertypen definiert, die während der Ausführung der Workflow-Aktion auftreten können. Wenn diese Methode nicht implementiert ist, existieren keinen benutzerdefinierten Fehler in der Aktion. Im Fall einer Ausnahme innerhalb der Aktions-Verarbeitung wird diese dann als allgemeine Ausnahme behandelt und der Fehlercode {{code}}ERROR_CODE_GENERAL{{/code}} zurück geliefert.

public IFileValueDescriptor getFileValueDescriptor()

Diese Methode ist zu implementieren, wenn die Workflow-Aktion Dateien zurückgeben kann. Diese Workflow-Aktion kann dann von anderen Aktionen ausgewählt werden, die Dateien erfordern. Wenn die Workflow-Aktion keine Dateien bereitstellt, ist die Methode zu entfernen.

public Class<? extends INodePropertyPluginBean<TData>> getMainPluginBeanClass()

Liefert die Bean-Klasse zurück, welche im Zusammenspiel mit der XHTML-Seite genutzt werden soll. Die Implementierung dieser Methode ist optional. Der XHTML-Seite wird immer die Variable model zur Verfügung gestellt, welche auf die Modelklasse verweist.

Schnittstelle IPluginConditionNodeHandler / APluginConditionNodeHandler

7.1.0+

Diese Schnittstelle enthält Default-Implementierung für reine If-Else-Bedingungen. Damit ist es einfacher möglich, eine If-Else-Bedingung zu implementieren, welche eine Bedingung prüft und je nach Resultat den If-Zweig oder den Else-Zweig ausführt.

Wir empfehlen, die abstrakte Klasse APluginConditionNodeHandler zu verwenden. Falls das Plugin eine andere Superklasse haben soll, kann stattdessen das Mixin-Interface IPluginConditionNodeHandler genutzt werden.

Methodensignaturen

Die vollständige Dokumentation findet sich in der JavaDoc zu diesem Interface. Im Folgenden einige der wichtigsten Methoden:

Erforderlich sind neben getName noch folgende zwei Methoden:

public boolean evaluateCondition(INodeExecutionParams<TData> params) throws AbstractAbruptCompletionException

Hier erfolgt die Implementierung der Business-Logik der Bedingung. Diese Methode muss zurückliefern, ob die Bedingung erfüllt ist. Über params.getWorkflowContext() kann auf die Modelklasse mit der Konfiguration zugegriffen werden. Über params.getWorkflowContext() stehen viele Hilfsmethoden bereit, die verwendet werden sollten, anstellte Funktionen selber zu implementieren.

Wird das Mixin-Interface IPluginConditionNodeHandler verwendet, muss noch getPluginInitializeData implementiert werden, welche nur den Wert zurückgibt, der in der initialize-Methode übergeben wurde.

Alle weiteren Methoden sind wie bei Aktion optional.