Plug-ins entwickeln und installieren

Überblick

Mit java-basierten Plug-ins können Sie die INUBIT-Software funktional erweitern. So können Sie z.B. Unternehmensanwendungen, für die es noch keine Systemkonnektoren gibt, an die INUBIT-Software anbinden. Die Anzahl von Plug-ins ist unbeschränkt.

Sie müssen alle selbst-entwickelten Plug-ins lizenzieren lassen und registrieren, bevor Sie diese nutzen können.

Siehe Plug-ins zur INUBIT-Software hinzufügen.

Plug-ins entwickeln

Übersicht

Es gibt zwei Plug-in-Typen: Server-Plug-ins und Client-Plug-ins. Jedem Server-Plug-in kann dabei genau ein Client-Plug-in zugeordnet sein.

  • Server-Plug-ins
    Ein Server-Plug-in verarbeitet die Eingangsnachrichten eines Prozessschritts und stellt die Ergebnisse der Verarbeitung als Ausgangsnachrichten zur Verfügung. Es liefert die technische Implementierung, um die Verarbeitung der Eingabedaten zu Ausgabedaten durchzuführen.

  • Client-Plug-ins
    Client-Plug-ins werden in der INUBIT Workbench benutzt und stellen eine grafische Oberfläche mit Dialogen bereit, um konkrete Modul-Instanzen zu erzeugen und deren Parameter zu konfigurieren. Die in einem Modul gespeicherten Parameter steuern und konfigurieren, wie und in welcher Art die Verarbeitung des Moduls während der Workflow-Ausführung durch die Process Engine stattfindet.

administration guide 376 1

Plug-in SDK installieren

So gehen Sie vor

Wählen Sie bei der INUBIT-Installation die Option Benutzerdefiniert > Plug-in SDK.
Das Plug-in-SDK wird in das Verzeichnis <inubit-installdir>/pluginSDK kopiert.

Wie Sie das Plug-in-SDK nachträglich installieren, siehe Komponenten der INUBIT-Software nachinstallieren.

Das Plug-in-SDK enthält folgende Daten:

  • lib
    ibis.jar und ibis_tools.jar zum Kompilieren der Plug-ins.

  • src/com/inubit/ibis/plugins/examples/ExampleConnector

    • example_connector.gif
      Beispielgrafik für das Connector-Symbol

    • ExampleConnector.java
      Client Plug-in des Connectors.

    • ExampleConnectorPlugin.java
      Implementierung des Server-Plug-ins.

    • ExampleConnectorWizardPanel.java
      Erstes Assistenten-Panel des Konnektors.

    • ExampleConnectorSecondWizardPanel.java
      Zweites Assistenten-Panel des Connectors.

  • src/com/inubit/ibis/plugins/examples/ExampleModule

    • example_module.gif
      Beispielgrafik für das Modulsymbol.

    • ExampleModule.java
      Client-Plug-in für das Modul.

    • ExampleModulePlugin.java
      Implementierung des Server-Plug-ins.

    • ExampleWizardPanel.java-
      Assistenten-Panel für das Client-Plug-in.

    • ExampleXulPlugin.java
      Beispiel-Klasse für einen Assistenten.

    • ExampleXulPlugin.xml
      Beispiel-XML mit der Beschreibung eines Assistenten.
      Siehe Assistenten für Client-Plug-ins erzeugen.

  • templates/images
    Templates für Modul-Aktionen, die im Designer verwendet werden.

    • svg
      SVG-Modul-Grafiken für das Erstellen von Plug-ins.

      administration guide 377 0

  • build.xml
    Beispieldatei für das Apache Ant Buildtool; erfordert die Installation von Apache Ant. Der Quellcode kann mit ant compile jar kompiliert werden.

Wenn Sie die INUBIT-Dokumentation installiert haben, dann finden Sie die Schnittstellenbeschreibung der Plug-in-Klassen im Verzeichnis <inubit-installdir>/documentation/apidoc/index.html. Oder rufen Sie die Dokumentation direkt auf.

Server Plug-ins

Alle Interfaces und Bibliotheken für die Entwicklung von Plug-ins befinden sich in den Dateien ibis.jar und ibis_tools.jar.

Zum Erstellen einer Server-Plug-in-Klasse müssen Sie eines der folgenden Interfaces implementieren:

  • Für Plug-ins, die keine Systemkonnektoren sind:
    I_IBISPluginInterface

  • Für Systemkonnektor-Plug-ins:
    I_IBIS_SC_PluginInterface

Selbstentwickelte Plug-ins können nicht als Listener-Konnektor implementiert werden.

Ein Beispiel für ein Systemkonnektor-Server-Plug-in finden Sie im Verzeichnis <inubit-installdir>/pluginSDK/src/com/inubit/ibis/plugins/examples/ExampleConnector.

Für die Plug-in-Entwicklung stehen Ihnen Hilfsklassen im Package com.inubit.ibis.plugins.utils zur Verfügung.

Siehe Hilfsklassen.

Zugriff auf Eingabenachricht

Die Eingabenachricht befindet sich in Form eines InputStream-Objekts in inputMessages[0]:
InputStream dataStream = inputMessages[0];
Am Ende der Modulausführung ist die Nachricht in outputMessages[0] zu schreiben.

Für das einfache Durchreichen der Nachricht kann Folgendes verwendet werden:
IBISPluginStreamUtils.readStream(inputMessages[0], outputMessages[0]);

Zugriff auf Variablen

Wenn im Server-Plug-in Variablen gesetzt werden sollen, dann müssen diese immer erst von der ersten Stelle des Input-Stream-Arrays (propertyMessages[1]) in die erste Stelle des Output-Stream-Arrays (propertyOutputMessages[1]) geschrieben werden. So werden die Variablen von der Plug-in-Engine unverändert an das nächste Modul weitergegeben.

Beispiel

public void execute(
  InputStream[] inputMessages,
  InputStream[] propertyMessages,
  OutputStream[] outputMessages,
  OutputStream[] propertyOutputMessages
  )
  throws InubitException){
    IBISPluginPropertyHandler variables = new
IBISPluginPropertyHandler(propertyMessages[1]);
    variables.setProperty("MyVariable", "12345");
    variables.save(propertyOutputMessages[1]);
  }

Siehe I_IBISPluginInterface unter <inubit-installdir>/documentation/apidoc/index.html.

Fehler erzeugen

Um einen Fehler zu erzeugen, ist eine InubitException zu werfen:
throw new InubitException(wertFürISErrorKey);
Der Parameter bei diesem Konstruktor wird als Inhalt der Variable ISErrorKey gesetzt.
Die Variable ISErrorString wird automatisch mit dem entsprechenden sprachabhängigen Fehlertext belegt, sofern ein Text für den gegebenen ISErrorKey vorliegt.

Um einen beliebigen Wert bei der Variable ISErrorString zu setzen, kann Folgendes verwendet werden:

throw new InubitException.newInstanceWithUnlocalizedMsg(wertFürISErrorKey,
wertFürISErrorString);

Um im Fehlerfall die Nachricht zu setzen, die an den Fehler- bzw. Scope-Ausgang weitergeben wird, ist vorher outputMessages[1] zu setzen:
IBISPluginStreamUtils.readStream(inputStreamOfErrorScopeMessage, outputMessages[1]);

Java-basierte Client Plug-ins

Um eine Java-basierte Client-Plug-in-Klasse zu erstellen, müssen Sie abstrakte Klassen implementieren.

  • Für alle Plug-ins gilt:

    • Die Plug-ins müssen das Interface I_ModulePlugin implementieren bzw. von AbstractModulePlugin ableiten. Die abgeleitete Klasse wird im Plug-in Manager als Client Plug-in Klasse angegeben.

    • Wenn ein Panel für einen Assistenten existiert, implementieren Sie die Methode getFirstWizardPanel(). Diese Methode muss ein Objekt ModuleEditorWizardBasePanel zurückliefern. Wenn kein Panel vorhanden ist, dann kann null zurückgeben werden.

    • Ein Assistenten-Panel leitet grundsätzlich von ModuleEditorWizardBasePanel ab. Alle Methoden, die überlagert werden sollen, müssen überschrieben und gemäß ihrer vorgesehenen Verwendung implementiert werden, wie in der Klasse WizardBasePanel beschrieben.

  • Für Systemkonnektor-Plug-ins gilt zusätzlich:
    Die Plug-ins müssen das Interface I_ConnectorPlugin implementieren. Dabei leitet sich I_ConnectorPlugin von I_ModulePlugin ab. Um eine einfache Tabelle für Properties darzustellen, leiten Sie von AbstractConnectorPlugin ab.

Sie finden die Klassen und Interfaces für die Beispielmodule mit Assistent im Verzeichnis <inubit-installdir>/pluginSDK/src/com/inubit/ibis/plugins/examples. Hilfsklassen für Client Plug-ins finden Sie im Package com.inubit.ibis.configuration.module.plugins.utils.

Voraussetzung ist, dass Sie das Plug-in SDK installiert haben. Siehe Plug-in SDK installieren.

Ein Beispiel für ein Systemkonnektor-Server-Plug-in finden Sie in Verzeichnis <inubit-installdir>/pluginSDK/src/com/inubit/ibis/plugins/examples/ExampleModule.

Assistenten für Client-Plug-ins erzeugen

Sie können Assistenten für Client-Plug-ins mithilfe des Formular-Designers im Task Generator erstellen. Dieses Vorgehen hat den Vorteil, dass Sie Layout und Scripting der Assistenten im Vorschau-Modus testen können.

Der Task Generator erzeugt eine XML-Struktur mit der Beschreibung des Assistenten, die dem Client Plug-in als Eingangsnachricht übergeben wird.

Ein Beispiel für diese XML-Struktur finden Sie in ExampleXulPlugin.xml, siehe Plug-in SDK installieren.

So gehen Sie vor

  1. Erzeugen Sie einen Task Generator. Markieren Sie dabei die folgenden Optionen:

    • Eintrag in der Taskliste > Formular

    • Allgemein > Eingangsnachricht ignorieren

  2. Ein- und mehrseitige Assistenten
    Jeder Dialog eines Assistenten wird durch ein Panel dargestellt. Um einen Assistenten mit mehreren Dialogen zu erzeugen, fügen Sie ein Panel für jeden Dialog hinzu:

    administration guide 380 1

    Beachten Sie, dass das Theme Toolset ausgewählt sein muss!

  3. Dialogtitel und Beschreibungen Für Dialogtitel und Beschreibungen verwenden Sie an den entsprechenden Elementen folgende Attribute:

    wizardTitle="Beispiel-Titel"
wizardDescription="Beispiel-Beschreibung"

  4. Fehler und Mehrsprachigkeit
    Felder können für unterschiedliche Sprachen mit dem Befehl pattern.<lang> auf bestimmte Kriterien überprüft werden, z.B. ob bei englischen Zahlenangaben Punkte statt Kommata gesetzt wurden. Entsprechend können Fehlertexte und deren Übersetzungen als Attribute angegeben werden, z.B.:

    errorText="Wer A wählt, muss auch B wählen!"
errorText.en="You must select…"/>
    administration guide 380 2

  5. Abhängigkeiten
    Abhängigkeiten zwischen Bedienelementen im Formular formulieren Sie mit einer der folgenden Sprachen: javascript, beanshell (java), jython und groovy (wenn im Classpath vorhanden).
    Siehe Panel 3 in der mitgelieferten Beispieldatei ExampleXulPlugin.xml.

  6. Führen Sie das XSLT Stylesheet im Bereich Formular Mapping aus. Das Ergebnis ist eine XML-Struktur, die im Bereich Formular Mapping im Register Ergebnis angezeigt wird.

  7. Speichern Sie dieses XML in einer Datei und in demselben Verzeichnis wie die Java-Klasse des Client-Plugins.

  8. Übergeben Sie das XML Ihrem Plug-in als Eingangsnachricht, z.B.:

    public class ExampleXulPlugin extends AbstractXulPlugin {
public ExampleXulPlugin() {
super(ExampleXulPlugin.class.getResourceAsStream("ExampleXulPlugin.xml"));
}
}

  9. Propertys
    Die Namen und Werte der Formular-Elemente können Sie als Propertys aus dem Formular auslesen und verarbeiten.
    Die Propertys, welche auf der Serverseite an das Plug-in übergeben werden, ergeben sich aus den Namen der Formularelemente und deren Inhalt.
    Beispiel: Ein TextField hat den Namen street und den Wert Wiener Str.. Die Property hat dann entsprechend den Namen street und den Wert Wiener Str..

Hilfsklassen

Als Hilfsklassen stehen Ihnen im Package com.inubit.ibis.utils u.a. folgende Klassen zur Verfügung:

  • IBISTracer
    Zur Ausgabe von Tracing-Informationen während der Laufzeit. Die INUBIT-Software verwendet intern log4j2 zum Tracing. Das Tracing kann in der laufenden INUBIT Process Engine aktiviert bzw. deaktiviert werden. Siehe Server Trace Log aktivieren und konfigurieren.

    Die Klasse IBISTracer kann nur für Packages verwendet werden, die sich im com.inubit-Namespace befinden. Zum Konfigurieren der Trace Level für eigene Server Plug-ins enthält die Klasse ExampleConnectorPlugin eine beispielhafte Implementierung.

    Pro Java-Klasse muss der IBISTracer einmal statisch initialisiert werden: static IBISTracer Tracer = IBISTracer.getTracer(MyPlugin.class.getName());
    Danach können Traces mit unterschiedlichen Levels im Code erzeugt werden, z.B.:

    • Tracer.log (’Mein erster Trace’); erzeugt einen Trace-Eintrag mit Level Info,

    • Tracer.debug (’Mein Debug-Trace’); erzeugt Trace mit Level debug,

    • Tracer.error (’Mein erster Fehler’, MeineException); erzeugt einen entsprechenden Trace mit Level Error.

  • InubitException
    Dient dem Fehlerhandling. Wenn in einem Plug-in eine InubitException generiert wird, dann wird die Modul-Ausführung abgebrochen und ein entsprechendes Fehlerhandling eingeleitet (u.a. Überführen des Workflows in den Errorzustand, Erzeugen der Einträge in Queue Manager und System Log, Ausführen von Error Branches bzw. Ersatzkonnektoren).

Die Stabilität wird nur für die API der im JavaDoc beschriebenen Klassen garantiert. Von der Verwendung anderer Klassen wird abgeraten!

Plug-ins zur INUBIT-Software hinzufügen

Überblick

Um selbst-entwickelte Plug-ins in der INUBIT-Software nutzen zu können, müssen Sie folgende Schritte in der angegebenen Reihenfolge ausführen:

  1. Plug-in lizenzieren lassen.
    Wenden Sie sich dazu an den Support.

  2. Plug-in installieren. Siehe

  3. Plug-in registrieren. Siehe

Plug-ins installieren

Beim Installieren werden die Klassen des Plug-ins in die Verzeichnisse <inubit-installdir>/client/lib/ext und <inubit-installdir>/server/lib/ext desjenigen Rechners kopiert, auf dem die INUBIT Workbench installiert ist.

Bei Toolsets < Version 5.0 und wenn Sie weitere INUBIT Workbenches auf anderen Rechnern nutzen: Kopieren Sie die Klassen manuell in das Verzeichnis <inubit-installdir>/client/lib/ext.

Voraussetzungen

Falls Sie für ein Client-Plug-in ein Icon anzeigen lassen möchten, muss dieses Icon in der installierten jar-Datei enthalten sein.

So gehen Sie vor

  1. Melden Sie sich als Systemadministrator an der INUBIT Workbench an.

  2. Zeigen Sie das Register Administration an.

  3. Wählen Sie im Burger-Menü Konfiguration > Library Manager….
    Ein Dialog öffnet sich.

  4. Klicken Sie auf das Icon administration guide 382 1, um eine neue Bibliothek hochzuladen.
    Der Dialog Bibliothek hochladen öffnet sich.

  5. Klicken Sie rechts neben dem Feld Datei auf administration guide 382 2.
    Ein Dateiexplorer öffnet sich.

  6. Navigieren Sie zu Ihrer JAR-Datei, markieren Sie diese und klicken Sie auf Öffnen.
    Der Dateiname wird im Feld Datei angezeigt.

  7. Wählen Sie im Bereich Bibliothekstyp die Plug-in Jar-Bibliothek.

    Wie Sie Treiber hochladen, nach Bibliotheken suchen und Bibliotheken löschen, siehe Bibliotheken verwalten.

  8. Klicken Sie auf Fertig stellen.

  9. Starten Sie die Process Engine(s) und die Workbench(es) neu.

Für Informationen, wie Sie Plug-ins auf Remote Connectoren oder entfernte INUBIT Process Engines laden, siehe Überwachte Komponenten aktualisieren.

Plug-ins registrieren

So gehen Sie vor

  1. Melden Sie sich als Systemadministrator an der INUBIT Workbench an.

  2. Zeigen Sie das Register Konfiguration an.

  3. Wählen Sie im Burger-Menü Konfiguration > Plug-in Manager…​.
    Ein Dialog öffnet sich.

  4. Markieren Sie die Plug-in-Gruppe, der das neue Plug-in hinzugefügt werden soll, oder legen Sie eine neue Gruppe an.

  5. Öffnen Sie das Kontextmenü der Gruppe und wählen Sie Neues Plug-in registrieren.
    Ein Dialog öffnet sich.

  6. Füllen Sie die Felder aus:

    • Name: Wählen Sie den Namen Ihres Plug-ins aus. Die Liste enthält alle Plug-in-Namen, die in der Lizenzdatei enthalten, aber noch nicht registriert sind.

    • Gruppe: Wählen Sie, in welcher Gruppe Ihr Plug-in angezeigt werden soll. Füllen Sie die folgenden Felder entweder im Bereich Client oder Server aus, abhängig davon, ob Ihr Plug-in die INUBIT Process Engine oder die INUBIT Workbench erweitert.

    • Klasse: Vollständiger Name der Klasse des Plug-ins.

    • Applikation: Bezeichnung für Ihr Plug-in.

    • Modul-Icon (nur Client): Relativer Pfad inkl. Name der Grafikdatei in der jar-Datei.

      Die standardmäßig installierten Plug-in-Gruppen können nicht umbenannt, geändert oder gelöscht werden.

      Plug-ins innerhalb dieser Gruppen können nicht umbenannt werden.

      Ihre UI-Optionen können nicht bearbeitet werden.

  7. Schließen Sie den Dialog mit OK.

  8. Öffnen Sie den User Manager und geben Sie den Rollen das Recht, Ihr neues Plug-in zu benutzen.

Siehe Benutzer verwalten

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