08 Erweiterte Funktionalität für Portalbetreiber #

Sämtliche Funktionen in diesem Kapitel erfordern eine SUPERADMIN Berechtigung bzw. den Zugang zur Google Cloud Konsole.

08.1 Daten im Bucket Browser ablegen #

Öffnen Sie die Google Cloud Konsole unter: https://console.cloud.google.com. Unter Projekt auswählen, wählen Sie das entsprechende Projekt für das Portal aus. Anschließend gehen Sie links auf das Navigationsmenü. Im Navigationsmenü dann unter Speicher auf Browser.

Dort finden Sie die Speicherorte ihrer verschiedenen Portale und Projekte. Suchen Sie den Ordner, in dem die Maschinen des Portals gespeichert werden. Der Ordner ist folgendermaßen benannt “Portal Name”.appspot.com. Dort finden Sie nun einen Ordner mit dem Namen “docs/”. Dieser Ordner wird automatisch bei der Erstellung des Portals angelegt. Im ”docs/” Ordner finden Sie die verschiedenen angelegten Organisationen mit ihren Organisations-IDs.

Die Organisations-ID finden Sie, in dem Sie im Portal die entsprechende Maschine aufrufen, die einen Bucket Browser erhalten soll. Nun können Sie in der URL-Zeile des Browsers die Organisations-ID und Maschinen-ID auslesen.

Öffnen Sie in der Google Cloud Konsole den entsprechenden Organisationsordner. Im Organisationsordner befinden sich die Maschinenordner, benannt mit der Maschinen-ID. Öffnen Sie auch hier den entsprechenden Maschinenordner. Nun befinden Sie sich im Ordner, auf den der Bucket Browser der Maschine Zugriff hat.

Sie können ihre Daten und Ordner nun per Drag&Drop oder über Dateihochladen bzw. Upload Folder in den Bucket Browser laden. Die Ordner bzw. Datenstruktur die Sie hier anlegen wird ebenso im Bucket Browser der Maschine angelegt.

08.1.1 Dokumentationen im Hilfe-Bereich hinterlegen #

Öffnen Sie die Google Cloud Konsole unter: https://console.cloud.google.com. Unter Projekt auswählen, wählen Sie das entsprechende Projekt für das Portal aus. Anschließend gehen Sie links auf das Navigationsmenü. Im Navigationsmenü dann unter Speicher auf Browser (Siehe Abbildungen bei Daten in Bucket Browser ablegen).

Dort finden Sie die Speicherorte ihrer verschiedenen Portale und Projekte. Suchen Sie den Ordner, in dem die Maschinen des Portals gespeichert werden. Der Ordner ist folgendermaßen benannt “Portal Name”.appspot.com. Dort finden Sie nun einen Ordner mit dem Namen “documentation/”, öffnen Sie diesen Ordnern. Alle Daten, die Sie in diesem Ordner hinterlegen, werden im Hilfe-Bereich unter Dokumentation im Portal angezeigt. Wie auch beim Bucket Browser können Daten per Drag&Drop oder über Dateihochladen in den Ordner verschoben werde.

08.1.2 Einrichten der Pub/Sub Trigger-Aktion #

Mithilfe von z.B. Pythonscripts können komplexe Analysen auf den ankommenden Daten ausgeführt werden, wie beispielsweise die Überwachung eines Gesamtzustands, der von mehreren Parametern abhängig ist. Dies könnte z.B. sein, wenn KI eine Abnutzung erkennt oder vor einem möglichen Ausfall warnt. Damit die Ergebnisse dieser Analyse nicht unbeachtet verloren gehen, kann das Ergebnis als Pub/Sub-Nachricht veröffentlicht werden. Anschließend kann ein Abonnement und eine Trigger-Aktion eingerichtet werden, sodass z.B. eine E-Mail verschickt wird. Im Folgenden werden die einzelnen Schritte dargestellt:

1. Endpunkt in der API-Konfiguration einrichten: In der Maschinenkonfiguration befindet sich der Tab API Konfiguration dort kann unter Neuer API-Endpunkt eine neue API-Konfiguration erstellt werden. Wenn eine API-Konfiguration erstellt werden soll, muss dieser eine URL-Endung gegeben werden, außerdem muss eine Aktion ausgewählt werden, die bei Aktivierung ausgeführt werden soll. Zusätzlich kann die maximale Anzahl an Anfragen pro Stunde eingestellt werden.

2. Pub/Sub-Topic mit Parametern erstellen: In der GCP-Konsole unter Pub/Sub können Sie ein neues Thema erstellen. Dieses Thema veröffentlicht eine Nachricht, mit der eine Trigger-Aktion ausgelöst werden kann. Dafür vergeben Sie für das neue Thema eine ID.

3. Push-Subscription in der Pub/Sub-Konfiguration einrichten: Wenn ein Thema erstellt wurde, anschließend in der GCP auf die ID des erstellten Pub/Sub-Themas klicken, auf dieser Seite (Themendetails) nach unten scrollen zu den ABOS, dort das ABO ERSTELLEN Drop-Down-Menü öffnen und auf Abo erstellen klicken. Um das Abo hinzuzufügen, muss zunächst eine Abo-ID ausgewählt werden, auf die gehört werden soll. Anschließend wählen Sie beim Zustellungstyp den Type Push aus und tragen bei Endpoint URL die URL ein, die zuvor in der API Endpunkt-Konfiguration festgelegt wurde.

WICHTIG: Die Checkbox zur Aktivierung der Authentifizierung (Authentifizierung aktivieren muss ebenfalls gesetzt werden. Unter Dienstkonto muss das Dienstkonto des Projektes ausgewählt und bei Zielgruppe trigger.api eingetragen werden. Anschließend speichern und wieder in die API-Konfiguration des Portals wechseln.

4. Nachricht im Pub/Sub Topic veröffentlich (z.B. über Python-Code): Eine Nachricht kann beispielsweise über Python-Code veröffentlicht werden. In dieser Nachricht können Parameter im json-file erstellt werden. Diese werden über das Pub/Sub-Topic an die entsprechende Trigger-Aktion weiter geleitet (siehe Abbildung unterhalb).

5. Trigger-Aktion einrichten: Unter Trigger-Aktion in der Maschinenkonfiguration kann eine Trigger-Aktion ausgewählt werden, wie zum Beispiel E-Mail. Im Nachrichtentext können die Parameter des Pub/Sub-Topics mit Platzhaltern eingefügt werden, sodass diese automatisch mit den Werten aus dem Pub/Sub-Topic ersetzt werden.

6. Trigger-Aktion zum API-Endpunkt hinzufügen: Die erstellte Trigger-Aktion kann nun dem API-Endpunkt in der Maschinenkonfiguration hinzugefügt werden. Nun muss der Endpunkt über das Play-Symbol aktiviert werden.

08.1.3 Administration API / Gateway API #

Die Administrations API ermöglicht es Maschinen, Gateways, Maschinengruppen und Organisationen von außerhalb des Portals mit anderen Systemen, wie z.B. Salesforce anzulegen. Wenn Sie Interesse an dieser Funktion haben, kontaktieren Sie uns bitte. Eine ausführliche Dokumentation der Funktionen kann über swagger abgerufen werden. Dafür müssen Sie in den folgenden Link ihre Portal-URL einsetzen. (Diese Dokumentation ist nur zugänglich für Benutzer, die auch dem GCP-Projekt hinzugefügt wurden.)

• Administration API: https://portalURL/documentation/administration/administration.html
• Gateway API: https://portalURL/documentation/gateway/gateway.html

08.1.4 Portal-spezifische Eingabefelder für Maschinen und Gateways #

Wenn eine Maschine oder ein Gateway erstellt wird, gibt das Portal bestimmte Felder vor, die ausgefüllt werden müssen, z.B. Name, Kategorie, Location und Organisation. Es kann jedoch sein, dass zusätzliche Informationen ergänzt werden sollen, die den Benutzern dann zur Verfügung stehen und gespeichert werden sollen. Um dies zu ermöglichen, gibt es eine flexible Definition von Portal-spezifischen Feldern. Über ein Schema-Konfigurations-File werden die Felder für Gateways und Maschinen definiert. Diese werden dann im Hintergrund hinzugefügt und können z.B. über die Administration- oder die vorhandene Maschinen-API befüllt werden. Momentan ist nur das Backend dafür vorbereitet. In einem nächsten Schritt wird diese Funktionalität mit den zusätzlichen Feldern in der Portaloberfläche eingebunden. Dafür wird der Maschinenkonfiguration und der Gatewaykonfiguration ein neuer Tab hinzufügen. In diesem Tab werden alle Informationen der zusätzlichen Felder angezeigt und können bearbeitet werden.

Im Folgenden die Erläuterung, wie neue Felder dem Backend hinzugefügt werden:

1. Schema-Konfigurations-File (JSON): Im Schema-Konfigurations-File werden die neuen Felder entsprechend dem Schema, das unterhalb dargestellt ist angelegt. Das Schema muss unbedingt eingehalten werden, damit die Daten korrekt übernommen werden. Es können beliebig viele Felder definiert werden, dafür das Schema entsprechend der Vorlage erweitern.

• name: kann frei gewählt werden
• label: Bezeichnung, die in der Portaloberfläche angezeigt wird
• type: Datentyp, aktuell STRING, INTEGER, FLOAT
• mode: ob das Feld notwendig ist oder nicht
• description: Beschreibung, wird nur im Backend angezeigt
• value: hinterlegen von Default-Werten möglich, z.B. um im Frontend ein Dropdown Menü mit vorgegebenen Werten anzulegen

2. JSON-Datei im GCP-Projekt ablegen und Portaleinstellungen vornehmen: Die erstellte JSON-Datei muss im Bucket des zum Portal gehörenden GCP-Projektes abgelegt werden. Dafür in der GCP und Cloud Storage die Datei im folgenden Ordnerpfad ablegen: projectID.appspot.com / config / metadata

Zusätzlich muss in den allgemeinen Portaleisntellungen (verwaltet durch den Portalbetreiber) die entsprechende Einstellung zur JSON-Datei vorgenommen werden. Kontaktieren Sie bitte Ihren Portalbetreiber für Details.

3. Maschinen und Gateways mit der API anlegen: Wird eine Maschine oder ein Gateway angelegt, werden die neuen Felder automatisch im Datastore in der Entität MachineMetadata bzw. GatewayMetadata angelegt und mit der Maschine oder dem Gateway verknüpft. Außerdem wird im Datensatz der Maschine in der BigQuery eine neue Tabelle ‘Metadaten’ erstellt. In dieser Tabelle befinden sich alle Informationen aus den Metadaten-Feldern für Gateways und Maschinen. Wird ein Eintrag geändert, wird eine neue Reihe inklusive des Zeitstempels hinzugefügt.

Sobald über die API zusätzliche Daten zu einer Maschine oder zu einem Gateway hinzugefügt werden, wird in deren Konfiguration der Tab ”Metainformationen” angezeigt. Dort können die hinzugefügten Werte verändert werden. Die verfügbaren Feldtypen hierfür sind:

• Text
• Zahl
• Dropdown
• Checkbox

Informationen über den Zeitpunkt der Erstellung, den Urheber, die Maschinenkategorie, sowie die Organisation, werden hier ebenfalls angezeigt. Die Werte werden in BigQuery gespeichert, sodass sie zur einfachen Abfrage zur Verfügung stehen. Diese Funktion ist nur in der neuen Oberfläche verfügbar und steht nach dem Design-Update bereit.

08.1.5 Verhindern von langen Ladezeiten bei Diagrammen mit vielen Signalen #

Auf den benutzerdefinierten Seiten können verschiedene Graphen angezeigt werden, die aktuelle Werte von ausgewählten Signalen in Echtzeit repräsentieren. Vor allem beim Liniendiagramm kann es zu langen Ladezeiten kommen, wenn Werte von Signalen der letzten zwei Stunden angezeigt werden sollten. Nun haben wir die Möglichkeit geschaffen, dass die Daten aus einem anderen Zwischenspeicher abgefragt werden. Dies sollte die Ladezeiten bei vielen Signalen auf den Diagrammen deutlich verkürzen. Die Auswahl dieses Zwischenspeichers (InfluxDB) ist optional und wird durch den Portalbetreiber vorgenommen. Bitte kontaktieren Sie uns, sollte dieser Wunsch bestehen.

08.1.6 Single-Sign-On mit Google SAML provider #

Für alle Kunden, die Google ebenfalls für ihre Mitarbeiter nutzen, z.B. mit der G-Suite und E-Mail-Konten, gibt es die Möglichkeit, dass sich diese nutzer nicht mehr auf unserer Portaloberfläche einloggen müssen, sondern ihre Google Log-In-Daten verwendet werden. Ist beispielsweise die Benutzerin bereits angemeldet, genügt das aufrufen der URL und sie erreicht direkt das Übersichtsdashboard. Einzige Voraussetzung ist, dass die Benutzer mit derselben E-Mail-Adresse im Portal angelegt sind.

08.1.7 Konfigurieren von Maschinenkategorien #

Sollen Maschinenkategorien hinzugefügt oder bearbeitet werden, kann dies in der Maschinen Kategorie Administration druchgeführt werden. Dafür öffnen Sie das User-Menü und klicken unter Einstellungen auf Maschinen Kategorie. Dieses Menü ist ausschließlich für SUPERADMINs erreichbar. Über den Import Kategorien Button werden die bereits vorhandenen Maschinenkategorien geladen. Wie auch bei anderen Administrationsseiten kann über den Aktionsbutton jeder Eintrag bearbeitet oder gelöscht werden.

Über den Neue Kategorie Button kann eine neue Maschinenkategorie hinzugefügt werden. Für eine neue Kategorie muss der Name und Display name vergeben werden. Referenz Maschine und Maschinen Tag sind Felder die bei jeder Maschinenkategorie vorhanden sind. Unter Kategorie Icon kann ein Icon für die Kategorie hinzugefügt werden, welches auf der Maschinenkarte angezeigt wird. Im Bereich Benutzerdefinierte Spalten können eigene Spalten mit Variablen zu der Maschinenkategorie hinzugefügt werden. Diese Spalten werden dem User beim Anlegen der Maschine angezeigt.