Implementierung¶

Services, die im best4Automic Service Portal angeboten werden, sind in der Automation Engine Workflows, die gegebenenfalls einen oder mehrere PromptSets für Eingabeparameter nutzen. Welche Funktionalitäten in diesem Zusammenhang unterstützt werden wird im Folgenden beschrieben.

Die Workflows können beliebige Aufgaben ausführen. Hier gibt es weder in der Anzahl noch vom Objekttyp her irgendwelche Einschränkungen. Regeln sind zu beachten, wenn es um die genutzten PromptSets und um Benachrichtigungsobjekte geht.

Eingabeparameter - PromptSets¶

In der folgenden Tabelle werden die unterstützten Attribute und Funktionen der verschiedenen Elementtypen aufgezeigt. Die Attribute Datenreferenz, Beschriftung und Variablenname werden von allen unterstützt und nicht separat in der Tabelle genannt. Bei dem Attribut Standardwert ist das manuelle setzen immer möglich. Das Setzen des Standardwerts über Variablen wird mit der geschwungenen Klammern Notation ({…}) als auch mit System-Variablen unterstützt.

PromptSet Elemente¶
Typ	Attribute	Hinweis
Überschrift/Text	Tooltip	Dieses Element kann ohne Einschränkung genutzt werden. Längere Texte werden umgebrochen und somit komplett dargestellt und können helfen Formulare zu erklären
Zahl	Minimum Maximum Schreibgeschützt Tooltip
Textfeld	Mehrzeilig Pflichtfeld Schreibgeschützt Großschreibung Regulärer Ausdruck Tooltip
Combobox	Schreibgeschützt Dynamisch aktualisieren Zurücksetzung bei Änderung Tooltip
Optionsfeld	Schreibgeschützt Tooltip
Checkbox	Schreibgeschützt Zurücksetzung bei Änderung Array Trennzeichen Tooltip
Zeit/Datum	Typ Schreibgeschützt Minimum Maximum Kalenderbedingung	Bei diesem Element werden alle Typen unterstützt (Datum, Zeitstempel und Zeit)
Datei-Upload (Textfeld)		Im PrompSet-Objekt wird dieses Feld als Textfeld eingefügt. Zusätzlich muss in dem Attribut benutzerdefiniertes Feld der folgende Wert eingetragen werden: { "type": "file-upload", "options": { "single": true }}

Zusätzliche Eingabefelder¶

Das best4Automic Service Portal erweitert die Möglichkeiten für Eingabemasken gegenüber dem Automic Web Interface. Einerseits gibt neue Eingabefelder und andererseits werden die Möglichkeiten für Datenquellen ausgebaut. Im Folgenden werden diese Techniken beschrieben.

Allgemein¶

Um die erweiterten Fähigkeiten nutzen zu können, müssen diese an den PromptSet-Objekten gespeichert werden. Dafür gibt es zwei Techniken. An den Feldern, die die Option Benutzerdefinierten Attribut haben kann die Information dort gespeichert werden. Alternativ können für alle Felder die Daten in der strukturierten Dokumentation des PromptSet-Objektes gespeichert werden (siehe Strukturierte Dokumentation). Diese Variante wird empfohlen, da das benutzerdefinierte Attribut eine Längenbegrenzung von 255 Zeichen hat. Welche strukturierte Dokumentation der PromptSet-Objekte genutzt werden soll, kann in der Konfigurationsdatei api.json festgelegt werden.

Strukturierte Dokumentation¶

Die Informationen sind im JSON-Format gespeichert. In den folgenden Abschnitten werden die genauen Definitionen für die jeweiligen Varianten erläutert.

Datei Upload¶

Ein zusätzlicher Feldtyp ist der Datei-Upload. Damit ist es möglich Dateien direkt an einen Automationsprozess zu übergeben. Um diesen zu nutzen, muss in dem PromptSet-Objekt ein Textfeld eingefügt werden. Bei dem Feld muss in die Option Benutzerdefiniertes Feld mit folgendem Text im JSON-Format gefüllt werden:

{
    "type": "FileUpload"
}

Dynamischer Text¶

Das Element Überschrift/Text in einem PromptSet-Objekt kann einen statischen Text in einer Eingabemaske anzeigen. Solche Text können beispielsweise zur Erläuterung der Eingabefelder genutzt werden. Das dynamische Textfeld ist eine Erweiterung dieses Feldes und ermöglicht es einen veränderbaren Text anzuzeigen. Dabei wird die Änderung des Textes durch die Änderung von Werten in anderen Eingabefeldern in dem PromptSet-Objekt ausgelöst. Welche Felder die Änderungen auslösen soll kann definiert werden. Der angezeigte Text kann dabei die Werte der anderen Felder beinhalten. Folgend ist ein Beispiel für solch eine Konfiguration zu sehen.

{
  "type": "DynamicLabel",
  "source": {
    "name": "dynamic-label",
    "options": {
      "dependsOn": [
        {"variable":"B4AP_APPLICATION_I#","default":""},
        {"variable":"B4AP_FUNCTION_I#","default": ""}
      ],
      "onEmpty": "Select application and function to see the generated b4A Package name",
      "else": "Generated b4A Package name: %(B4AP_APPLICATION_I#.value).%(B4AP_FUNCTION_I#.value)"
    }
  }
}

Die beiden Attribute onEmpty und else definieren den jeweiligen Text, den das Feld anzeigen soll. onEmpty definiert den Text für den Fall, dass alle Attribute, von denen das Feld abhängt, leer sind. Hat mindestens eins der Felder einen nicht leeren Wert, dann wird der Text aus dem Attribut else angezeigt. In den beiden Attributen können b4A Expressions genutzt werden, um den Text zu generieren. Dabei setzen alle Felder aus dem PromptSet-Objekt zur Verfügung. Jedes Feld hat zwei Unterattribute. Einmal gibt es das Attribut label, dass den in der Eingabemaske anzuzeigenden Text enthält und zusätzlich gibt es das Attribut value, dass den Text enthält, der an den Service-Workflow übergeben wird.

Steckt beispielweise hinter der Variable B4AP_APPLICATION_I# eine Combobox, die ihre Daten aus einer benutzerdefinierten Datenquelle bekommt (siehe Benutzerdefinierte Datenquelle), die folgende Liste liefert, dann kann mit dem b4A Expression Ausdruck %(B4AP_APPLICATION_I#.label) auf den Wert best4Automic oder SAP Business Warehouse zugegriffen werden (je nach dem welcher Wert aktuell ausgewählt ist). Mit dem Ausdruck %(B4AP_APPLICATION_I#.value) kann entsprechend auf die Werte B4A oder SAP_BW zugegriffen werden.

Die weitere Struktur der Konfiguration wird in dem folgenden Abschnitt genauer erklärt, da sie einem Standard entspricht, der von allen Erweiterungen genutzt wird.

[
    {
        "value": "B4A",
        "label": "best4Automic"
    },
    {
        "value": "SAP_BW",
        "label": "SAP Business Warehouse"
    }
]

In der Beispielkonfiguration ist in dem Attribut dependsOn zu sehen, wie die Abhängigkeit zu den anderen Felder definiert wird. Hier ist pro Feld einmal die Variable und ein Vorgabewert zu definieren. Ist das angegebene Feld noch nicht gesetzt, dann wird der Vorgabewert genutzt.

Benutzerdefinierte Datenquelle¶

Eingabefelder wie Combobox, Checkbox und Optionsfeld nutzen Datenquellen, um die möglichen Werte zu definieren. Die Automation Engine bietet hier die Möglichkeit mit Variable-Objekten dynamische Listen zu erzeugen. In manchen Anwendungsfällen ist dies gegebenenfalls nicht ausreichend oder führt zu längeren Wartezeiten. Um dies zu lösen und zusätzlich einen möglichst hohen Grad an Flexibilität zu bieten, werden benutzerdefinierte Datenquellen unterstützt. Während einige solcher Datenquellen Teil der best4Automic RESTful API sind, können auch weitere kundenspezifische Datenquellen ergänzt werden.

Um solche Datenquellen zu nutzen, muss in den PromptSet-Implementierungen ein Feld definiert werden, dass vom Typ Textfeld ist. Bei diesem Feld muss in der Option Benutzerdefiniertes Feld die Konfiguration der Datenquelle eingetragen werden. Als Format wird JSON verwendet.

Die folgende Beispielkonfiguration zeigt den grundlegenden Aufbau einer benutzerdefinierten Datenquelle. Mit dem Wert für type wird festgelegt welche Art Feld im Service Portal gezeigt werden soll. Hier sind die Werte ComboBox, CheckBox und RadioGroup möglich. Mit dem Feld source wird die Datenquelle festgelegt. Dabei definiert name den Namen der Datenquelle und unterhalb von options werden Optionen für die jeweilige Datenquelle definiert. Welche Datenquellen im Produkt verfügbar sind und welche Optionen diese haben ist in der Dokumentation der best4Automic RESTful API zu finden.

{
    "type": "ComboBox|CheckBox|RadioGroup",
    "source": {
        "name": "<Name der Datenquelle>",
        "options": {
            <Optionen der Datenquelle>
        }
    },
    "options": {
        <abhängig vom Typ>
    }
}

Zu dem definierten Typ (type) gibt es ebenfalls Optionen. Folgend werden diese in Abhängigkeit vom Typen beschrieben:

RadioGroup

defaultValue: Definiert den Vorgabewert. Als Wert ist hier ein Objekt mit den Attributen label und value anzugeben.

"options" : {
    "defaultValue": { "label": "AE21A-0012", "value": "AE21A-0012"}
}

CheckBox

resets: Liste mit Variablen, deren Werte zurückgesetzt werden sollen, wenn sich der Wert dieser Option ändert. Beim Variablennamen ist das führende & wegzulassen.
required: Wenn der Wert auf true gesetzt ist, dann muss mindestens ein Wert ausgewählt werden
separator: Ist ein Zeichen angegeben, dann werden die gewählten Werte in einer Zeichenkette zusammengefasst mit dem angegebenen Separator. Ist keiner angegeben, dann wird ein Semikolon (;) verwendet
defaultValue: Definiert den Vorgabewert. Als Wert ist hier ein Objekt mit den Attributen label und value anzugeben.

"options" : {
    "resets": ["B4A_PARAM1_I#", "B4A_PARAM2_I#"],
    "required": true,
    "separator": ";",
    "defaultValue": [{ "label": "AE21A-0012", "value": "AE21A-0012"}, { "label": "AE21A-0014", "value": "AE21A-0014"}]
}

ComboBox

resets: Liste mit Variablen, deren Werte zurückgesetzt werden sollen, wenn sich der Wert dieser Option ändert. Beim Variablennamen ist das führende & wegzulassen.
dynamicReload: Ist der Wert der Option true, dann wird die letzte der erlaubten Werte beim Öffnen der Combobox erneut geladen.
defaultValue: Definiert den Vorgabewert. Als Wert ist hier ein Objekt mit den Attributen label und value anzugeben.

"options" : {
    "resets": ["B4A_PARAM1_I#", "B4A_PARAM2_I#"],
    "dynamicReload": true,
    "defaultValue": { "label": "AE21A-0012", "value": "AE21A-0012"}
}

Mitgelieferte Datenquelle¶

base-folders : Liefert die Liste aller konfigurierter Basisordner

packages : Liefert die Liste aller b4A Package in einem konfigurierten Mandanten.

Option	Beschreibung „Pflicht“
devConnection	Verbindung zum Entwicklungsmandant	ja

Mit der Option devConnection kann der Mandant definiert werden.

connections : Liefert die Liste aller konfigurierter Verbindungen

dynamic-labels : Wird für die dynamischen Textfelder genutzt, um die anzuzeigenden Texte zu konfigurieren

Option	Beschreibung „Pflicht“
dependsOn	Liste der Felder von denen dieses Feld abhängt	ja
onEmpty	Sind alle Felder leer, von denen dieses Feld abhängt, dann wird dieser Text angezeigt	ja
else	Aus dieser Vorlage wird der Text erzeugt, wenn mindestens ein Feld aus Abhängigkeitsliste gesetzt wurde	ja

branches : Liefert die Liste aller Git Branches zu einem b4A Package.

Option	Beschreibung „Pflicht“
devConnection	Verbindung zum Entwicklungsmandant	ja
repository	Name des b4A Package bzw. des Repositorys	ja
pattern	Ein Muster dem alle aufzulistenden Branches vom Namen her entsprechen müssen	nein, Vorgabewert ist `.*`

repository : Kann entweder die Liste aller b4A Packages im Release-Repository liefern oder die Liste der verfügbaren Versionen eines b4A Package.

Option	Beschreibung „Pflicht“
operation	‚packages‘ oder ‚version‘, je nachdem was aufgelistet werden soll	ja
package	bei der Operation ‚versions‘ muss die Option für den Namen des Packages mitgegeben werden	ja

Benachrichtigungen - Genehmigungen¶

Das best4Automic Service Portal unterstützt Services, die Genehmigungen beinhalten. Somit ist es möglich Services zu integrieren, die vor der Ausführung von einem Mitglied aus einer Liste von Gruppen bestätigt oder abgelehnt werden müssen. Technisch nutzen Workflows in der Automation Engine für diesen Mechanismus die Benachrichtigungsobjekte (CALL). Unterstützt wird der Typ Rückfrage mit allen möglichen Prioritäten. Die Optionen der Eskalation werden durch das best4Automic Service Portal nicht abgebildet.

Eine Erweiterung die das best4Automic Service Portal für die Benachrichtigungen bietet, ist die Möglichkeit HTML zur Formatierung in der Nachricht zu nutzen. Damit können auch Strukturen wie beispielsweise Tabellen oder Listen genutzt und dargestellt werden.