Der Einsatz von Workiva Scripting und APIs kann Arbeitsabläufe und Workflows erheblich rationalisieren. Wie bei allen Scripting-Projekten führt die Einhaltung bewährter Verfahren für die Code-Entwicklung und Versionskontrolle zu einem effektiven Projektmanagement, Kontinuität und Erfolg.
Nachfolgend finden Sie einige Tipps und Tricks zu Workiva Scripting für die Projektentwicklung und die Arbeitsabläufe.
Workiva Skripting-Editor
Der Workiva Scripting Editor wurde entwickelt, um bei der Integration von Produktionscode in Workiva zu helfen, Produktionsläufe zu überwachen und erste Fehler zu beheben, wenn Probleme auftreten. ist kein umfassender Code-Editor ( ), und wir haben auch nicht vor, ihn zu einem solchen zu machen.
Entwicklungsumgebung
Wenn Sie bereits über eine Entwicklungsumgebung und ein Versionskontrollsystem verfügen, empfehlen wir Ihnen, dies für die Entwicklung und das Testen von Skripten zu verwenden.
Zu den wichtigsten Komponenten einer Entwicklungsumgebung gehören ein Code-Editor (beliebte Beispiele sind VSCode, PyCharm, Jupyter, usw.) und ein Versionskontrollsystem (beliebte Beispiele sind GitHub und GitLab). Für Nicht-Ingenieure oder diejenigen, die es vorziehen, nicht mit einer Befehlszeilenschnittstelle zu arbeiten, gibt es leichtgewichtige Tools wie GitHub Desktop und SourceTree, die die Arbeit in Versionskontrollsystemen vereinfachen können.
Wenn Sie keine Entwicklungsumgebung haben, sollten Sie eine einrichten. Achten Sie in der Zwischenzeit darauf, Kopien Ihrer Skripte zu speichern (vor, während und nach allen Änderungen/Aktualisierungen) und stellen Sie sicher, dass Sie die Entwicklungs-/Arbeitsversionen Ihrer Skripte getrennt von den Produktionsversionen aufbewahren, um versehentliches Überschreiben zu vermeiden.
Skripting-Entwicklung
Beachten Sie bei der Entwicklung und dem Testen von Skripting-Projekten die führenden Python- und Versionskontrollpraktiken:
Python
Befolgen Sie PEP 8 - Style Guide for Python Code so weit wie möglich. Die Konsistenz des Codes ist von großem Vorteil für die Lesbarkeit, Wartbarkeit und Kontinuität.
Um robuste, zuverlässige und skalierbare Python-Skripte auf Produktionsebene zu erstellen, sollten Sie sich auf folgende Schlüsselbereiche konzentrieren:
- Authentifizierung: Das effektive Erstellen, Verwalten und Regenerieren des entsprechenden Träger-Tokens stellt sicher, dass nur autorisierte Benutzer oder Systeme auf die Ressourcen, Daten oder Funktionen des Arbeitsbereichs zugreifen können.
- Modularität: Zerlegen Sie große Skripte in kleinere, unabhängige und wiederverwendbare Einheiten (Funktionen, Klassen, Module/Dateien). Dies erleichtert das Lesen, Testen, Debuggen und die Pflege des Skripts im Laufe der Zeit.
- Protokollierung: Fügen Sie eine ausführliche Protokollierung ein, um wichtige Ereignisse und Statusmeldungen zu erfassen, was für die Überwachung der Leistung und die Behebung von Problemen unerlässlich ist.
-
Fehlerbehandlung: Fügen Sie eine Logik für die Fehlerbehandlung ein, um Skripte robuster, zuverlässiger und benutzerfreundlicher zu machen, indem Sie unerwartete Situationen elegant bewältigen, anstatt sie zum Absturz zu bringen.
Hinweis: Verwenden Sie die Fehlerbehandlung, um unerwartete Situationen zu behandeln. Verlassen Sie sich nicht darauf, um die Auswirkungen eines suboptimalen Skriptdesigns auf die Leistung zu kompensieren oder zu verschleiern (wenn Ihr Skript beispielsweise eine große Anzahl von 429/Too Many Requests-Antworten generiert, sollten Sie Ihr Skriptdesign und Ihren Arbeitsablauf überarbeiten, um die API-Aufrufe zu optimieren, und sich für den Erfolg des Skripts nicht auf die effektive Handhabung einer großen Anzahl von 429er-Antworten verlassen).
- Dokumentation: Erklärt, was der Code tut und wie er zu verwenden ist (sowohl intern über Kommentare und Docstrings als auch extern über Benutzerhandbücher (READMEs), damit andere Entwickler und Sie selbst das Skript effektiv und effizient verstehen und verändern können.
- Versionsverfolgung: Integrieren Sie semantische Versionierung in Ihre Skript-Projekte, um die Versionsverfolgung zu erleichtern.
- Benennungskonventionen: Verwenden Sie klare Namenskonventionen für Ihre Skripte (zum Beispiel:
customername_function_v1_3.py). - Testen und verifizieren Sie die Einhaltung des Codes. Verwenden Sie Python-Pakete wie
ruffundflake8, um Lint- und Formatprüfungen durchzuführen. Sie können auch die umfangreichen Zusatztools und Erweiterungen nutzen, die für gängige Code-Editoren verfügbar sind, um Anleitungen und Unterstützung bei der Codeformatierung und beim Linting zu erhalten. -
KI-Code-Assistenten: gibt es viele kostenlose und kostenpflichtige KI-Code-Tools, die Ihnen bei der Fehlersuche und Optimierung helfen können.
Hinweis: KI-Code-Assistenten sind zwar hilfreich, ersetzen jedoch nicht das Wissen und die Erfahrung, die für die Entwicklung fortgeschrittener Skripte und Automatisierungen erforderlich sind.
Versionskontrolle
- Eine einzige Quelle der Wahrheit: Verwenden Sie Ihr Versionskontrollsystem als zentrales Repository und als einzige Quelle der Wahrheit für Ihre Skriptprojekte. Übertragen Sie Änderungen häufig, um sicherzustellen, dass alle aktuellen Entwicklungsarbeiten und Tests erfasst und zentral gespeichert werden.
- Dokumentieren Sie Änderungen vollständig: Fügen Sie allen Commits und Pull-Requests in Ihrem Versionskontrollsystem so viele Details und unterstützende Informationen wie möglich hinzu, um alle Änderungen zu dokumentieren (wer hat die Änderung vorgenommen, was ist die Änderung, warum wurde sie vorgenommen usw.).
Bewährte Praktiken für den Workflow
Bei der Entwicklung, dem Testen und der Bereitstellung von Skripten können Sie die Leistung von Skripten maximieren und potenzielle Fehler und Probleme minimieren, wenn Sie die bewährten Arbeitsabläufe befolgen. Einige der wichtigsten Säulen des Entwicklungs-Workflows sind:
- Führen Sie die gesamte Skriptentwicklung und das Testen in Ihrer Entwicklungsumgebung durch, nicht in Ihrer Produktionsumgebung.
- Übertragen Sie Ihr Skript auf einen Staging-Arbeitsbereich, in dem Sie Ihr Skript auf Workiva testen können.
WICHTIG: Verwenden Sie für Ihre Tests nicht-produktive Daten. - Setzen Sie Ihr Skript erst dann in Ihrem Produktionsarbeitsbereich ein, wenn Sie es erfolgreich getestet haben.
Code zu Workiva übertragen
Sobald Ihre Hauptentwicklung und die Tests abgeschlossen sind und alles wie erwartet funktioniert, können Sie Ihren Code zu Workiva übertragen. Sie können Änderungen zwar auch manuell über den Workiva Scripting Editor in Workiva einspielen, wir empfehlen jedoch dringend, dass Sie das Einspielen Ihres Codes von Ihrem Versionskontrollsystem in Workiva mit Hilfe der Scripting APIs automatisieren. Dies ist der empfohlene Prozess, da die Automatisierung Zeit spart und Fehler reduziert.
Ausführen und Überwachen von Skripts
Skripte können direkt aus dem Skript-Editor, aus Ketten, aus den Skripting-APIs oder aus integrierten Automatisierungen ausgelöst werden. Unabhängig davon, wie Ihre Skripte ausgelöst werden, empfehlen wir Ihnen, den Skript-Editor zur Überwachung der Ausführung und zur Fehlerbehebung zu verwenden.
Protokollierung
Der Skript-Editor enthält einen Abschnitt "Protokolle". Wir empfehlen, dass Ihre Skripte ausführliche Protokolle enthalten, um detaillierte und umfassende Informationen über die Operationen des Skripts zu erhalten. Diese Informationen sind oft sehr nützlich für die Fehlersuche, die Überwachung und das Verständnis der Vorgänge in Ihrem Skript. Das Standard-Python-Paket logging ist ein Beispiel für ein Protokollierungsprogramm, das so eingerichtet werden kann, dass es nützliche Informationen über Skriptoperationen liefert (z.B. Zeitstempel, Protokollstufe, Meldung usw.). Achten Sie darauf, dass Sie die verschiedenen Protokollebenen (INFO, DEBUG, ERROR usw.) verwenden und detaillierte und nützliche Protokollnachrichten einfügen.
Viele fortgeschrittene Benutzer verfügen auch über die Funktion, Protokolle in ein bestimmtes Workiva-Tabellenblatt im selben Arbeitsbereich zu verschieben. Dies ermöglicht einen einfacheren Zugriff, eine schnellere Analyse und eine effiziente Abfrage von Protokollen. Hier sehen Sie ein Beispiel für die Ausgabe eines Protokolls in ein Workiva-Arbeitsblatt (die IDs von Arbeitsblatt und Tabellenkalkulation wurden verschleiert):
Fehlersuche und Hinzufügen neuer Funktionen
Sollten bei der Ausführung Ihres Skripts Probleme auftreten, empfehlen wir Ihnen, das Debugging und die Aktualisierung in Ihrer Entwicklungsumgebung durchzuführen, nicht in Ihrer Produktionsumgebung. Sobald diese Korrekturen/Aktualisierungen fertiggestellt, getestet und in Ihr Versionskontrollsystem übertragen wurden, können Sie das aktualisierte Skript sicher zurück zu Workiva übertragen.
Derselbe Arbeitsablauf sollte verwendet werden, wenn Sie neue Funktionen zu bestehenden Skripten hinzufügen: Führen Sie alle Aktualisierungen und Tests in Ihrer Entwicklungsumgebung durch. Sobald alle Skriptaktualisierungen abgeschlossen, erfolgreich getestet und an Ihr Versionskontrollsystem übergeben wurden, können Sie das aktualisierte Skript an Workiva übergeben.