Skriptmodul

Das Scripting Module integriert Octave- und Python-Engines, sodass Benutzer Berechnungen in beiden Sprachen innerhalb des Requirements & Systems Portal schreiben und ausführen können. Das Modul ist dafür ausgelegt, komplexe Berechnungen durchzuführen, die mit der standardmäßigen ValiEngine nicht möglich sind.

Wenn Benutzer andere Objekte als numerische Valis bearbeiten möchten, müssen sie die Python API des Requirements & Systems Portal verwenden. Beispiele für Anwendungsfälle sind:

• Erstellen eines Werts und dessen massenhaftes Hinzufügen zu mehreren Blocks

• Massenbearbeitung von Anforderungskennungen

• Ausführen von Simulationen mit Python

• Umwandeln von Einheiten von Leistungswerten in kW.

• Ausführen eines benutzerdefinierten Workflow-Verhaltens auf Basis automatisierter Trigger

Ablauf des Scripting Module

Zur Verwendung des Moduls erstellt der Benutzer ein neues Skript, fügt Ein- und Ausgaben hinzu, schreibt Code in .m oder .py und führt den Code aus, um die gewünschte Ausgabe zu erhalten.

Workflow des Scripting Module.

Erstellen eines neuen Skripts

Um ein neues Skript zu erstellen, klicken Sie innerhalb der Scripting Modules auf die Option „+ Script“ (1).

Es erscheint ein Dialogfeld, in dem Sie den Skriptnamen eingeben, die Engine (Octave oder Python) auswählen und zusätzliche Optionen zur Verwendung/Wiederverwendung aus den Vorlagen festlegen können.

Option „Neues Skript erstellen“

Sobald ein neues Skript erstellt wurde, können Benutzer zusätzlich Text-, JSON- und YAML-Dateien für ihre Skripte anlegen. Um eine neue Datei hinzuzufügen, klicken Sie auf die Option „+Add file“ (1), vergeben einen Namen und wählen im Dialogfeld einen Dateityp aus. Dadurch wird dem Skript eine Datei hinzugefügt.

Um eine der zusätzlich erstellten Dateien zu verwenden, müssen Benutzer die folgenden zwei Codezeilen am Anfang der Datei main.py einfügen:

import site
site.addsitedir('script_code/')

Nach diesen beiden Zeilen können alle zusätzlichen Dateien mit der standardmäßigen import Anweisung aufgerufen werden.

Verwaltung von Secrets:

Um die Verwendung notwendiger Zugangsdaten bei Skripten, die entweder eine Verbindung zu unserer API oder zu der anderer Tools herstellen, nicht offenzulegen, können persönliche Secret-Variablen definiert werden. Diese können zur Laufzeit des Skripts aufgerufen werden, ohne dass das Risiko besteht, sie anderen Benutzern in der Deployment-Umgebung offenzulegen, indem sie in Skriptdateien gespeichert werden.

Wie und wo sie hinzugefügt werden

Secrets können im Einstellungsbereich unter User Secrets definiert werden. Diese Secrets können innerhalb des Skripts wiederverwendet werden, um sich beim Requirements & Systems Portal anzumelden. Hier ist ein kurzes Video, das zeigt, wie Sie User Secrets erstellen können.

Wie der Name schon sagt, sind diese Secrets für jeden Benutzer eindeutig und nur für diejenigen zugänglich, die sie definiert haben.

Verwendung von Secrets in einem Skript

Durch Importieren des Secret-Namens aus dem Modul „.settings“ können Benutzer Secrets zur Authentifizierung innerhalb von Skripten verwenden.

from .settings import USERNAME, PASSWORD  #Groß-/Kleinschreibung beachten, verwenden Sie dasselbe Wort wie in den User Secrets.

LOGIN_DATA = {
    'domain': 'API_URL',
    'username': USERNAME,
    'password': PASSWORD
}

Zur Laufzeit rufen die Skripte den Wert dieser Variablen aus den in den Benutzereinstellungen des Benutzers definierten Secrets ab, der das Skript auslöst, und sie hängen von den Berechtigungen dieses Benutzers ab. Skripte sollten keine Ausgabefunktionen für diese Variablen enthalten, damit User Secrets nicht offengelegt werden.

Allgemeine Skripte, die so eingerichtet sind, dass sie durch Automatisierungen ausgelöst werden, können mit einer Authentifizierung durch einen Benutzer auf Admin-Ebene eingerichtet werden, der Leseberechtigungen für alle anderen Benutzer entfernen kann, sodass das Skript verborgen bleibt.

Warteschlangensystem

Mit dem Warteschlangensystem können Benutzer sicher sein, dass ihre Skripte immer ausgeführt werden, insbesondere wenn vordefinierte Automatisierungen regelmäßig benutzerdefinierte Workflow-Skripte auslösen. Rufen Sie dazu bitte den Abschnitt „Runs“ auf. Dort können Sie entweder alle Ausführungen aller Skripte oder die Ausführungen eines bestimmten Skripts ansehen.

Alle Skriptausführungen werden nun im Deployment gespeichert und können pro Skript oder für alle Skripte eingesehen werden, indem oben im Baum des Script Module die Option „All scripting“ ausgewählt wird.

Sie können ein laufendes Skript stoppen, indem Sie im Dropdown-Menü Actions auf die Schaltfläche „Stop“ klicken.

Aktion „Stop“ für ein Skript.

Verwaltung von Berechtigungen

Skripte haben eigene Berechtigungen, die entweder direkt im Scripting Module oder im Project Module unter „Permissions“ verwaltet werden können.

Skripte über ein Dashboard ausführen

Benutzer können auch benutzerdefinierte Interaktions-Dashboards mithilfe von Schaltflächen vom Typ „Run Script“ erstellen. Diese ähneln den zuvor verfügbaren Request-Schaltflächen zum Auslösen von REST-Aufrufen, können jedoch so konfiguriert werden, dass sie per Knopfdruck entweder ein einzelnes oder mehrere Skripte ausführen.

Durch die Verwendung der Python API in den aufgerufenen Skripten können benutzerdefinierte Interaktions-Dashboards eingerichtet werden, in denen Elemente wie Standard-Textfelder als Ein- und Ausgabefelder für ein Skript verwendet werden können, das dann auch direkt und indirekt andere angezeigte Elemente beeinflussen kann.

Gehen Sie dazu in das Project Module und dort zu „Dashboards“. Öffnen Sie dann Ihr benutzerdefiniertes Dashboard und klicken Sie auf das Plus-Symbol in der unteren rechten Ecke. Wählen Sie anschließend im Dropdown-Menü „Actions“ die Option „Run script“ aus.

Dadurch wird eine Schaltfläche erstellt, über die Sie Skripte ausführen können, die bestimmte Blocks Ihres Dashboards aktualisieren.

Ein interessanter Anwendungsfall ist das Zählen bestandener und fehlgeschlagener Testläufe und deren Anzeige in einem Textblock auf demselben Dashboard.

Skript & Automatisierungen

Voreingestellte Automatisierungen können Skripte auslösen. Beispielsweise kann eine komplexe Berechnung so eingerichtet werden, dass sie automatisch ausgeführt wird, wenn ihre definierten Eingaben geändert werden. Zusätzlich kann mithilfe der Python API des Requirements & Systems Portal auch maßgeschneidertes komplexes Verhalten programmiert werden, um benutzerdefinierte Workflows zu erstellen.

Nicht nur lösen Automatisierungen Skripte aus, sie übergeben auch Informationen darüber, welche Objekte sie ausgelöst haben, sodass Skripte direkt auf diese Objekte wirken können. Die Objektinformationen werden in der Dictionary-Variablen „kwargs“ unter dem Schlüssel „triggered_objects“ bereitgestellt, wie im folgenden Beispiel:

object_data = kwargs['triggered_objects'][0]

Automatisierungen führen Skripte auch dann aus, wenn sie von Benutzern ausgelöst werden, die keine Berechtigung haben, diese Skripte anzuzeigen. Dadurch sind Workflow-Anpassungen und Berechnungen durch Admin-Benutzer möglich, während der Zugriff auf den zugrunde liegenden Code, etwa proprietäre mathematische und physikalische Modelle, eingeschränkt bleibt.

Beispiel-Workflow-Skripte finden Sie im öffentlichen Repository valifn im Ordner templates.

Benutzerdefinierte Valifn-Images

On-Prem-Benutzer haben zusätzlich die Möglichkeit, ihre valifn-Instanz so anzupassen, dass beliebige Python-Pakete ausgeführt werden können, sofern ihre Server-Hardware dies bewältigen kann. On-Prem-Benutzer können außerdem verwalten, welches valifn-Image zur Laufzeit eines Skripts verwendet werden soll.

Wie gezeigt, ist diese Option als Textfeld in den General Settings für jedes einzelne Skript verfügbar.

So erstellen Sie ein benutzerdefiniertes Image

Weitere Anweisungen zum Einrichten eigener valifn-Images finden Sie auf den Dokumentationsseiten des öffentlichen Repository:

• Usage · valispace/valifn-octave Wiki (github.com)

• Usage · valispace/valifn-python Wiki (github.com)

Beispiele für Python-Skripte

Verwendbare Skriptbeispiele finden Sie sowohl im Beispielprojekt Valicopter 5000 einer Deployment-Umgebung (neue Deployments) als auch im öffentlichen Github-Repository von ValiFn.

Diese Beispiele können manuell oder durch Automatisierungen ausgelöst werden (in manchen Fällen ausschließlich) und können entweder unverändert verwendet oder von Benutzern angepasst werden, um beliebiges maßgeschneidertes Verhalten auszuführen.

Viele dieser Beispiele wurden erstellt, um die Möglichkeiten des Scripting Module und der Automatisierungen zur Erstellung maßgeschneiderter automatisierter Workflows zu demonstrieren. Benutzer werden ermutigt, bestehende Skripte an ihre Bedürfnisse anzupassen und allgemeingültige Skripte sowie Verbesserungen mit dem öffentlichen Repository von ValiFn zu teilen.

Warnung bei verdächtigen untergeordneten Elementen (Automatisierung)

Begründung

Dieses Skript wird durch eine Automatisierung ausgelöst, die so eingerichtet sein muss, dass sie durch eine Änderung an einer bestehenden Anforderung ausgelöst wird, da das Skript auf die Eigenschaften der bearbeiteten Anforderung wirkt. Die derzeit definierte Aktion besteht darin, in jedem seiner untergeordneten Elemente (falls vorhanden) eine Diskussion mit einer benutzerdefinierten Nachricht zum Änderungsstatus der übergeordneten Anforderung zu platzieren.

Vorgeschlagene Anpassung

Andere mögliche Aktionen wären das Erstellen einer Aufgabe oder das Hinzufügen der bearbeiteten Anforderung zu einem Review.

Aktuelle Aktionen

• Prüft, ob die Anforderung, die die voreingestellte Automatisierung ausgelöst hat, untergeordnete Elemente hat

• Falls sie untergeordnete Elemente hat, wird in jeder untergeordneten Anforderung eine Diskussion veröffentlicht, die darauf hinweist, dass die übergeordnete Anforderung aktualisiert wurde.

• Die Diskussion enthält die Identität des Benutzers, der die Anforderung bearbeitet und dadurch die Automatisierung ausgelöst hat.

Neue Aufgabe (Automatisierung)

Begründung

Beim Erstellen eines neuen Blocks bestand die Anforderung eines Interessenten darin, dass Aufgaben automatisch erstellt und einem bestimmten Benutzer zugewiesen werden. In diesem Beispiel erstellt eine voreingestellte Automatisierung, die durch das Erstellen eines neuen Blocks ausgelöst wird, eine neue Aufgabe und weist ihr einen Benutzer zu. Es war vorgesehen, das auslösende Objekt als Eingabe hinzuzufügen, aber diese Entwicklung wurde nicht abgeschlossen.

Vorgeschlagene Anpassung

Verwenden Sie das kwargs['triggered_objects'][0], um die Informationen des Objekts zu extrahieren, das die Automatisierung ausgelöst hat, und fügen Sie sie dem Eingabefeld der Aufgabe hinzu.

Aktuelle Aktionen

• Erstellt eine neue Aufgabe, die einem angegebenen Benutzer zugewiesen wird.

Anforderungsstatistiken

Begründung

Ein einfaches Beispiel dafür, wie ein stärker angepasster Zähler mit mehr statistischen Werten erstellt werden kann als denjenigen, die in den standardmäßig in Dashboards und Analysedokumenten verfügbaren Blöcken bereitgestellt werden. Er kann manuell ausgeführt oder so eingerichtet werden, dass er durch eine Automatisierung jedes Mal ausgeführt wird, wenn eine Anforderung erstellt, geändert oder gelöscht wird.

Vorgeschlagene Anpassungen

1. Nehmen Sie die extrahierten Informationen zu Anforderungen und leiten Sie daraus komplexere Statistiken ab, indem Sie sie mit zuvor aktualisierten Werten vergleichen. Jeder Wert kann angeben, wie stark er sich erhöht/verringert hat, ausgedrückt in Prozent.

2. Vergleichen Sie Bereitstellungsstatistiken, indem Sie das Skript einzeln in jedem Projekt ausführen und eine spezielle Instanz hinzufügen, die Statistiken aus jedem Projekt bezieht und sie in einem Dashboard anzeigt.

3. Legen Sie eine benutzerdefinierte Warnung für Projektadministratoren fest, wenn die Statistiken einen plötzlichen Rückgang der Anzahl von Anforderungen zeigen, was auf eine möglicherweise drastische Änderung am Projekt hinweist.

Aktuelle Aktionen

• Erstellt allgemeine Anforderungsstatistiken für ein einzelnes Projekt in der Bereitstellung.

• Aktualisiert vorab erstellte Valis mit Ergebnissen.

Spezifikationserstellung

Begründung

Ein Beispielskript, das die Leistungsfähigkeit der Python-API zur Erstellung vollständig automatisierter Berichte demonstriert. Obwohl das Hauptskript auch auf der Dokumentationsseite für Integrationen verfügbar ist, wurde diese spezielle Version für die Ausführung über das Skriptmodul der Bereitstellung angepasst.

Es kann durch eine Automatisierung ausgelöst oder manuell ausgeführt werden.

Vorgeschlagene Anpassungen

1. Erstellen Sie einen vollständigen Bericht, indem Sie den aktuellen Prozess zum Abrufen von Anforderungen so anpassen, dass Blöcke und andere Objekte extrahiert werden, die im Bericht ausgefüllt werden sollen.

2. Fügen Sie weitere anpassbare Felder hinzu, die aus benutzerdefinierten Dashboard-Textblöcken abgerufen werden können und von denen aus es ebenfalls ausgelöst werden kann.

3. Ändern Sie die endgültige Ausgabedatei in eine PDF-Datei anstelle einer bearbeitbaren Word-Datei.

Aktuelle Aktionen

• Verwendet eine Word-Datei als Vorlage aus einer bestimmten Bereitstellung und gibt als Ausgabe generierte Dateien zurück – so viele, wie es Spezifikationen gibt –, die in der Dateiverwaltung der Bereitstellung abgelegt werden (siehe Specification export based on Microsoft Word Template für weitere Details).

Test-Dashboard

Begründung

Dashboard-Zähler haben das Testmodul noch nicht eingeholt, und es gibt noch keine automatisierten Zähler für Tests. Dieses Skript wurde als Machbarkeitsnachweis für einen benutzerdefinierten Zähler entwickelt, der noch nicht implementiert wurde. Es war ursprünglich dafür gedacht, manuell über eine Run Script button in a Dashboard ausgelöst zu werden.

Vorgeschlagene Anpassungen

1. Erweitern Sie die Teststatistiken, die an Dashboards zurückgemeldet werden.

2. Wenn ein Testlauf erfolgreich ist, veröffentlichen Sie das Ergebnis in einer verknüpften Aufgabe und ändern Sie deren Status auf „Erledigt“.

Aktuelle Aktionen

• Gibt eine Zeichenfolge zurück, die in vordefinierten Dashboard-Textblöcken platziert wird und berechnete Testlaufstatistiken enthält.

• Es kann Eingaben aus einer Automatisierung übernehmen oder manuell ausgelöst werden.