Konfiguration¶

Wenn alle Schritte aus dem Kapitel Installation abgeschlossen sind, muss die Basiskonfiguration der best4Automic Module zur Anpassung an die Umgebung durchgeführt werden. Hierfür sind Einstellungen in einer Konfigurationsdatei vorzunehmen und die zu verwendende Java-Laufzeitumgebung festzulegen.

Die Konfiguration der Core Edition und der Rest Edition sind weitestgehend gleich, da sie auf die gleichen Mechanismen aufsetzen. Die Unterschiede der Rest Edition zur Core Edition werden im Abschnitt Rest Edition beschrieben

Basiskonfiguration¶

Im ersten Schritt sollte die zu nutzende Java-Laufzeitumgebung festgelegt werden. Ist direkt die im System installierte und bevorzugte Java-Laufzeitumgebung zu verwenden, dann sind keine Anpassungen notwendig. Muss für best4Automic allerdings eine besondere Java-Laufzeitumgebung genutzt werden, so sollte dies über die Umgebungsvariable JAVA_HOME definiert werden. Die best4Automic Start-Skripte nutzen diese Variable um die richtige Java-Installation zu ermitteln.

Ist die Java-Laufzeitumgebung entsprechend gesetzt kann die Basiskonfiguration für best4Automic erstellt werden. Für jedes einzelne best4Automic Modul kann eine eigene Konfigurationsdatei angelegt werden. Die Namenskonvention für diese Konfigurationsdatei ist <Modul>.conf, wobei <Modul> durch den Namen des jeweiligen Moduls zu ersetzen ist. Sie ist standardmäßig im Unterverzeichnis conf abzulegen. Die Vorgabewerte werden zeilenweise nach dem Format <langer Optionenname>=Wert in diese Datei eingetragen (beispielsweise name=*TEST* oder connection=B4A-1). Ist diese nicht vorhanden werden Vorgabewerte aus der Datei defaults.conf, die genau in genanntem Unterverzeichnis liegt, gelesen. Zusätzlich zu den Voreinstellungen für die Module sind in dieser Datei auch Einstellungen zu finden, die für die grundsätzliche Funktion der Module notwendig sind. Diese werden im Folgenden beschrieben.

Lizenz¶

Vor der Verwendung von best4Automic muss eine entsprechende Lizenz eingespielt werden. Diese kann vom best4Automic Vertrieb bezogen werden. Ausgeliefert wird die Lizenz als ein ZIP-Archiv in dem sich zwei Dateien befinden. Diese beiden Dateien (license.json und license.sig) müssen in das conf-Verzeichnis der best4Automic Installation kopiert werden.

Solange keine Lizenz eingespielt ist können alle best4Automic Module gestartet und konfiguriert werden, nur die Ausführung wird verhindert. Das best4Automic Dashboard sowie best4Automic Setup können weiterhin genutzt werden.

Verbindungen¶

Damit die Module eine Verbindung zu einem oder mehreren Automic Automation Engine^®-Servern aufbauen können, müssen die Verbindungen in der Konfigurationsdatei spezifiziert werden. Dies wird in Form von URLs vorgenommen, die in der Option connections als komma-separierte Liste angegeben werden. Eine URL definiert die folgenden Verbindungsparameter:

Server: IP-Adresse bzw. Name des Automic Automation Engine^®-Servers
Port: Port des CP (Communication Process) für die Verbindung
Umgebung: Name einer in der Konfiguration definierten Umgebung
Mandant: Nummer des Mandanten, zu dem die Verbindung aufgebaut wird
Name: Ein sprechender Name für die Verbindung
Benutzername (zweite Variante): Benutzer, der für die Verbindung genutzt werden soll
Passwort (zweite Variante): Passwort des Benutzers
Abteilung (zweite Variante): Abteilung des Benutzers

Mit diesen Parametern wird die URL wie folgt aufgebaut:

automic://<Server>:<Port>/<Name>#<Mandant>

In der zweiten Variante der URL können auch die Zugangsdaten in der URL angegeben werden:

automic://<Server>:<Port>/<Name>?client=<Mandant>;username=<Benutzername>;department=<Abteilung>;password=<Passwort>

Es können beliebig viele dieser URLs definiert werden, sodass die Verbindungsdaten zu allen existierenden Mandanten vordefiniert werden können. Ein Beispiel für eine Liste mit mehreren Verbindungen ist in der ausgelieferten Konfigurationsdatei enthalten.

connections=automic://10.0.1.130:2217/B4A-1#1, \
    automic://10.0.1.130:2217/B4A-2?client=2;username=writer;department=b4a;password=test1234, \
    automic://172.16.138.128:2217/ORA0#0

Eine weitere Variante der URLs erlaubt es, die Definition des Servers und des Ports auszulagern und durch eine Menge von Transportadressen zu ersetzen. Dies ist dann sinnvoll wenn eine Ausfallsicherheit beim Verbindungsaufbau implementiert werden soll. In den bisher beschriebenen Varianten kann best4Automic immer nur einen CP ansprechen um die Verbindung aufzubauen. Ist dieser aus irgendwelchen Gründen nicht erreichbar, kann das Modul die Verbindung nicht herstellen und somit die gewünschte Funktion nicht ausführen. Damit best4Automic die Möglichkeit hat auf andere CPs auszuweichen, kann eine Liste von CPs definiert werden. Auf diese kann in der URL referenziert werden. Dafür ist in der Konfigurationsdatei ein Eintrag nach dem folgenden Format zu definieren:

servers-<Umgebungsname> = <IP-Adresse oder Name>:<Port>, ...

In den URLs kann dann statt <Server>:<Port> der Ausdruck <Umgebungsname> genutzt werden wie in dem folgenden Format aufgezeigt:

automic://<Umgebungsname>/<Name>?client=<Mandant>;username=<Benutzername>;department=<Abteilung>;password=<Passwort>

Beispiel:

servers-prod = 10.18.99.1:2217, 10.18.99.1:2218, 10.18.99.2:2219, 10.18.99.3:2220
connections = automic://prod/prod10?client=10,username=WRITER,department=B4A,password=--10DJH342HDNDQA

Protokolle¶

Die best4Automic Module können die durchgeführten Aufgaben auf verschiedenen Leveln protokollieren. Dabei wird zwischen zwei Arten unterschieden.

Fortschritt (PROGRESS): Dient als eine Anzeige des Fortschritts der Verarbeitung
Report (REPORT): Ist die eigentliche Protokollierung der durchgeführten Arbeiten

Die Menge der protokollierten Informationen kann über fünf verschiedene Level kontrolliert werden. Dabei können die Level beliebig miteinander kombiniert werden.

ERROR: Wichtige Fehlermeldungen
WARNING: Warnhinweise
INFO: Grundsätzliche Informationen zur Verarbeitung
DEBUG: Erweiterte Informationen (für Entwickler)
TRACE: Protokolliert den Zeitverbrauch von bestimmten Aktionen, beispielsweise von Abfragen vom Automic-Server
JAVA_API: Aktiviert den internen Debugger der Java-API, der weitestgehend die Kommuniaktion mit der Automic Automation Engine^® protokolliert
DATASTREAM: Weitere Details im Kapitel best4Automic Datenströme

Zusätzlich kann der Detailgrad der Protokollierung noch durch Flags beeinflusst werden:

Zeitstempel: Vorangestellte Zeitstempel bei Reportzeilen an- bzw. ausschalten
Zeitmessung: Zusätzliche Ausgabe am Ende über die benötigte Zeit
Sitzung: Details zu der geöffneten Sitzung
Monochrom (Terminal): Ist die Option deaktiviert werden auf UNIX-Terminal Farben verwendet

Alle diese Log-Einstellungen können über Optionen der Module geändert werden.

log-levels: Zum Setzen der Level für die Protokollierung
log-variants: Zum Aktivieren der Fortschrittsanzeige und des Reports
log-flags: Hiermit können Formate und zusätzliche Informationen in den Logs festgelegt werden.

Kodierung der Ausgabe¶

Normalerweise wird für die Ausgabe der Protokolle die Kodierung der Umgebung genutzt, in der best4Automic gestartet wird. Dies ist heutzutage häufig UTF-8. Die Automic Automation Engine^® unterstützt diese Kodierung nicht. Daher kann es notwendig sein, die Kodierung für die Ausgabe unabhängig von der Umgebung zu setzen. Dies kann mit der Option log-encoding getan werden. Hier können die bekannten Kennungen für Kodierungen genutzt werden. Beispiele:

UTF-8
ISO-8859-1
ISO-8859-15

Verhalten im Fehlerfall¶

Wie sich die Module verhalten, wenn ein Fehler auftritt, kann über die Option log-error-mode konfiguriert werden. Dafür stehen drei Modi zur Verfügung:

Niemals: In dem Fall läuft das Modul bis alle Objekte verarbeitet bzw. alle Aufgaben erledigt sind. Nur in Ausnahmefällen wird das Modul mit einem Fehlercode beendet. Dies sind Fehler, die das Modul nicht korrigieren kann oder die ein weiteres Arbeiten unmöglich machen.
Beim ersten Fehler: Wenn bei der Verarbeitung eines Objektes in dem Vorgang ein Fehler auftritt, wird das Modul sofort beendet. Unabhängig davon, ob andere Objekte noch hätten verarbeitet werden können (kein fataler Fehler wie Verbindungsabbruch)
Beim Ende des Vorgangs: Selbst wenn bei mehreren Objekten Fehler auftreten, dann wird das Modul erst mit einem Fehler beendet, wenn das letzte Objekt verarbeitet wurde.

Grafische Oberfläche¶

Jedes der best4Automic Module kann als Kommandozeilenprogramm oder mit einer grafischen Oberfläche verwendet werden. Für einige Funktionen der grafischen Oberfläche muss eine Verbindung ausgewählt sein. Beispielweise für die Auswahl eines Ordners für Operationen.

Einige der Optionen werden in Untergruppen dargestellt, die eingeklappt werden können. Mit der Einstellung gui-bundle-expand kann definiert werden, ob diese Gruppen initial ausgeklappt oder eingefahren sind.

Erweiterte Konfigurationen¶

In diesem Abschnitt werden Konfigurationsmöglichkeiten beschrieben, die sich auf zentrale Einstellungen für die gesamte best4Automic Distribution beziehen. Diese werden über Umgebungsvariablen oder Java-Systemeigenschaften gesetzt. Um die Java-Systemeigenschaft and ie java-Laufzeitumgebung zu übergeben kann die Umgebungsvariable JAVA_OPTS genutzt werden. In den folgenden Abschnitten sind dazu Beispiele zu finden.

Verzeichnisse¶

Die best4Automic Distribution enthält eine vordefinierte Verzeichnisstruktur, die den Standard vorgibt. Jedes dieser Verzeichnisse kann geändert werden. Dafür können Umgebungsvariablen oder Java-Systemeigenschaften genutzt werden, welche im folgenden beschrieben werden.

Umgebungsvariable	Java-Systemeigenschaft	Beschreibung
B4J_BIN_DIR	b4j.binary.directory	Absoluter Pfad zu den Start-Scripten
B4J_LIB_DIR	b4j.library.directory	Absoluter Pfad zu den jar-Bibliotheken und den Metadaten
B4J_DOC_DIR	b4j.documentation.directory	Absoluter Pfad zur Dokumentation
B4J_DATA_DIR	b4j.data.directory	Absoluter Pfad zum Datenverzeichnis, in dem per Vorgabe viele Module ihre Ausgabedateien ablegen
B4J_CONF_DIR	b4j.configuration.directory	Absoluter Pfad zu den Konfigurationsdateien. Sowohl die defaults.conf, modules.conf und die optionalen Modulkonfigurationen werden in dem Ort gesucht. Ist zusätzlich die Umgebungsvariable `B4J_CONF_FILE` gesetzt, dann wird die Modulkonfiguration aus der angegebenen Datei gelesen. Alle anderen Konfigurationen werden weiterhin in dem Verzeichnis `B4J_CONF_DIR` gesucht
B4J_TEMP_DIR	b4j.temp.directory	Absoluter Pfadzu einem Verzeichnis in dem temporäre Dateien abgelegt werden

Beispiel für die Nutzung der Umgebungsvariablen.

export B4J_CONF_DIR = "/applications/configuration/best4Automic"
export B4J_DATA_DIR = "/tmp"
./b4A

Um die Java-Systemeigenschaften zu setzen kann die Umgebungsvariable JAVA_OPTS genutzt werden wie in dem folgenden Beispiel gezeigt wird.

export JAVA_OPTS = "-Db4j.configuration.directory=/applications/configuration/best4Automic -Db4j.data.directory=/tmp"
./b4A

Sprache¶

Unterstützt werden von den Modulen die folgenden Sprachen:

deutsch
englisch

Wenn die best4Automic Module gestartet werden wird die verwendete Sprache anhand der Umgebung bestimmt. Sollte dies nicht die gewünschte Sprache sein, kann diese über die Java-Systemeigenschaft user.language angepasst werden. Die Eigenschaft unterstützt die Werte de und en. Gesetzt wird diese über den Kommandozeilenparameter -D.

export JAVA_OPTS="-Duser.language=de"
./b4A ...

Diese Option kann auch in den Start-Scripten ergänzt werden.

best4Automic Setup¶

Zum Anlegen und Bearbeiten der Verbindungen gibt es eine grafische Oberfläche.

Hier lassen sich die in der defaults.conf hinterlegten Verbindungen und Umgebungen bearbeiten.

Nach dem Hinzufügen, Bearbeiten oder Löschen einer Verbindung oder Umgebung kann der Button Speichern genutzt werden, um die Änderungen in die defaults.conf zu übernehmen. Verlässt man das Setup über den Schließen-Button und es gibt ungespeicherte Änderungen, erscheint eine Rückfrage, ob die Konfiguration vor dem Schließen gespeichert werden soll.

Umgebungen¶

Die Verbindungen benötigen als Grundlage erst einmal Umgebungen. Diese kann man in diesem Bereich bearbeiten. Der Hinzufügen-Button öffnet einen Dialog, in dem der Umgebungsname und die Kommunikationsprozesse angegeben werden können. Der Umgebungsname darf pro best4Automic Installation nur ein Mal vorkommen.

../_images/util-setup-add-environment.png

Durch einen Doppelklick auf eine Zeile der Tabelle öffnet sich ein Dialog zum Ändern der entsprechenden Umgebung.

../_images/util-setup-change-environment.png

Verbindungen¶

Die Umgebungen können nun bei den Verbindungen genutzt werden. Auch hier öffnet der Hinzufügen-Button einen Dialog. Hier lässt sich über ein Dropdown die Umgebung auswählen. Sobald Umgebung und Mandant angegeben sind wird der empfohlene Name für die Verbindung generiert. Dieser lässt sich manuell ändern, wird aber wieder überschrieben, wenn die Umgebung oder der Mandant modifiziert wird. Sobald die Gruppe Anmeldetdaten angeben (hinzufügen) ausgeklappt wird sind die Felder Benutzername und Passwort Pflichtfelder.

Meistens ähneln sich die Verbindungen sehr. Daher lässt sich mit dem Button Duplizieren eine bestehende Verbindung duplizieren und im folgenden Dialog anpassen.

../_images/util-setup-add-connection.png

Durch einen Doppelklick auf eine Zeile der Tabelle öffnet sich ein Dialog zum Ändern der entsprechenden Verbindung.

../_images/util-setup-change-connection.png

Rest Edition¶

Die Rest Edition wird als WAR-Archiv ausgeliefert. Um die Konfiguration zu bearbeiten muss das WAR-Archiv ausgepackt werden. Darin befindet sich wie im Abschnitt REST-API beschrieben eine Verzeichnisstruktur, die der aus der Core Edition ähnelt. Die Dateien im conf-Verzeichnis sind die gleichen. Es gibt eine weitere Konfigurationsdatei mit dem Namen api.json. Dort werden Einstellungen für die REST-API vorgenommen, die im folgenden beschrieben werden.

rest.auth.basic: Schaltet die Basic Authentisierung ein oder aus
rest.auth.groups.execute: Name der Benutzergruppe, der ein Benutzer angehören muss, um zusätzlich zu GET auch POST-oder DELETE-Anfragen gegen die RESTful-API zu senden
rest.auth.groups.read: Name der Benutzergruppe, der ein Benutzer angehören muss, um GET-Anfragen gegen die RESTful-API zu senden
rest.auth.connection: b4A-Verbindung, in der die Authentisierung und Authorisierung stattfindet
rest.cors.origin: Legt fest welche entfernten Server auf die Daten der RESTful-API zugreifen dürfen. Diese Einstellung dient zur Unterstützung von CORS (Cross-Origin Resource Sharing)

Zusätzlich kann eine weitere Einstellungen in der application.properties angepasst werden. Diese befindet sich in dem Verzeichnis WEB-INF/classes.

spring.jpa.properties.hibernate.show_sql: Legt fest, ob die SQL-Statements in den Tomcat Protokollen aufgezeichnet werden sollen

Bei allen Änderungen an Konfigurationen muss der Tomcat neu gestartet werden, damit die Änderungen herangezogen werden.