REST-API¶

Die Basis-URI für jede Anfrage hat standardmäßig die Form http[s]://{host}:{port}/best4automic-rest-v2/api. Die OpenAPI Spezifikation kann über /swagger-ui.html aufgerufen werden.

Beim Start der |b4ARA| muss eine gültige Lizenz für b4A im Konfigurationsverzeichnis liegen.

Authentisierung¶

Je nach Konfiguration, siehe Rest Edition, authentisiert man sich entweder mit Benutzernamen und Passwort (Basic-Authentisierung) oder mit einem JWT-Token.

Basic-Authentisierung¶

Ist die Basic-Authentisierung aktiviert, muss bei jeder Anfrage gegen die |b4ARA| der Benutzername und das Passwort im Authentisierungsheader mitgegeben werden. Der Benutzername ist dabei mit USERNAME/DEPARTMENT anzugeben. Der gesamte Service-Bereich der |b4ARA| steht hierbei, unabhängig von den Rollen des Benutzers, nicht zur Verfügung. Der Authentisierungsheader ist wie bei Basic-Authentisierung üblich mit <BENUTZERNAME>:<PASSWORT> in Base64-Codierung. Beispiel

Authorization: Basic REVNTy9CNEE6RHVEZWNvZGVzdEFsc29VbnNlclBhc3N3b3J0LlNvU28h

Tokenbasierte Authentisierung¶

Bei dieser Authentisierungsmethode steht grundsätzlich das volle Funktionsspektrum der |b4ARA| zur Verfügung. Für welche Anfragen ein Benutzer berechtigt ist, hängt von seinen Rollen ab. Bei jeder Anfrage muss ein JWT-Token im Authentisierungsheader mitgegeben werden. Zur Erzeugung eines solchen Tokens muss zuerst der Anmelde-Endpunkt (POST-Anfrage) aufgerufen werden.

http[s]://{host}:{port}/best4automic-rest-v2/api/login

Die Anmeldedaten müssen im Body mitgegeben werden.

{
  "username": "DEMO/B4A",
  "password": "<Passwort>",
  "language": "de"
}

Die Antwort sieht beispielsweise so aus.

  {
  "user": {
      "username": "DEMO/B4A",
      "firstName": "Demo",
      "lastName": "b4A"
  },
  "emailAddress": "demo@b4A.de",
  "expires": "2022-08-05T12:00:00.000Z",
  "roles": [
      {
          "name": "B4A.ROLE.1",
          "title": "Erste Rolle"
      },
      {
          "name": "B4A.ROLE.2",
          "title": "Zweite Rolle"
      }
  ]
}

Der JWT-Token wird nicht im Body mitgeschickt, sondern befindet sich im Header der Antwort unter dem Key Authorization. Dem Body kann man bereits entnehmen, dass das Token zu einer bestimmten Zeit abläuft. Wie lange das erzeugte Token gültig ist kann konfiguriert werden. Zusätzlich lässt sich das sogenannte Secret (ein geheimer Schlüssel) und der Issuer (Herausgeber des Tokens) konfigurieren, auf dessen Grundlage das Token erzeugt wird. Siehe dazu Rest Edition. Nach einem Neustart der |b4ARA| sind alle zuvor erstellten Token ungültig.

Alle weiteren Anfragen müssen nun dieses erzeugte Token im Header mitschicken. Der Authentisierungsheader sieht beispielsweise so aus.

Authorization: Bearer eyJhbGciOiJIUzUxGjkiJ9.nOIHfIjoiZGUuYmVzdGJsdS5yZXN0YXBpIiwiaWF0IjoxNjQzMDA4Njc1LCJleHAiOjE2NDMwMzc0NzV9.xYGmrfMidALVySU6yfoO4sNWbdl4LSIpcbDJTdgiIc0O4cAHxp6UP9KXlF_wh1fmEGcK3WY_b5

Da bei jedem Login eine Verbindung zur Automation Engine aufgebaut wird, sollte jede Sitzung auch sauber wieder mit dem Abmelde-Endpunkt (POST-Anfrage) geschlossen werden, falls sie nicht mehr benötigt wird. Ein Body ist nicht mitzusenden.

http[s]://{host}:{port}/best4automic-rest-v2/api/logout

Rollen¶

Die Authorisierung wird in der |b4ARA| über vier Rollen verwaltet. Die Rollen werden über Benutzergruppen in der Automation Engine abgebildet. Wie die Benutzergruppen in der Automation Engine heißen kann konfiguriert werden. Siehe dazu im Kapitel Rest Edition nach den in der Spalte „Konfiguration“ beschriebenen Schlüsseln.

Rolle	Konfiguration	Beschreibung
Info	rest.auth.groups.info	Ein Benutzer mit dieser Rolle hat ausschließlich „lesenden“ Zugriff auf die \|b4ARA\|. Es sind ausschließlich die Lizenz-, Connection-und Version-Endpunkte sowie GET-Anfragen an den Module-Endpunkt erlaubt.
Module	rest.auth.groups.module	Benutzer dieser Gruppe haben zusätzlich zu den Info-Berechtigungen zusätzlich die Berechtigung Module auszuführen.
Service	rest.auth.groups.service	Diese Berechtigung wird benötigt, wenn zusätzlich zu den Module-Berechtigungen auch der Service-Bereich der \|b4ARA\| verwendet werden soll. Ausgeschlossen sind administrative Endpunkte und der Endpunkt für Meldungen aus der Automation Engine.
Admin	rest.auth.groups.admin	Die Gruppe der Admins darf zusätzlich zu den Berechtigungen der Service-Rolle noch die administrativen Endpunkte bedienen sowie Aufräumarbeiten mithilfe der DELETE-Anfragen des Modul-Endpunkts durchführen. Der einzige Endpunkt, der sogar dem Admin-User verwehrt wird ist der bereits angesprochene Endpunkt für Meldungen aus der Automation Engine.

Meldungen aus der Automation Engine¶

Die Post-Anfrage zum Senden von Meldungen aus der Automation Engine nimmt eine Sonderrolle in der |b4ARA| ein. Sie ist ausschließlich dafür gedacht Meldungen aus der Automation Engine an das |b4ASP| zu senden. Es bedarf eines installationsspezifischen Tokens, um diesen Endpunkt nutzen zu können. Dieser kann konfiguriert werden. Siehe dazu im Kapitel Rest Edition den Schlüssel rest.auth.status.token. Mit dem b4A Package B4A.WEB wird eine Action bereitgestellt, mit der Meldungen an das |b4ASP| gesendet werden können. Mehr Infomationen zu diesem b4A Package gibt es unter https://docs.best4automic.de/packages. Für weitere Informationen zum |b4ASP| sei hier auf die Dokumentation dieser verwiesen. Meldungen, die über diese Action an die |b4ARA| gesendet werden, werden über Websockets an alle an dem |b4ASP| angemeldeten Benutzer verteilt.

Websockets¶

Die |b4ARA| erzeugt an einigen Stellen Nachrichten, die über Websockets verteilt werden. Ein Websocket zur |b4ARA| wird gegen folgende URL geöffnet.

http[s]://{host}:{port}/best4automic-rest-v2/api/service/event

Allerdings gibt es die Besonderheit, dass ein Authorisierungsheader, analog zu einer Anfrage an die |b4ARA| mit JWT-Token, mitgegeben werden muss.

Im Folgenden werden alle abonnierbaren Topics aufgelistet und beschrieben.

Topic	Beschreibung
/user/queue/service/status/changed	Wenn sich der Status eines Services geändert hat wird eine Nachricht an alle Benutzer mit offener Websocket gesendet, die für den spezifischen Service berechtigt sind.
/user/queue/service/notifications/changed	Wenn ein Benachrichtigungsobjekt ausgeführt wird, für das der Benutzer als Empfänger eingetragen ist, wird eine entsprechende Nachricht über die Websocket geschickt. Für den Empfang muss der Benutzer mindestens ein Mal vorher die GET-Anfrage /service/notifications an die \|b4ARA\| geschickt haben. Ansonsten bekommt der Benutzer nichts von diesen Änderungen mit.
/user/queue/service/notification/approved	Wurde ein Benachrichtigungsobjekt, für das der Benutzer als Empfänger eingetragen ist, über die POST-Anfrage /service/notification/{runId} von jemand anderem als ihm selbst beantwortet, erhält der Benutzer hierüber eine entsprechende Nachricht.
/user/queue/service/message/added	Hierüber werden die Meldungen aus der Automation Engine weitergeleitet.
/user/queue/service/start/initiated	Wurde ein Service erfolgreich über die POST-Anfrage /service gestartet, wird über dieses Topic eine Nachricht an alle Benutzer gesendet, die für den spezifischen Service berechtigt sind.
/user/queue/service/start/failed	War der Start eines Services über die POST-Anfrage /service nicht erfolgreich, wird über dieses Topic eine Nachricht an den Benutzer gesendet, der versucht hat den Service zu starten.
/user/queue/service/config/changed	Wurde die Konfiguration über die PUT-Anfrage /service/admin/config/reload neu geladen, werden alle Benutzer darüber informiert.

Beispielanfragen¶

Eine Beschreibung aller Endpunkte mit Schema und Beispielen befinden sich in der OpenAPI-Spezifikation, auf die eingangs verwiesen wurde. Dennoch sollen hier einige Beispiele dokumentiert werden.

Lizenz¶

Zur Überprüfung, ob die RESTful-API korrekt installiert und konfiguriert wurde, kann der Lizenz-Endpunkt aufgerufen werden (GET-Anfrage).

http[s]://{host}:{port}/best4automic-rest-v2/api/license

War der Request erfolgreich, sollte die erworbene Lizenz zurückgegeben werden. Die Antwort sollte beispielsweise so aussehen.

{
  "license": {
    "company": "best-blu consulting with energy GmbH",
    "type": "Production",
    "bundle": "All-in-One",
    "categories": [
      "te",
      "ana",
      "mc",
      "info",
      "util",
      "tp",
      "pm",
      "ta",
      "vcs"
    ]
  },
  "valid": true,
  "message": ""
}

Module¶

Modul ausführen¶

Zur Auführung eines Moduls muss eine POST-Anfrage an folgenden Endpunkt geschickt werden.

http[s]://{host}:{port}/best4automic-rest-v2/api/module

Bei dieser Anfrage muss ein Body mitgeschickt werden. Dieser muss folgendes Format haben.

{
  "name": "info.Search",
  "options": {
    "connection": "AE12PROD-1000",
    "save-objects": "suchergebnisse.txt",
    "name": "*BEST*"
  }
}

Bei Erfolg gibt es als Antwort den HTTP-Status 202 Accepted zurück. Wie für REST-APIs üblich wird hier also nicht auf das Ende der Ausführung gewartet. Der Status der Ausführung kann mit einer weiteren Anfrage abgefragt werden. Vorweg die Beispielantwort für eine POST-Anfrage.

{
  "id": 1,
  "updated": "2021-06-28T13:39:06.705+00:00",
  "name": "info.Search",
  "status": "INITIATED",
  "returnCode": 0,
  "errorMessage": "",
  "options": {
      "log-flags": [
          "MONOCHROME",
          "TIMESTAMP"
      ],
      "log-variants": [
          "REPORT"
      ],
      "log-datastream-separator": "§§",
      "log-datastream-prefix": "@B4A_STREAM@",
      "recursive": true,
      "folder-ignore-missing": false,
      "log-levels": [
          "ERROR",
          "WARNING",
          "INFO"
      ],
      "parse-processes": false,
      "encryption-key": "server",
      "save-success-only": true,
      "connection": "AE12PROD-1000",
      "end": "2021-06-28 15:39:06",
      "test-mode": false,
      "exclude-list": "/var/lib/tomcat9/webapps/best4automic-rest-v2#api/data/3/exclude-list",
      "search-date": "none",
      "log-error-mode": "never",
      "search-in-vara-type": "text",
      "types": [
          "CALE",
          "CALL",
          "CITC",
          "CLNT",
          "CODE",
          "CONN",
          "CPIT",
          "DASH",
          "DOCU",
          "EVNT",
          "FILTER",
          "FOLD",
          "HOST",
          "HOSTG",
          "HSTA",
          "JOBF",
          "JOBG",
          "JOBI",
          "JOBS",
          "JOBP",
          "JOBQ",
          "LINK",
          "LOGIN",
          "JSCH",
          "SCRI",
          "SYNC",
          "TZ",
          "USER",
          "USRG",
          "VARA",
          "XSL",
          "PRPT",
          "QUEUE",
          "STORE",
          "SLO",
          "PERIOD"
      ],
      "exclude-ignore": false,
      "save-append": false,
      "input-mode": "search",
      "include-links": false,
      "datastream-object-type": false,
      "save-objects": "/var/lib/tomcat9/webapps/best4automic-rest-v2#api/data/3/suchergebnisse.txt",
      "traverse-flows": false,
      "name": "*BEST*",
      "begin": "2021-05-28 15:39:06"
  },
  "_links": {
      "get_module": {
          "href": "http[s]://<host>:<port>/best4automic-rest-v2/api/module/1"
      },
      "get_report": {
          "href": "http[s]://<host>:<port>/best4automic-rest-v2/api/module/1/report"
      },
      "get_output": {
          "href": "http[s]://<host>:<port>/best4automic-rest-v2/api/module/1/output/save-objects"
      }
  }
}

Im unteren Abschnitt der Antwort werden sinnvolle Folgeanfragen aufgelistet. In diesem Fall kann mit der ersten Anfrage der Status und weitere Informationen über den Lauf des Moduls abgefragt werden. Mit der zweiten kann der Report und mit der dritten die Ausgabedatei der Option save-objects geholt werden.

Weitere Anfragen zu diesem Lauf¶

Die GET-Requests sind so abzuschicken, wie sie in der Antwort oben geschickt wurden.

Für die Informationen über die Optionen, den Status oder eventuelle Fehlermeldungen wird diese Anfrage verschickt.

http[s]://<host>:<port>/best4automic-rest-v2/api/module/1

Die Antwort ähnelt stark der POST-Anfrage. In diesem Fall ist das Modul aber bereits erfolgreich durchgelaufen.

{
  "id": 1,
  "updated": "2021-06-28T12:17:40.999+00:00",
  "name": "info.Search",
  "status": "COMPLETED",
  "returnCode": 0,
  "errorMessage": "",
  "options": {
    "all": "options",
    "for": "this",
    "run": "!"
  },
  "_links": {
    "get_report": {
        "href": "http://<host>:<port>/best4automic-rest-v2/api/module/1/report"
    },
    "delete_module": {
        "href": "http://<host>:<port>/best4automic-rest-v2/api/module/cleanup/1"
    }
  }
}

Die Status können sein:

INITIATED: Lauf wurde initialisiert
IN_PROGRESS: Das Modul wurde gestartet, aber noch nicht beendet
COMPLETED: Das Modul wurde erfolgreich beendet
FAILED: Das Modul wurde mit Fehlern beendet. In diesem Fall sind dem returnCode und der errorMessage weitere Informationen zu entnehmen.

Für den Report des Laufs ist folgende Anfrage abzuschicken.

http://<host>:<port>/best4automic-rest-v2/api/module/1/report

Die Ausgabedatei der Option save-objects wird ähnlich abgefragt.

http://<host>:<port>/best4automic-rest-v2/api/module/1/output/save-objects

Abhängig von der Dateiendung, die bei der Post-Anfrage angegeben wurde, wird der Medientyp der Datei geraten und in dem Header der Antwort gesetzt.

Service¶

Kategorien¶

Diese GET-Anfrage gibt die Kategorien zurück, für die der Benutzer berechtigt ist.

http[s]://<host>:<port>/best4automic-rest-v2/api/service/categories

{
  "categories": [
    {
      "key": "EXAMPLES",
      "label": "Examples"
    },
    {
      "key": "TESTING",
      "label": "Test Automation"
    },
    {
      "key": "DEPLOYMENT",
      "label": "Deployment"
    },
    {
      "key": "PROJECT",
      "label": "Project Management"
    }
  ]
}

Liste der Services¶

Mit dieser GET-Anfrage wird für eine bestimmte Kategorie die Liste der Services zurückgegeben. Beispiel:

http[s]://<host>:<port>/best4automic-rest-v2/api/service/list/EXAMPLES

{
  "category": "EXAMPLES",
  "services": [
    {
      "name": "B4AE.WEB.JOBP.SMOKE-TEST",
      "title": "Smoke Test",
      "description": "Check if the configuration is correct and ensure that the communication between Automation Engine, b4A RESTful API and the b4A WebUI works",
      "promptSets": [
        {
          "name": "B4AE.WEB.PRPT.SMOKE-TEST",
          "title": "Smoke Test",
          "parameters": [
            {
              "variable": "B4AW_TEST_I#",
              "label": "Test Parameter",
              "defaultValue": "",
              "dynamicDefaultValue": false,
              "tooltip": "",
              "type": "TextView",
              "dataReference": "UC_DATATYPE_STRING",
              "readOnly": false,
              "regex": "",
              "upperCase": false,
              "multiline": false,
              "required": false,
              "showAsPassword": false,
              "resets": []
            }
          ]
        }
      ]
    },
  ...
  ]
}

Liste der aktiven Instanzen von Services¶

Um nun die aktiven Instanzen aller Services der Kategorie zu bekommen muss folgende GET-Anfrage geschickt werden. Standardmäßig werden hier nur diejenigen Instanzen zurückgegeben, die keinen Parent haben, also direkt von einem Benutzer gestartet wurden. Sollen auch Instanzen zurückgegeben werden, die beispielsweise von einem Scheduler gestartet wurden, muss dies pro Service konfiguriert werden. Dazu finden Sie mehr Informationen in der Dokumentation des |b4ASP|s

http[s]://<host>:<port>/best4automic-rest-v2/api/service/tasks/EXAMPLES

{
  "category": "EXAMPLES",
  "services": [
    {
      "name": "B4AE.WEB.JOBP.SMOKE-TEST",
      "title": "Smoke Test",
      "instances": [
        {
          "user": {
            "username": "DEMO/B4A",
            "firstName": "Demo",
            "lastName": "best4Automic"
          },
          "runId": 1928407,
          "completedTasks": 2,
          "numberOfTasks": 3,
          "status": null,
          "statusCode": 1550,
          "statusText": "Aktiv",
          "messages": [
            {
              "message": " Thanks for using b4A Web UI :-)\r\n",
              "type": "INFO"
            },
            {
              "message": " This is quite a long message which is used to show you what happens with such log text segments in the b4A Service Portal. Beautiful, right?\r\n",
              "type": "INFO"
            },
            {
              "message": " This is quite a long message which is used to show you what happens with such long text fragment in the b4A Service Portal. Beautiful, right?\r\n",
              "type": "INFO"
            },
            {
              "message": " First task of service has been finished\r\n",
              "type": "INFO"
            },
            {
              "message": " Second task of service is going to start\r\n",
              "type": "INFO"
            },
            {
              "message": " Second task of service has been finished\r\n",
              "type": "INFO"
            }
          ],
          "parameters": [
            {
              "variable": "B4AW_TEST_I#",
              "label": "Test Parameter",
              "value": "Demo"
            }
          ],
          "startTime": "2022-08-05 23:06:00"
        },
        ...
      ]
    },
    ...
  ]
}

Starten eines Services¶

Zum Starten eines Services bedarf es einer POST-Anfrage.

http[s]://<host>:<port>/best4automic-rest-v2/api/Service

Der Body der Anfrage sieht beispielsweise folgendermaßen aus.

{
  "name": "B4AE.WEB.JOBP.SMOKE-TEST",
  "category": "EXAMPLES",
  "parameters": {
    "B4AW_TEST_I#":"Demo"
  }
}

Als Antwort erhält man die RunId des gestarteten Services.

{
  "runId": 1919242
}

Wartung und Administration¶

Bei der |b4ARA| fallen gewisse administrative Aufgaben an. Die Modulausführung erzeugt Ausgabedateien und Einträge in der Datenbank. Diese sollten regelmäßig bereinigt werden. Dafür bietet die |b4ARA| zwei DELETE-Endpunkte an. Mit der ersten Möglichkeit können anhand der Id alle Daten zu einem spezifischen Lauf gelöscht werden.

http[s]://<host>:<port>/best4automic-rest-v2/api/module/{id}

Der zweite DELETE-Endpunkt löscht alle Daten, die älter sind als eine ausgewählte Anzahl an Tagen.

http[s]://<host>:<port>/best4automic-rest-v2/api/module/cleanup

Bei dieser Anfrage bedarf es einem Body, der mitgegeben werden muss.

{
  "numberOfDaysToKeep": 7
}

Für den Service-Bereich gibt es zwei Endpunkte, die bei der Administration unterstützen. Für diese werden in dem Package B4A.WEB bereits Services mit ausgeliefert. Sie können damit direkt aus dem |b4ASP| aufgerufen werden. Um die Automation Engine nicht mit zu vielen Anfragen zu konfrontieren besitzt die |b4ARA| mehrere Caches. Zum Einen wird die XML-Konfiguration der Services und Rollen zwischengespeichert. Gibt es Änderungen an dieser, muss folgende PUT-Anfrage aufgerufen werden.

http[s]://<host>:<port>/best4automic-rest-v2/api/service/admin/config/reload

Zusätzlich werden Objekte zwischengespeichert, um diese nicht ständig aus der Automation Engine abzufragen. Dies erfordert, dass diese Caches bei Änderungen an den Services zurückgesetzt werden. Dies geschieht mit folgender PUT-Anfrage.

http[s]://<host>:<port>/best4automic-rest-v2/api/service/admin/cache/reset