Python- und HCL-Skripterstellung in Robots

Die Robots-App bietet ein systemeigenes, cloudbasiertes Skripting, das Sie zur Datenanalyse und zur Automatisierung von Teilen des Diligent One-Workflows Ihrer Organisation verwenden können. Das Skripting in der Robots-App vereinigt die vollständige Leistungskraft von Python und allen unterstützten Bibliotheken mit HighBond Command Language (HCL), unserer benutzerdefinierten Python-Bibliothek zur domänenfokussierten Datenanalyse und der Automatisierung von Diligent One.

Die Robots-App unterstützt weiterhin die Datenanalyse und Datenautomatisierung mit ACLScript und Skripts, die aus Analytics hochgeladen werden. Sie können also von bestehenden Investitionen in ACL (Audit Command Language) profitieren und gleichzeitig alle Möglichkeiten nutzen, die Python, eine branchenübliche Programmiersprache, und HCL bieten.

Drei Robottypen

Die Robots-App beinhaltet drei Robottypen. Sie ähneln sich zwar in vielen Punkten, unterstützen aber unterschiedliche Skriptszenarien:

• ACL-Robot Unterstützt eine umfassende Datenanalyse mit Skripts, die Sie aus Analytics hochladen, und mit geplanten Aufgaben. Skripts können in der Cloud oder lokal ausgeführt werden.

• HighBond-Robot Unterstützt eine umfassende Datenanalyse mit Python/HCL-Skripts, die direkt im Robot programmiert werden, und geplanten Aufgaben. Skripts können nur in der Cloud ausgeführt werden.

• Workflow-Robot Unterstützt die einfache Datenanalyse oder die Automatisierung von Teilen des Diligent One-Workflows mit Python/HCL-Skripten, die direkt im Robot erstellt werden, sowie geplante oder ereignisbasierte Aufgaben. Skripts können nur in der Cloud ausgeführt werden.

  Hinweis

  Um auf Workflow-Robots zugreifen zu können, muss Ihnen der Benutzertyp des Systemadministrators mit einem Professional-Abonnement zugewiesen werden.

  Ziel ist es, dass ein Systemadministrator mit einem Professional-Abonnement Aufgaben in Workflow-Robots konfigurieren kann, die von Diligent One-Ereignissen ausgelöst werden. Diese Funktionen werden gerade entwickelt und sind noch nicht verfügbar.

Vergleich der Robottypen

Die drei Robottypen sind für unterschiedliche Zwecke vorgesehen und unterscheiden sich in ihren Funktionen. Sie können ACLScript und Python/HCL nicht in einem einzelnen Robot kombinieren.

Robot-Eigenschaft	ACL-Robot	HighBond-Robot	Workflow-Robot
Beabsichtigter Zweck	Datenanalyse und Automatisierung		Automatisierung der Diligent One-Plattform
Unterstützte Sprache	ACLScript	Python Pandas, NumPy, Requests und andere Standardbibliotheken von Python Selbsterstellte Python-Bibliothek namens HCL (HighBond Command Language)
Ort der Skripterstellung	Analytics	Robots
Ort der Skriptausführung	Cloud lokal vor Ort	Cloud
Optionen für die Ausführung einer Aufgabe	geplant Ad-hoc-Ausführung (manuell)		durch Diligent One-Ereignis ausgelöst geplant Ad-hoc-Ausführung (manuell)
Maximale Aufgabenausführungsdauer	cloudbasierter Robots-Agent: 60 Minuten lokaler Robots-Agent: durch Kundennetzwerk kontrolliert	Keine Beschränkung Hinweis Eine Begrenzung auf 12 Stunden ist geplant, wurde aber noch nicht umgesetzt. Wenn Sie eine Aufgabe, die schon zu lange läuft, stoppen müssen, können Sie auf der Registerkarte Aufgabenausführungen auf Aufgabenausführung abbrechen klicken.	15 Minuten
Maximale Anzahl der Aufgaben, die gleichzeitig ausgeführt werden können	5	5	50
Notwendige Berechtigungen	Mitarbeiter beim Robot Ausmaß des Zugriffs wird durch die Rolle des Mitarbeiters beim Robot kontrolliert (Eigentümer, Bearbeiter, Kontrollprüfer)		Benutzertyp des Systemadministrators mit einem Professional-Abonnement

Robots-Skript-Editor

HighBond-Robots und Workflow-Robots enthalten einen integrierten Skript-Editor für die Programmierung von Python/HCL-Skripts und deren (manuelle) interaktive Ausführung. Der Skript-Editor ist auf Basis der Jupyter Notebook App gestaltet, einer beliebten Entwicklungsumgebung im Data-Science-Bereich. Informationen über den Ansatz des Skript-Editors finden Sie unter „Zellenbasierter Ansatz für die Skripterstellung“.

Zellenbasierter Ansatz für die Skripterstellung

Die auffälligste Funktion des Skript-Editors ist die Möglichkeit, mehrere Zellen zu verwenden, die einzelne Codeblöcke enthalten und ein einzelnes Skript bilden. Wenn Sie sich noch nicht mit Jupyter Notebook auskennen, könnte der zellenbasierte Ansatz der Skripterstellung anfangs kompliziert erscheinen. Er ist jedoch einfach und hat Vorteile, die Sie schon bald schätzen werden.

Hauptmerkmale der zellenbasierten Skripterstellung

• Mehrere Zellen sind optional Sie müssen mehrere Zellen nicht verwenden, wenn Sie dies nicht möchten. Es ist möglich, ein gesamtes Skript mit nur einer Zelle zu erstellen und auszuführen.

• Logische Unterteilungen Zellen ermöglichen die Aufteilung eines Skripts in logische Blöcke Ihrer eigenen Wahl. Diese Blöcke können dann einzeln und in beliebiger Reihenfolge manuell ausgeführt werden oder als gesamte Sequenz.

  Eine einfache Aufteilung eines Skripts in vier Zellen könnte beispielsweise so aussehen:

  • Erste Zelle Python-Bibliotheken importieren

  • Zweite Zelle Daten importieren

  • Dritte Zelle Datenanalyse durchführen

  • Vierte Zelle Ergebnisse der Analyse ausgeben

• Vorteile von Zellen Die Verwendung von Zellen zur Skriptentwicklung hat die folgenden Vorteile:

  • Sie können isoliert an einzelnen Zellen arbeiten, diese testen und verbessern, während Sie die Skriptlogik anderer Zellen vorübergehend ignorieren.

  • Nachdem Sie die ersten Importzellen ausgeführt haben, müssen Sie sie nicht immer wieder erneut ausführen, während Sie die darauffolgenden Zellen entwickeln und testen.

  • Sie können Zellen verwenden, um Ihre Skripts visuell anzuordnen. Dadurch wird die Beziehung unterschiedlicher logischer Blöcke für Sie und für andere Personen einfacher erkennbar und leichter verständlich.

• Sortierfolgeindikator Neben jeder Zelle befindet sich ein numerischer Indikator, der anzeigt, in welcher Reihenfolge die Zelle während einer Skriptsitzung ausgeführt wird. Zum Beispiel: [7].

  Sobald Sie eine Zelle ausführen, wird der Indikator erhöht. Dabei berücksichtigt er andere Zellen, die Sie in der Zwischenzeit ausgeführt haben. Ein Indikator könnte sich beispielsweise von [7] auf [10] ändern, falls Sie zwischenzeitlich zwei andere Zellen oder eine andere Zelle zweimal ausgeführt haben.

• Sitzungsspeicher und gespeicherte Werte Datenrahmen und Variablenwerte, die sich während einer Skriptsitzung im Arbeitsspeicher befinden, werden auf Basis der Reihenfolge aktualisiert, in der Sie die Zellen ausführen.

  In der Regel sehen Sie vor, dass Zellen sequenziell von oben nach unten während einer geplanten und unbeaufsichtigten Skriptausführung abgearbeitet werden. Einige Datenrahmen oder Variablenwerte könnten auf Basis der Skriptlogik im Verlauf aktualisiert werden. Falls Sie Zellen in einer anderen Reihenfolge manuell ausführen, ist es möglich, dass ein Datenrahmen oder eine Variable nicht den angenommenen Wert aufweisen. In diesem Fall könnte es zu einem Fehler oder einem falschen Ergebnis kommen. Um den Datenrahmen oder den Variablenwert wieder in den beabsichtigten Zustand zu überführen, führen Sie einfach noch einmal alle Zellen, die den Datenrahmen oder die Variable referenzieren, in der richtigen Reihenfolge aus.

• Anzeige der Zellenausgabe Standardmäßig wird bei der Ausführung einer Zelle nur die Ausgabe des letzten Ausdrucks innerhalb der Zelle angezeigt. Wenn Sie die Ausgabe mehrerer Ausdrücke in einer Zelle sehen möchten, können Sie die Ausdrücke in eigenständige Zellen stellen. Es ist jedoch bequemer, eine Konfigurationsoption im Skript-Editor einzustellen.

  • Zellen so konfigurieren, dass sie die Ausgabe aller Ausdrücke anzeigen:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "all"

  • Zellen zurücksetzen, damit sie nur die Ausgabe des letzten Ausdrucks anzeigen:

    from IPython.core.interactiveshell import InteractiveShell
    InteractiveShell.ast_node_interactivity = "last_expr"

  Tipp

  Sie können die Konfigurationseinstellung verwenden, um je nach Bedarf zwischen den beiden Modi hin- und herzuschalten. Für zusätzliche Konfigurationsoptionen für die Zellenausgabe lesen Sie die Onlinedokumentation von Jupyter oder IPython.

Tastenkombinationen im Robots-Skript-Editor

Tastenkombinationen im Skript-Editor sind praktisch und beschleunigen die Entwicklung eines Skripts. Um im Skript-Editor eine Liste der verfügbaren Tastenkombinationen anzuzeigen, können Sie eine dieser Methoden verwenden:

• Drücken Sie Strg + /.

• Klicken Sie in der Titelleiste auf das Symbol Tastenkombination .

Die verfügbaren Tastenkombinationen sind unten aufgeführt.

Tastenkombination	Aktion
Strg + Umschalt + Eingabe	Ausgewählte Zelle ausführen
Strg + Umschalt + M	Alle Zellen sequenziell ausführen
Strg + Umschalt + Y	Ausgewählte Zelle und alle Zellen darüber ausführen
Strg + Umschalt + U	Ausgewählte Zelle und alle Zellen darunter ausführen
Strg + Umschalt + I	Skriptausführung beenden
Strg + Umschalt + K Strg + Umschalt + Nach-oben-Pfeil	Zelle darüber auswählen
Strg + Umschalt + J Strg + Umschalt + Nach-unten-Pfeil	Zelle darunter auswählen
Strg + Umschalt + H Strg + Umschalt + Pos1	Erste Zelle auswählen
Strg + Umschalt + L Strg + Umschalt + Ende	Letzte Zelle auswählen
Strg + Umschalt + A	Zelle oberhalb hinzufügen
Strg + Umschalt + B	Zelle unten hinzufügen
Strg + Umschalt + D	Ausgewählte Zelle löschen
Strg + Umschalt + Z	Zelle nach oben verschieben
Strg + Umschalt + X	Zelle nach unten verschieben

Nicht im Robots-Skript-Editor enthaltene Funktionen von Jupyter Notebook

Oben wurde bereits erwähnt, dass der Robots-Skript-Editor auf Basis der Jupyter Notebook App gestaltet ist. Die folgenden Jupyter-Funktionen sind im Skript-Editor nicht enthalten, was sich bei einigen Funktionen aber während der Fortentwicklung des Projekts ändern kann:

• Vorgänge auf Zellenebene:

  • Vorgänge zum Rückgängigmachen/Wiederholen von Zellen

  • Kopieren/Einfügen von Zellen

  • Teilen/Zusammenführen von Zellen

• Markdown von Zellen (für Textinhalte)

Skriptausgabe in einer Protokolldatei speichern

Wenn Sie ein Python-/HCL-Skript mit einer Robot-Aufgabe ausführen, haben Sie die Möglichkeit, die Skriptausgabe in der Protokolldatei zu speichern, die zu jeder Aufgabenausführung gehört. Das Protokoll ist eine JSON-Datei, die denselben Namen wie die Aufgabe trägt (Aufgabenname.json).

Zum Aktivieren der Option wählen Sie Skriptausgabe in der Protokolldatei der Aufgabenausführung speichern, wenn Sie eine Version eines Skripts speichern und übermitteln. Die Option kann für jede Version eines Skripts separat konfiguriert werden. Das heißt, wenn Sie weniger Skriptausgaben wünschen, achten Sie darauf, nur die Option für die jeweilige Skriptversion auszuwählen, die die Aufgabe ausführt.

Skriptausgabe bezeichnet alles, was im stdout-Stream enthalten ist, der von einem Skript produziert wird. In der Regel ist stdout alles, was das Skript druckt oder auf dem Bildschirm anzeigt, wenn Sie ein Skript interaktiv ausführen. Durch Auswahl von Skriptausgabe in der Protokolldatei der Aufgabenausführung speichern erfassen Sie im Grunde alles, was auf dem Bildschirm dargestellt wird, dauerhaft. Diese erfasste Ausgabe kann zu Prüfzwecken bei der Entwicklung von Fehlerbehebung von Skripten hilfreich sein.

Weitere Informationen:

• Die Option gilt nur für Aufgaben. Selbst wenn Sie Skriptausgabe in der Protokolldatei der Aufgabenausführung speichern im Robots-Skript-Editor auswählen, gilt die Option nur für Skripts, die von einer Robot-Aufgabe ausgeführt werden. Wenn Sie ein Skript interaktiv im Skript-Editor ausführen, hat die Option keine Wirkung.

• Fehlermeldungen in der Protokolldatei der Aufgabenausführung Python-Fehlermeldungen (der stderr-Stream) sind immer in der Protokolldatei der Aufgabenausführung enthalten, unabhängig davon, wie Sie Skriptausgabe in der Protokolldatei der Aufgabenausführung speichern konfigurieren.

• Auf die Protokolldatei der Aufgabenausführung zugreifen Für jede Aufgabenausführung auf der Registerkarte Aufgabenausführungen ist eine entsprechende Protokolldatei verfügbar. Wählen Sie eine Aufgabenausführung aus. Die zugehörige Protokolldatei wird im Seitenbereich Details zur Aufgabenausführung im Abschnitt Ausgabe angezeigt. Sie können die Datei zur Überprüfung auf Ihren Computer herunterladen.

Von ACLScript auf Python und HCL übergehen

Python ist eine allgemein verwendbare Programmiersprache, die wesentlich komplexer als ACLScript ist. ACLScript ist eine recht leicht verständliche Skriptsprache, die ursprünglich für Audit-Analysen entworfen wurde.

Wir beabsichtigen, dass HCL im Laufe der Zeit viele Befehle und Funktionen repliziert, die in ACLScript vorhanden sind. Um mit HCL, unserer selbsterstellten Python-Bibliothek zu beginnen, benötigen Sie zumindest grundlegende Python-Kenntnisse. Wenn Sie von ACLScript zu Python/HCL wechseln möchten, sollten Sie einen guten Python-Einführungskurs absolvieren.

Programmierungskonventionen in Python

Sie müssen sich an einige Programmierungskonventionen gewöhnen, die in ACLScript nicht erzwungen werden, in Python und HCL aber schon:

• Beachtung der Groß- und Kleinschreibung Bei Python- und HCL-Syntax wird die Groß- und Kleinschreibung beachtet, bei ACLScript-Syntax aber nicht.

  In Python:

  • print("Hello World!") funktioniert.

  • PRINT("Hello World!") führt zu einem Fehler.

• Keine Abkürzung Funktions-, Methoden- und Parameternamen in Python und HCL müssen vollständig ausgeschrieben werden. Im Gegensatz zu ACLScript werden keine Abkürzungen unterstützt.

• Der Einzug ist wichtig Python verwendet den Einzug, um Kontrollstrukturen wie Bedingungsanweisungen und Schleifen zu implementieren. Ein fehlerhafter Einzug verursacht Fehler. ACLScript ignoriert Einzüge.

Externe Python-Bibliotheken

Python unterstützt eine große Anzahl von externen Bibliotheken oder Paketen, die Sie installieren können, um die Funktionalität der Python-Kerninstallation und der Python-Standardbibliothek zu erweitern. Eine externe Python-Bibliothek ist eine Sammlung zusammengehöriger Code-Module, die für bestimmte Aufgaben gedacht sind, die über das hinausgehen, was Sie mit dem eigentlichen Python und der Standardbibliothek tun können. Oder bestimmte Abläufe können schneller und einfacher als im eigentlichen Python erledigt werden.

In Diligent One Python enthaltene externe Bibliotheken

Die Diligent One-Installation von Python enthält standardmäßig bestimmte externe Bibliotheken, die Sie nicht explizit installieren müssen. Mit Ausnahme der Diligent-eigenen HCL-Python-Bibliothek müssen Sie die vorinstallierten Bibliotheken importieren, um sie in der nachfolgenden Python/HCL-Skript-Logik verwenden zu können.

Externe Bibliotheken, die in der Diligent One Python-Umgebung vorinstalliert sind:

Bibliothek	Beschreibung	Python Import-Anweisungen
HCL	Die HCL-Bibliothek (HighBond Command Language) ist eine von Diligent entwickelte Python-Bibliothek für die domänenspezifische Datenanalyse und Diligent One-Automatisierung.	nicht erforderlich
Pandas	Die Pandas-Bibliothek bietet eine Reihe leistungsfähiger Werkzeuge für die Datenmanipulation und -analyse in Python. Dazu gehören auch Dataframes, bei denen es sich um kalkulations- oder tabellenähnliche zweidimensionale Datenarrays handelt.	import pandas oder import pandas as pd (erstellt optional einen Kurzalias für den Bibliotheksnamen)
NumPy	Die NumPy-Bibliothek ermöglicht schnelle und leistungsstarke wissenschaftliche Berechnungen in Python, einschließlich grundlegender algebraischer und statistischer Operationen, fortschrittlicher mathematischer Operationen und dem Aufbau und der Durchführung von Berechnungen auf mehrdimensionalen Arrays.	import numpy oder import numpy as np (erstellt optional einen Kurzalias für den Bibliotheksnamen)
Requests	Die Requests-Bibliothek bietet eine schlanke Syntax für die Erstellung von HTTP-Anfragen in Python und die Interaktion mit webbasierten APIs.	import requests oder import requests as req (erstellt optional einen Kurzalias für den Bibliotheksnamen)
Cryptography	Die Cryptography-Bibliothek unterstützt die Einbindung von kryptographischen Algorithmen in Python.	import cryptography oder import cryptography as crypt (erstellt optional einen Kurzalias für den Bibliotheksnamen)

Weitere externe Bibliotheken installieren

HighBond-Robots unterstützen die Installation weiterer externer Bibliotheken, die nicht zusammen mit der Diligent One Python-Umgebung vorinstalliert wurden. Installieren Sie eine weitere Bibliothek mit pip, einem Tool zum Herunterladen und Installieren von Python-Paketen. Standardmäßig lädt pip die Pakete aus dem Python Package Index (PyPI) herunter, einem Open-Source-Repository für Python-Software. Sie können mit pip auch Pakete von anderen Quellen installieren.

Um zum Beispiel pyexcel, eine Python-Bibliothek für die Arbeit mit Excel-Dateien und -Daten, zu installieren, verwenden Sie den folgenden Befehl im Robots Skript-Editor:

pip install pyexcel

Selbst wenn Sie eine externe Bibliothek installieren, gibt es keine Garantie dafür, dass der Robots Skript Editor alle Funktionen der externen Bibliothek unterstützt. So ist es beispielsweise möglich, dass die Anzeige von Grafiken und Diagrammen, die in bestimmten externen Bibliotheken verfügbar sind, nicht unterstützt wird.

Python und HCL zusammen mit APIs verwenden

Sie können Python/HCL-Skripts in Robots zur Arbeit mit APIs verwenden – sowohl APIs von Drittanbietern als auch die eigene API von Diligent One.

Mit einer Drittanbieter-API arbeiten

Um mit einer Drittanbieter-API zu arbeiten, importieren Sie zuerst die Bibliothek „Python Requests“ in den Skript-Editor von Robots:

import requests

Sie können jetzt API-Anfragen mit der Anfragesyntax von Python erstellen und Antworten empfangen. Ein einfaches Beispiel für die Verwendung von Python für Drittanbieter-API-Anforderungen in Robots finden Sie in Teil 3: Die Reichweite erweitern in Erste Schritte mit Robots-Skripting und der Diligent-HighBond-API.

Die Verwendung von Python mit APIs von Fremdherstellern im Detail zu erläutern, würde den Rahmen unserer Dokumentation sprengen. Es gibt jedoch viele Online-Ressourcen, die detaillierte Anweisungen hierzu enthalten.

Mit der HighBond-API arbeiten

Die HighBond-API ist die Entwicklerschnittstelle der Diligent One-Plattform. Sie können die API verwenden, um Interaktionen mit Diligent One sowie den Workflow zu automatisieren, Berichte zu erstellen und Diligent One mit anderen Systemen in Ihrer Organisation zu integrieren.

HCL enthält Methoden, durch die eine Interaktion mit der HighBond-API einfach wird. Weitere Informationen finden Sie unter HCL-HighBond-API-Methoden.

Sie können auch die Bibliothek „Python Requests“ zusammen mit der HighBond-API verwenden. Zur Vereinfachung empfehlen wir aber, die HCL-Methoden zu verwenden.

Ein einführendes Tutorial zur Verwendung von Python und HCL mit der HighBond-API finden Sie unter Erste Schritte mit Robots-Skripting und der Diligent-HighBond-API.