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_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 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.

_images/util-setup-overview.png

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 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>