Package Management

Package Management

Bei der Entwicklung von neuen Prozessen in der Automation Engine ist es für Entwickler hilfreich, wenn bestimmte Versionen gesichert werden können. Dies ist beispielsweise dann hilfreich wenn Entwickler neue Versionen der Prozesse mit neuen Fähigkeiten implementieren und zwischen drin eine Korrektur für die Produktionsversion erstellen müssen.

Ist eine Entwicklung abgeschlossen müssen die fertigen Versionen „eingefroren“ werden, so dass diese zu jeder Zeit wiederhergestellt und in andere Umgebungen installiert werden können. Dafür ist das Konzept von Releases aus der Softwareentwicklung bekannt. Auch hierfür werden durch best4Automic Module bereitgestellt.

Definitionen

Das Thema Package Management vereint den Bereich der Automation mit der Softwareentwicklung. Dafür werden Begriffe aus beiden Bereichen benötigt und zusätzliche neuer definiert. Im folgenden werden diese Begriffe definiert um die Ideen und Funktionen der Module besser verstehen zu können.

Packages

Unter dem Begriff Package wird eine Sammlung von Objekten verstanden, die in einem Verzeichnis liegen und dabei einer definierten Ordnerstruktur unterliegen. Diese Definition basiert auf den Automic Action Packs, die vom Automic Package Manager unterstützt werden.

Die Packages des Automic Package Manager liegen unterhalb des Ordners PACKAGES. Pro Package wird in diesem Verzeichnis ein Ordner angelegt. Unterhalb dieses Ordners liegen die Objekte, die Teil des Package sind. Dies sind nur Teile der Definition der Automic Packages. Sie bilden das Grundgerüst für die Arbeitsweise dieser b4A Module. Die weiteren Strukturen unterhalb der Package-Ordner sind für diese Module nur teilweise relevant. Alles was unterhalb eines solchen Ordners liegt wird als Teil des Package angesehen.

Bei der Erstellung von Releases von Packages werden die Objekte in dem Unterordner CONFIG besonders behandelt. Alle statischen Variablen sind Konfigurationsvariablen von denen es einige besondere gibt.

  • Endet der Name einer solchen Variable mit #RUNTIME, dann wird diese als Laufzeitvariable betrachtet.

  • Endet der Name einer solchen Variable mit @TEMPLATES@ definiert diese zu registrierende Templates.

  • Endet der Name einer solchen Variable mit @SCHEDULE@

  • Beinhaltet der Name die Zeichenkette „$$$“ wird die als Konfigurationsobjekt für einen bestimmten Mandanten oder eine bestimmte Umgebung genutzt.

Für die Umgebungs- und Mandanten-spezifischen Konfigurationsobjekte gelten folgende Regeln.

  • <Objektname>$$$<Umgebungsname>: Der Umgebungsname muss einer Server-Definition in der defaults.conf entsprechen. In dem Fall wird diese Konfigurationsvariable als <Objektname> installiert wenn das Ziel in der Umgebung <Umgebungsname> liegt

  • <Objektname>$$$<b4A Verbindungsname>: Entspricht der Zielmandant der Installation dem Namen der b4A Verbindung <b4A Verbindungsname>, dann wird dieses Konfigurationsobjekt als <Objektname> installiert.

  • Gibt es für ein Konfigurationsobjekt <Objektname> weder ein Umgebungs- noch Mandanten-spezifische Konfigurationsobjekt, wenn wird das Objekt <Objektname> verwendet. Diese muss immer existieren, da ansonsten auch die anderen beiden Objekte nicht erkannt werden.

Der Inhalt der Packages bzw. der Aufbau kann sich zwischen den Versionen von best4Automic unterscheiden, da auch das Format weiterentwickelt wird. Dafür gibt es den Packages ab der Format-Version 2 eine zusätzliche Datei package.info, die solche Informationen enthält. Welche Package Format-Versionen unterstützt werden ist in der folgenden Liste festgehalten:

Format Version

Besonderheit

1

Alle Konfigurationsvariablen werden als CSV-Dateien gespeichert

2

Die Datei package.info ist in jedem Package enthalten und enthält die Format-Version; Konfigurationsvariablen werden als XML-Dateien gespeichert

3

Die Datei package.info wurde um weitere Informationen ergänzt, wie beispielsweise den Objektnamen der Metadaten-Variable

4

Mit dieser Version werden mehrere Basisordner für Packages unterstützt

Jeder Release eines Package wird mit einer Versionsnummer versehen. Diese sind drei- oder vierstellig und jede Komponente wird durch einen Punkt von den anderen getrennt (bis auf die letzte Stelle).

X.Y.Z oder X.Y.Z-N

Dieses Versionssystem ist im Bereich der Software-Entwicklung weit verbreitet und wird auch Semantic Versioning genannt. Die Komponenten der Versionsnummer sind wie folgt zu interpretieren.

  • X (Major-Version): Wird diese Komponente erhöht, dann wurden in dem Package Änderungen durchgeführt, die inkompatibel zu vorherigen Versionen sind.

  • Y (Minor-Version): Wird diese Komponente erhöht, dann wurden in dem Package Änderungen durchgeführt, die neue Funktionen mitbringen, aber dabei nicht die Kompatibilität zu vorherigen Versionen beeinflussen.

  • Z (Revision- oder Korrektur-Version): Wird diese Komponente erhöht, dann wurden in dem Package Änderungen durchgeführt, die ausschließlich Korrekturen sind und somit keine neuen Funktionen oder Inkompatibilitäten enthalten. Wird keine vierte Stelle verwendet, dann werden auch Konfigurationsänderungen mit dieser Stelle angegeben.

  • N (Konfigurationsänderung-Version): Wird diese vierte Stelle genutzt, dann werden ausschließlich Änderungen in der Konfiguration damit gekennzeichnet.

Abhängigkeiten

Packages können Abhängigkeiten auf andere Packages haben. Das bedeutet, dass die Objekte eines Packages, auf die Objekte eines anderen Package zugreifen. Beispielsweise können Include-Objekte für häufig vorkommende Aufgaben von einem Package zur Verfügung gestellt werden und diese werden von vielen anderen Objekten aus anderen Packages genutzt. Damit diese Abhängigkeit klar definiert ist und leicht zu erkennen ist wird die Information zu Abhängigkeiten in der Metadaten-Variable gespeichert. Dafür existiert der Eintrag Dependencies.

Für die Angabe der Abhängigkeiten in der Metadaten-Variable ist ein vordefiniertes Format zu verwenden, dass sich wie folgt zusammensetzt.

<Package-Name> <Vergleichsoperator> <Versionsmuster>

Hängt ein Package von mehreren anderen ab so können durch Komma oder Semikolon getrennt weitere Abhängigkeitsdefinitionen eingetragen werden.

PCK.BEST4AUTOMIC_BASE ~> 1.4.0;PCK.BEST4AUTOMIC_DEMO >= 2.0.0

Als Vergleichsoperatoren stehen folgende zur Verfügung:

>= : Die Version des Package muss genau der angegeben Version entsprechen oder größer sein

  • 1.8.0 >= 2.0.0 -> falsch

  • 1.8.20 >= 2.0.0 -> falsch

  • 2.0.0 >= 2.0.0 -> richtig

  • 5.1.0 >= 2.0.0 -> richtig

<= : Die Version des Package muss genau der angegeben Version entsprechen oder kleiner sein

  • 1.8.0 <= 2.0.0 -> richtig

  • 1.8.20 <= 2.0.0 -> richtig

  • 2.0.0 <= 2.0.0 -> richtig

  • 2.1.2 <= 2.0.0 -> falsch

~> : Die Version des Package muss der angegebenen Version entsprechen, d.h. alle Stellen ungleich Null müssen gleich sein. Nur die Stellen mit einer Null müssen größer sein.

  • 1.3.0 ~> 1.4.0 -> falsch

  • 1.4.0 ~> 1.4.0 -> falsch

  • 1.4.1 ~> 1.4.0 -> richtig

  • 1.5.0 ~> 1.4.0 -> falsch

~= : Die Version des Package muss der angegebenen Version entsprechen, d.h. alle Stellen ungleich Null müssen gleich sein. Nur die Stellen mit einer Null müssen größer oder gleich Null sein.

  • 1.3.0 ~= 1.4.0 -> falsch

  • 1.4.0 ~= 1.4.0 -> richtig

  • 1.4.7 ~= 1.4.0 -> richtig

  • 1.5.0 ~= 1.4.0 -> falsch

Des weiteren gibt es noch die einfachen Operatoren > (größer), < (kleiner) und = (gleich).

Schedule-Einträge

Soll ein Package Schedule-Einträge mitbringen, dann sind diese in einer statischen Variable zu finden, die einem definierten Namenschema entsprechen muss. In der statischen Variable müssen die Einträge wie folgt angegeben werden:

  • Key: eindeutiger Schlüssel (z.B. eine laufende Nummer)

    1. Wert: Startzeit im Format HH:MM

    1. Wert: Eine Komma-separierte Liste von Kalender-Bedingungen. Jedes Element besteht aus einem Kalender-Objektnamen und einen Keyword getrennt durch einen Doppelpunkt (z.B. CALE1:KEY1,CALE2:KEY2)

    1. Wert: legt die Regel für die Kalenderbedingungen fest. Hier kann eins der Schlüsselworte: ALL, NONE oder ONE verwendet werden

    1. Wert: Objektname das gestartet werden soll

    1. Wert: Name des Schedule-Objekts

Zugangsdaten-Storage

Login- sowie Connection-Objekte können wie alle anderen Objekte transportiert werden. Allerdings verlieren diese Objekte die Werte von Attributen, die Passwörter enthalten. Da solche Daten sehr sensibel behandelt werden müssen bietet das b4A Deployment eine Möglichkeit diese Informationen separat von den Release-Archiven aufzubewahren und ausschließlich in einem zentralen Ort in verschlüsselter Form zu speichern. Während des Installationsvorgangs werden diese Daten über eine verschlüsselte Verbindung abgerufen und in die installierten Login- und Connection-Objekte eingetragen.

Der vom b4A Package Management unterstützte zentraler Speicherort ist ein Storage-Objekt. In diesem wird pro Login- und Connection-Objekt ein Eintrag hinterlegt. Diese Einträge enthalten jeweils eine kleine Textdatei, die alle relevanten Informationen für die Zugangsdaten eines Objektes enthalten. Gibt es beispielsweise ein Login-Objekte PCK.B4A_CREDENTIALS.LOGIN.WIN und ein Connection-Objekt PCK.B4A_CREDENTIALS.CONN.REST, dann kann ein Storage-Objekt mit den Zugangsdaten wie folgt aussehen.

Name

Dateiname

Typ

PCK.B4A_CREDENTIALS.LOGIN.WIN

login.win.credentials

TEXT

PCK.B4A_CREDENTIALS.CONN.REST

conn.rest.credentials

TEXT

Die Einträge in dem Storage-Objekt können entweder mit dem Modul pm.CredentialStorageAdd hinzugefügt oder manuell erstellt werden. Um diese Einträge korrekt zu erzeugen müssen für die unterstützen Objekttypen unterschiedliche Dateiformate eingehalten werden. Das Basisformat aller Daten ist das Java-Properties-Format.

Login-Objekte

Für diese Objekte können Dateien erstellt werden, die beliebig viele Zeilen des folgenden Formates enthalten.

<Host>/<Hosttyp> = <Benutzername>;<verschlüsseltes Password>

Beispiel:

*/UNIX = techuser01;--10B41571A6ED5B9D28
*/WINDOWS = domain\\techwin01;--10B41571A6ED5B9D28
WIN01/WINDOWS = domain\\user2;--10B41571A6ED5B9D28

RA-Connection (WEBSERVICEREST, WEBSERVICESOAP, WEBSERVICE, MAILAGENT, FTPAGENT, INFORMATICA)

Für diese Objekttypen müssen ausschließlich zwei Einträge in die Datei geschrieben werden, die dem folgenden Format entsprechen.

username = <Benutzername>
password = <verschlüsseltes Passwort>

Beispiel:

username = techwebservice01
password = --10B41571A6ED5B9D28

Andere RA-Connection-Objekte werden aktuell nicht unterstützt.

Für Informatica-Connection Objekte können zusätzlich noch der Domänen-Benutzer und sein Passwort angegeben werden.

domain-username = <Benutzername>
domain-password = <verschlüsseltes Passwort>

Bei FTPAGENT-Connection-Objekten kann zusätzlich noch eine Passphrase für den GPG-Schlüssel angegeben werden.

passphrase = <verschlüsseltes Passwort>

Datenbank-Connection

Das Format für diese Art von Connection-Objekten gleicht dem Format für die zuvor beschriebenen RA-Connection-Objekten.

username = <Benutzername>
password = <verschlüsseltes Passwort>

Beispiel:

user = usersql
password = --10B41571A6ED5B9D28

R3-Connection

Das Format dieser Connection-Objekt ist gleich dem Format der vorherigen Connection-Objekte. Zusätzlich werden weitere Einträge unterstützt, die nur benötigt werden, wenn die SMSE-Schnittstelle genutzt wird.

ae-user = <AE Benutzername>
ae-department = <AE Abteilung des Benutzers>
ae-password = <verschlüsseltes Passwort für den AE Benutzer>
ae-client = < AE Mandant>

Beispiel:

user = userr3
password = --10B41571A6ED5B9D28
ae-user = WRITER
ae-department = B4A
ae-password = --10B41571B7ED5B9D40
ae-client = 10

Sind die Daten im richtigen Format erstellt worden kann dann diese als Eintrag in ein Storage-Objekt eingefügt werden. Dabei sind folgende Regeln zu beachten.

  • Der Eintrag muss den gleichen Namen haben wie das Login- oder Connection-Objekt für das diese Zugangsdaten gedacht sind

  • Der Typ muss auf TEXT gesetzt

Da Zugangsdaten in der Regel sich in den Umgebungen unterscheiden bietet das b4A Deployment eine Möglichkeit die Zugangsdaten Umgebungs- und sogar Mandanten-spezifisch zu speichern. Dafür wird das gleiche Namenskonzept eingesetzt, dass auch für Konfigurationsvariablen genutzt wird. Gibt es beispielsweise ein zentrales Storage-Objekt SYSTEMS.CREDENTIALS und in der b4A Konfiguration wurde eine Umgebung AE12PROD definiert, dann können Zugangsdaten für die Umgebung AE12PROD in dem Storage-Objekt SYSTEM.CREDENTIALS$$$AE12PROD abgelegt werden. Gibt es Zugangsdaten, die ausschließlich für den Mandant 1200 in der Umgebung gedacht sind und die b4A Verbindung dahin heißt AE12PROD-1200, dann können die Zugangsdaten in dem Storage-Objekt SYSTEM.CREDENTIALS$$$AE12PROD-1200 gespeichert werden.

Besondere Objekttypen

Für einige Objekttypen gelten besondere Regeln.

Login- und Connection-Objekte

Die Objekte können transportiert werden allerdings werden dabei die enthaltenen Passwörter nicht transportiert (siehe vorheriger Abschnitt). Außerdem werden diese nur importiert, wenn sie in der Zielumgebung noch nicht existieren. Je nachdem ob bei der Installation ein Storage-Objekt mit Zugangsdaten angegeben oder ob die Option zum Erzwingen der Installation für Connection-Objekte angegeben wurde kann sich das Verhalten ändern. Im folgenden werden die verschiedenen Fälle gesondert betrachtet.

  • Connection-Objekte

    • Erste Installation

      • Ohne Storage-Objekt wird einfach nur das Objekt importiert

      • Mit einem Storage-Objekt werden nach dem Import die Zugangsdaten wiederhergestellt, wenn diese gefunden werden

    • Aktualisierung

      • Ohne Option zum erzwungenen Import

        • Ohne Storage-Objekt wird das Objekt nicht importiert

        • Mit Storage-Objekt wird das Objekt nicht importiert, sondern nur die Zugangsdaten aktualisiert

      • Mit Option zum erzwungenen Import

        • Ohne Storage-Objekt wird das Objekt nicht importiert, wenn die aktuell installierte Version Zugangsdaten enthält

        • Mit Storage-Objekt wird das Objekt installiert, wenn Zugangsdaten in dem Storage-Objekt gefunden wurden

  • Login-Objekte

    • Erste Installation

      • Ohne Storage-Objekt wird einfach nur das Objekt importiert

      • Mit einem Storage-Objekt werden nach dem Import die Zugangsdaten wiederhergestellt, wenn diese gefunden werden

    • Aktualisierung

      • Ohne Storage-Objekt wird das Objekt nicht importiert

      • Mit Storage-Objekt wird das Objekt nicht importiert, sondern nur die Zugangsdaten aktualisiert. Dazu werden zuerst alle Zugangsdaten aus dem Login-Objekt entfernt und anschließend die Zugangsdaten aus dem Storageobjekt eingetragen.

Schedule-Objekte

Bei diesen Objekten wird nach der Installation ein Neuladen beim Periodenwechsel automatisch angestoßen

Sync- und Queue-Objekte

Diese Objekte enthalten in ihrer Objektdefinition Statusinformationen. Daher werden diese Objekte in der Vorkonfiguration nur installiert, wenn diese noch nicht existieren. Dies ist konfigurierbar.

Objektberechtigungen

An den einzelnen Objekten können gesonderte Berechtigungen für das jeweilige Objekt definiert werden. Diese überschreiben die globalen Regeln, die am Benutzer oder den Gruppen, in denen dieser Mitglied ist, definiert sind. Diese Berechtigungen sind nicht Teil der Objekt-Definitionen, sondern werden gespeichert. Mit dem Package Management werden diese Daten ebenfalls transportiert. Dabei gelten die folgenden Regeln.

  • Werden Objektberechtigungen vergeben, dann muss der von b4A verwendete Benutzer weiterhin Rechte an dem Objekt haben, da anderenfalls der Transport nicht mehr möglich ist.

  • Bei Konfigurationsobjekten gilt, dass die Objektberechtigungen des jeweiligen Standard-Konfigurationsobjekt genutzt werden. Somit haben Objektberechtigungen an Mandanten- und Umgebungsspezifische Objekte keine Auswirkungen

  • Die Objektberechtigungen werden auch bei der Git-Integration berücksichtigt. Das Modul pm.Push speichert diese im Repository und mit dem Modul pm.Pull werden diese wiederhergestellt.

Index

Wenn die Menge der Packages in einer Umgebung wächst, dann wird das Abfragen der Metadaten von Packages mehr Zeit in Anspruch nehmen. Beispielsweise die Liste aller Packages mit dem Modul pm.List zu ermitteln wird länger dauern. Um dies zu verhindern und auch um mittels Automation Engine-Script mit den Metadaten von Packages arbeiten zu können kann optional ein Index aufgebaut werden, der den Zugriff auf die Metadaten aller Packages eines Mandant ermöglicht.

Um den Package-Index zu nutzen muss dieser initial einmalig mit dem Modul pm.Index erzeugt werden. Anschließend aktualisieren die Module pm.Build, pm.Install, pm.DependencyDefinitionCreate und pm.Init automatisch den Index des jeweiligen Mandant (siehe Package: Installieren und Package: Release erstellen).

Konfiguration

Für die Module aus diesem Bereich gibt es die Konfigurationsdateie pm.conf, die einige Vorgaben für das Verhalten der Module definiert. In der Regel sollten diese Einstellungen auf den Standardwerten belassen werden. In Ausnahmefällen können diese angepasst werden.

Package Management Einstellungen

Variable

Beschreibung

pm-runtime-variables

Muster für Objektnamen von Laufzeitvariablen

pm-config-separator

Eine Zeichenkette, die Konfigurationsvariablen als Mandantenkonfiguration kennzeichnen

pm-config-folder

Name des Ordners in dem sich die Konfigurationsvariablen befinden

pm-base-folder

Standard-Basisordner in dem sich die Packages befinden. Ein Basisordner kann auf einer beliebigen Ebene der Ordnerstruktur liegen. Beispielsweise PACKAGES, PACKAGES/SYSTEM oder INTERN/TEST/B4A.

pm-alternative-base-folders

Weitere Basisordner in denen sich Packages befinden können.

pm-bin-folder

Ordner in dem sich die öffentlichen ausführbaren Objekte (Actions) befinden

pm-source-folder

Ordner in dem sich die genutzten Objekte (z.B. Aufgaben in Workflows) befinden

pm-deprecated-folder

Ordner in den veraltete Objekte verschoben werden

pm-deprecated-pattern

Muster für die Umbenennung der veralteten Objekten. In dem Muster können die Attribute %(object_name) (alter Objektname) und %(timestamp) genutzt werden. Der Zeitstempel hat das Format yyyy-MM-ddTHHmmss.

pm-templates-pattern

Muster für den Objektnamen der Variable mit zu registrierenden Templates. In dem Muster kann das Attribut %(package) verwendet werden

pm-metadata-pattern

Eine komm-separierte Liste mit Mustern für den Objektnamen der Metadaten-Variable. In den Mustern kann das Attribut %(package) verwendet werden. Das erste Muster ist der präferierte Name und wird beispielsweise durch das Modul pm.Init verwendet. Eine Liste von Mustern kann dann relevant werden, wenn mehrere Typen genutzt werden. Beispielsweise das eigene Package-Format sowie Actions Packs von Automic.

pm-schedule-pattern

Muster für den Objektnamen der Variable mit Schedule-Definitionen. In dem Muster kann das Attribut %(package) verwendet werden

pm-releasenotes-pattern

Muster für den Objektnamen der Release Notes-Variable. In dem Muster kann das Attribut %(package) verwendet werden

pm-metadata-key-dependencies

Name für den Eintrag mit den Abhängigkeitsdefinitionen

pm-metadata-key-categories

Name für den Eintrag der Kategorien, die bei der Registrierung der Actions genutzt werden können

pm-metadata-key-version

Name für den Eintrag der Versionsnummer des Package

pm-metadata-key-built-on

Name für den Eintrag des Bau-Zeitstempel des Package

pm-metadata-key-installed-on

Name für den Eintrag des Installations-Zeitstempel des Package

pm-metadata-key-initialized-on

Name für den Eintrag des Initialisierungs-Zeitstempel des Package

pm-actions-folder

Ordner in dem registrierte öffentlich ausführbare Objekte (Actions) verknüpft werden (AWI)

pm-createonly-objecttypes

Eine Komma-separierte Liste von Objekttypen, die nur installiert werden, wenn sie im Zielmandant noch nicht existieren. Diese Regel wird nur angewendet, wenn diese nicht im Ordner für Konfigurationsvariablen liegen.

pm-index-folder

Ordner in dem das Objekt des Package-Index gespeichert wird

pm-index-variable

Name der XML-Variable des Package-Index

pm-index-packages-key

Key in der XML-Variable in dem der Package-Index zu finden ist

pm-index-basefolders-key

Key in der XML-Variable in dem der Basisordner-Index zu finden ist

pm-index-additional-entries

Eine komma-separierte Liste mit Einträgen aus den Metadaten, die zusätzlich in dem Index gespeichert werden sollen

pm-package-name-regex

Ein regulärer Ausdruck, der die erlaubten Package-Namen definiert. Dieser Ausdruck wird verwendet um Package-Namen auf Korrektheit zu prüfen. Dies kann beispielsweise bei den Package-Ordner und dem Namen in den Metadaten-Variablen angewendet werden. Der Ausdruck muss den gesamten Namen beschreiben.

pm-object-name-regex

Ein regulärer Ausdruck, der genutzt wird um aus Objektnamen den Package-Namen zu extrahieren. Der Name muss durch die benannte Gruppe package eingeschlossen werden. Wenn gewünscht, dann kann über das b4A Expression Attribute package-name auf den regulären Ausdruck für Package-Namen referenziert werden.

Module