4.1. Plugins - Getting Started

Notwendige Tools

Notwendig Tools, die benötigt werden

Java 8 

https://www.java.com/de/

Maven 3 

http://maven.apache.org/

„mvn -v" muss in der Konsole/CMD-Line gehen.

Git 

https://git-scm.com/

Git ist optional, aber macht vieles einfacher

Aufbau eines Plugins


Plugin-ID


Jedes Plugin muss eine eindeutige Plugin-ID haben, die systemweit einmalig ist. Hierzu sollte die Firmen-Domain zzgl. des Plugin-Namens in der „Reverse Domain Name Notation" verwendet werden. Für bluebiz (mit der Domain bluebiz.de) fangen entsprechend alle bluebiz-Plugins mit „de.bluebiz." an. Nehmen sie bitte entsprechende Notationen für Ihre Firma bzw. Person. Wir nennen unser Plugin hier nun „smartmes-example", sodass die Plugin-ID entsprechend


de.bluebiz.smartmes-example


lautet.

Plugin-Layout

Ein Plugin besteht minimal aus drei Dateien:

  • pom.xml
  • src/main/resources/smartmes.json
  • src/main/java/de/bluebiz/smartmes/example/ExamplePlugin.java

Unter https://github.com/bluebiz/smartmes-plugin-template finden Sie eine entsprechende Vorlage. Sie können das entsprechende Repository mit „git clone" klonen und dann für Ihr Plugin anpassen.
Des Weiteren gibt es unter Resources noch eine Readme-Datei, die eine Beschreibung des Plugins als Markdown erlaubt (und vor dem Installieren in smartMES angezeigt wird).

pom.xml

Die pom.xml beschreibt das Plugin durch ein Maven-Artefakt. Zusätzlich zu den normalen Maven-Informationen wie artifactId, gibt es unter <properties> eine Reihe von Informationen, die smartMES zum Starten des Plugins benötigt.
Ändern Sie die entsprechenden Identifier in der pom.xml ab, sodass sie zu Ihrem Plugin und Ihrer Plugin-ID passen:

  • groupId: Die Gruppe, unter dem das Artefakt zusammengefasst werden soll
  • artifactId: Muss ihrer Plugin-ID entsprechend
  • version: Die Version muss 3 Stellen haben, also major.minor.build

Beispiele: 1.0.0 oder 16.11.22 oder ggf. mit SNAPSHOT entsprechend 1.0.0-SNAPSHOT etc.

  • properties.plugin.class: dieses muss auf auf die Datei zeigen, die unter src/main/java/ liegt (hier ist es ExamplePlugin.java)

Des Weiteren ist ein build-Plugin notwendig, dass in der pom.xml angegeben werden muss, damit das Plugin korrekt gebaut wird. Dieses einfach aus der Vorlage übernehmen.

smartmes.json

Die smartmes.json beschreibt einige Informationen für das Plugin, z.B. einen lesbaren Namen, den Anbieter, eine Beschreibung und eine URL:

{
  "name": "Smartmes Example Plugin",
  "url": "http://www.bluebiz.de",
  "vendor": "bluebiz OHG",
  "description": "This is an example plugin for SmartMES",
...
}

Des Weiteren dient die smartmes.json noch weiter, um ein paar andere Informationen bereitzustellen (z.B. zu Abhängigkeiten oder, um Views zu deklarieren).


ExamplePlugin.java

Dies ist die Hauptdatei des Plugins und wird automatisch gestartet/gestoppt, wenn das Plugin geladen wird. Ändern Sie den Namen der Datei und auch ggf. den Paketnamen entsprechend ab.
Wenn Ihre Plugin-ID z.B. de.acme.smartmes.first-plugin ist, dann sollten Sie ExamplePlugin entsprechend ändern in src/main/java/de/acme/smartmes/FirstPlugin.java
In der pom.xml unter properties muss dann entsprechend auch geändert werden: <plugin.class>de.acme.smartmes.FirstPlugin</plugin.class>
ExamplePlugin muss von Plugin ableiten.
Die Methode start() wird beim Starten des Plugins ausgeführt und stop() entsprechend beim Beenden vom SmartMES ausgeführt. Später mehr zu den Funktionen.

Neues Plugin erstellen

Erstellen sie zunächst ein entsprechenden Ordner für das Plugin-Projekt.
Am einfachsten ist es, dass Template zu klonen, indem folgendes per Console ausgeführt wird:


git clone https://github.com/bluebiz/smartmes-plugin-template.git .



Passen Sie dann die entsprechenden Identifier in der pom.xml an, wie oben beschrieben. Also groupId, artifactId und ggf. plugin.class, wenn sie auch den Dateipfad ändern. Diese sollten nicht mehr auf "de.bluebiz" bzw. example-plugin beinhalten, sondern die Bezeichner Ihres eigenen Plugins!


Installieren sie dann die Abhängigkeiten, die von Maven automatisch installiert werden.

mvn verify 

Dann können sie das Plugin erstellen:

mvn package 


Im Unterordner Target befindet sich dann ihr Plugin als gepacktes Jar, in unserem Beispiel heißt diese: 

smartmes-example-1.0.0-SNAPSHOT.jar

Diese Datei stellt das Plugin dar und können Sie dann im smartMES hinzufügen. Wir benutzten diese Datei dann weiter unten. 

SmartMES Herunterladen


Unter Downloads gibt es die aktuelle Version des Jar-Archivs (eine *.war-Datei). Diese herunterladen und ein leeres Verzeichnis ablegen.

SmartMES Datenbank konfigurieren

Das System benötigt eine Datenbank. Unterstützt werden MySQL oder MariaDB. Bitte beachten, dass nicht alle Versionen unterstützt werden.

Da das System auf Unicode bzw. utf8 beruht, ist die Datenbank entsprechend anzulegen: Als Character-Set ist "utf8" und als Collation ist "utf8_unicode_ci" sinnvoll. Dies bspw. mit folgenden SQL-Statement möglich:

CREATE DATABASE `smartmes_example` CHARACTER SET 'utf8' COLLATE 'utf8_unicode_ci';

Erstellen Sie eine Datei "application-prod.yml", um die Datenbank zu konfigurieren. 

Angenommen für die Datenbank gibt es folgende Zugangsdaten:

Datenbank-Host:         localhost
Datenbank-Port:          3306
Datenbank-Name:       smartmes_example
Datenbank-User:         smartmesuser
Datenbank-Passwort:  12345678

Dann muss die application-prod.yml wie folgt aussehen:

spring:
    datasource:
        driver-class-name: com.mysql.jdbc.jdbc2.optional.MysqlDataSource
        url: jdbc:mysql://localhost:3306/smartmes_example?useUnicode=true&characterEncoding=utf8
        name:
        username: smartmesuser
        password: 12345678

Entsprechend müssen Host, Port und Datenbank in den url-Parameter angegeben werden udn entsprechend Benutzer und Passwort danach. 

In der Formatierung der yml-Datei ist darauf zu achten, dass das Einrücken korrekt ist: hier sollten 4 Leerzeichen pro Ebene verwendet werden.

Die yml-Datei wird noch für weitere Konfigurationen des Systems verwendet! Beispielsweise lässt sich der Port, auf dem das System startet, wie folgt ändern:

server:
port: 8999

Hinzufügen des Plugins

SmartMES lädt automatisch alle Plugins, die sich im Verzeichnis „plugins" befinden. Die Plugins selbst sind dabei Jar-Dateien. Jedes Plugin muss dabei ein paar bestimmte Dinge bereitstellen, damit SmartMES das Plugin erfolgreich laden kann.
Legen Sie daher, falls noch nicht existiert, ein Verzeichnis plugins an:


 
Legen Sie nun ihre Jar, die weitere oben erstellt wurde, in den Ordner plugins (hier die smartmes-example-1.0.0-SNAPSHOT.jar).

SmartMES starten


Gestartet werden kann SmartMES dann per CMD bzw. Console mit


java -jar smartmes-core-19.1.355.war --spring.profiles.active=prod

Der Zusatz "--spring.profiles.active=prod" ist wichtig und sorgt dafür, dass das System mit der oben konfigurierten Datenbank startet. Beim ersten Start werden vom System alle notwendigen Dinge, wie Verzeichnisse, Datenbank-Struktur und -Inhalte angelegt. Daher kann der erste Start länger dauer.


Sie müssten nun in der Konsole sehen, dass Ihr Plugin gestartet wurde. Das Beispiel-Plugin gibt nur „EXAMPLE PLUGIN STARTS" aus

SmartMES GUI

Das System kann dann mit dem Browser unter http://localhost:8080 geöffnet werden.
Der initiale Nutzer ist „admin" mit Passwort „admin".
Unter „Plugins" – „Installierte Plugins" müsste ihr Plugin zu sehen sein.

Plugin als Projekt öffnen

Da es sich um ein Maven-Projekt handelt, können Sie die pom.xml als Maven-Projekt in ihre Java-IDE als neues Projekt importieren.

Wie benutzten dazu IntelliJ, es sollte jedoch analog auch in anderen IDEs gehen, die Maven unterstüzen!

In IntelliJ sieht das so aus:




Dies sollte dann so aussehen:

IntelliJ sollte dafür sorgen, dass auch die entsprechenden notwendigen Bibliotheken eingebunden werden. Hierzu gehört auch die Schnittstelle zum smartMES, die dann unter "External Libraries" auftauchen sollte. 

Verwenden einer Schnittstelle

Der Haupteinstiegspunkt ist die Klassse „SmartMES“.

Folgendes erstellt beispielsweise einen Auftrag mit dern Nummer 1000 beim Starten und entfernt es beim Beenden des Plugins, indem der ProductionOrder-Service benutzt wird. 

Ein Auftrag benötigt mindestens eine Position (ein ProductionOrderItem), das wir entsprechend hinzufügen.

public class ExamplePlugin extends Plugin {

    private Long orderId;

    public ExamplePlugin(PluginWrapper wrapper) {
        super(wrapper);
    }

    @Override
    public void start() throws PluginException {
        try {
            ProductionOrderADO order = new ProductionOrderADO();
            order.setNumber("1000");                        // Belegnummer des Produktionsauftrags
            order.setCaseHandler("Max Muster");             // Name der Ansprechperson
            order.setOrderDate(LocalDate.now());            // Datum des Produktionsauftrags
            // Einen Artikel hinzufügen
            ProductionOrderItemADO item = new ProductionOrderItemADO();
            item.setArticlenumber("1234");                  // Artikelnummer
            item.setName("Test-Artikel");                   // Artikelname
            item.setDescription("Ein Test-Artikel");        // Artikelbeschreibung
            item.setIdentifier("TEST_BOM_1");               // Bezeichner der Stückliste
            item.setRevision("A1");                         // Revision der Stückliste
            item.setCount(10.0);                            // 10 Stück des Artikels
            item.setDueDate(LocalDate.now().plusWeeks(2));  // Lieferdatum in 2 Wochen
            // eine Zusatzinformation für den Artikel erstellen
            ProductionInformationADO info1 = new ProductionInformationADO();
            info1.setName("Farbe");                         // Name der Information ist "Farbe"
            info1.setValue("schwarz");                      // Wert der Information ist "schwarz"
            item.getProductionInformations().add(info1);    // Information zum Artikel hinzufügen

            order.getProductionOrderItems().add(item);      // Artikel zum Auftrag hinzufügen
            // Auftrag erstellen - die Antwort ist der erstellte Auftrag
            order = SmartMES.getService().productionOrders().createProductionOrder(order);
            orderId = order.getId();
            System.out.println("Created order with ID: "+order.getId());
        } catch (ServiceException e) {
            e.printStackTrace();
        }
    }

    @Override
    public void stop() throws PluginException {
        try {

            boolean result = SmartMES.getService().productionOrders().deleteProductionOrder(orderId);
            System.out.println("Created order removed: "+result);
        } catch (ServiceException e) {
            e.printStackTrace();
        }
    }
}

In der GUI unter "Aufträge" sehen Sie nun den Auftrag.

Beim Beenden des Plugins wird der Auftrag entfernt.

Klicken Sie Unter Plugins / Installierte Plugins auf "Stop" Ihres Plugins:

Sie sehen dann, dass der Auftrag entfernt wurde:

Und dieser auch nicht mehr in der GUI bei den Aufträgen zu sehen ist!

Mehr zu verfügbaren Services gibt es hier: SmartMES-Services