b4A Packages

Mit best4Automic (b4A) werden Objekte für die Automation Engine ausgeliefert. Die Objekte werden in sogenannten b4A Packages organisiert. Sie dienen der Steuerung von b4A Modulen aus der AE heraus und bieten hilfreiche Objekte, die den Umgang mit b4A in der Automation erleichtern.

Das Format der b4A Packages ähnelt dem Format des Automic Package Managers. An dieser Stelle wird auf das Kapitel Package Management im Benutzerhandbuch verwiesen.

Die nachfolgende Auflistung beschreibt die standardmäßige Ordnerstruktur eines b4A Packages:

Ordner

Beschreibung

ACTIONS

Dieser Ordner enthält generische Objekte, die an verschiedenen Stellen eingebunden werden können.

CONFIG

Dieser Ordner enthält die Konfigurationsvariablen, die für den Betrieb des b4A Package notwendig sind und angepasst werden können.

DOCUMENTATION

Dieser Ordner enthält allgemeine Dokumentation des b4A Package.

SERVICES

Dieser Ordner enthält vorbereitetete und ausführbare Objekte die Konfigurationen erleichtern oder Funktionen bereitstellen.

SOURCE

Dieser Ordner enthält alle Objekte, die bei den Actions und Services verwendet werden.

TEST

Dieser Ordner enthält die Cucumber/Gherkin Testspezifikationen. An dieser Stelle wird auf das Kapitel der Test Automation im Benutzerhandbuch verwiesen.

Hinweis: Leere Ordnern werden nicht mit exportiert und werden dementsprechend bei der Installation auch nicht erstellt.

In den nachfolgenden Kapiteln wird das b4A Package PCK.BEST4AUTOMIC_BASE detaillierter beschrieben.

Installation eines b4A Packages

b4A Packages können mit dem b4A Modul pm.Install per Kommandozeile oder per grafischer Obfläche installiert werden. Die Installation wird nachfolgend beschrieben. Weitere Informationen zum Modul pm Install sind unter Package: Installiere zu finden.

Installation per Kommandozeile

Die b4A Packages sind mit dem b4A-Modul pm.Install zu installieren. Für die Installation müssen folgende Parameter angegeben werden.

  • connection (-C): Verbindung zum Mandanten, auf dem das b4A Package installiert werden soll.

  • package: Name des b4A Package

  • zip-file: Speicherort des b4A Package auf dem lokalen Betriebsystem

Allgemein sieht der Befehl zum Installieren wie folgt aus:

./b4A pm.Install -C <Verbindung> --package <Package-Name> --zip-file <Speicherort>

Hinweis: Für weitere Informationen lesen Sie bitte das Kapitel „Package Management“.

Zur Installation des b4A Package kann folgender Befehl verwendet werden:

Beispiel unter Unix:

./b4A pm.Install -C <Verbindung> --package PCK.BEST4AUTOMIC_BASE --zip-file PCK.BEST4AUTOMIC_BASE.zip

Beispiel unter Windows:

.\b4A.bat pm.Install -C <Verbindung> --package PCK.BEST4AUTOMIC_BASE --zip-file PCK.BEST4AUTOMIC_BASE.zip

Nach der erfolgreicher Installation sind die b4A Packages unterhalb des Ordners PACKAGES zu finden. Bevor die Workflows genutzt werden können, muss das b4A Package konfiguriert werden. Die Konfiguration wird in den Kaptiteln der einzelnen b4A Packages erläutert.

Um die Installation im grafischen Modus durchzuführen kann die Option -X zum Befehl hinzugefügt werden. Diese Option öffnet einen grafischen Dialog.

Installation per grafischer Oberfläche

Die Installation lässt sich auch mit der grafischen Oberfläche durchführen. Wenn sie das Package per Kommandozeile installiert haben, können sie diesen Abschnitt überspringen.

  1. Starten von b4A

  • Navigation ins Verzeichnis /<Installationsverzeichnis>/bin bzw. unter Windows <Laufwerk>:<Installationspfad>bin

  • Starten von b4A bzw. unter Windows b4A.bat

  1. Modul Package: Installieren (pm.Install) öffnen

  2. Parameter eingeben

  • Verbindung auswählen (unter dem Reiter Zugangsdaten)

  • Namen vergeben (unter dem Reiter Optionen)

  • Zip-Datei auswählen (unter dem Reiter Optionen)

Nach der erfolgreicher Installation sind die b4A Packages unterhalb des Ordners PACKAGES zu finden. Bevor die Workflows genutzt werden können, muss das b4A Package konfiguriert werden. Die Konfiguration wird in den Kaptiteln der einzelnen b4A Packages erläutert.

PCK.BEST4AUTOMIC_BASE

Das b4A Package PCK.BEST4AUTOMIC_BASE ist das wichtigste Package, um die mitgelieferten Objekte und anderen b4A Packages zu verwenden. Es liefert zentrale Objekte für das Starten von b4A Modulen in Automationsprozessen. Zusätzlich stellt es die Basis für den Betrieb weiterer b4A Packages bereit.

Im Nachfolgenden wird die Struktur des Package erläutert:

Installation

An dieser Stelle wird auf die Installationsanleitung unter Installation eines b4A Packages verwiesen.

Konfiguration

Die Konfiguration des b4A Package erfolgt über Variablen-Objekte, welche in dem Unterordner PCK.BEST4AUTOMIC_BASE/CONFIG/ liegen.

Die Basiskonfiguration ist in dem Objekt PCK.BEST4AUTOMIC_BASE.VARA.SETTINGS zu finden.

  • DEFAULT_CONNECTION: Die Voreinstellungen bei der Auswahl einer Verbindung

    B4A-1

  • SQL_CONNECTION: Ein SQL-Verbindungsobjekt für die SQL-Variablen in diesem Package. Dafür wird eine lesende Verbindung zur Automation Engine-Datenbank benötigt.

    CONN.AE_DB_READONLY

  • SQL_OWNER: Wenn der Datenbank-Benutzer in der SQL-Verbindung nicht der Besitzer ist dann kann in dieser Einstellung der Besitzer gefolgt von einem Punkt angegeben werden.

    uc4.

  • DATABASE: Die mitgelieferten SQL-Statements zum Abfragen von Informationen werden für die Oracle Datenbank, PostgreSQL und für den Microsoft SQL Server bereitgestellt. Mit dieser Option wird definiert welcher Datenbank-Server in der Umgebung eingesetzt wird. Für eine Oracle Datenbank ist der Wert ORACLE und für den Microsoft SQL Server der Wert MSSQL einzutragen und für einen PostgreSQL Server der Wert POSTGRES.

    ORACLE

  • AGENT: Der zu verwendende Agent

  • BIN_DIR: bin-Verzeichnis von best4Automic

  • LOGIN: Das LOGIN-Objekt für best4Automic Jobs

In dem Variable-Objekt PCK.BEST4AUTOMIC_BASE.VARA.CONNECTIONS werden die auswählbaren Verbindungen eingetragen. Dabei muss der Name der Verbindung sowohl im Key als auch im ersten Wert eingetragen werden. Die Befüllung der Variable kann mit dem Modul util.ConnectionsSaveTo durchgeführt werden (siehe b4A Verbindungen: Speichern).

Um die Optionen zu beeinflussen, mit denen die Module gestartet werden, kann das Variablen-Objekt PCK.BEST4AUTOMIC_BASE.VARA.CONFIG#BASIC angepasst werden. In der Auslieferung sind hier die Optionen für die Log-Einstellungen zu finden. In der Regel können diese Optionen übernommen werden.

  • log-levels: Die zu aktivierenden Log-Level

    INFO,WARNING,ERROR

  • log-variants: Die zu aktivierenden Log-Varianten. Auf PROGRESS sollte hier verzichtet werden, da es in den Job-Reports nichts lesbar ist

    REPORT

  • log-flags: Die zu aktivierenden Log-Flags. Um die Zeitstempel zu entfernen, muss der Wert auf -TIMESTAMP gesetzt werden

    TIMESTAMP,TIMEKEEPING,SESSION,MONOCHROME

  • log-encoding: Setzt die Kodierung der Ausgabe im Report. Da die Automation Engine kein UTF-8 unterstützt wird hier eine andere Kodierung erzwungen

    ISO-8859-15

  • log-error-mode: Hiermit wird das Verhalten im Fehlerfall festgelegt

    on-progress-finished

Des weiteren kann es notwendig sein, die SQL-Variablen anzupassen. Aktuell werden einige SQL-Variablen als SQL von den b4A Packages eingesetzt. Je nach Einstellungen der Automation Engine können in der Umgebung eventuell keine SQL-Variablen genutzt werden. In dem Fall müssen die Variablen vom gewünschten Typ (SQLI, SEC_SQLI oder SEC_SQL) neu unter dem gleichen Namen angelegt werden. Zuvor müssen die SQL-Variablen umbenannt werden, da diese aktuell diese Namen haben.

Starten von b4A-Modulen

Ist die Konfiguration der Objekte abgeschlossen, können die Objekte des Package genutzt werden um b4A Module zu starten. In diesem b4A Package sind einige Vorlagen enthalten, die Vorgaben liefern wie mit den Objekten b4A Module gestartet werden können.

Für das Starten von b4A Modulen gibt es drei Phasen. In der ersten wird die Konfiguration für den Aufruf erzeugt. In der zweiten wird das b4A-Modul ausgführt und in der letzten Phase werden die Ergebnisse des Laufs ausgewertet. Im folgenden werden die Include-Objekte für die einzelnen Phasen genauer beschrieben. Alle diese Include-Objekte sind plattform-unabhängig.

Phase 1 - Konfiguration

Die Konfiguration wird mit drei Include-Objekten erzeugt, geschrieben und nach der Ausführung wieder gelöscht.

PCK.BEST4AUTOMIC.BASE.JOBI.CONFIG_CREATE

Dieses Include-Objekt erzeugt in Abhängigkeit von dem gesetzten Modus (CONFIG_MODE) eine Konfigurationsdatei oder Variable.

PCK.BEST4AUTOMIC.BASE.JOBI.CONFIG_ADD ENTRY = "<Key>=<Value>"

Mit diesem Include-Objekt wird ein neuer Konfigurationseintrag hinzugefügt.

PCK.BEST4AUTOMIC.BASE.JOBI.CONFIG_REMOVE

Nach der Ausführung des b4A-Moduls sollte die Konfiguration wieder entfernt werden. Dies wird durch dieses Include-Objekt durchgeführt.

Einige Optionen von b4A Modulen bekommen eine Datei übergeben. Die Inhalte werden bei der Ausführung in der Automation öfter in temporären Dateien gehalten. Um diese zu erzeugen werden einige Include-Objekte mitgeliefert.

PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_START

Dieses Include-Objekt definiert den Start des Inhalts einer temporären Datei.

PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_END

Dieses Include-Objekt definiert das Ende des Inhalts einer temporären Datei.

PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_DELETE

Dieses Include-Objekt löscht die temporäre Datei.

Der Name der temporären Datei steht in der Script-Variable &temp_file#.

Wenn der Inhalt der temporären Datei aus einem Variable-Objekt gelesen wird, dann kann dies mit den folgenden beiden Include-Objekten vereinfacht werden. Dabei wird den Include-Objekten eine Ersetzungsregel übergeben:

VARACOL = „<Variablen-Objekt>[:<Spalte>[,<Spalte 2>]]“

PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_VARA

Dies Include-Objekt liest aus einem Variablen-Objekt die angegebene Spalte aus und schreibt jeden Wert in eine Zeile der temporären Datei.

PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_VARA#2COLUMNS

Dies Include-Objekt liest zwei Spalten aus dem Variablen-Objekt und schreibt die Werte getrennt durch ein Semikolon in jeweils eine Zeile.

Beispiele:

:inc PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_START
Dies ist
der Inhalte
der temporären Dateien
:inc PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_END

:p "Der Text steht jetzt in der Datei &temp_file#"

:p "Löschen der temporären Datei"

:inc PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_DELETE

:inc PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_VARA VARACOL = "PCK.B4A_TEST.VARA.VALUES:3"
:p "Der Inhalt der Spalte drei steht jetzt in der Datei &temp_file#"

:inc PCK.BEST4AUTOMIC.BASE.JOBI.TEMPFILE_VARA#2COLUMNS VARACOL = "PCK.B4A_TEST.VARA.VALUES:1,2"
:p "Der Inhalt des Key und der Spalte 2 (1. Wert) steht jetzt in der Datei &temp_file#"

Phase 2 - Ausführung

Zusätzlich zu der zuvor beschriebenen Technik um dynamische Konfigurationen zu erzeugen können auch statische Variablen erzeugt werden, die den Modulen als zusätzliche Konfiguration übergeben werden können. Diese Variablen müssen dem Namenschema PCK.BEST4AUTOMIC_BASE.VARA.CONFIG#<Name> folgen. <Name> wird dabei durch eine beliebige Zeichenkette ersetzt. Um diese Konfigurationen an ein Modul beim Aufruf zu übergeben, können diese als Parameter an das Include-Objekt für den Aufruf übergeben werden.

:inc PCK.BEST4AUTOMIC.BASE.JOBI.RUN MODULE = "<Module>:<Name>,..."

Soll keine statische Konfiguration übergeben werden, dann kann das Modul wie folgt gestartet werden.

:inc PCK.BEST4AUTOMIC.BASE.JOBI.RUN MODULE = "<Module>"

Beispiele:

:inc PCK.BEST4AUTOMIC.BASE.JOBI.RUN MODULE = "ObjectSearch:BASIC"
:inc PCK.BEST4AUTOMIC.BASE.JOBI.RUN MODULE = "ObjectSearch"
:inc PCK.BEST4AUTOMIC.BASE.JOBI.RUN MODULE = "ObjectSearch:BASIC,FOLDER"

Phase 3 - Auswertung

Sollte ein b4A Modul in einen Fehler laufen, dann wird ein entsprechender Exit-Code verwendet. Damit dieser auch vom Job verwendet wird kann das Include-Objekt PCK.BEST4AUTOMIC_BASE.JOBI.EXIT genutzt werden. Wird dieses Objekt eingesetzt ist die Verwendung des Include-Objekts PCK.BEST4AUTOMIC_BASE.JOBI.CONFIG_REMOVE nicht notwendig, da diese Funktionalität inkludiert ist.

Ist der Lauf erfolgreich gewesen, kann im Post-Script mit dem folgenden Include-Objekt das Ergebnis der letzten Fortschrittsanzeige ausgelesen werden. Damit kann ermittelt werden wie viele Objekte erfolgreich bearbeitet worden sind, wie viele fehlgeschlagen sind und wie viele ignoriert worden sind.

:include PCK.BEST4AUTOMIC_BASE.JOBI.PROCESS_RESULTS

:p "success: &success#"
:p "failed : &failed#"
:p "ignored: &ignored#"

Alternative: Action

Die zuvor beschriebenen Include-Objekte werden von der generischen Action PCK.BEST4AUTOMIC_BASE.JOBP.RUN genutzt. Im PromptSet werden die Parameter Modulname, Verbindung und die Optionen für das Modul abgefragt. Letztere werden in einem mehrzeiligen Textfeld eingegeben. Zusätzlich gibt es noch zwei Actions, die Optionen unterstützen, denen eine Datei mit Eingabedateien übergeben werden müssen. Dabei kann der Inhalt der Datei aus einer Variable ausgelesen werden oder aus einer Zeichenkette erzeugt werden.

PCK.BEST4AUTOMIC_BASE.JOBP.RUN#LOGIN

Mit dieser Action ist es möglich Zugangsdaten aus einem LOGIN-Objekte zu lesen. Dies kann für den Benutzer für die Verbindung zur AutomationEngine genutzt werden oder beispielsweise auch für den Benutzer eines Versionskontrollsystems.

PCK.BEST4AUTOMIC_BASE.JOBP.RUN_WITH_VARA_PARAMETER

Mit dieser Action kann für eine Option eine Variable definiert werden aus der eine temporäre Datei erzeugt wird. Entweder werden die Einträge einer Spalte untereinander in die Datei geschrieben oder es kann optional eine zweite Spalte angegeben werden. In diesem Fall werden die beiden Werte in eine Zeile geschrieben mit einem Semikolon getrennt.

PCK.BEST4AUTOMIC_BASE.JOBP.RUN_WITH_STR_PARAMETER

Mit dieser Action kann für eine Option eine Zeichenkette angegebenen werden, die in eine temporäre Datei geschrieben wird. Der Name der Datei wird an die Option übergeben.

Alle Actions können sowohl auf Unix als auch unter Windows genutzt werden, da sie generische Jobs nutzen. Die Implementierung für Windows in dem generischen Job nutzt Batch. Dies ist die auf allen unterstützen Windows-Systemen vorhandene Schnittstelle. Allerdings ist diese schon älter und hat einige Schwächen, die sich beispielsweise auf die Verwendung von einigen Sonderzeichen beziehen. Als Alternative werden daher Actions mitgeliefert, die ausschließlich für Windows-System genutzt werden können und auf die Powershell aufsetzen. Diese moderne Schnittstelle ist noch nicht auf allen Windows-Systemen verfügbar bzw. in sehr alten Versionen verfügbar. Die Actions benötigen mindestens die Powershell 5.0, die auf älteren Windows im Standard nicht installiert ist. Hier müsste für die Nutzung der Action erst eine Aktualisierung durchgeführt werden. Die Actions funktionieren genauso wie die zuvor beschriebenen und haben am Ende des Objektnamen noch die Kennung #PS1.

../_images/ae-objects-base-action.png

b4A Einstellungen

Um die getroffenen Einstellungen für b4A zu lesen muss nicht direkt auf die Variable PCK.BEST4AUTOMIC_BASE.VARA.SETTINGS zugegriffen werden. Dafür gibt es das Include-Objekt PCK.BEST4AUTOMIC_BASE.JOBI.VARIABLES. Es liest die entsprechenden Einstellungen und erzeugt Script-Variablen mit den Werten.

Agents und Logins

Um automatisch den Agent und das Login-Objekt zu setzen kann das Include-Objekt PCK.BEST4AUTOMIC_BASE.JOBI.genutzt werden. Es nutzt ebenfalls das Include-Objekt PCK.BEST4AUTOMIC_BASE.JOBI.VARIABLES im die Einstellungen zu lesen.

Ist in den Einstellungen für den Agent eine Agentengruppen gesetzt, dann löst dieses Include-Objekt die Gruppe selbstständig auf. Damit bei Workflows, die mehrere b4A Module starten immer der gleiche Agent genutzt wird hat das Include-Objekt einen Mechanismus um dies sicherzustellen.

Eine weitere Funktion, die das Include-Objekt mitbringt, ist das Überschreiben der Standard b4A Verbindung. Ist die Objekt-Variable &B4A_OVERWRITE_CONNECTION# gesetzt, dann wird die Script-Variable &B4A_DEFAULT_CONNECTION# auf diesen Wert gesetzt anstelle des Wertes aus den Einstellungen. In dem Fall wird zusätzlich die Script-Variable &B4A_LOCAL_CONNECTION# angelegt, die die ursprüngliche Standard b4A Verbindung enthält.