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://ae21.b4a.local:2217/B4A-1#1, \
automic://ae21.b4a.local:2217/B4A-2?client=2;username=writer;department=b4a;password=test1234, \
automic://ae21.b4a.local: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 = ae21-1.b4a.local:2217, ae21-1.b4a.local:2218, ae21-2.b4a.local:2219, ae21-2.b4a.local:2220
connections = automic://prod/prod10?client=10,username=WRITER,department=B4A,password=--10DJH342HDNDQA
Sollte die Automation Engine ein Zertifikat nutzen, dass durch die systemweiten CA-Zertifikate nicht verifiziert werden kann muss b4A das Verzeichnis bekannt gegeben werden in dem das richtige Zertifikat zu finden ist. Dafür kann die Einstellung certificate-directory genutzt werden. Hier muss das Verzeichnis angegeben werden in dem das notwendige CA-Zertifikat im PEM Format zu finden ist. Im folgenden Beispiel würden die Zertifikate in einem Ordner certs gesucht werden, der sich im Basisordner der b4A-Installation befindet.
certificate-directory = ../certs
Diese Einstellung kann durch die System-Eigenschaft b4j.cert.directory überschrieben werden.
Wiederaufbau von Verbindungen
Für den Fall, dass eine geöffnete Verbindung abbricht, beispielsweise durch das plötzliche Wegfallen des JCPs, versucht best4Automic diese Verbindung wiederherzustellen. Zwischen zwei Wiederherstellungsversuchen verdoppelt sich die Zeit bis zum nächsten Versuch. Beginnend mit 500 Millisekunden. Die maximale Dauer zwischen zwei Versuchen kann, genau wie die maximale Anzahl der Versuche, konfiguriert werden. Dafür dienen die folgenden beiden Einstellungen:
max-reconnect-attempts = 10
max-reconnect-wait-time = 60000
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 Kommunikation 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_TEMP_DIR |
b4j.temp.directory |
Absoluter Pfad zu einem Verzeichnis in dem temporäre Dateien abgelegt werden |
b4j.cert.directory |
Pfad zu einem Verzeichnis in dem Zertifikate abgelegt sind, die für die verschlüsselte Verbindung zur Automation Engine benötigt werden |
|
B4J_SCRIPT_DIR |
b4j.script.directory |
Absoluter Pfad zu einem Verzeichnis in dem b4A Groovy Script Dateien abgelegt werden |
B4J_CUSTOM_COMPLIANCE_DIR |
b4j.custom.compliance.directory |
Absoluter Pfad zu einem Verzeichnis in dem kundenspezifische Compliance Tests abgelegt werden können. Diese werden in Form von b4A Compliance Test Distributions ausgeliefert. |
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.
Durch einen Doppelklick auf eine Zeile der Tabelle öffnet sich ein Dialog zum Ändern der entsprechenden Umgebung.
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.
Durch einen Doppelklick auf eine Zeile der Tabelle öffnet sich ein Dialog zum Ändern der entsprechenden Verbindung.
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 b4A RESTful API vorgenommen, die im folgenden beschrieben werden.
rest.fileUploadDirectory: Legt das Verzeichnis fest, in dem Dateien abgelegt werden, die über den Endpunkt /file/upload hochgeladen werden. Ist die Option nicht gesetzt oder das angegebene Verzeichnis nicht vorhanden wird auf das Data-Verzeichnis der b4A RESTful API-Installation zurückgegriffen.
rest.enableServiceEndpoints: Legt fest, ob die XML-Konfiguration geladen wird und die Service Endpunkte erreichbar sind
rest.log.levels: Log-Level der b4A RESTful API
rest.log.flags: Hiermit können Formate und zusätzliche Informationen in den Logs festgelegt werden
rest.auth.type: Legt die Authentisierungsmethode fest. Kann Basic oder Token sein
rest.auth.token.secret: Schlüssel für die Erzeugung des Tokens. Dieser muss mindestens 512 Bits lang sein.
rest.auth.token.issuer: Herausgeber des Tokens
rest.auth.token.ttl: Gültigkeitsdauer des Tokens in Minuten
rest.auth.status.token: Token für das Senden einer Meldung aus der Automation Engine mithilfe der mitgelieferten Action und für die beiden mitgelieferten Services
rest.auth.groups.module: Name der Benutzergruppe, der ein Benutzer angehören muss, um zusätzlich zu GET auch POST-Anfragen gegen die b4A RESTful API zu senden
rest.auth.groups.info: Diese Benutzergruppe darf nur GET-Anfragen gegen die b4A RESTful API senden. Ausgenommen sind Anfragen an den Service-Bereich.
rest.auth.groups.service: Benutzergruppe, um GET- und POST-Anfragen gegen die b4A RESTful API zu senden. Ausgenommen sind die Admin-Anfragen und das Senden von Meldungen aus der Automation Engine
rest.auth.groups.admin: Die hier hinterlegte Benutzergruppe darf alle Anfragen gegen die b4A RESTful API senden. Ausgenommen ist nur das Senden von Meldungen aus der Automation Engine
rest.auth.connection: b4A-Verbindung, in der die Authentisierung und Authorisierung stattfindet. Diese Verbindung kümmert sich außerdem um viele lesende Operationen sowie Änderungen an der XML-Konfiguration durch b4A RESTful API-Administratoren.
rest.service.configuration: Legt den Namen der XML-Vara fest, in der die Konfiguration der Rollen und Services abgelegt sind
rest.cors.origin: Legt fest welche entfernten Server auf die Daten der b4A RESTful API zugreifen dürfen. Diese Einstellung dient zur Unterstützung von CORS (Cross-Origin Resource Sharing)
rest.performance.parallel.service: Begrenzt global für die b4A RESTful API die parallelen Anfragen an die Automation Engine für die Liste der Aktivitäten. Hier kann angegeben werden, für wie viele Services parallel Anfragen geschickt werden können.
rest.performance.parallel.instance: Begrenzt global für die b4A RESTful API die parallelen Anfragen an die Automation Engine für die Liste der Aktivitäten. Hier kann angegeben werden, für wie viele Instanzen von Services parallel Anfragen geschickt werden können.
rest.performance.cache.maxObjects: Begrenzt die Anzahl der in den internen Caches hinterlegten Automic Objekte
rest.performance.cache.defaultValidTime: Begrenzt die Zeit in Millisekunden, die ein Objekt im Cache bleibt
rest.performance.monitoring.externalCheckInterval: Legt fest, in welchen Abständen nach Ausführungen von Services geprüft werden soll, die außerhalb des b4A Service Portal aufgerufen werden und als TaskFilter in der Konfiguration none hinterlegt haben. Services, die über das Attribut isPassive mit true als passiv gekennzeichnet sind, haben automatisch den TaskFilter none. Auch dann, wenn das Attribut anders gesetzt wurde. Wird eine solche Instanz gefunden, werden die dafür authorisierten Benutzer im b4A Service Portal über den Start informiert und die Ausführung erscheint in der Übersicht. Die regelmäßige Überprüfung kann die Last auf der Automation Engine maßgeblich erhöhen. Daher wäre auch eine Option die Zeit beispielsweise auf fünf Minuten zu erhöhen. Services mit einer geringeren Laufzeit sollten dabei nach dem Ende nicht automatisch deaktivieren, damit sie in der Liste der Ausführungen im b4A Service Portal auftauchen, auch wenn zwischen Start und Ende des Services keine Überprüfung gelaufen ist. Die Zeit ist in Millisekunden anzugeben.
Zusätzlich können 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 Apache Tomcat ® Protokollen aufgezeichnet werden sollen
spring.servlet.multipart.max-file-size: Legt die maximale Größe einzelner Dateien fest, die über eine multipart/form-data-Anfrage geschickt werden können. Dies beschränkt die Größe der Dateien, die über den Endpunkt /file/upload geschickt werden können und ist standardmäßig auf 10MB eingestellt.
spring.servlet.multipart.max-request-size: Legt die Gesamtgröße der Anfrage für eine multipart/form-data-Anfrage fest, die theoretisch aus mehreren Dateien bestehen kann. Dies ist relevant für die Gesamtgröße der Anfrage über den Endpunkt /file/upload.
Bei allen Änderungen an Konfigurationen muss der Apache Tomcat ® neu gestartet werden, damit die Änderungen herangezogen werden.
Auslagern von Verzeichnissen
Mithilfe des Java Naming and Directory Interfaces (JNDI) können die Verzeichnisse zu den jar-Bibliotheken und den Metadaten (lib-Verzeichnis), dem Konfigurationsverzeichnis (conf) und dem Standard Datenverzeichnis (data) ausgelagert werden.
Im Tomcat muss dazu beispielweise eine Konfigurationsdatei unter <CATALINA_HOME>/conf/Catalina/<hostname>/<war-name>.xml mit folgendem Inhalt abgelegt werden:
<Context>
<Environment name="b4j.configuration.directory" value="C:/Pfad/zum/conf/verzeichnis/" type="java.lang.String"/>
<Environment name="b4j.library.directory" value="C:/Pfad/zum/lib/verzeichnis/" type="java.lang.String"/>
<Environment name="b4j.data.directory" value="C:/Pfad/zum/data/verzeichnis/" type="java.lang.String"/>
</Context>